Integra Gestore delle credenziali con la soluzione del tuo fornitore di credenziali

Gestore delle credenziali si riferisce a un insieme di API introdotte in Android 14 che supportano più metodi di accesso, come nome utente e password, passkey e soluzioni di accesso federato (ad esempio Accedi con Google). Quando viene richiamata l'API Credential Manager, il sistema Android aggrega le credenziali di tutti i provider di credenziali installati sul dispositivo. Questo documento descrive l'insieme di API che forniscono endpoint di integrazione per questi provider di credenziali.

Configurazione

Prima di implementare la funzionalità nel tuo provider di credenziali, completa i passaggi di configurazione illustrati nelle sezioni seguenti.

Dichiarazione di dipendenze

Aggiungi le seguenti dipendenze allo script di build del modulo dell'app per utilizzare la versione più recente della libreria Gestore delle credenziali:

Kotlin

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

Trendy

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

Dichiarazione dell'elemento service nel file manifest

Nel file manifest dell'app AndroidManifest.xml, includi una <service> dichiarazione per una classe di servizio che estende la CredentialProviderService classe dalla libreria androidx.credentials, come mostrato nell'esempio seguente.

<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>

L'autorizzazione e il filtro per intent mostrati nell'esempio precedente sono parte integrante del flusso di Gestore delle credenziali per funzionare come previsto. L'autorizzazione è necessaria per consentire l'associazione solo al sistema Android. Il filtro per intent viene utilizzato per la rilevabilità di questo servizio come provider di credenziali da utilizzare da Gestore delle credenziali.

Dichiarazione dei tipi di credenziali supportati

Nella directory res/xml, crea un nuovo file chiamato provider.xml. In questo file, dichiara i tipi di credenziali supportati dal tuo servizio tramite le costanti definite per ogni tipo di credenziale nella libreria. Nell'esempio seguente, il servizio supporta le password tradizionali e le passkey, le cui costanti sono definite come TYPE_PASSWORD_CREDENTIAL e 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>

Nei livelli API precedenti, i provider di credenziali si integrano con API come la compilazione automatica per password e altri dati. Questi provider possono utilizzare la stessa infrastruttura interna per archiviare i tipi di credenziali esistenti, espandendola per supportarne altri, incluse le passkey.

Approccio in due fasi all'interazione con il provider

Gestore delle credenziali interagisce con i provider di credenziali in due fasi:

La prima fase è la fase di inizio/query in cui il sistema esegue il binding ai servizi del provider di credenziali e richiama i onBeginGetCredentialRequest(), onBeginCreateCredentialRequest() o onClearCredentialStateRequest() metodi con le richieste Begin…. I provider devono elaborare queste richieste e rispondere con le risposte Begin…, inserendo le voci che rappresentano le opzioni visive da mostrare nel selettore dell'account. Ogni voce deve avere un PendingIntent impostato.
Una volta che l'utente seleziona una voce, inizia la fase di selezione e viene attivato il PendingIntent associato alla voce, che visualizza l'attività del provider corrispondente. Una volta che l'utente ha terminato l'interazione con questa attività, il provider di credenziali deve impostare la risposta sul risultato dell'attività prima di terminarla. Questa risposta viene quindi inviata all'app client che ha richiamato Gestore delle credenziali.

Gestire la creazione di passkey

Gestire le query per la creazione di passkey

Quando un'app client vuole creare una passkey e archiviarla con un provider di credenziali, chiama l'API createCredential. Per gestire questa richiesta nel servizio del provider di credenziali in modo che la passkey venga effettivamente archiviata nello spazio di archiviazione, completa i passaggi illustrati nelle sezioni seguenti.

Esegui l'override del metodo onBeginCreateCredentialRequest() nel servizio esteso da CredentialProviderService.
Gestisci BeginCreateCredentialRequest creando un corrispondente BeginCreateCredentialResponse e passandolo tramite il callback.
Durante la creazione di BeginCreateCredentialResponse, aggiungi i CreateEntries obbligatori. Ogni CreateEntry deve corrispondere a un account in cui è possibile salvare la credenziale e deve avere un PendingIntent impostato insieme ad altri metadati obbligatori.

L'esempio seguente illustra come implementare questi passaggi.

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
            )
    )
}

La creazione di PendingIntent deve rispettare le seguenti regole:

