Integrowanie Menedżera danych logowania z rozwiązaniem dostawcy danych uwierzytelniających

Credential Manager to zestaw interfejsów API wprowadzonych w Androidzie 14, które obsługują wiele metod logowania, takich jak nazwa użytkownika i hasło, klucze dostępu i rozwiązania logowania federacyjnego (np. Zaloguj się przez Google). Gdy wywołasz interfejs API menedżera danych uwierzytelniających, system Android agreguje dane uwierzytelniające ze wszystkich dostawców danych uwierzytelniających zainstalowanych na urządzeniu. Ten dokument opisuje zestaw interfejsów API, które udostępniają punkty końcowe integracji dla tych dostawców danych logowania.

Konfiguracja

Zanim zaczniesz wdrażać funkcje w dostawcy danych logowania, wykonaj czynności konfiguracyjne opisane w następnych sekcjach.

Deklarowanie zależności

W pliku build.gradle modułu zadeklaruj zależność, używając najnowszej wersji biblioteki Menedżera danych logowania:

implementation "androidx.credentials:credentials:1.2.0-{latest}"

Zadeklaruj element usługi w pliku manifestu

W pliku manifestu aplikacji AndroidManifest.xml dodaj deklarację <service> dla klasy usługi, która rozszerza klasę CredentialProviderService z biblioteki androidx.credentials, jak pokazano w tym przykładzie.

<service android:name=".MyCredentialProviderService"
    android:enabled="true"
    android:exported="true"
    android:label="My Credential Provider"
    android:icon="<any drawable icon>"
    android:permission="android.permission.BIND_CREDENTIAL_PROVIDER_SERVICE"
    tools:targetApi="upside_down_cake">
    <intent-filter>
        <action android:name="android.service.credentials.CredentialProviderService"/>
    </intent-filter>
    <meta-data
        android:name="android.credentials.provider"
        android:resource="@xml/provider"/>
</service>
AndroidManifest.xml

Uprawnienie i filtr intencji pokazane w poprzednim przykładzie są niezbędne, aby proces w Menedżerze danych logowania działał zgodnie z oczekiwaniami. Uprawnienie jest potrzebne, aby z usługą mógł się powiązać tylko system Android. Filtr intencji służy do zwiększenia widoczności tej usługi jako dostawcy poświadczeń, której używa Menedżer poświadczeń.

Deklarowanie obsługiwanych typów danych logowania

W katalogu res/xml utwórz nowy plik o nazwie provider.xml. W tym pliku zadeklaruj typy danych uwierzytelniających obsługiwane przez usługę za pomocą stałych zdefiniowanych dla każdego typu danych uwierzytelniających w bibliotece. W tym przykładzie usługa obsługuje tradycyjne hasła oraz klucze dostępu, których stałe są zdefiniowane jako TYPE_PASSWORD_CREDENTIAL i TYPE_PUBLIC_KEY_CREDENTIAL:

<credential-provider xmlns:android="http://schemas.android.com/apk/res/android">
    <capabilities>
        <capability name="android.credentials.TYPE_PASSWORD_CREDENTIAL" />
        <capability name="androidx.credentials.TYPE_PUBLIC_KEY_CREDENTIAL" />
    </capabilities>
</credential-provider>
provider.xml

Na poprzednich poziomach interfejsu API dostawcy danych uwierzytelniających integrują się z interfejsami API, takimi jak autouzupełnianie haseł i innych danych. Ci dostawcy mogą używać tej samej wewnętrznej infrastruktury do przechowywania istniejących typów danych logowania, a także rozszerzać ją o inne, w tym klucze dostępu.

Dwuetapowe podejście do interakcji z dostawcą

Menedżer danych uwierzytelniających współpracuje z dostawcami danych uwierzytelniających w 2 etapach:

  1. Pierwsza faza to faza rozpoczęcia/zapytania, w której system łączy się z usługami dostawcy danych logowania i wywołuje metody onBeginGetCredentialRequest(), onBeginCreateCredentialRequest() lub onClearCredentialStateRequest() z żądaniami Begin…. Dostawcy muszą przetwarzać te żądania i wysyłać odpowiedzi Begin…, wypełniając je wpisami, które reprezentują opcje wizualne wyświetlane w selektorze kont. Każdy wpis musi mieć ustawioną wartość PendingIntent.
  2. Gdy użytkownik wybierze pozycję, rozpoczyna się faza wyboru i wyzwala się PendingIntent powiązany z nią, co powoduje wyświetlenie odpowiedniej aktywności dostawcy. Gdy użytkownik skończy interakcję z tą aktywnością, dostawca danych logowania musi ustawić odpowiedź na wynik tej aktywności, zanim ją zakończy. Ta odpowiedź jest następnie wysyłana do aplikacji klienta, która wywołała Menedżera danych logowania.

Tworzenie kluczy dostępu

Obsługa zapytań dotyczących tworzenia kluczy dostępu

