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

Menedżer danych logowania 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 oraz rozwiązania do logowania federacyjnego (np. Zaloguj się przez Google). Gdy wywoływany jest interfejs Credential Manager API, system Android agreguje dane logowania od wszystkich dostawców danych logowania 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 zaimplementujesz funkcję w usłudze dostawcy danych logowania, wykonaj czynności konfiguracyjne opisane w kolejnych sekcjach.

Deklarowanie zależności

W pliku build.gradle modułu zadeklaruj zależność, używając najnowszej wersji biblioteki Credential Manager:

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

Zadeklaruj element usługi w pliku manifestu

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

<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 do prawidłowego działania przepływu Menedżera danych logowania. Uprawnienie jest wymagane, aby można było z tą usługą powiązać tylko system Android. Filtr intencji służy do wykrywania tej usługi jako dostawcy danych logowania, z którego może korzystać 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 logowania obsługiwane przez Twoją usługę za pomocą stałych zdefiniowanych dla każdego typu danych logowania w bibliotece. W tym przykładzie usługa obsługuje zarówno tradycyjne hasła, jak i klucze dostępu. Stałe wartości dla tych elementów 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 logowania integrują się z interfejsami API, takimi jak autouzupełnianie haseł i innych danych. Ci dostawcy mogą używać tej samej infrastruktury wewnętrznej do przechowywania dotychczasowych typów danych logowania, a także rozszerzyć ją o obsługę innych typów, w tym kluczy dostępu.

Dwufazowe podejście do interakcji z dostawcą

Menedżer danych logowania wchodzi w interakcję z dostawcami danych logowania w 2 fazach:

  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 odpowiadać na nie Begin…, wypełniając je wpisami reprezentującymi opcje wizualne, które mają być wyświetlane w selektorze kont. Każdy wpis musi zawierać zestaw PendingIntent.
  2. Gdy użytkownik wybierze wpis, rozpocznie się faza wyboru i wywoła się PendingIntent powiązany z tym wpisem, co spowoduje wyświetlenie odpowiedniej aktywności dostawcy. Gdy użytkownik zakończy interakcję z tym działaniem, dostawca danych logowania musi ustawić odpowiedź na wynik działania przed jego zakończeniem. Odpowiedź jest następnie wysyłana do aplikacji klienckiej, która wywołała Menedżera danych logowania.

Obsługa tworzenia klucza dostępu

Obsługa zapytań o utworzenie klucza dostępu

Gdy aplikacja kliencka chce utworzyć klucz dostępu i zapisać go u dostawcy danych logowania, wywołuje interfejs createCredential API. Aby obsłużyć tę prośbę w usłudze dostawcy danych logowania w taki sposób, aby klucz dostępu był faktycznie przechowywany w pamięci, wykonaj czynności opisane w kolejnych sekcjach.

  1. Zastąp metodę onBeginCreateCredentialRequest() w usłudze rozszerzonej z CredentialProviderService.
  2. Obsłuż BeginCreateCredentialRequest, tworząc odpowiedni element BeginCreateCredentialResponse i przekazując go przez wywołanie zwrotne.
  3. Podczas tworzenia BeginCreateCredentialResponse dodaj wymagane CreateEntries. Każdy element CreateEntry powinien odpowiadać kontu, na którym można zapisać dane logowania, i musi mieć ustawiony element 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

Konstrukcja PendingIntent powinna być zgodna z tymi zasadami:

  • Odpowiednia aktywność powinna być skonfigurowana tak, aby wyświetlać wymagany monit biometryczny, potwierdzenie lub wybór.
  • Wszelkie wymagane dane, których dostawca potrzebuje, gdy wywoływana jest odpowiednia aktywność, powinny być ustawione jako dodatkowe w intencji używanej do tworzenia PendingIntent, np. accountId w procesie tworzenia.
  • Twój PendingIntent musi być skonstruowany z użyciem flagi PendingIntent.FLAG_MUTABLE, aby system mógł dołączyć ostateczne żądanie do dodatkowych informacji o intencji.
  • Tag PendingIntent nie może być tworzony za pomocą flagi PendingIntent.FLAG_ONE_SHOT, ponieważ użytkownik może wybrać wpis, cofnąć się i ponownie go wybrać, co spowoduje dwukrotne uruchomienie tagu PendingIntent.
  • Twój PendingIntent musi być utworzony z unikalnym kodem żądania, aby każdy wpis miał swój własny PendingIntent.