L'attività corrispondente deve essere configurata per mostrare qualsiasi richiesta biometrica, conferma o selezione richiesta.
Tutti i dati richiesti dal provider quando viene richiamata l'attività corrispondente devono essere impostati come extra nell'intent utilizzato per creare PendingIntent, ad esempio un accountId nel flusso di creazione.
Il tuo PendingIntent deve essere creato con il flag PendingIntent.FLAG_MUTABLE in modo che il sistema possa aggiungere la richiesta finale all'extra dell'intent.
Il tuo PendingIntent non deve essere creato con il flag PendingIntent.FLAG_ONE_SHOT perché l'utente potrebbe selezionare una voce, tornare indietro e selezionarla di nuovo, il che causerebbe l'attivazione di PendingIntent due volte.
PendingIntent deve essere creato con un codice di richiesta univoco in modo che ogni voce possa avere il proprio PendingIntent corrispondente.

Gestire la selezione delle voci per le richieste di creazione di passkey

Quando l'utente seleziona un CreateEntry compilato in precedenza, viene richiamato il PendingIntent corrispondente e viene creata l'Activity del provider associata.
Dopo aver richiamato il metodo onCreate dell'attività, accedi all' intent associato e passalo alla classe PendingIntentHander per ottenere il ProviderCreateCredentialRequest.
Estrai requestJson, callingAppInfo e clientDataHash dalla richiesta.
Estrai accountId locale dall'extra dell'intent. Si tratta di un'implementazione specifica dell'app di esempio e non è obbligatoria. Questo ID account può essere utilizzato per archiviare questa credenziale rispetto a questo ID account specifico.
Convalida requestJson. L'esempio seguente utilizza classi di dati locali come PublicKeyCredentialCreationOptions per convertire il JSON di input in una classe strutturata in base alla specifica WebAuthn. In qualità di provider di credenziali, puoi sostituire questo parser con il tuo.
Controlla l'asset link per l'app di chiamate se la chiamata proviene da un'app per Android nativa.
Mostra un prompt di autenticazione. L'esempio seguente utilizza l'API biometrica di Android Biometric.
Se l'autenticazione ha esito positivo, genera un credentialId e una coppia di chiavi.
Salva la chiave privata nel database locale rispetto a callingAppInfo.packageName.
Crea una risposta JSON dell'API Web Authentication che è composta dalla chiave pubblica e da credentialId. L'esempio seguente utilizza classi di utilità locali come AuthenticatorAttestationResponse e FidoPublicKeyCredential che aiutano a creare un JSON basato sulla specifica menzionata in precedenza.In qualità di provider di credenziali, puoi sostituire queste classi con i tuoi builder.
Crea un CreatePublicKeyCredentialResponse con il JSON generato sopra.
Imposta CreatePublicKeyCredentialResponse come extra su un Intent tramite PendingIntentHander.setCreateCredentialResponse() e imposta quell' intent sul risultato dell'attività.
Termina l'attività.

L'esempio di codice seguente illustra questi passaggi. Questo codice deve essere gestito nella classe Activity una volta richiamato 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)}"
}

Gestire le query per le richieste di creazione di password

Per gestire le query per le richieste di creazione di password:

All'interno del metodo processCreateCredentialRequest() menzionato nella sezione precedente, aggiungi un altro caso all'interno del blocco switch per la gestione delle richieste di password.
Durante la creazione di BeginCreateCredentialResponse, aggiungi i CreateEntries obbligatori.
Ogni CreateEntry deve corrispondere a un account in cui è possibile salvare la qualifica e deve avere un PendingIntent impostato insieme ad altri metadati.

L'esempio seguente illustra come implementare questi passaggi:

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)
}

Gestire la selezione delle voci per le richieste di creazione di password

Quando l'utente seleziona un CreateEntry compilato, viene eseguito il PendingIntent corrispondente e viene visualizzata l'attività associata. Accedi all'intent associato passato in onCreate e passalo alla classe PendingIntentHander per ottenere il metodo ProviderCreateCredentialRequest.

L'esempio seguente illustra come implementare questa procedura. Questo codice deve essere gestito nel metodo onCreate() dell'attività.

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()

L'accesso dell'utente viene gestito con i seguenti passaggi:

Quando un'app client tenta di consentire l'accesso a un utente, prepara un' GetCredentialRequest istanza.
Il framework Android propaga questa richiesta a tutti i provider di credenziali applicabili associandosi a questi servizi.
Il servizio del provider riceve quindi un BeginGetCredentialRequest che contiene un elenco di BeginGetCredentialOption, ognuno dei quali contiene parametri che possono essere utilizzati per recuperare le credenziali corrispondenti.

Per gestire questa richiesta nel servizio del provider di credenziali, completa i seguenti passaggi:

Esegui l'override del metodo onBeginGetCredentialRequest() per gestire la richiesta. Tieni presente che se le credenziali sono bloccate, puoi impostare immediatamente un AuthenticationAction nella risposta e richiamare il callback.

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())
    }
}

I provider che richiedono lo sblocco delle credenziali prima di restituire qualsiasi credentialEntries devono configurare un intent in attesa che indirizzi l'utente al flusso di sblocco dell'app:

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
            )
    )
}

Recupera le credenziali dal database locale e configurale utilizzando CredentialEntries per visualizzarle nel selettore. Per le passkey, puoi impostare credentialId come extra nell'intent in modo da sapere a quale credenziale si associa quando l'utente seleziona questa voce.

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)
}

Esegui query sulle credenziali dal database, crea voci di passkey e password da compilare.

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)
    )
}

Dopo aver eseguito query e compilato le credenziali, devi gestire la fase di selezione delle credenziali selezionate dall'utente, che si tratti di una passkey o di una password.

Gestire la selezione dell'utente per le passkey

Nel metodo onCreate dell'attività corrispondente, recupera l' intent associato e passalo a PendingIntentHandler.retrieveProviderGetCredentialRequest().
Estrai GetPublicKeyCredentialOption dalla richiesta recuperata sopra. Successivamente, estrai requestJson e clientDataHash da questa opzione.
Estrai credentialId dall'extra dell'intent, che è stato compilato dal provider di credenziali quando è stato configurato il PendingIntent corrispondente.
Estrai la passkey dal database locale utilizzando i parametri della richiesta a cui hai accesso sopra.

Verifica che la passkey sia valida con i metadati estratti e la verifica dell'utente.

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
)

Per convalidare l'utente, mostra una richiesta biometrica (o un altro metodo di asserzione). Lo snippet di codice riportato di seguito utilizza l'API biometrica di Android.
Una volta completata l'autenticazione, crea una risposta JSON basata sulla specifica W3 Web Authentication Assertion. Nello snippet di codice riportato di seguito, le classi di dati helper come AuthenticatorAssertionResponse vengono utilizzate per accettare parametri strutturati e convertirli nel formato JSON richiesto. La risposta contiene una firma digitale dalla chiave privata di una credenziale WebAuthn. Il server della relying party può verificare questa firma per autenticare un utente prima di consentire l'accesso.
Crea un PublicKeyCredential utilizzando il JSON generato sopra e impostalo su un GetCredentialResponse finale. Imposta questa risposta finale sul risultato di questa attività.

L'esempio seguente illustra come implementare questi passaggi:

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)

Gestire la selezione dell'utente per l'autenticazione con password

Nell'attività corrispondente, accedi all'intent passato a onCreate ed estrai ProviderGetCredentialRequest utilizzando PendingIntentHandler.

Utilizza GetPasswordOption nella richiesta per recuperare le credenziali della password per il nome del pacchetto in entrata.

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
    }
}

Una volta recuperata, imposta la risposta per la credenziale della password selezionata.

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

Gestire la selezione di una voce di azione di autenticazione

Come accennato in precedenza, un provider di credenziali può impostare un AuthenticationAction se le credenziali sono bloccate. Se l'utente seleziona questa voce, viene richiamata l'attività corrispondente all'azione dell'intent impostata in PendingIntent. I provider di credenziali possono quindi mostrare un flusso di autenticazione biometrica o un meccanismo simile per sbloccare le credenziali. Se l'operazione ha esito positivo, il provider di credenziali deve creare un BeginGetCredentialResponse, in modo simile a quanto descritto sopra per la gestione dell'accesso dell'utente, poiché le credenziali sono ora sbloccate. Questa risposta deve quindi essere impostata tramite il PendingIntentHandler.setBeginGetCredentialResponse() metodo prima che l' intent preparato venga impostato come risultato e l'attività venga completata.