Gdy aplikacja klienta chce utworzyć klucz dostępu i przechowywać go u dostawcy danych logowania, wywołuje interfejs API createCredential. Aby obsłużyć to żądanie w usłudze dostawcy danych logowania, tak aby klucz dostępu był faktycznie przechowywany w Twoim magazynie, wykonaj czynności opisane w następnych sekcjach.

  1. Zastąp metodę onBeginCreateCredentialRequest() w usłudze rozszerzonej z usługi CredentialProviderService.
  2. Obsługuj BeginCreateCredentialRequest, tworząc odpowiednią wartość BeginCreateCredentialResponse i przekazując ją przez funkcję wywołania zwrotnego.
  3. Podczas tworzenia pliku BeginCreateCredentialResponse dodaj wymagane informacje CreateEntries. Każdy element CreateEntry powinien odpowiadać kontu, na którym można zapisać dane logowania. Musisz też podać wartość elementu PendingIntent wraz z innymi wymaganymi metadanymi.

Przykład poniżej pokazuje, jak wdrożyć te kroki.

override fun onBeginCreateCredentialRequest(
    request: BeginCreateCredentialRequest,
    cancellationSignal: CancellationSignal,
    callback: OutcomeReceiver<BeginCreateCredentialResponse, CreateCredentialException>,
) {
    val response: BeginCreateCredentialResponse? = processCreateCredentialRequest(request)
    if (response != null) {
        callback.onResult(response)
    } else {
        callback.onError(CreateCredentialUnknownException())
    }
}

fun processCreateCredentialRequest(request: BeginCreateCredentialRequest): BeginCreateCredentialResponse? {
    when (request) {
        is BeginCreatePublicKeyCredentialRequest -> {
            // Request is passkey type
            return handleCreatePasskeyQuery(request)
        }
    }
    // Request not supported
    return null
}

private fun handleCreatePasskeyQuery(
    request: BeginCreatePublicKeyCredentialRequest
): BeginCreateCredentialResponse {

    // Adding two create entries - one for storing credentials to the 'Personal'
    // account, and one for storing them to the 'Family' account. These
    // accounts are local to this sample app only.
    val createEntries: MutableList<CreateEntry> = mutableListOf()
    createEntries.add( CreateEntry(
        PERSONAL_ACCOUNT_ID,
        createNewPendingIntent(PERSONAL_ACCOUNT_ID, CREATE_PASSKEY_INTENT)
    ))

    createEntries.add( CreateEntry(
        FAMILY_ACCOUNT_ID,
        createNewPendingIntent(FAMILY_ACCOUNT_ID, CREATE_PASSKEY_INTENT)
    ))

    return BeginCreateCredentialResponse(createEntries)
}

private fun createNewPendingIntent(accountId: String, action: String): PendingIntent {
    val intent = Intent(action).setPackage(PACKAGE_NAME)

    // Add your local account ID as an extra to the intent, so that when
    // user selects this entry, the credential can be saved to this
    // account
    intent.putExtra(EXTRA_KEY_ACCOUNT_ID, accountId)

    return PendingIntent.getActivity(
        applicationContext, UNIQUE_REQ_CODE,
        intent, (
            PendingIntent.FLAG_MUTABLE
                or PendingIntent.FLAG_UPDATE_CURRENT
            )
    )
}
MyCredentialProviderService.kt

Twoja konstrukcja PendingIntent powinna być zgodna z tymi wytycznymi:

  • Odpowiednia aktywność powinna być skonfigurowana tak, aby wyświetlać wymagane prompty biometryczne, potwierdzenia lub wybory.
  • Wszelkie wymagane dane, których dostawca potrzebuje do wykonania odpowiedniej czynności, należy ustawić jako dodatkowe w intencji używanej do tworzenia PendingIntent, np. accountId w procesie tworzenia.
  • Wartość PendingIntent musi być skonstruowana z flagą PendingIntent.FLAG_MUTABLE, aby system mógł dołączyć ostateczne żądanie do rozszerzenia intencji.
  • Funkcja PendingIntent nie może być zbudowana z flagą PendingIntent.FLAG_ONE_SHOT, ponieważ użytkownik może wybrać wpis, wrócić i ponownie go wybrać, co spowoduje, że funkcja PendingIntent zostanie wywołana dwukrotnie.
  • Wartość PendingIntent musi być utworzona za pomocą unikalnego kodu żądania, aby każda pozycja miała odpowiadającą jej wartość PendingIntent.

