Аутентификация пользователей с помощью WebView

В этом документе описывается, как интегрировать API Credential Manager с приложением Android, использующим WebView.

Обзор

Прежде чем погрузиться в процесс интеграции, важно понять поток взаимодействия между собственным кодом Android, веб-компонентом, отображаемым в WebView, который управляет аутентификацией вашего приложения, и серверной частью. Этот поток включает в себя регистрацию (создание учетных данных) и аутентификацию (получение существующих учетных данных).

Регистрация (создание пароля)

  1. Серверная часть генерирует исходный регистрационный JSON и отправляет его на веб-страницу, отображаемую в WebView.
  2. Веб-страница использует navigator.credentials.create() для регистрации новых учетных данных. Вы будете использовать внедренный JavaScript, чтобы переопределить этот метод на более позднем этапе и отправить запрос в приложение Android.
  3. Приложение Android использует API диспетчера учетных данных для создания запроса учетных данных и использования его для createCredential .
  4. API диспетчера учетных данных передает учетные данные открытого ключа приложению.
  5. Приложение отправляет учетные данные открытого ключа обратно на веб-страницу, чтобы внедренный JavaScript мог проанализировать ответы.
  6. Веб-страница отправляет открытый ключ на серверную часть, которая проверяет и сохраняет открытый ключ.
Диаграмма, показывающая процесс регистрации ключа доступа
Рисунок 1. Процесс регистрации ключа доступа.

Аутентификация (получение ключа доступа)

  1. Серверная часть генерирует аутентификационный JSON для получения учетных данных и отправляет их на веб-страницу, которая отображается в клиенте WebView.
  2. Веб-страница использует navigator.credentials.get . Используйте внедренный JavaScript, чтобы переопределить этот метод и перенаправить запрос в приложение Android.
  3. Приложение получает учетные данные с помощью API диспетчера учетных данных, вызывая getCredential .
  4. API диспетчера учетных данных возвращает учетные данные приложению.
  5. Приложение получает цифровую подпись закрытого ключа и отправляет ее на веб-страницу, чтобы внедренный JavaScript мог проанализировать ответы.
  6. Затем веб-страница отправляет ее на сервер, который проверяет цифровую подпись с помощью открытого ключа.
Диаграмма, показывающая процесс аутентификации с помощью ключа доступа
Рисунок 2. Процесс аутентификации с помощью ключа доступа.

Тот же поток можно использовать для паролей или федеративных систем идентификации.

Предварительные условия

Чтобы использовать Credential Manager API, выполните действия, описанные в разделе «Предварительные требования» руководства Credential Manager, и обязательно выполните следующие действия:

JavaScript-коммуникация

Чтобы JavaScript в WebView и собственный код Android могли взаимодействовать друг с другом, вам необходимо отправлять сообщения и обрабатывать запросы между двумя средами. Для этого внедрите собственный код JavaScript в WebView. Это позволяет вам изменять поведение веб-контента и взаимодействовать с собственным кодом Android.

JavaScript-инъекция

Следующий код JavaScript устанавливает связь между WebView и приложением Android. Он переопределяет методы navigator.credentials.create() и navigator.credentials.get() , которые используются API WebAuthn для описанных ранее потоков регистрации и аутентификации.

Используйте уменьшенную версию этого кода JavaScript в своем приложении.

Создайте прослушиватель паролей

Настройте класс PasskeyWebListener , который обрабатывает взаимодействие с JavaScript. Этот класс должен наследовать от WebViewCompat.WebMessageListener . Этот класс получает сообщения от JavaScript и выполняет необходимые действия в приложении Android.

Котлин 

// The class talking to Javascript should inherit:
class PasskeyWebListener(
    private val activity: Activity,
    private val coroutineScope: CoroutineScope,
    private val credentialManagerHandler: CredentialManagerHandler
) : WebViewCompat.WebMessageListener

// ... Implementation details

Ява 

// The class talking to Javascript should inherit:
class PasskeyWebListener implements WebViewCompat.WebMessageListener {

  // Implementation details
  private Activity activity;

  // Handles get/create methods meant for Java:
  private CredentialManagerHandler credentialManagerHandler;

  public PasskeyWebListener(
    Activity activity,
    CredentialManagerHandler credentialManagerHandler
    ) {
    this.activity = activity;
    this.credentialManagerHandler = credentialManagerHandler;
  }

// ... Implementation details
}

Внутри PasskeyWebListener реализуйте логику для запросов и ответов, как описано в следующих разделах.

Обработка запроса аутентификации

Для обработки запросов на операции WebAuthn navigator.credentials.create() или navigator.credentials.get() метод onPostMessage класса PasskeyWebListener вызывается, когда код JavaScript отправляет сообщение приложению Android:

