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ą wielokrotne logowanie, takie 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 swoim dostawcy danych logowania, wykonaj czynności konfiguracyjne opisane w tych sekcjach.

Deklarowanie zależności

Aby używać najnowszej wersji biblioteki Menedżera danych logowania, dodaj te zależności do skryptu kompilacji modułu aplikacji:

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha01"
}

Deklarowanie elementu usługi w pliku manifestu

W pliku manifestu aplikacji AndroidManifest.xml, dodaj <service> deklarację dla klasy usługi, która rozszerza 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="@mipmap/ic_launcher"
    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>

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 potrzebne, aby tylko system Android mógł powiązać się z tą usługą. Filtr intencji służy do wykrywania tej usługi jako dostawcy danych logowania, który ma być używany przez Credential Manager.

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 tradycyjne hasła i 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>

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 istniejących typów danych logowania, rozszerzając 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 wiąże się z usługami dostawcy danych logowania i wywołuje onBeginGetCredentialRequest(), onBeginCreateCredentialRequest() lub onClearCredentialStateRequest() metody z żądaniami Begin…. Dostawcy muszą przetworzyć te żądania i odpowiedzieć za pomocą odpowiedzi Begin…, wypełniając je wpisami reprezentującymi opcje wizualne, które mają być wyświetlane w selektorze kont. Każdy wpis musi mieć ustawioną wartość PendingIntent.
  2. Gdy użytkownik wybierze wpis, rozpoczyna się faza wyboru, a powiązana z nim wartość PendingIntent zostaje uruchomiona, co powoduje wyświetlenie odpowiedniej aktywności dostawcy. Gdy użytkownik zakończy interakcję z tą aktywnością, dostawca danych logowania musi ustawić odpowiedź na wynik aktywności przed jej zakończeniem. Ta 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ć to żądanie w usłudze dostawcy danych logowania w taki sposób, aby klucz dostępu był faktycznie przechowywany w Twoim magazynie, wykonaj czynności opisane w tych sekcjach.

  1. Zastąp metodę onBeginCreateCredentialRequest() w usłudze rozszerzonej z CredentialProviderService.
  2. Obsłuż BeginCreateCredentialRequest, tworząc odpowiednią BeginCreateCredentialResponse i przekazując ją przez wywołanie zwrotne.
  3. Podczas tworzenia BeginCreateCredentialResponse dodaj wymagane CreateEntries. Każda CreateEntry powinna odpowiadać kontu, na którym można zapisać certyfikat, i musi mieć ustawioną wartość PendingIntent wraz z innymi wymaganymi metadanymi.

Ten przykład pokazuje, jak zaimplementować 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
            )
    )
}

Tworzenie PendingIntent powinno być zgodne z tymi zasadami:

  • Odpowiednia aktywność powinna być skonfigurowana tak, aby wyświetlać wymagany monit biometryczny, potwierdzenie lub wybór.
  • Wszystkie wymagane dane, których dostawca potrzebuje, gdy wywoływana jest odpowiednia aktywność, powinny być ustawione jako dodatkowe w intencji używanej do utworzenia PendingIntent, np. accountId w przepływie tworzenia.
  • Wartość PendingIntent musi być utworzona z flagą PendingIntent.FLAG_MUTABLE, aby system mógł dołączyć ostateczne żądanie do dodatkowych danych intencji.
  • Wartość PendingIntent nie może być utworzona z flagą PendingIntent.FLAG_ONE_SHOT ponieważ użytkownik może wybrać wpis, wrócić i ponownie go wybrać, co spowoduje dwukrotne uruchomienie PendingIntent.
  • Wartość PendingIntent musi być utworzona z unikalnym kodem żądania, aby każdy wpis mógł mieć własną odpowiednią wartość PendingIntent.