Obsługa wyboru wpisu w przypadku żądań tworzenia kluczy dostępu

  1. Gdy użytkownik wybierze wypełnioną wcześniej wartość CreateEntry, wywoływana jest odpowiadająca jej wartość PendingIntent i tworzy się powiązany dostawca Activity.
  2. Po wywołaniu metody onCreate aktywności uzyskaj dostęp do powiązanego zamiaru i przekaż go do klasy PendingIntentHander, aby uzyskać wartość ProviderCreateCredentialRequest.
  3. Wyodrębnij z prośby wartości requestJson, callingAppInfo i clientDataHash.
  4. Wyodrębnij lokalny accountId z dodatkowych informacji o zamiarze. To przykładowa implementacja w aplikacji, która nie jest wymagana. Ten identyfikator konta może służyć do przechowywania tych danych logowania w związku z tym konkretnym identyfikatorem konta.
  5. Zweryfikuj requestJson. Przykład poniżej używa lokalnych klas danych, takich jak PublicKeyCredentialCreationOptions, do konwertowania danych wejściowych w formacie JSON na klasę uporządkowaną zgodnie ze specyfikacją WebAuthn. Jako dostawca danych logowania możesz zastąpić te dane własnym parsowaniem.
  6. Jeśli połączenie pochodzi z natywnej aplikacji na Androida, sprawdź asset-link tej aplikacji.
  7. wyświetlić monit uwierzytelniania; Przykład poniżej korzysta z interfejsu Biometric API w Androidzie.
  8. Po pomyślnym uwierzytelnieniu wygeneruj credentialId i parę kluczy.
  9. Zapisz klucz prywatny w lokalnej bazie danych na potrzeby callingAppInfo.packageName.
  10. Utwórz odpowiedź Web Authentication API w formacie JSON, która składa się z klucza publicznego i credentialId. Przykład poniżej używa lokalnych klas pomocniczych, takich jak AuthenticatorAttestationResponse i FidoPublicKeyCredential, które pomagają tworzyć dane JSON na podstawie wcześniej wspomnianej specyfikacji.Jako dostawca danych logowania możesz zastąpić te klasy własnymi konstruktorami.
  11. Utwórz obiekt CreatePublicKeyCredentialResponse, korzystając z wygenerowanego powyżej pliku JSON.
  12. Ustaw CreatePublicKeyCredentialResponse jako dodatek do Intent za pomocą PendingIntentHander.setCreateCredentialResponse() i ustaw tę intencję jako wynik aktywności.
  13. Zakończ aktywność.

Przykładowy kod poniżej ilustruje te kroki. Ten kod musi być obsługiwany w klasie Activity po wywołaniu onCreate().

override fun onCreate(savedInstanceState: Bundle?, persistentState: PersistableBundle?) {
    super.onCreate(savedInstanceState, persistentState)
    // ...

    val request =
        PendingIntentHandler.retrieveProviderCreateCredentialRequest(intent)

    val accountId = intent.getStringExtra(CredentialsRepo.EXTRA_KEY_ACCOUNT_ID)
    if (request != null && request.callingRequest is CreatePublicKeyCredentialRequest) {
        val publicKeyRequest: CreatePublicKeyCredentialRequest =
            request.callingRequest as CreatePublicKeyCredentialRequest
        createPasskey(
            publicKeyRequest.requestJson,
            request.callingAppInfo,
            publicKeyRequest.clientDataHash,
            accountId
        )
    }
}

@SuppressLint("RestrictedApi")
fun createPasskey(
    requestJson: String,
    callingAppInfo: CallingAppInfo?,
    clientDataHash: ByteArray?,
    accountId: String?
) {
    val request = PublicKeyCredentialCreationOptions(requestJson)

    val biometricPrompt = BiometricPrompt(
        this,
        {  }, // Pass in your own executor
        object : AuthenticationCallback() {
            override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
                super.onAuthenticationError(errorCode, errString)
                finish()
            }

            override fun onAuthenticationFailed() {
                super.onAuthenticationFailed()
                finish()
            }

            @RequiresApi(VERSION_CODES.P)
            override fun onAuthenticationSucceeded(
                result: AuthenticationResult
            ) {
                super.onAuthenticationSucceeded(result)

                // Generate a credentialId
                val credentialId = ByteArray(32)
                SecureRandom().nextBytes(credentialId)

                // Generate a credential key pair
                val spec = ECGenParameterSpec("secp256r1")
                val keyPairGen = KeyPairGenerator.getInstance("EC");
                keyPairGen.initialize(spec)
                val keyPair = keyPairGen.genKeyPair()

                // Save passkey in your database as per your own implementation

                // Create AuthenticatorAttestationResponse object to pass to
                // FidoPublicKeyCredential

                val response = AuthenticatorAttestationResponse(
                    requestOptions = request,
                    credentialId = credentialId,
                    credentialPublicKey = getPublicKeyFromKeyPair(keyPair),
                    origin = appInfoToOrigin(callingAppInfo!!),
                    up = true,
                    uv = true,
                    be = true,
                    bs = true,
                    packageName = callingAppInfo.packageName
                )

                val credential = FidoPublicKeyCredential(
                    rawId = credentialId,
                    response = response,
                    authenticatorAttachment = "", // Add your authenticator attachment
                )
                val result = Intent()

                val createPublicKeyCredResponse =
                    CreatePublicKeyCredentialResponse(credential.json())

                // Set the CreateCredentialResponse as the result of the Activity
                PendingIntentHandler.setCreateCredentialResponse(
                    result,
                    createPublicKeyCredResponse
                )
                setResult(RESULT_OK, result)
                finish()
            }
        }
    )

    val promptInfo = BiometricPrompt.PromptInfo.Builder()
        .setTitle("Use your screen lock")
        .setSubtitle("Create passkey for ${request.rp.name}")
        .setAllowedAuthenticators(
            BiometricManager.Authenticators.BIOMETRIC_STRONG
            /* or BiometricManager.Authenticators.DEVICE_CREDENTIAL */
        )
        .build()
    biometricPrompt.authenticate(promptInfo)
}

