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

Con Gestore delle credenziali si intende un insieme di API introdotte in Android 14 che supportano più metodi di accesso come nome utente-password, passkey e soluzioni di accesso federato (come 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.

Configura

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

Dichiara le dipendenze

Nel file build.gradle del modulo, dichiara una dipendenza utilizzando la versione più recente della libreria di Gestore delle credenziali:

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

Dichiara l'elemento del servizio nel file manifest

Nel file manifest AndroidManifest.xml della tua app, includi una dichiarazione <service> per una classe di servizio che estende la classe CredentialProviderService 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="<any drawable icon>"
         android:permission="android.permission.BIND_CREDENTIAL_PROVIDER_SERVICE">
    <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 sopra sono essenziali affinché il flusso di Gestore delle credenziali funzioni come previsto. L'autorizzazione è necessaria affinché solo il sistema Android possa associarsi a questo servizio. Il filtro per intent viene utilizzato per scoprire questo servizio come provider di credenziali da utilizzare da Gestore delle credenziali.

Dichiara i tipi di credenziali supportati

Nella directory res/xml, crea un nuovo file denominato 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, costanti per le quali sono definite come TYPE_PASSWORD_CREDENTIAL e TYPE_PUBLIC_KEY_CREDENTIAL:

<?xml version="1.0" encoding="utf-8"?>
<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 fornitori 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, estendendola al supporto di altri, incluse le passkey.

Approccio in due fasi all'interazione con il fornitore

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

  1. La prima fase è la fase di avvio/query, in cui il sistema si vincola ai servizi del provider di credenziali e richiama i metodi onBeginGetCredentialRequest(), onBeginCreateCredentialRequest() o onClearCredentialStateRequest() con richieste Begin…. I provider devono elaborare queste richieste e rispondere con risposte Begin…, compilandole con voci che rappresentano le opzioni visive da mostrare sul selettore di account. Per ogni voce deve essere impostato un valore PendingIntent.
  2. Una volta che l'utente seleziona una voce, inizia la fase di selezione e la PendingIntent associata alla voce viene attivata, mostrando l'attività del provider corrispondente. Una volta che l'utente ha finito di interagire 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 della passkey

Gestisci le query per la creazione di passkey

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

  1. Esegui l'override del metodo onBeginCreateCredentialRequest() nel tuo servizio esteso da CredentialProviderService.
  2. Gestisci la BeginCreateCredentialRequest costruendo una BeginCreateCredentialResponse corrispondente e trasmettendola tramite il callback.
  3. Durante la creazione della BeginCreateCredentialResponse, aggiungi il CreateEntries obbligatorio. Ogni elemento CreateEntry deve corrispondere a un account in cui è possibile salvare la credenziale e deve avere un PendingIntent impostato insieme agli altri metadati richiesti.

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 struttura della tua PendingIntent deve rispettare quanto segue:

  • L'attività corrispondente deve essere configurata in modo da mostrare qualsiasi prompt biometrico, conferma o selezione richiesti.
  • Tutti i dati richiesti di cui il provider ha bisogno 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.
  • PendingIntent deve essere creata con il flag PendingIntent.FLAG_MUTABLE in modo che il sistema possa aggiungere la richiesta finale all'intent extra.
  • PendingIntent non deve essere creato con il flag PendingIntent.FLAG_ONE_SHOT perché l'utente può selezionare una voce, tornare indietro e riselezionarla, 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 valore PendingIntent corrispondente.

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

  1. Quando l'utente seleziona un CreateEntry compilato in precedenza, viene richiamato il PendingIntent corrispondente e viene creato il provider associato Activity.
  2. Una volta richiamato il metodo onCreate dell'attività, accedi all'intent associato e passalo alla classe PendingIntentHander per ottenere ProviderCreateCredentialRequest.
  3. Estrai requestJson, callingAppInfo e clientDataHash dalla richiesta.
  4. Estrai accountId locale dall'intent extra. Questa è un'implementazione di esempio specifica dell'app e non è obbligatoria. Questo ID account può essere utilizzato per archiviare la credenziale in questo specifico ID account.
  5. Convalida il requestJson. L'esempio seguente utilizza classi di dati locali come PublicKeyCredentialCreationOptions per convertire il codice JSON di input in una classe strutturata secondo la specifica WebAuthn. In qualità di provider di credenziali, puoi sostituirlo con il tuo parser.
  6. Controlla il link asset per l'app di chiamata se la chiamata proviene da un'app Android nativa.
  7. Mostra un prompt di autenticazione. L'esempio seguente utilizza l'API Biometric di Android.
  8. Se l'autenticazione ha esito positivo, genera un credentialId e una coppia di chiavi.
  9. Salva la chiave privata nel tuo database locale su callingAppInfo.packageName.
  10. Crea una risposta JSON dell'API Web Authentication composta dalla chiave pubblica e dalla credentialId. L'esempio riportato di seguito utilizza classi di utilità locali come AuthenticatorAttestationResponse e FidoPublicKeyCredential, che consentono di creare un JSON in base alle specifiche menzionate in precedenza.In qualità di fornitore di credenziali, puoi sostituire queste classi con i tuoi builder.
  11. Crea un oggetto CreatePublicKeyCredentialResponse con il JSON generato in precedenza.
  12. Imposta CreatePublicKeyCredentialResponse come extra su Intent tramite PendingIntentHander.setCreateCredentialResponse() e imposta questo intento come risultato dell'attività.
  13. Termina l'attività.

Il codice di esempio riportato di seguito illustra questi passaggi. Questo codice deve essere gestito nella classe Attività dopo la chiamata a onCreate().

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

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

  val biometricPrompt = BiometricPrompt(
    this,
    <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)

        // 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
        )
        val result = Intent()

        val createPublicKeyCredResponse =
          CreatePublicKeyCredentialResponse(credential.json())

        // Set the CreateCredentialResponse as the result of the Activity
        PendingIntentHandler.setCreateCredentialResponse(
          result, createPublicKeyCredResponse
        )
        setResult(Activity.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)
}

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'altra richiesta all'interno del blocco switch per gestire le richieste di password.
  • Durante la creazione di BeginCreateCredentialResponse, aggiungi il valore CreateEntries richiesto.
  • Ogni CreateEntry deve corrispondere a un account in cui è possibile salvare la credenziale 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
}

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

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