Cancellare le richieste di credenziali

Un'app client può richiedere la cancellazione di qualsiasi stato mantenuto per la selezione delle credenziali, ad esempio un provider di credenziali può ricordare la credenziale selezionata in precedenza e restituirla solo la volta successiva. Un'app client chiama questa API e si aspetta che la selezione permanente venga cancellata. Il servizio del provider di credenziali può gestire questa richiesta eseguendo l'override del metodo onClearCredentialStateRequest():

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

Aggiungere la possibilità di creare un link alla pagina delle impostazioni del provider

Per consentire agli utenti di aprire le impostazioni del provider dalla schermata Password, passkey e compilazione automatica , le app del provider di credenziali devono implementare l'attributo manifest settingsActivity di credential-provider in res/xml/provider.xml. Questo attributo ti consente di utilizzare un intent per aprire la schermata delle impostazioni della tua app se un utente fa clic sul nome di un provider nell'elenco dei servizi Password, passkey e compilazione automatica. Imposta il valore di questo attributo sul nome dell'attività da avviare dalla schermata delle impostazioni.

<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>

Diagramma che mostra le funzioni dei pulsanti Modifica e Apri — **Figura 1:** il pulsante **Modifica** apre la finestra di dialogo di selezione esistente, consentendo all'utente di selezionare il provider di credenziali preferito. Il pulsante **Apri** avvia l'attività delle impostazioni definita nella modifica del manifest e apre una pagina delle impostazioni specifica per quel provider.

Intent delle impostazioni

Apri impostazioni: l'intent android.settings.CREDENTIAL_PROVIDER visualizza una schermata delle impostazioni in cui l'utente può selezionare i provider di credenziali preferiti e aggiuntivi.

La schermata delle impostazioni Password, passkey e compilazione automatica — **Figura 2:** la schermata delle impostazioni Password, passkey e compilazione automatica.

Servizio di credenziali preferito: l'intent ACTION_REQUEST_SET_AUTOFILL_SERVICE reindirizza l'utente alla schermata di selezione del provider preferito. Il provider selezionato in questa schermata diventa il provider di credenziali e compilazione automatica preferito.

Ottenere una lista consentita di app con privilegi

Le app con privilegi, come i browser web, effettuano chiamate a Gestore delle credenziali per conto di altre relying party impostando il parametro origin nei metodi GetCredentialRequest() e CreatePublicKeyCredentialRequest() di Gestore delle credenziali. Per elaborare queste richieste, il provider di credenziali recupera il origin utilizzando l'getOrigin() API.

Per recuperare origin, l'app del provider di credenziali deve passare un elenco di chiamanti con privilegi e attendibili all'API androidx.credentials.provider.CallingAppInfo's getOrigin(). Questa lista consentita deve essere un oggetto JSON valido. origin viene restituito se packageName e le impronte digitali del certificato ottenute da signingInfo corrispondono a quelle di un'app trovata in privilegedAllowlist passata all'API getOrigin(). Dopo aver ottenuto il valore origin, l'app per fornitori deve considerarla una chiamata con privilegi e impostare questo origin nei dati del client in AuthenticatorResponse, anziché calcolare origin utilizzando la firma dell'app chiamante.

Se recuperi un origin, utilizza clientDataHash fornito direttamente in CreatePublicKeyCredentialRequest() o GetPublicKeyCredentialOption() anziché assemblare e sottoporre ad hashing clientDataJSON durante la richiesta di firma. Per evitare problemi di analisi JSON, imposta un valore segnaposto per clientDataJSON nella risposta di attestazione e asserzione. Gestore delle password di Google utilizza una lista consentita disponibile pubblicamente per le chiamate a getOrigin(). In qualità di provider di credenziali, puoi utilizzare questo elenco o fornire il tuo in formato JSON descritto dall'API. La scelta dell'elenco da utilizzare spetta al provider. Per ottenere l'accesso con privilegi con provider di credenziali di terze parti, consulta la documentazione fornita dalla terza parte.

Attivare i provider su un dispositivo

Gli utenti devono attivare il provider tramite Impostazioni del dispositivo > Password e account > Il tuo provider > Attiva o disattiva.

fun createSettingsPendingIntent(): PendingIntent