Credential Manager – interfejs API Holder

Interfejs Credential Manager – Holder API umożliwia aplikacjom na Androida zarządzanie cyfrowymi danymi logowania i przedstawianie ich podmiotom weryfikującym.

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

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

Interfejs selektora Menedżera danych logowania

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

W tym przykładzie metadane są kompilowane z bazy danych wpisów z informacjami o logowaniu. 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 z tym samym identyfikatorem i typem spowoduje zastąpienie poprzedniego rekordu rejestracji. Dlatego musisz ponownie zarejestrować się tylko wtedy, gdy zmienią się dane logowania.

Opcjonalnie: utwórz dopasowanie

Menedżer danych logowania jest niezależny od protokołu. Rejestr metadanych traktuje 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 uruchomi dopasowywanie w środowisku piaskownicy bez dostępu do sieci ani dysku, aby przed wyświetleniem interfejsu użytkownikowi nic nie wyciekło do portfela.

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 wybranego zestawu 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ść, 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 obiekt ProviderGetCredentialRequest zawierający wszystkie informacje powiązane z danym żądaniem weryfikatora. Składają się one z 3 kluczowych elementów:

  • Aplikacja, która przesłała żądanie. Możesz to zrobić za pomocą getCallingAppInfo.
  • Wybrane dane logowania. Informacje o tym, który kandydat został wybrany przez użytkownika, możesz uzyskać za pomocą metody rozszerzenia selectedEntryId. Będzie ona pasować do zarejestrowanego identyfikatora danych logowania.
  • wszelkie konkretne prośby zgłoszone przez weryfikatora; Możesz go uzyskać za pomocą metody getCredentialOptions. W takim przypadku na liście powinna się znajdować ikonaGetDigitalCredentialOption, która oznacza prośbę o Cyfrowe dokumenty.

Najczęściej weryfikator będzie wysyłać prośbę o przesłanie cyfrowych poświadczeń. Możesz ją 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.