Quando l'utente seleziona un valore CreateEntry completato, viene eseguito e visualizzato l'attività associata PendingIntent corrispondente. Accedi all'intent associato trasmesso 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)

val request: CreatePasswordRequest = createRequest.callingRequest as CreatePasswordRequest

// Fetch the ID and password from the request and save it in your database
<your_database>.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)
this@<activity>.finish()

Gestire l'accesso degli utenti

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

  • Quando un'app client tenta di accedere a un utente, prepara un'istanza di GetCredentialRequest.
  • Il framework Android propaga questa richiesta a tutti i provider di credenziali applicabili associandoli a questi servizi.
  • Il servizio provider riceve quindi un BeginGetCredentialRequest che contiene un elenco di BeginGetCredentialOption, ognuno dei quali contiene parametri utilizzabili per recuperare le credenziali corrispondenti.

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

  1. Esegui l'override del metodo onBeginGetCredentialRequest() per gestire la richiesta. Tieni presente che se le tue 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 di sbloccare le credenziali prima di restituire qualsiasi credentialEntries devono configurare un intent in attesa che rimandi 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
        )
    )
}

  2. Recupera le credenziali dal tuo database locale e configurale utilizzando CredentialEntries da mostrare sul selettore. Per le passkey, puoi impostare credentialId come ulteriore nell'intent in modo da sapere a quale credenziale viene mappata 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 processGetCredentialsRequest(
request: BeginGetCredentialRequest
): BeginGetCredentialResponse {
    val callingPackage = request.callingAppInfo?.packageName
    val credentialEntries: MutableList<CredentialEntry> = mutableListOf()

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

  3. Esegui una query sulle credenziali dal tuo 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
              ),
              beginPublicKeyCredentialOption = 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. Dopo aver eseguito la query e completato le credenziali, ora devi gestire la fase di selezione delle credenziali selezionate dall'utente, che si tratti di una passkey o di una password.

Gestire la selezione degli utenti per le passkey

  1. Nel metodo onCreate dell'attività corrispondente, recupera l'intent associato e passa a PendingIntentHandler.retrieveProviderGetCredentialRequest().
  2. Estrai GetPublicKeyCredentialOption dalla richiesta recuperata in precedenza. Successivamente, estrai requestJson e clientDataHash da questa opzione.
  3. Estrai credentialId dall'intent aggiuntivo, che è stato compilato dal provider di credenziali al momento della configurazione del PendingIntent corrispondente.
  4. Estrai la passkey dal tuo database locale utilizzando i parametri della richiesta a cui hai eseguito l'accesso in precedenza.

  5. Dichiara che la passkey è valida con i metadati estratti e la verifica utente.

    val getRequest =
    PendingIntentHandler.retrieveProviderGetCredentialRequest(intent)