@RequiresApi(VERSION_CODES.P)
fun appInfoToOrigin(info: CallingAppInfo): String {
    val cert = info.signingInfo.apkContentsSigners[0].toByteArray()
    val md = MessageDigest.getInstance("SHA-256");
    val certHash = md.digest(cert)
    // This is the format for origin
    return "android:apk-key-hash:${b64Encode(certHash)}"
}
CredentialProviderDummyActivity.kt

Obsługa zapytań dotyczących próśb o utworzenie hasła

Aby obsłużyć zapytania dotyczące żądań utworzenia hasła:

  • W metodzie processCreateCredentialRequest(), o której mowa w poprzedniej sekcji, dodaj w bloku switch kolejny case do obsługi żądań hasła.
  • Podczas tworzenia BeginCreateCredentialResponse dodaj wymagane CreateEntries.
  • Każdy element CreateEntry powinien odpowiadać kontu, na którym można zapisać dane logowania, oraz musi mieć ustawiony element PendingIntent wraz z innymi metadanymi.

Przykład poniżej pokazuje, jak wdrożyć te kroki:

fun processCreateCredentialRequest(
    request: BeginCreateCredentialRequest
): BeginCreateCredentialResponse? {
    when (request) {
        is BeginCreatePublicKeyCredentialRequest -> {
            // Request is passkey type
            return handleCreatePasskeyQuery(request)
        }

        is BeginCreatePasswordCredentialRequest -> {
            // Request is password type
            return handleCreatePasswordQuery(request)
        }
    }
    return null
}

@RequiresApi(VERSION_CODES.M)
private fun handleCreatePasswordQuery(
    request: BeginCreatePasswordCredentialRequest
): BeginCreateCredentialResponse {
    val createEntries: MutableList<CreateEntry> = mutableListOf()

    // Adding two create entries - one for storing credentials to the 'Personal'
    // account, and one for storing them to the 'Family' account. These
    // accounts are local to this sample app only.
    createEntries.add(
        CreateEntry(
            PERSONAL_ACCOUNT_ID,
            createNewPendingIntent(PERSONAL_ACCOUNT_ID, CREATE_PASSWORD_INTENT)
        )
    )
    createEntries.add(
        CreateEntry(
            FAMILY_ACCOUNT_ID,
            createNewPendingIntent(FAMILY_ACCOUNT_ID, CREATE_PASSWORD_INTENT)
        )
    )

    return BeginCreateCredentialResponse(createEntries)
}
CredentialProviderDummyActivity.kt

Obsługa wyboru wpisów w przypadku próśb o utworzenie hasła

Gdy użytkownik wybierze wypełnioną komórkę CreateEntry, zostanie wykonana odpowiadająca jej komórka PendingIntent i wyświetlona powiązana aktywność. Uzyskaj dostęp do powiązanego zamiaru przekazanego w onCreate i przekaż go do klasy PendingIntentHander, aby uzyskać metodę ProviderCreateCredentialRequest.

Przykład poniżej pokazuje, jak wdrożyć ten proces. Ten kod musi być obsługiwany w metodzie onCreate() aktywności.

val createRequest = PendingIntentHandler.retrieveProviderCreateCredentialRequest(intent)
val accountId = intent.getStringExtra(CredentialsRepo.EXTRA_KEY_ACCOUNT_ID)

if (createRequest == null) {
    return
}

val request: CreatePasswordRequest = createRequest.callingRequest as CreatePasswordRequest

// Fetch the ID and password from the request and save it in your database
mDatabase.addNewPassword(
    PasswordInfo(
        request.id,
        request.password,
        createRequest.callingAppInfo.packageName
    )
)

//Set the final response back
val result = Intent()
val response = CreatePasswordResponse()
PendingIntentHandler.setCreateCredentialResponse(result, response)
setResult(Activity.RESULT_OK, result)
finish()
CredentialProviderDummyActivity.kt

Zarządzanie logowaniem użytkowników