Obsługa wyboru wpisu na potrzeby żądań utworzenia klucza dostępu

  1. Gdy użytkownik wybierze wcześniej wypełnioną wartość CreateEntry, zostanie wywołana odpowiednia wartość PendingIntent i utworzona powiązana aktywność dostawcy Activity.
  2. Po wywołaniu metody onCreate aktywności uzyskaj dostęp do powiązanej intencji i przekaż ją do klasy PendingIntentHander, aby uzyskać ProviderCreateCredentialRequest.
  3. Wyodrębnij z żądania requestJson, callingAppInfo i clientDataHash.
  4. Wyodrębnij lokalny accountId z dodatkowych danych intencji. Jest to implementacja specyficzna dla przykładowej aplikacji i nie jest wymagana. Ten identyfikator konta może służyć do przechowywania tych danych logowania na tym konkretnym koncie.
  5. Sprawdź poprawność requestJson. W tym przykładzie używane są lokalne klasy danych, takie jak PublicKeyCredentialCreationOptions, aby przekonwertować wejściowe dane JSON na klasę strukturalną zgodnie ze specyfikacją WebAuthn. Jako dostawca danych logowania możesz zastąpić ją własnym parserem.
  6. Jeśli wywołanie pochodzi z natywnej aplikacji na Androida, sprawdź link do zasobu aplikacji wywołującej.
  7. Wyświetl monit uwierzytelniania. W tym przykładzie używany jest interfejs Android Biometric API.
  8. Gdy uwierzytelnianie się powiedzie, wygeneruj credentialId i kluczy parę.
  9. Zapisz klucz prywatny w lokalnej bazie danych w polu callingAppInfo.packageName.
  10. Utwórz odpowiedź JSON interfejsu Web Authentication API, która zawiera klucz publiczny i credentialId. Poniższy przykład używa lokalnych klas narzędziowych, takich jak AuthenticatorAttestationResponse i FidoPublicKeyCredential, które pomagają utworzyć kod 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 wygenerowanym powyżej kodem JSON.
  12. Ustaw CreatePublicKeyCredentialResponse jako dodatkowe dane w Intent za pomocą PendingIntentHander.setCreateCredentialResponse() i ustaw tę intencję jako wynik aktywności.
  13. Zakończ aktywność.

Ten przykład kodu 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)}"
}

Obsługa zapytań o utworzenie hasła

Aby obsługiwać zapytania o utworzenie hasła:

  • W metodzie processCreateCredentialRequest() wspomnianej w poprzedniej sekcji dodaj kolejny przypadek w bloku switch do obsługi żądań haseł.
  • Podczas tworzenia BeginCreateCredentialResponse dodaj wymagane CreateEntries.
  • Każda CreateEntry powinna odpowiadać kontu, na którym można zapisać dane logowania, i musi mieć ustawioną wartość PendingIntent wraz z innymi metadanymi.

Ten przykład pokazuje, jak zaimplementować 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)
}

Obsługa wyboru wpisu na potrzeby żądań utworzenia hasła

Gdy użytkownik wybierze wypełnioną wartość CreateEntry, zostanie wykonana odpowiednia wartość PendingIntent i wyświetli się powiązana aktywność. Uzyskaj dostęp do powiązanej intencji przekazanej w onCreate i przekaż ją do klasy PendingIntentHander, aby uzyskać metodę ProviderCreateCredentialRequest.

Ten przykład pokazuje, jak zaimplementować 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()

Obsługa logowania użytkownika

Logowanie użytkownika jest obsługiwane 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, wiążąc się z tymi usługami.
  • Usługa dostawcy otrzymuje wtedy BeginGetCredentialRequest, które 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ć to żądanie 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 od razu 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())
    }
}

    Dostawcy, którzy wymagają odblokowania danych logowania przed zwróceniem jakichkolwiek credentialEntries, muszą skonfigurować intencję oczekującą, która przekierowuje użytkownika do przepływu 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
            )
    )
}

  2. Pobierz dane logowania z lokalnej bazy danych i skonfiguruj je za pomocą CredentialEntries, aby były wyświetlane w selektorze. W przypadku kluczy dostępu możesz ustawić credentialId jako dodatkowe dane w 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)
}

  3. Wyślij zapytanie o dane logowania z bazy danych, utwórz klucz dostępu i wpisy haseł, 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)
    )
}

  4. Gdy zapytasz o dane logowania i je wypełnisz, musisz obsłużyć fazę wyboru danych logowania wybranych 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 metodzie onCreate odpowiedniej aktywności pobierz powiązaną intencję i przekaż ją do PendingIntentHandler.retrieveProviderGetCredentialRequest().
  2. Wyodrębnij GetPublicKeyCredentialOption z żądania pobranego powyżej. Następnie wyodrębnij z tej opcji requestJson i clientDataHash.
  3. Wyodrębnij credentialId z dodatkowych danych intencji, które zostały wypełnione przez dostawcę danych logowania podczas konfigurowania odpowiedniej wartości PendingIntent.
  4. Wyodrębnij klucz dostępu z lokalnej bazy danych za pomocą parametrów żądania, do których uzyskano dostęp powyżej.

  5. Sprawdź, czy klucz dostępu jest prawidłowy, używając 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
)

  6. Aby zweryfikować użytkownika, wyświetl monit biometryczny (lub inną metodę potwierdzenia). W tym fragmencie kodu używany jest interfejs Android Biometric API.

  7. Gdy uwierzytelnianie się powiedzie, utwórz odpowiedź JSON na podstawie specyfikacji W3 Web Authentication Assertion. W tym fragmencie kodu poniżej używane są pomocnicze klasy danych, takie jak AuthenticatorAssertionResponse, które przyjmują parametry strukturalne i przekształcają je 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 za pomocą wygenerowanego powyżej kodu JSON i ustaw go w końcowej GetCredentialResponse. Ustaw tę ostateczną odpowiedź jako wynik tej aktywności.