Obsługa wyboru wpisu w przypadku próśb o utworzenie klucza dostępu

  1. Gdy użytkownik wybierze wcześniej wypełniony element CreateEntry, wywoływany jest odpowiedni element PendingIntent i tworzony jest powiązany dostawca Activity.
  2. Po wywołaniu onCreate metody działania uzyskaj dostęp do powiązanego zamiaru i przekaż go do klasy PendingIntentHander, aby uzyskać ProviderCreateCredentialRequest.
  3. Wyodrębnij z żądania wartości requestJson, callingAppInfo i clientDataHash.
  4. Wyodrębnij lokalny accountId z dodatkowych informacji o intencji. Jest to implementacja specyficzna dla aplikacji przykładowej i nie jest wymagana. Ten identyfikator konta może służyć do przechowywania danych logowania na tym konkretnym koncie.
  5. Sprawdź requestJson. W przykładzie poniżej użyto lokalnych klas danych, takich jak PublicKeyCredentialCreationOptions, aby przekonwertować wejściowy plik JSON na klasę strukturalną zgodnie ze specyfikacją WebAuthn. Jako dostawca danych logowania możesz zastąpić ten kod własnym parserem.
  6. Sprawdź asset-link aplikacji do połączeń, jeśli połączenie pochodzi z natywnej aplikacji na Androida.
  7. wyświetlać monit uwierzytelniania, W przykładzie poniżej użyto interfejsu API Biometric w Androidzie.
  8. Gdy uwierzytelnianie się powiedzie, wygeneruj credentialId i parę kluczy.
  9. Zapisz klucz prywatny w lokalnej bazie danych w odniesieniu do callingAppInfo.packageName.
  10. Utwórz odpowiedź JSON interfejsu Web Authentication API, która składa się z klucza publicznego i credentialId. W poniższym przykładzie użyto lokalnych klas narzędziowych, takich jak AuthenticatorAttestationResponse i FidoPublicKeyCredential, które pomagają utworzyć plik JSON na podstawie wspomnianej wcześniej specyfikacji.Jako dostawca danych logowania możesz zastąpić te klasy własnymi konstruktorami.
  11. Utwórz CreatePublicKeyCredentialResponse z wygenerowanego powyżej kodu JSON.
  12. Ustaw CreatePublicKeyCredentialResponse jako dodatkowy element w Intent za pomocą PendingIntentHander.setCreateCredentialResponse() i ustaw ten zamiar jako wynik działania.
  13. Zakończ aktywność.

Poniższy przykład kodu ilustruje te kroki. Ten kod musi być obsługiwany w klasie Activity po wywołaniu funkcji 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ługiwać zapytania dotyczące próśb o utworzenie hasła, wykonaj te czynności:

  • W metodzie processCreateCredentialRequest() wspomnianej w poprzedniej sekcji dodaj kolejny przypadek w bloku switch, aby obsługiwać żądania dotyczące haseł.
  • Podczas tworzenia pliku BeginCreateCredentialResponse dodaj wymagane CreateEntries.
  • Każdy element CreateEntry powinien odpowiadać kontu, na którym można zapisać dane logowania, i musi mieć ustawiony element PendingIntent wraz z innymi metadanymi.

Poniższy przykład 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 wpisu w przypadku żądań utworzenia hasła

Gdy użytkownik wybierze wypełniony element CreateEntry, zostanie wykonany odpowiedni element PendingIntent i wyświetli się powiązane działanie. Uzyskaj dostęp do powiązanego zamiaru przekazanego w onCreate i przekaż go do klasy PendingIntentHander, aby uzyskać metodę ProviderCreateCredentialRequest.

Poniższy przykład 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

Obsługa logowania użytkowników