Logowanie użytkownika odbywa się w taki sposób:

  • Gdy aplikacja klienta próbuje zalogować użytkownika, przygotowuje wystąpienie GetCredentialRequest.
  • Platforma Androida przekazuje to żądanie wszystkim odpowiednim dostawcom danych logowania, łącząc się z tymi usługami.
  • Usługa dostawcy otrzymuje wtedy odpowiedź BeginGetCredentialRequest, która zawiera listę BeginGetCredentialOption, z których każda zawiera parametry, których można użyć do pobrania pasujących danych logowania.

Aby obsłużyć to żądanie w usłudze dostawcy danych logowania:

  1. Przesłonij metodę onBeginGetCredentialRequest(), aby obsłużyć żądanie. Jeśli Twoje dane logowania są zablokowane, możesz natychmiast ustawić odpowiedź AuthenticationAction i wywołać funkcję wywołania zwrotnego.

    private val unlockEntryTitle = "Authenticate to continue"

override fun onBeginGetCredentialRequest(
    request: BeginGetCredentialRequest,
    cancellationSignal: CancellationSignal,
    callback: OutcomeReceiver<BeginGetCredentialResponse, GetCredentialException>,
) {
    if (isAppLocked()) {
        callback.onResult(BeginGetCredentialResponse(
            authenticationActions = mutableListOf(
                AuthenticationAction(
                    unlockEntryTitle, createUnlockPendingIntent())
                )
            )
        )
        return
    }
    try {
        response = processGetCredentialRequest(request)
        callback.onResult(response)
    } catch (e: GetCredentialException) {
        callback.onError(GetCredentialUnknownException())
    }
}
    MyCredentialProviderService.kt

    Dostawcy, którzy wymagają odblokowania danych logowania przed zwróceniem credentialEntries, muszą skonfigurować oczekujący zamiar, który przekieruje użytkownika do procesu odblokowywania aplikacji:

    private fun createUnlockPendingIntent(): PendingIntent {
    val intent = Intent(UNLOCK_INTENT).setPackage(PACKAGE_NAME)
    return PendingIntent.getActivity(
        applicationContext, UNIQUE_REQUEST_CODE, intent, (
            PendingIntent.FLAG_MUTABLE
                or PendingIntent.FLAG_UPDATE_CURRENT
            )
    )
}
    MyCredentialProviderService.kt

  2. Pobierz dane logowania z lokalnej bazy danych i skonfiguruj je za pomocą CredentialEntries, aby były widoczne w selektorze. W przypadku kluczy dostępu możesz ustawić opcjonalną wartość credentialId w intencji, aby wiedzieć, do których danych logowania odwołuje się klucz, gdy użytkownik wybierze ten wpis.

    companion object {
    // These intent actions are specified for corresponding activities
    // that are to be invoked through the PendingIntent(s)
    private const val GET_PASSKEY_INTENT_ACTION = "PACKAGE_NAME.GET_PASSKEY"
    private const val GET_PASSWORD_INTENT_ACTION = "PACKAGE_NAME.GET_PASSWORD"

}

fun processGetCredentialRequest(
    request: BeginGetCredentialRequest
): BeginGetCredentialResponse {
    val callingPackageInfo = request.callingAppInfo
    val callingPackageName = callingPackageInfo?.packageName.orEmpty()
    val credentialEntries: MutableList<CredentialEntry> = mutableListOf()

    for (option in request.beginGetCredentialOptions) {
        when (option) {
            is BeginGetPasswordOption -> {
                credentialEntries.addAll(
                    populatePasswordData(
                        callingPackageName,
                        option
                    )
                )
            }
            is BeginGetPublicKeyCredentialOption -> {
                credentialEntries.addAll(
                    populatePasskeyData(
                        callingPackageInfo,
                        option
                    )
                )
            } else -> {
                Log.i(TAG, "Request not supported")
            }
        }
    }
    return BeginGetCredentialResponse(credentialEntries)
}
    MyCredentialProviderService.kt

  3. Wykonuj zapytania o dane logowania z bazy danych, twórz wpisy z kluczem dostępu i hasłem, aby je wypełnić.

    private fun populatePasskeyData(
    callingAppInfo: CallingAppInfo?,
    option: BeginGetPublicKeyCredentialOption
): List<CredentialEntry> {
    val passkeyEntries: MutableList<CredentialEntry> = mutableListOf()
    val request = PublicKeyCredentialRequestOptions(option.requestJson)
    // Get your credentials from database where you saved during creation flow
    val creds = getCredentialsFromInternalDb(request.rpId)
    val passkeys = creds.passkeys
    for (passkey in passkeys) {
        val data = Bundle()
        data.putString("credId", passkey.credId)
        passkeyEntries.add(
            PublicKeyCredentialEntry(
                context = applicationContext,
                username = passkey.username,
                pendingIntent = createNewPendingIntent(
                    GET_PASSKEY_INTENT_ACTION,
                    data
                ),
                beginGetPublicKeyCredentialOption = option,
                displayName = passkey.displayName,
                icon = passkey.icon
            )
        )
    }
    return passkeyEntries
}

