Integrowanie Menedżera danych logowania z komponentem WebView

Z tego dokumentu dowiesz się, jak zintegrować interfejs Credential Manager API z aplikacją na Androida, która używa WebView.

Przegląd

Zanim zagłębimy się w proces integracji, warto poznać przepływ komunikacji między natywnym kodem Androida, czyli komponentem sieciowym renderowanym w komponencie WebView, który zarządza uwierzytelnianiem aplikacji, a także z backendem. Proces ten obejmuje rejestrację (tworzenie danych logowania) i uwierzytelnianie (uzyskiwanie istniejących danych logowania).

Rejestracja (utwórz klucz dostępu)

1. Backend generuje początkowy plik JSON rejestracyjny i wysyła go na stronę internetową renderowaną w WebView.
2. Strona internetowa używa navigator.credentials.create() do zarejestrowania nowych danych logowania. Użyjesz wstrzykniętego JavaScriptu, aby zastąpić tę metodę w późniejszym kroku i wysłać żądanie do aplikacji na Androida.
3. Aplikacja na Androida używa interfejsu Credential Manager API do tworzenia żądania danych logowania i używania ich w createCredential.
4. Interfejs Credential Manager API udostępnia aplikacji dane logowania klucza publicznego.
5. Aplikacja wysyła dane logowania klucza publicznego z powrotem na stronę internetową, aby wstrzyknięty JavaScript mógł przeanalizować odpowiedzi.
6. Strona internetowa wysyła klucz publiczny do backendu, który weryfikuje i zapisuje klucz publiczny.

Uwierzytelnianie (uzyskiwanie klucza dostępu)

1. Backend generuje uwierzytelnianie JSON, aby pobrać dane logowania i wysyła je na stronę internetową renderowaną w kliencie WebView.
2. Strona internetowa używa navigator.credentials.get. Aby zastąpić tę metodę, użyj wstrzykniętego JavaScriptu i przekieruj żądanie do aplikacji na Androida.
3. Aplikacja pobiera dane logowania przy użyciu interfejsu Credential Manager API, wywołując metodę getCredential.
4. Interfejs Credential Manager API zwraca dane logowania do aplikacji.
5. Aplikacja otrzymuje cyfrowy podpis klucza prywatnego i wysyła go na stronę internetową, aby wstrzyknięty JavaScript mógł przeanalizować odpowiedzi.
6. Następnie strona internetowa wysyła go do serwera, który weryfikuje podpis cyfrowy za pomocą klucza publicznego.

Ten sam proces można zastosować w przypadku haseł i sfederowanych systemów tożsamości.

Wymagania wstępne

Aby korzystać z interfejsu Credential Manager API, wykonaj czynności opisane w sekcji wymagania wstępne przewodnika po usłudze Credential Manager:

• Dodaj wymagane zależności.
• Zachowaj klasy w pliku ProGuard.
• Dodaj obsługę Digital Asset Links.

Komunikacja JavaScript

Aby umożliwić komunikację między JavaScriptem w komponencie WebView i natywnym kodzie Androida, musisz wysyłać komunikaty i obsługiwać żądania między tymi środowiskami. Aby to zrobić, wstrzyknij niestandardowy kod JavaScript do komponentu WebView. Pozwala to modyfikować działanie treści internetowych i wchodzić w interakcje z natywnym kodem Androida.

Wstrzyknięcie kodu JavaScript

Ten kod JavaScript umożliwia nawiązanie komunikacji między komponentem WebView a aplikacją na Androida. Zastępuje metody navigator.credentials.create() i navigator.credentials.get() używane przez interfejs WebAuthn API do rejestracji i uwierzytelniania, które zostały opisane wcześniej.

Użyj w swojej aplikacji zminifikowanej wersji tego kodu JavaScript.

Utwórz odbiornik kluczy dostępu

