Credential Manager – interfejs API Holder

Interfejs Credential Manager – Holder API umożliwia aplikacjom na Androida zarządzanie cyfrowymi dokumentami tożsamości i przedstawianie ich weryfikatorom.

Rozpocznij

Aby używać 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-alpha02"

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, gdy nadejdzie żądanie.

Ilustracja przedstawiająca interfejs cyfrowych dokumentów tożsamości w Menedżerze dokumentów tożsamości
Rysunek 1. Interfejs cyfrowych dokumentów tożsamości.

Interfejs selektora Credential Manager

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 wpisów z danymi logowania. Odpowiednie odniesienie znajdziesz w naszym przykładowym portfelu, który rejestruje metadane podczas wczytywania aplikacji. W przyszłości interfejs Jetpack API będzie obsługiwać kompozycję bazy danych logowania. W tym momencie możesz zarejestrować metadane danych logowania jako dobrze zdefiniowane struktury danych.

Rejestr jest zachowywany po ponownym uruchomieniu urządzenia. Ponowna rejestracja tego samego rejestru o tym samym identyfikatorze i typie spowoduje zastąpienie poprzedniego rekordu rejestru. Dlatego ponownie rejestruj się tylko wtedy, gdy zmienią się dane logowania.

Opcjonalnie: utwórz dopasowanie

Menedżer danych logowania jest niezależny od protokołu. Traktuje rejestr metadanych jako nieprzezroczystą strukturę danych i nie weryfikuje ani nie sprawdza jego zawartości. Dlatego portfel musi udostępniać narzędzie dopasowujące, czyli wykonywalny 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 uruchamia dopasowywanie w środowisku piaskownicy bez dostępu do sieci ani dysku, dzięki czemu nic nie wycieka do portfela, zanim interfejs użytkownika zostanie wyświetlony użytkownikowi.

Interfejs Credential Manager API będzie udostępniać narzędzia dopasowujące do popularnych protokołów, obecnie OpenID4VP. Nie został on jeszcze oficjalnie udostępniony, więc na razie używaj naszego przykładowego narzędzia do dopasowywania w przypadku protokołu OpenID4VP.

Obsługa wybranych danych uwierzytelniających

Następnie portfel musi obsługiwać sytuację, w której użytkownik wybierze dane logowania. Możesz zdefiniować działanie, które nasłuchuje filtra intencji androidx.credentials.registry.provider.action.GET_CREDENTIAL. Nasz przykładowy portfel pokazuje tę procedurę.

Intencja, która uruchamia aktywność, zawiera żądanie weryfikatora i pochodzenie wywołania, które możesz wyodrębnić za pomocą funkcjiPendingIntentHandler.retrieveProviderGetCredentialRequest. Interfejs API zwraca obiekt ProviderGetCredentialRequest zawierający wszystkie informacje powiązane z żądaniem weryfikatora. Wyróżniamy 3 kluczowe komponenty:

  • Aplikacja, która przesłała żądanie. Możesz to zrobić za pomocą getCallingAppInfo.
  • Wybrane dane logowania. Informacje o tym, którego kandydata wybrał użytkownik, możesz uzyskać za pomocą metody rozszerzenia selectedEntryId. Będzie ona pasować do zarejestrowanego identyfikatora danych logowania.
  • wszelkie konkretne prośby, które zgłosił weryfikator. Możesz go uzyskać za pomocą metody getCredentialOptions. W takim przypadku na liście powinna się znajdować ikona GetDigitalCredentialOption, która oznacza prośbę o przesłanie dokumentów tożsamości w formie cyfrowej.

Najczęściej weryfikator wysyła żądanie prezentacji cyfrowych poświadczeń. Możesz je 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 naszym przykładowym portfelu.

Renderowanie interfejsu portfela

Po wybraniu danych logowania portfel zostanie wywołany, a użytkownik zostanie przekierowany do jego interfejsu. W przykładzie jest to prompt biometryczny.

Zwracanie odpowiedzi dotyczącej danych logowania

Gdy portfel będzie gotowy do odesłania wyniku, możesz to zrobić, kończąc działanie z odpowiedzią dotyczącą dokumentu:

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

Jeśli istnieje wyjątek, możesz w podobny sposób przesłać wyjątek dotyczący danych logowania:

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

Przykład zwracania odpowiedzi dotyczącej danych logowania w kontekście znajdziesz w przykładowej aplikacji.