val publicKeyRequest =
getRequest.credentialOption as GetPublicKeyCredentialOption

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

// Get the saved passkey from your database based on the credential ID
// from the publickeyRequest
val passkey = <your database>.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. Per convalidare l'utente, visualizza un prompt biometrico (o un altro metodo di asserzione). Lo snippet di codice riportato di seguito utilizza l'API Android Biometric.

  7. Una volta completata l'autenticazione, crea una risposta JSON basata sulla specifica asserzione dell'autenticazione web W3. Nello snippet di codice riportato di seguito, vengono utilizzate classi di dati helper come AuthenticatorAssertionResponse per acquisire parametri strutturati e convertirli nel formato JSON richiesto. La risposta contiene una firma digitale della chiave privata di una credenziale WebAuthn. Il server del richiedente può verificare questa firma per autenticare un utente prima di accedere.

  8. Crea una PublicKeyCredential utilizzando il JSON generato in precedenza e impostalo su una 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,
    <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
        )
        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)

Gestione della selezione degli utenti per l'autenticazione tramite password

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

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

    val getRequest =
PendingIntentHandler.retrieveProviderGetCredentialRequest(intent)

val passwordOption = getRequest.credentialOption as GetPasswordCredentialOption

val username = passwordOption.username
// Fetch the credentials for the calling app package name
val creds = <your_database>.getCredentials(callingAppInfo.packageName)
val passwords = creds.passwords
val it = passwords.iterator()
var password = ""
while (it.hasNext() == true) {
    val passwordItemCurrent = it.next()
    if (passwordItemCurrent.username == username) {
       password = passwordItemCurrent.password
       break
    }
}

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

Gestisci la selezione di un'azione di autenticazione

Come menzionato in precedenza, un fornitore di credenziali può impostare un AuthenticationAction se le credenziali sono bloccate. Se l'utente seleziona questa voce, viene richiamata l'attività corrispondente all'azione per 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 riesce, il provider di credenziali deve creare un BeginGetCredentialResponse, in modo simile a come viene descritta la gestione dell'accesso degli utenti in precedenza, poiché le credenziali ora sono sbloccate. Questa risposta deve quindi essere impostata tramite il metodo PendingIntentHandler.setBeginGetCredentialResponse() prima che l'intent preparato venga impostato come risultato e l'attività sia terminata.

Cancella richieste di credenziali

Un'app client può richiedere che qualsiasi stato mantenuto per la selezione delle credenziali venga cancellato, ad esempio un fornitore di credenziali potrebbe ricordare le credenziali selezionate in precedenza e restituirle solo la volta successiva. Un'app client chiama questa API e prevede che la selezione fissa venga cancellata. Il tuo servizio del provider di credenziali può gestire questa richiesta eseguendo l'override del metodo onClearCredentialStateRequest():

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

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 parti dell'utente impostando il parametro origin nei metodi Gestore delle credenziali GetCredentialRequest() e CreatePublicKeyCredentialRequest(). Per elaborare queste richieste, il provider di credenziali recupera origin utilizzando l'API getOrigin().

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. Il valore origin viene restituito se packageName e le fingerprint del certificato ottenute da signingInfo corrispondono a quelle di un'app rilevata in privilegedAllowlist passata all'API getOrigin(). Una volta ottenuto il valore origin, l'app del provider deve considerare questa chiamata come una chiamata con privilegi e impostare questo origin sui dati del client nella AuthenticatorResponse, invece di calcolare il origin utilizzando la firma dell'app chiamante.

Se recuperi un origin, usa l'elemento 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 aperta per le chiamate a getOrigin(). In qualità di provider di credenziali, puoi utilizzare questo elenco o fornirne uno nel formato JSON descritto dall'API. Spetta al provider scegliere quale elenco utilizzare. Per ottenere l'accesso privilegiato con provider di credenziali di terze parti, consulta la documentazione fornita dalla terza parte.

Abilitare i provider su un dispositivo

Gli utenti devono abilitare il provider tramite impostazioni del dispositivo > Password e account > Il tuo provider > Attiva o Disattiva.

Su Android 14 o versioni successive, chiama l'API createSettingsPendingIntent() per restituire un intent in attesa quando viene richiamato e viene visualizzata una schermata che consente a un utente di attivare il tuo provider di Gestore delle credenziali.

fun createSettingsPendingIntent(): PendingIntent