Котлин 

class PasskeyWebListener(...)... {
// ...

  /** havePendingRequest is true if there is an outstanding WebAuthn request.
      There is only ever one request outstanding at a time. */
  private var havePendingRequest = false

  /** pendingRequestIsDoomed is true if the WebView has navigated since
      starting a request. The FIDO module cannot be canceled, but the response
      will never be delivered in this case. */
  private var pendingRequestIsDoomed = false

  /** replyChannel is the port that the page is listening for a response on.
      It is valid if havePendingRequest is true. */
  private var replyChannel: ReplyChannel? = null

  /**
  * Called by the page during a WebAuthn request.
  *
  * @param view Creates the WebView.
  * @param message The message sent from the client using injected JavaScript.
  * @param sourceOrigin The origin of the HTTPS request. Should not be null.
  * @param isMainFrame Should be set to true. Embedded frames are not
    supported.
  * @param replyProxy Passed in by JavaScript. Allows replying when wrapped in
    the Channel.
  * @return The message response.
  */
  @UiThread
  override fun onPostMessage(
    view: WebView,
    message: WebMessageCompat,
    sourceOrigin: Uri,
    isMainFrame: Boolean,
    replyProxy: JavaScriptReplyProxy,
  ) {
    val messageData = message.data ?: return
    onRequest(
      messageData,
      sourceOrigin,
      isMainFrame,
      JavaScriptReplyChannel(replyProxy)
    )
  }

  private fun onRequest(
    msg: String,
    sourceOrigin: Uri,
    isMainFrame: Boolean,
    reply: ReplyChannel,
  ) {
    msg?.let {
      val jsonObj = JSONObject(msg);
      val type = jsonObj.getString(TYPE_KEY)
      val message = jsonObj.getString(REQUEST_KEY)

      if (havePendingRequest) {
        postErrorMessage(reply, "The request already in progress", type)
        return
      }

      replyChannel = reply
      if (!isMainFrame) {
        reportFailure("Requests from subframes are not supported", type)
        return
      }
      val originScheme = sourceOrigin.scheme
      if (originScheme == null || originScheme.lowercase() != "https") {
        reportFailure("WebAuthn not permitted for current URL", type)
        return
      }

      // Verify that origin belongs to your website,
      // it's because the unknown origin may gain credential info.
      if (isUnknownOrigin(originScheme)) {
        return
      }

      havePendingRequest = true
      pendingRequestIsDoomed = false

      // Use a temporary "replyCurrent" variable to send the data back, while
      // resetting the main "replyChannel" variable to null so it’s ready for
      // the next request.
      val replyCurrent = replyChannel
      if (replyCurrent == null) {
        Log.i(TAG, "The reply channel was null, cannot continue")
        return;
      }

      when (type) {
        CREATE_UNIQUE_KEY ->
          this.coroutineScope.launch {
            handleCreateFlow(credentialManagerHandler, message, replyCurrent)
          }

        GET_UNIQUE_KEY -> this.coroutineScope.launch {
          handleGetFlow(credentialManagerHandler, message, replyCurrent)
        }

        else -> Log.i(TAG, "Incorrect request json")
      }
    }
  }

  private suspend fun handleCreateFlow(
    credentialManagerHandler: CredentialManagerHandler,
    message: String,
    reply: ReplyChannel,
  ) {
    try {
      havePendingRequest = false
      pendingRequestIsDoomed = false
      val response = credentialManagerHandler.createPasskey(message)
      val successArray = ArrayList<Any>();
      successArray.add("success");
      successArray.add(JSONObject(response.registrationResponseJson));
      successArray.add(CREATE_UNIQUE_KEY);
      reply.send(JSONArray(successArray).toString())
      replyChannel = null // setting initial replyChannel for the next request
    } catch (e: CreateCredentialException) {
      reportFailure(
        "Error: ${e.errorMessage} w type: ${e.type} w obj: $e",
        CREATE_UNIQUE_KEY
      )
    } catch (t: Throwable) {
      reportFailure("Error: ${t.message}", CREATE_UNIQUE_KEY)
    }
  }

  companion object {
    const val TYPE_KEY = "type"
    const val REQUEST_KEY = "request"
    const val CREATE_UNIQUE_KEY = "create"
    const val GET_UNIQUE_KEY = "get"
  }
}

Ява 

class PasskeyWebListener implements ... {
// ...