// Fetch password credentials and create password entries to populate to the user
private fun populatePasswordData(
    callingPackage: String,
    option: BeginGetPasswordOption
): List<CredentialEntry> {
    val passwordEntries: MutableList<CredentialEntry> = mutableListOf()

    // Get your password credentials from database where you saved during
    // creation flow
    val creds = getCredentialsFromInternalDb(callingPackage)
    val passwords = creds.passwords
    for (password in passwords) {
        passwordEntries.add(
            PasswordCredentialEntry(
                context = applicationContext,
                username = password.username,
                pendingIntent = createNewPendingIntent(
                    GET_PASSWORD_INTENT
                ),
                beginGetPasswordOption = option,
                displayName = password.username,
                icon = password.icon
            )
        )
    }
    return passwordEntries
}

private fun createNewPendingIntent(
    action: String,
    extra: Bundle? = null
): PendingIntent {
    val intent = Intent(action).setPackage(PACKAGE_NAME)
    if (extra != null) {
        intent.putExtra("CREDENTIAL_DATA", extra)
    }

    return PendingIntent.getActivity(
        applicationContext, UNIQUE_REQUEST_CODE, intent,
        (PendingIntent.FLAG_MUTABLE or PendingIntent.FLAG_UPDATE_CURRENT)
    )
}
    MyCredentialProviderService.kt

  4. Po wysłaniu zapytania i wypełnieniu danych logowania musisz teraz obsłużyć fazę wyboru danych logowania wybranych przez użytkownika, niezależnie od tego, czy są to dane klucza dostępu czy hasło.

Obsługa wyboru użytkownika w przypadku kluczy dostępu

  1. W metodzie onCreate odpowiedniej aktywności pobierz powiązany zamiar i przekaż go do PendingIntentHandler.retrieveProviderGetCredentialRequest().
  2. Wyodrębnij z powyższego zapytania GetPublicKeyCredentialOption. Następnie wyodrębnij z tej opcji wartości requestJson i clientDataHash.
  3. Wyodrębnij credentialId z intent extra, który został wypełniony przez dostawcę danych logowania podczas konfigurowania odpowiedniego PendingIntent.
  4. Wyodrębnij klucz dostępu z bazy danych lokalnej, korzystając z parametrów żądania opisanych powyżej.

  5. Upewnij się, że klucz dostępu jest prawidłowy, na podstawie wyodrębnionych metadanych i weryfikacji użytkownika.

    val getRequest = PendingIntentHandler.retrieveProviderGetCredentialRequest(intent)
val publicKeyRequest = getRequest?.credentialOptions?.first() as GetPublicKeyCredentialOption

val requestInfo = intent.getBundleExtra("CREDENTIAL_DATA")
val credIdEnc = requestInfo?.getString("credId").orEmpty()

// Get the saved passkey from your database based on the credential ID from the PublicKeyRequest
val passkey = mDatabase.getPasskey(credIdEnc)

// Decode the credential ID, private key and user ID
val credId = b64Decode(credIdEnc)
val privateKey = b64Decode(passkey.credPrivateKey)
val uid = b64Decode(passkey.uid)

val origin = appInfoToOrigin(getRequest.callingAppInfo)
val packageName = getRequest.callingAppInfo.packageName

validatePasskey(
    publicKeyRequest.requestJson,
    origin,
    packageName,
    uid,
    passkey.username,
    credId,
    privateKey
)
    CredentialProviderDummyActivity.kt

  6. Aby zweryfikować użytkownika, wyświetl prompt biometryczny (lub inną metodę potwierdzenia). Fragment kodu poniżej używa interfejsu API dotyczącego danych biometrycznych na Androidzie.

  7. Po pomyślnym uwierzytelnieniu zbuduj odpowiedź JSON na podstawie specyfikacji W3 Web Authentication Assertion. W poniżej zamieszczonym fragmencie kodu użyto pomocniczych klas danych, takich jak AuthenticatorAssertionResponse, aby przyjmować parametry uporządkowane i konwertować je do wymaganego formatu JSON. Odpowiedź zawiera podpis cyfrowy z klucza prywatnego danych logowania WebAuthn. Serwer strony uwierzytelniającej może zweryfikować ten podpis, aby uwierzytelnić użytkownika przed zalogowaniem.

  8. Utwórz element PublicKeyCredential, używając wygenerowanego powyżej kodu JSON, i ustaw go na ostatecznym GetCredentialResponse. Ustaw tę ostateczną odpowiedź na podstawie wyniku tej aktywności.

Ten przykład pokazuje, jak można wdrożyć te kroki:

val request = PublicKeyCredentialRequestOptions(requestJson)
val privateKey: ECPrivateKey = convertPrivateKey(privateKeyBytes)

