Credential Manager – interfejs API Holder

Interfejs Credential Manager – Holder API umożliwia aplikacjom na Androida zarządzanie cyfrowymi danymi logowania i ich prezentowanie weryfikatorom.

Rozpocznij

Aby korzystać z interfejsu Credential Manager – Holder API, dodaj te zależności do skryptu kompilacji modułu aplikacji:

// In your app module's build.gradle:
dependencies {
    implementation(libs.androidx.registry.provider)
    implementation(libs.androidx.registry.provider.play.services)
}

// In libs.versions.toml:
registryDigitalCredentials = "1.0.0-alpha01"

androidx-registry-provider = { module = "androidx.credentials.registry:registry-provider", version.ref = "registryDigitalCredentials" }
androidx-registry-provider-play-services = { module = "androidx.credentials.registry:registry-provider-play-services", version.ref = "registryDigitalCredentials" }

Rejestrowanie danych logowania w Menedżerze danych logowania

Portfel musi zarejestrować metadane danych logowania, aby Menedżer danych logowania mógł je filtrować i wyświetlać w selektorze danych logowania po otrzymaniu żądania.

Obraz pokazujący interfejs cyfrowych poświadczeń w Menedżerze poświadczeń
Rysunek 1. Interfejs cyfrowych dokumentów tożsamości.

Interfejs selektora Menedżera danych logowania

Format tych metadanych jest przekazywany do RegisterCredentialsRequest. Utwórz [RegistryManager][1] i zarejestruj dane logowania:

W tym przykładzie metadane są kompilowane z bazy danych z wpisami z danymi logowania. Przykładowy portfel zawiera odwołania, które rejestrują metadane podczas wczytywania aplikacji. W przyszłości interfejs Jetpack API będzie obsługiwać dekompozycję bazy danych z danymi logowania. Wtedy możesz zarejestrować metadane poświadczeń jako dobrze zdefiniowane struktury danych.

Rejestr jest zachowywany po ponownym uruchomieniu urządzenia. Ponowne zarejestrowanie tego samego identyfikatora w tym samym rejestrze spowoduje zastąpienie poprzedniego rekordu w rejestrze. Dlatego musisz ponownie zarejestrować się tylko wtedy, gdy zmienią się Twoje dane logowania.

Opcjonalnie: tworzenie dopasowywania

Menedżer danych logowania jest niezależny od protokołu. Traktuje rejestr metadanych jako nieprzezroczysty blok i nie weryfikuje ani nie sprawdza jego zawartości. Dlatego portfel musi udostępnić narzędzie do dopasowywania, czyli uruchamialny plik binarny, który może przetwarzać własne dane portfela i generować metadane wyświetlania na podstawie przychodzącego żądania. Menedżer danych logowania uruchomi narzędzie do dopasowywania w środowisku piaskownicy bez dostępu do sieci ani dysku, aby nic nie wyciekło do portfela, zanim interfejs nie zostanie wyrenderowany dla użytkownika.

Interfejs API Menedżera danych logowania będzie udostępniać dopasowywacze dla popularnych protokołów, obecnie OpenID4VP. Nie został on jeszcze oficjalnie opublikowany, więc na razie użyj przykładowego narzędzia do dopasowywania dla protokołu OpenID4VP w wersji 24.

Obsługa wybranych danych uwierzytelniających

Następnie portfel musi obsłużyć wybranie przez użytkownika danych logowania. Możesz zdefiniować aktywność, która nasłuchuje filtra intencji androidx.credentials.registry.provider.action.GET_CREDENTIAL. Nasz przykładowy portfel pokazuje tę procedurę.

Intencja uruchamiająca aktywność będzie zawierać żądanie weryfikatora i źródło wywołania, które można wyodrębnić za pomocą funkcji PendingIntentHandler.retrieveProviderGetCredentialRequest. Interfejs API zwraca ProviderGetCredentialRequest zawierający wszystkie informacje powiązane z danym żądaniem weryfikatora. Składa się on z 3 kluczowych elementów:

  • Aplikacja, która wysłała żądanie. Możesz to zrobić za pomocą getCallingAppInfo.
  • Wybrane dane uwierzytelniające. Informacje o tym, którego kandydata wybrał użytkownik, możesz uzyskać za pomocą metody rozszerzenia selectedEntryId. Identyfikator zalogowanych danych będzie pasował do zarejestrowanego identyfikatora danych logowania.
  • wszelkie konkretne żądania weryfikatora; Możesz go uzyskać z metody getCredentialOptions. W takim przypadku na tej liście powinieneś/powinnaś znaleźć element GetDigitalCredentialOption zawierający prośbę o cyfrowe dokumenty tożsamości.

Najczęściej weryfikator wysyła prośbę o pokazanie dokumentu tożsamości cyfrowego, którą możesz przetworzyć za pomocą tego przykładowego kodu:

request.credentialOptions.forEach { option ->
    if (option is GetDigitalCredentialOption) {
        Log.i(TAG, "Got DC request: ${option.requestJson}")
        processRequest(option.requestJson)
    }
}

Przykład znajdziesz w przykładowym portfelu.

Renderowanie interfejsu portfela

Po wybraniu danych logowania uruchamia się portfel, a użytkownik przechodzi do jego interfejsu. W tym przykładzie jest to prompt biometryczny.

Zwracanie odpowiedzi dotyczącej danych logowania

Gdy portfel będzie gotowy do wysłania wyniku, możesz to zrobić, kończąc aktywność z odpowiedzią dotyczącą danych logowania:

PendingIntentHandler.setGetCredentialResponse(
    resultData,
    GetCredentialResponse(DigitalCredential(response.responseJson))
)
setResult(RESULT_OK, resultData)
finish()

Jeśli jest to wyjątek, możesz przesłać dokument z wyjątkiem dotyczącym danych logowania:

PendingIntentHandler.setGetCredentialException(
    resultData,
    GetCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

Przykładowy sposób zwracania odpowiedzi z danymi logowania w kontekście znajdziesz w przykładowej aplikacji.