  /**
  * Called by the page during a WebAuthn request.
  *
  * @param view Creates the WebView.
  * @param message The message sent from the client using injected JavaScript.
  * @param sourceOrigin The origin of the HTTPS request. Should not be null.
  * @param isMainFrame Should be set to true. Embedded frames are not
    supported.
  * @param replyProxy Passed in by JavaScript. Allows replying when wrapped in
    the Channel.
  * @return The message response.
  */
  @UiThread
  public void onPostMessage(
    @NonNull WebView view,
    @NonNull WebMessageCompat message,
    @NonNull Uri sourceOrigin,
    Boolean isMainFrame,
    @NonNull JavaScriptReplyProxy replyProxy,
  ) {
      if (messageData == null) {
        return;
    }
    onRequest(
      messageData,
      sourceOrigin,
      isMainFrame,
      JavaScriptReplyChannel(replyProxy)
    )
  }

  private void onRequest(
    String msg,
    Uri sourceOrigin,
    boolean isMainFrame,
    ReplyChannel reply
  ) {
      if (msg != null) {
        try {
          JSONObject jsonObj = new JSONObject(msg);
          String type = jsonObj.getString(TYPE_KEY);
          String message = jsonObj.getString(REQUEST_KEY);

          boolean isCreate = type.equals(CREATE_UNIQUE_KEY);
          boolean isGet = type.equals(GET_UNIQUE_KEY);

          if (havePendingRequest) {
              postErrorMessage(reply, "The request already in progress", type);
              return;
          }
          replyChannel = reply;
          if (!isMainFrame) {
              reportFailure("Requests from subframes are not supported", type);
              return;
          }
          String originScheme = sourceOrigin.getScheme();
          if (originScheme == null || !originScheme.toLowerCase().equals("https")) {
              reportFailure("WebAuthn not permitted for current URL", type);
              return;
          }

          // Verify that origin belongs to your website,
          // Requests of unknown origin may gain access to credential info.
          if (isUnknownOrigin(originScheme)) {
            return;
          }

          havePendingRequest = true;
          pendingRequestIsDoomed = false;

          // Use a temporary "replyCurrent" variable to send the data back,
          // while resetting the main "replyChannel" variable to null so it’s
          // ready for the next request.

          ReplyChannel replyCurrent = replyChannel;
          if (replyCurrent == null) {
              Log.i(TAG, "The reply channel was null, cannot continue");
              return;
          }

          if (isCreate) {
              handleCreateFlow(credentialManagerHandler, message, replyCurrent));
          } else if (isGet) {
              handleGetFlow(credentialManagerHandler, message, replyCurrent));
          } else {
              Log.i(TAG, "Incorrect request json");
          }
        } catch (JSONException e) {
        e.printStackTrace();
      }
    }
  }
}

Для handleCreateFlow и handleGetFlow обратитесь к примеру на GitHub .

Обработка ответа

Чтобы обрабатывать ответы, отправляемые из собственного приложения на веб-страницу, добавьте JavaScriptReplyProxy в JavaScriptReplyChannel .

Котлин 

class PasskeyWebListener(...)... {
// ...
  // The setup for the reply channel allows communication with JavaScript.
  private class JavaScriptReplyChannel(private val reply: JavaScriptReplyProxy) :
    ReplyChannel {
    override fun send(message: String?) {
      try {
        reply.postMessage(message!!)
      } catch (t: Throwable) {
        Log.i(TAG, "Reply failure due to: " + t.message);
      }
    }
  }

  // ReplyChannel is the interface where replies to the embedded site are
  // sent. This allows for testing since AndroidX bans mocking its objects.
  interface ReplyChannel {
    fun send(message: String?)
  }
}

Ява 

class PasskeyWebListener implements ... {
// ...

  // The setup for the reply channel allows communication with JavaScript.
  private static class JavaScriptReplyChannel implements ReplyChannel {
    private final JavaScriptReplyProxy reply;

    JavaScriptReplyChannel(JavaScriptReplyProxy reply) {
      this.reply = reply;
    }

    @Override
    public void send(String message) {
      reply.postMessage(message);
    }
  }

  // ReplyChannel is the interface where replies to the embedded site are
  // sent. This allows for testing since AndroidX bans mocking its objects.
  interface ReplyChannel {
    void send(String message);
  }
}

Обязательно обнаруживайте любые ошибки в собственном приложении и отправляйте их обратно на сторону JavaScript.

Интеграция с WebView

В этом разделе описывается, как настроить интеграцию WebView.

Инициализировать веб-представление

В активности вашего приложения Android инициализируйте WebView и настройте соответствующий WebViewClient . WebViewClient обрабатывает связь с кодом JavaScript, внедренным в WebView .

Настройте WebView и вызовите диспетчер учетных данных:

Котлин 

val credentialManagerHandler = CredentialManagerHandler(this)
// ...