val biometricPrompt = BiometricPrompt(
    this,
    {  }, // Pass in your own executor
    object : BiometricPrompt.AuthenticationCallback() {
        override fun onAuthenticationError(
            errorCode: Int, errString: CharSequence
        ) {
            super.onAuthenticationError(errorCode, errString)
            finish()
        }

        override fun onAuthenticationFailed() {
            super.onAuthenticationFailed()
            finish()
        }

        override fun onAuthenticationSucceeded(
            result: BiometricPrompt.AuthenticationResult
        ) {
            super.onAuthenticationSucceeded(result)
            val response = AuthenticatorAssertionResponse(
                requestOptions = request,
                credentialId = credId,
                origin = origin,
                up = true,
                uv = true,
                be = true,
                bs = true,
                userHandle = uid,
                packageName = packageName
            )

            val sig = Signature.getInstance("SHA256withECDSA");
            sig.initSign(privateKey)
            sig.update(response.dataToSign())
            response.signature = sig.sign()

            val credential = FidoPublicKeyCredential(
                rawId = credId,
                response = response,
                authenticatorAttachment = "", // Add your authenticator attachment
            )
            val result = Intent()
            val passkeyCredential = PublicKeyCredential(credential.json())
            PendingIntentHandler.setGetCredentialResponse(
                result, GetCredentialResponse(passkeyCredential)
            )
            setResult(RESULT_OK, result)
            finish()
        }
    }
)

val promptInfo = BiometricPrompt.PromptInfo.Builder()
    .setTitle("Use your screen lock")
    .setSubtitle("Use passkey for ${request.rpId}")
    .setAllowedAuthenticators(
        BiometricManager.Authenticators.BIOMETRIC_STRONG
        /* or BiometricManager.Authenticators.DEVICE_CREDENTIAL */
    )
    .build()
biometricPrompt.authenticate(promptInfo)
CredentialProviderDummyActivity.kt

Obsługa wyboru użytkownika w przypadku uwierzytelniania za pomocą hasła

  1. W odpowiedniej czynności uzyskaj dostęp do intencji przekazanej do onCreate i wyodrębnij ProviderGetCredentialRequest za pomocą PendingIntentHandler.

  2. Użyj parametru GetPasswordOption w żądaniu, aby pobrać poświadczenia logowania zawierające hasło do nazwy przychodzącego pakietu.

    val getRequest = PendingIntentHandler.retrieveProviderGetCredentialRequest(intent)

val passwordOption = getRequest?.credentialOptions?.first() as GetPasswordOption

val username = passwordOption.allowedUserIds.first()
// Fetch the credentials for the calling app package name
val creds = mDatabase.getCredentials(callingAppInfo.packageName)
val passwords = creds.passwords
val it = passwords.iterator()
var password = ""
while (it.hasNext()) {
    val passwordItemCurrent = it.next()
    if (passwordItemCurrent.username == username) {
        password = passwordItemCurrent.password
        break
    }
}
    CredentialProviderDummyActivity.kt

  3. Po pobraniu ustaw odpowiedź dla wybranych danych logowania.

    // Set the response back
val result = Intent()
val passwordCredential = PasswordCredential(username, password)
PendingIntentHandler.setGetCredentialResponse(
    result, GetCredentialResponse(passwordCredential)
)
setResult(Activity.RESULT_OK, result)
finish()
    CredentialProviderDummyActivity.kt

Obsługa wyboru wpisu działania uwierzytelniania

Jak wspomniano wcześniej, dostawca danych logowania może ustawić parametr AuthenticationAction, jeśli dane są zablokowane. Jeśli użytkownik wybierze tę pozycję, zostanie wywołana aktywność odpowiadająca działaniu intencji określonemu w PendingIntent. Dostawcy danych logowania mogą wyświetlić proces uwierzytelniania biometrycznego lub podobny mechanizm, aby odblokować dane logowania. W przypadku powodzenia dostawca danych logowania musi utworzyć BeginGetCredentialResponse, podobnie jak w przypadku obsługi logowania użytkownika opisanej powyżej, ponieważ dane logowania są teraz odblokowane. Ta odpowiedź musi zostać ustawiona za pomocą metody PendingIntentHandler.setBeginGetCredentialResponse(), zanim przygotowany zamiar zostanie ustawiony jako wynik, a działanie zostanie zakończone.

Wyczyszczenie żądań dotyczących danych logowania

Aplikacja klienta może poprosić o wyczerpanie stanu przechowywanego w celu wyboru danych logowania. Na przykład dostawca danych logowania może zapamiętać wcześniej wybrane dane logowania i zwrócić je przy następnym użyciu. Aplikacja klienta wywołuje ten interfejs API i oczekuje, że ta trwała pozycja zostanie wyczyszczona. Usługa dostawcy danych uwierzytelniających może obsłużyć to żądanie, zastępując metodę onClearCredentialStateRequest():