Logowanie użytkownika odbywa się w tych krokach:

  • Gdy aplikacja kliencka próbuje zalogować użytkownika, przygotowuje instancję GetCredentialRequest.
  • Platforma Android przekazuje to żądanie do wszystkich odpowiednich dostawców danych logowania, łącząc się z tymi usługami.
  • Usługa dostawcy otrzymuje wtedy BeginGetCredentialRequest, która zawiera listę BeginGetCredentialOption. Każda z nich zawiera parametry, których można użyć do pobrania pasujących danych logowania.

Aby obsłużyć tę prośbę w usłudze dostawcy danych logowania, wykonaj te czynności:

  1. Zastąp metodę onBeginGetCredentialRequest(), aby obsłużyć żądanie. Pamiętaj, że jeśli Twoje dane logowania są zablokowane, możesz natychmiast ustawić AuthenticationAction w odpowiedzi i wywołać wywołanie zwrotne.

    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 jakichkolwiek informacjicredentialEntries, muszą skonfigurować oczekujący zamiar, który przekierowuje użytkownika do procesu odblokowywania w 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ą funkcji CredentialEntries, aby były widoczne w selektorze. W przypadku kluczy dostępu możesz ustawić credentialId jako dodatkowy element intencji, aby wiedzieć, z którymi danymi logowania jest powiązany, 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. Wykonywanie zapytań o dane logowania z bazy danych, tworzenie wpisów klucza dostępu i hasła do wypełnienia.

    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ć etap wyboru danych logowania przez użytkownika, niezależnie od tego, czy jest to klucz dostępu czy hasło.

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

  1. W onCreate metody odpowiedniej aktywności pobierz powiązany zamiar i przekaż go do PendingIntentHandler.retrieveProviderGetCredentialRequest().
  2. Wyodrębnij z pobranej powyżej prośby wartość GetPublicKeyCredentialOption. Następnie wyodrębnij z tej opcji symbole requestJson i clientDataHash.
  3. Wyodrębnij credentialId z dodatkowych informacji o intencji, które zostały wypełnione przez dostawcę danych logowania podczas konfigurowania odpowiedniego PendingIntent.
  4. Wyodrębnij klucz dostępu z lokalnej bazy danych za pomocą parametrów żądania, do których dostęp uzyskano powyżej.

  5. Potwierdź, że klucz dostępu jest prawidłowy, korzystając z 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 potwierdzić tożsamość użytkownika, wyświetl prośbę o uwierzytelnianie biometryczne (lub inną metodę potwierdzenia). Poniższy fragment kodu korzysta z interfejsu Android Biometric API.

  7. Po pomyślnym uwierzytelnieniu utwórz odpowiedź JSON na podstawie specyfikacji W3C Web Authentication Assertion. W poniższym fragmencie kodu klasy danych pomocniczych, takie jak AuthenticatorAssertionResponse, są używane do przyjmowania uporządkowanych parametrów i przekształcania ich w wymagany format JSON. Odpowiedź zawiera podpis cyfrowy z klucza prywatnego danych logowania WebAuthn. Serwer strony ufającej może zweryfikować ten podpis, aby uwierzytelnić użytkownika przed zalogowaniem.

  8. Utwórz PublicKeyCredential, używając wygenerowanego powyżej kodu JSON, i ustaw go w końcowym GetCredentialResponse. Ustaw tę ostateczną odpowiedź na wynik tej aktywności.

Poniższy 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 aktywności uzyskaj dostęp do intencji przekazanej do onCreate i wyodrębnij ProviderGetCredentialRequest za pomocą PendingIntentHandler.

  2. Użyj w żądaniu parametru GetPasswordOption, aby pobrać dane logowania do hasła dla przychodzącej nazwy 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 wybranego hasła.

    // 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 wspomnieliśmy wcześniej, dostawca danych logowania może ustawić wartość AuthenticationAction, jeśli dane logowania są zablokowane. Jeśli użytkownik wybierze ten wpis, zostanie wywołana aktywność odpowiadająca działaniu intencji ustawionemu w PendingIntent. Dostawcy danych logowania mogą wtedy wyświetlić proces uwierzytelniania biometrycznego lub podobny mechanizm odblokowywania danych logowania. W przypadku powodzenia dostawca danych logowania musi utworzyć BeginGetCredentialResponse, podobny do opisanego powyżej sposobu obsługi logowania użytkownika, ponieważ dane logowania są teraz odblokowane. Następnie należy ustawić tę odpowiedź za pomocą metody PendingIntentHandler.setBeginGetCredentialResponse(), zanim przygotowany zamiar zostanie ustawiony jako wynik i aktywność zostanie zakończona.