Ten przykład pokazuje, jak zaimplementować 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)

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 GetPasswordOption w żądaniu, aby pobrać dane logowania 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
    }
}

  3. Po pobraniu ustaw odpowiedź dla wybranych danych logowania 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()

Obsługa wyboru wpisu działania uwierzytelniania

Jak wspomnieliśmy wcześniej, dostawca danych logowania może ustawić 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ć przepływ uwierzytelniania biometrycznego lub podobny mechanizm odblokowywania danych logowania. Po pomyślnym zakończeniu 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() przed ustawieniem przygotowanej intencji jako wyniku i zakończeniem aktywności.

Żądania wyczyszczenia danych logowania

Aplikacja kliencka może zażądać wyczyszczenia dowolnego stanu utrzymywanego na potrzeby wyboru danych logowania. Na przykład dostawca danych logowania może zapamiętać wcześniej wybrane dane logowania i następnym razem zwrócić tylko te dane. Aplikacja kliencka wywołuje ten interfejs API i oczekuje, że trwały wybór zostanie wyczyszczony. Usługa dostawcy danych logowania 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.
}

Aby umożliwić użytkownikom otwieranie ustawień dostawcy na ekranie Hasła, klucze dostępu i autouzupełnianie, aplikacje dostawców danych logowania powinny zaimplementować atrybut manifestu credential-provider settingsActivity w res/xml/provider.xml. Ten atrybut umożliwia użycie intencji do otwarcia ekranu ustawień aplikacji, jeśli użytkownik kliknie nazwę dostawcy na liście usług Hasła, klucze dostępu i autouzupełnianie. Ustaw wartość tego atrybutu na nazwę aktywności, która ma zostać uruchomiona 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>
Diagram przedstawiający funkcje przycisków zmiany i otwierania
Rysunek 1: przycisk Zmień otwiera dotychczasowe okno wyboru, umożliwiając użytkownikowi wybranie preferowanego dostawcy danych logowania. Przycisk Otwórz uruchamia aktywność ustawień zdefiniowaną w zmianie manifestu i otwiera stronę ustawień konkretnego dostawcy.

Intencje ustawień

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
Rysunek 2: ekran ustawień haseł, kluczy dostępu i autouzupełniania.

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

Diagram przedstawiający funkcje przycisków zmiany i otwierania
Rysunek 3: ekran ustawień preferowanej usługi haseł, kluczy dostępu i autouzupełniania.

Uzyskiwanie listy dozwolonych aplikacji z uprawnieniami

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

Aby pobrać origin, aplikacja dostawcy danych logowania musi przekazać listę uprzywilejowanych i zaufanych elementów wywołujących do androidx.credentials.provider.CallingAppInfo's getOrigin() API. Ta lista dozwolonych musi być prawidłowym obiektem JSON. Wartość origin jest zwracana, jeśli packageName i odciski palców certyfikatu uzyskane z signingInfo pasują do tych w aplikacji znalezionej w privilegedAllowlist przekazanej do interfejsu getOrigin() API. Po uzyskaniu wartości origin aplikacja dla usługodawców powinna uznać to za wywołanie z podwyższonymi uprawnieniami i ustawić ten origin w danych klienta w AuthenticatorResponse zamiast obliczać origin za pomocą podpisu aplikacji wywołującej.

Jeśli pobierzesz origin, użyj clientDataHash podanego bezpośrednio w CreatePublicKeyCredentialRequest() lub GetPublicKeyCredentialOption() zamiast tworzyć i haszować clientDataJSON podczas żądania podpisu. Aby uniknąć problemów z analizowaniem kodu JSON, ustaw wartość zastępczą dla clientDataJSON w odpowiedzi na atest i potwierdzenie. Menedżer haseł Google używa publicznie dostępnej listy dozwolonych do 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 decyduje, której listy użyć. Aby uzyskać dostęp z podwyższonymi uprawnieniami u 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ę w sekcji Ustawienia urządzenia > Hasła i konta > Twój dostawca > Włącz lub wyłącz.

fun createSettingsPendingIntent(): PendingIntent