override fun onClearCredentialStateRequest(
    request: ProviderClearCredentialStateRequest,
    cancellationSignal: CancellationSignal,
    callback: OutcomeReceiver<Void?, ClearCredentialException>
) {
    // Delete any maintained state as appropriate.
}
MyCredentialProviderService.kt

Aby umożliwić użytkownikom otwieranie ustawień dostawcy na ekranie Hasła, klucze dostępu i autouzupełnianie, aplikacje dostawców danych logowania powinny implementować atrybut credential-provider settingsActivity w pliku manifestu res/xml/provider.xml. Ten atrybut umożliwia użycie intencjonalnego wywołania do otwarcia ekranu ustawień aplikacji, jeśli użytkownik kliknie nazwę dostawcy na liście usług Hasła, klucze dostępu i automatyczne wypełnianie. Ustaw dla tego atrybutu nazwę aktywności, która ma być uruchamiana na ekranie ustawień.

<credential-provider
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:settingsSubtitle="Example settings provider name"
    android:settingsActivity="com.example.SettingsActivity">
    <capabilities>
        <capability name="android.credentials.TYPE_PUBLIC_KEY_CREDENTIAL" />
    </capabilities>
</credential-provider>
provider_settings.xml
Diagram pokazujący funkcje przycisku zmiany i otwierania
Rysunek 1. Przycisk Zmień otwiera okno wyboru, w którym użytkownik może wybrać preferowanego dostawcę danych logowania. Przycisk Otwórz uruchamia aktywność ustawień zdefiniowaną w zmianie pliku manifestu i otwiera stronę ustawień konkretnego dostawcy.

Zamiary dotyczące ustawień

Otwórz ustawienia: intencja android.settings.CREDENTIAL_PROVIDER powoduje wyświetlenie ekranu ustawień, na którym użytkownik może wybrać preferowanych i dodatkowych dostawców danych logowania.

Ekran ustawień Hasła, klucze dostępu i autouzupełnianie
Ilustracja 2. Ustawienia Hasła, klucze dostępu i autouzupełnianie

Usługa preferowanych danych logowania: instrukcja ACTION_REQUEST_SET_AUTOFILL_SERVICE przekierowuje użytkownika do ekranu wyboru preferowanego dostawcy. Wybrany na tym ekranie dostawca stanie się preferowanym dostawcą danych uwierzytelniających i autouzupełniania.

Diagram pokazujący funkcje przycisku zmiany i otwierania
Ilustracja 3. Ekran ustawień preferowanej usługi dla haseł, kluczy dostępu i autouzupełniania.

Uzyskiwanie listy dozwolonych aplikacji z podwyższonymi uprawnieniami

Aplikacje z uprawnieniami, takie jak przeglądarki internetowe, wykonują wywołania do Menedżera danych logowania w imieniu innych stron, ustawiając parametr origin w metodach GetCredentialRequest() i CreatePublicKeyCredentialRequest() Menedżera danych logowania. Aby przetworzyć te żądania, dostawca danych logowania pobiera dane origin za pomocą interfejsu API getOrigin().

Aby pobrać origin, aplikacja dostawcy danych logowania musi przekazać do interfejsu API androidx.credentials.provider.CallingAppInfo's getOrigin() listę uprzywilejowanych i zaufanych wywołujących. Ta lista dozwolonych musi być prawidłowym obiektem JSON. Wartość origin jest zwracana, jeśli packageName i odcisk cyfrowy certyfikatu uzyskany z signingInfo są zgodne z odciskiem cyfrowym aplikacji znalezionej w privilegedAllowlist przekazanej do interfejsu API getOrigin(). Po uzyskaniu wartości origin aplikacja dostawcy powinna uznać to za wywołanie z przywilejami i ustawić wartość origin w danych klienta w AuthenticatorResponse, zamiast obliczać wartość origin za pomocą podpisu wywołującej aplikacji.

Jeśli pobierasz origin, użyj wartości clientDataHash podanej bezpośrednio w CreatePublicKeyCredentialRequest() lub GetPublicKeyCredentialOption() zamiast składać i szyfrować clientDataJSON podczas żądania podpisu. Aby uniknąć problemów z analizowaniem pliku JSON, w odpowiedzi na potwierdzenie tożsamości i oświadczenie ustaw wartość zastępczą dla clientDataJSON. Menedżer haseł Google używa publicznie dostępnej listy dozwolonych dla wywołań do usługi getOrigin(). Jako dostawca danych logowania możesz użyć tej listy lub podać własną w formacie JSON opisanym przez interfejs API. Dostawca sam wybiera, której listy użyć. Aby uzyskać dostęp uprzywilejowany za pomocą dostawców danych logowania innych firm, zapoznaj się z dokumentacją dostarczoną przez danego dostawcę.

Włączanie dostawców na urządzeniu

Użytkownicy muszą włączyć dostawcę w sekcji Ustawienia urządzenia > Hasła i konta > Twój dostawca > Włącz lub wyłącz.

fun createSettingsPendingIntent(): PendingIntent