Skonfiguruj klasę PasskeyWebListener do obsługi komunikacji z JavaScriptem. Ta klasa powinna dziedziczyć element z klasy WebViewCompat.WebMessageListener. Te zajęcia odbierają wiadomości z JavaScriptu i wykonują niezbędne działania w aplikacji na Androida.

// 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
}

W PasskeyWebListener zaimplementuj logikę żądań i odpowiedzi zgodnie z poniższymi sekcjami.

Obsługa żądania uwierzytelnienia

Aby obsługiwać żądania dotyczące operacji WebAuthn navigator.credentials.create() lub navigator.credentials.get(), metoda onPostMessage klasy PasskeyWebListener jest wywoływana, gdy kod JavaScript wysyła wiadomość do aplikacji na Androida:

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();
      }
    }
  }
}

W przypadku handleCreateFlow i handleGetFlow zapoznaj się z przykładem na GitHubie.

Obsługa odpowiedzi

Aby obsługiwać odpowiedzi wysyłane z aplikacji natywnej na stronę internetową, dodaj JavaScriptReplyProxy w interfejsie 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);
  }
}

Pamiętaj, aby wychwytywać wszystkie błędy z aplikacji natywnej i odesłać je z powrotem na stronę JavaScriptu.

Integracja z komponentem WebView

W tej sekcji opisujemy, jak skonfigurować integrację WebView.

Inicjowanie komponentu WebView

W aktywności aplikacji na Androida zainicjuj WebView i skonfiguruj powiązany z nią WebViewClient. WebViewClient obsługuje komunikację z kodem JavaScript wstawionym do interfejsu WebView.

Skonfiguruj komponent WebView i wywołaj Menedżera danych logowania:

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);
}

Utwórz nowy obiekt kliencki WebView i wstrzyknij JavaScript na stronie internetowej:

// 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);

Konfigurowanie odbiornika wiadomości internetowych

Aby zezwolić na publikowanie wiadomości między JavaScriptem a aplikacją na Androida, skonfiguruj detektor wiadomości internetowych za pomocą metody 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
  )
}

Integracja internetowa

Aby dowiedzieć się, jak utworzyć proces płatności z integracją internetową, utwórz klucz dostępu do logowania bez hasła i zaloguj się za pomocą klucza dostępu przez autouzupełnianie formularza.

Testowanie i wdrażanie

Dokładnie przetestuj cały proces w kontrolowanym środowisku, aby zapewnić prawidłową komunikację między aplikacją na Androida, stroną internetową i backendem.

Wdróż zintegrowane rozwiązanie w środowisku produkcyjnym, upewniając się, że backend będzie w stanie obsługiwać przychodzące żądania rejestracji i uwierzytelniania. Kod backendu powinien wygenerować początkowy kod JSON na potrzeby procesów rejestracji (tworzenia) i uwierzytelniania (get). Powinien też obsługiwać weryfikację odpowiedzi otrzymanych ze strony internetowej.

Sprawdź, czy implementacja odpowiada zaleceniom UX.

Ważne uwagi

• Użyj podanego kodu JavaScript do obsługi operacji navigator.credentials.create() i navigator.credentials.get().
• Klasa PasskeyWebListener to most między aplikacją na Androida a kodem JavaScript w komponencie WebView. Obsługuje przekazywanie wiadomości, komunikację i wykonywanie wymaganych działań.
• Dostosuj udostępnione fragmenty kodu do struktury projektu, konwencji nazewnictwa i wszelkich konkretnych wymagań.
• Wykrywaj błędy po stronie aplikacji natywnej i wysyłaj je z powrotem do JavaScriptu.

Postępując zgodnie z tym przewodnikiem i integrując interfejs Credential Manager API z aplikacją na Androida, która korzysta z komponentu WebView, możesz zapewnić użytkownikom bezpieczne i wygodne logowanie z włączoną obsługą kluczy, a jednocześnie skutecznie zarządzać ich danymi logowania.