Wyczyść prośby o dane logowania

Aplikacja kliencka może zażądać wyczyszczenia wszystkich stanów utrzymywanych na potrzeby wyboru dokumentu tożsamości. Na przykład dostawca dokumentu tożsamości może zapamiętać wcześniej wybrany dokument tożsamości i przy następnym wyborze zwrócić tylko ten dokument. Aplikacja kliencka wywołuje ten interfejs API i oczekuje, że trwały wybór zostanie wyczyszczony. 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 manifestu credential-provider settingsActivity w res/xml/provider.xml. Ten atrybut umożliwia użycie intencji do otwarcia ekranu ustawień aplikacji, gdy użytkownik kliknie nazwę dostawcy na liście usług Hasła, klucze dostępu i autouzupełnianie. Ustaw dla tego atrybutu nazwę aktywności, która ma być uruchamiana z ekranu 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 przedstawiający funkcje przycisków zmiany i otwierania
Ilustracja 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ń przeznaczoną specjalnie dla tego dostawcy.

Zamiary związane z ustawieniami

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

Ekran ustawień haseł, kluczy dostępu i autouzupełniania
Ilustracja 2. Ekran ustawień haseł, kluczy dostępu i autouzupełniania.

Preferowana usługa uwierzytelniania: intencja ACTION_REQUEST_SET_AUTOFILL_SERVICE przekierowuje użytkownika na ekran wyboru preferowanego dostawcy. Wybrany na tym ekranie dostawca stanie się preferowanym dostawcą danych logowania i autouzupełniania.

Diagram przedstawiający funkcje przycisków zmiany i otwierania
Ilustracja 3. Ekran ustawień Preferowana usługa dla haseł, kluczy dostępu i autouzupełniania.

Uzyskiwanie listy dozwolonych aplikacji z podwyższonymi uprawnieniami

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

Aby pobrać origin, aplikacja dostawcy danych logowania musi przekazać listę uprzywilejowanych i zaufanych wywołujących do interfejsu androidx.credentials.provider.CallingAppInfo's getOrigin() API. Ta lista dozwolonych musi być prawidłowym obiektem JSON. Wartość origin jest zwracana, jeśli wartości packageName i odciski cyfrowe certyfikatu uzyskane z signingInfo są zgodne z wartościami aplikacji znalezionej w privilegedAllowlist przekazanym do interfejsu API getOrigin(). Po uzyskaniu wartości origin aplikacja dostawcy powinna traktować to jako wywołanie uprzywilejowane i ustawić wartość origin w danych klienta w parametrze AuthenticatorResponse zamiast obliczać wartość origin na podstawie podpisu aplikacji wywołującej.

Jeśli pobierzesz origin, użyj clientDataHash, który jest podany bezpośrednio w CreatePublicKeyCredentialRequest() lub GetPublicKeyCredentialOption(), zamiast tworzyć i haszować clientDataJSON podczas żądania podpisu. Aby uniknąć problemów z analizowaniem formatu JSON, ustaw wartość zastępczą dla parametru clientDataJSON w odpowiedzi dotyczącej atestu i zapewnienia. Menedżer haseł Google używa publicznie dostępnej listy dozwolonych w przypadku wywołań getOrigin(). Jako dostawca danych logowania możesz użyć tej listy lub podać własną w formacie JSON opisanym w interfejsie API. To dostawca wybiera, która lista będzie używana. Aby uzyskać dostęp uprzywilejowany za pomocą dostawców danych logowania innych firm, zapoznaj się z dokumentacją dostarczoną przez tę firmę.

Włączanie dostawców na urządzeniu

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

fun createSettingsPendingIntent(): PendingIntent