AndroidView(factory = {
  WebView(it).apply {
    settings.javaScriptEnabled = true

    // Test URL:
    val url = "https://credman-web-test.glitch.me/"
    val listenerSupported = WebViewFeature.isFeatureSupported(
      WebViewFeature.WEB_MESSAGE_LISTENER
    )
    if (listenerSupported) {
      // Inject local JavaScript that calls Credential Manager.
      hookWebAuthnWithListener(this, this@MainActivity,
      coroutineScope, credentialManagerHandler)
      } else {
        // Fallback routine for unsupported API levels.
      }
      loadUrl(url)
    }
  }
)

Ява 

// Example shown in the onCreate method of an Activity

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_main);

  WebView webView = findViewById(R.id.web_view);
  // Test URL:
  String url = "https://credman-web-test.glitch.me/";
  Boolean listenerSupported = WebViewFeature.isFeatureSupported(
    WebViewFeature.WEB_MESSAGE_LISTENER
  );
  if (listenerSupported) {
    // Inject local JavaScript that calls Credential Manager.
    hookWebAuthnWithListener(webView, this,
      coroutineScope, credentialManagerHandler)
  } else {
    // Fallback routine for unsupported API levels.
  }
  webView.loadUrl(url);
}

Создайте новый клиентский объект WebView и внедрите JavaScript на веб-страницу:

Котлин 

// This is an example call into hookWebAuthnWithListener
val passkeyWebListener = PasskeyWebListener(
  activity, coroutineScope, credentialManagerHandler
)

val webViewClient = object : WebViewClient() {
  override fun onPageStarted(view: WebView?, url: String?, favicon: Bitmap?) {
    super.onPageStarted(view, url, favicon)
    // Handle page load events
    passkeyWebListener.onPageStarted();
    webView.evaluateJavascript(PasskeyWebListener.INJECTED_VAL, null)
  }
}

webView.webViewClient = webViewClient

Ява 

// This is an example call into hookWebAuthnWithListener
PasskeyWebListener passkeyWebListener = new PasskeyWebListener(
  activity, credentialManagerHandler
)

WebViewClient webiewClient = new WebViewClient() {
  @Override
  public void onPageStarted(WebView view, String url, Bitmap favicon) {
    super.onPageStarted(view, url, favicon);
    // Handle page load events
    passkeyWebListener.onPageStarted();
    webView.evaulateJavascript(PasskeyWebListener.INJECTED_VAL, null);
  }
};

webView.setWebViewClient(webViewClient);

Настройка прослушивателя веб-сообщений

Чтобы разрешить отправку сообщений между JavaScript и приложением Android, настройте прослушиватель веб-сообщений с помощью метода WebViewCompat.addWebMessageListener .

Котлин 

val rules = setOf("*")
if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_MESSAGE_LISTENER)) {
  WebViewCompat.addWebMessageListener(
    webView, PasskeyWebListener.INTERFACE_NAME, rules, passkeyWebListener
  )
}

Ява 

Set<String> rules = new HashSet<>(Arrays.asList("*"));

if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_MESSAGE_LISTENER)) {
  WebViewCompat.addWebMessageListener(
    webView, PasskeyWebListener.INTERFACE_NAME, rules, passkeyWebListener
  )
}

Веб-интеграция

Чтобы узнать, как создать проверку веб-интеграции, создайте ключ доступа для входа в систему без пароля и войдите в систему с помощью ключа доступа посредством автозаполнения формы .

Тестирование и развертывание

Тщательно протестируйте весь процесс в контролируемой среде, чтобы обеспечить правильную связь между приложением Android, веб-страницей и серверной частью.

Разверните интегрированное решение в рабочей среде, гарантируя, что серверная часть сможет обрабатывать входящие запросы на регистрацию и аутентификацию. Серверный код должен генерировать исходный JSON для процессов регистрации (создания) и аутентификации (получения). Он также должен выполнять проверку и проверку ответов, полученных с веб-страницы.

Убедитесь, что реализация соответствует рекомендациям UX .

Важные примечания

  • Используйте предоставленный код JavaScript для обработки операций navigator.credentials.create() и navigator.credentials.get() .
  • Класс PasskeyWebListener — это мост между приложением Android и кодом JavaScript в WebView. Он управляет передачей сообщений, связью и выполнением необходимых действий.
  • Адаптируйте предоставленные фрагменты кода в соответствии со структурой вашего проекта, соглашениями об именах и любыми конкретными требованиями, которые могут у вас возникнуть.
  • Перехватывайте ошибки на стороне собственного приложения и отправляйте их обратно на сторону JavaScript.

Следуя этому руководству и интегрировав API диспетчера учетных данных в свое приложение Android, использующее WebView, вы сможете обеспечить безопасный и удобный вход в систему с использованием пароля для своих пользователей, одновременно эффективно управляя их учетными данными.