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

Gestore delle credenziali fa riferimento a un insieme di API introdotte in Android 14 che supportano più metodi di accesso come nome utente-password, passkey e soluzioni di accesso (come Accedi con Google). Quando l'API Credential Manager viene richiamato, il sistema Android aggrega le credenziali di tutte le credenziali provider installati sul dispositivo. Questo documento descrive l'insieme di API che forniscono endpoint di integrazione per questi fornitori di credenziali.

Nota: questa guida è rivolta ai fornitori di credenziali, come le app di gestori delle password, per aggiungere il supporto dell'API Gestore delle credenziali sui dispositivi Android con Android 14 e versioni successive. Se vuoi integrare la tua app con Gestore delle credenziali per utilizzare le credenziali dei gestori delle password, come Gestore delle password di Google, leggi la guida su come far accedere l'utente con Gestore delle credenziali.

Configura

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

Dichiara le dipendenze

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

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

Dichiara l'elemento di servizio nel file manifest

Nel file manifest AndroidManifest.xml della tua app, includi un <service> per una classe di servizio che estende CredentialProviderService della raccolta androidx.credentials, come mostrato nell'esempio riportato di seguito.

<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 parte integrante della credenziale Il flusso del gestore deve funzionare come previsto. L'autorizzazione è necessaria per consentire l'associazione solo al sistema Android. Il filtro intent viene utilizzato per la rilevabilità di questo servizio come fornitore di credenziali da utilizzare da Gestione credenziali.

Nota: il servizio delle credenziali viene combinato con qualsiasi servizio di compilazione automatica definito nello stesso pacchetto, quindi se è già stata definita un'icona di compilazione automatica, il sistema la riutilizza per la visualizzazione nella pagina Impostazioni.

Dichiara i tipi di credenziali supportati

Nella directory res/xml, crea un nuovo file denominato provider.xml. In questo dichiara i tipi di credenziali supportati dal tuo servizio, mediante costanti definiti per ogni tipo di credenziale nella libreria. Nel seguente Ad esempio, il servizio supporta password tradizionali e passkey, costanti per le quali sono definite 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 integravano con API come la compilazione automatica per password e altri dati. Questi fornitori possono utilizzare la stessa infrastruttura interna per archiviare i tipi di credenziali esistenti, espandendola al contempo per supportarne altri, incluse le passkey.

Nota: per le passkey, le chiavi private devono essere criptate.

Approccio in due fasi all'interazione con i fornitori

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

1. La prima fase è la fase di inizio/query in cui il sistema si associa i servizi e le chiamate del provider di credenziali onBeginGetCredentialRequest(), onBeginCreateCredentialRequest() oppure Metodi onClearCredentialStateRequest() con Begin… richieste. I fornitori devono elaborare queste richieste e rispondere con risposte Begin…, completandole con voci che rappresentano le opzioni visive da mostrare nel selettore dell'account. Ogni voce deve avere un PendingIntent impostato.
2. Quando l'utente seleziona una voce, inizia la fase di selezione e PendingIntent associato alla voce viene attivato, visualizzando la all'attività del fornitore corrispondente. Una volta che l'utente ha finito di interagire attività, il fornitore di credenziali deve impostare la risposta in base al risultato 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 memorizzarla con un fornitore di credenziali, chiama l'API createCredential. Per gestire questo richiesta nel servizio del fornitore di credenziali, in modo che la passkey sia effettivamente archiviati nel tuo spazio di archiviazione, completa i passaggi mostrati nelle sezioni seguenti.

1. Sostituisci il metodo onBeginCreateCredentialRequest() nel servizio esteso da CredentialProviderService.
2. Gestisci BeginCreateCredentialRequest creando un BeginCreateCredentialResponse corrispondente e passandolo al callback.
3. Durante la costruzione di BeginCreateCredentialResponse, aggiungi il CreateEntries richiesto. Ogni CreateEntry deve corrispondere a un account in cui è possibile salvare la credenziale e deve avere un valore PendingIntent impostato insieme ad 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 tua costruzione di PendingIntent deve rispettare i seguenti requisiti:

• L'attività corrispondente deve essere impostata in modo da mostrare eventuali Prompt biometrico, conferma o selezione obbligatoria.
• Tutti i dati richiesti dal fornitore quando viene invocata l'attività corrispondente devono essere impostati come extra nell'intent utilizzato per creare il PendingIntent, ad esempio un accountId nel flusso di creazione.
• PendingIntent deve essere creato con il flag PendingIntent.FLAG_MUTABLE in modo che il sistema possa aggiungere la richiesta richiesta all'intent aggiuntivo.
• PendingIntent non deve essere costruito con il flag PendingIntent.FLAG_ONE_SHOT perché l'utente potrebbe selezionare una voce, tornare indietro e riselezionarla, il che causerebbe l'attivazione di PendingIntent due volte.
• Il PendingIntent deve essere creato con un codice 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

1. Quando l'utente seleziona un CreateEntry compilato in precedenza, viene richiamato il PendingIntent corrispondente e viene creato il fornitore associato Activity.
2. Dopo aver richiamato il metodo onCreate della tua attività, accedi a per intent associato e passarlo alla classe PendingIntentHander per ottenere ProviderCreateCredentialRequest.
3. Estrai requestJson, callingAppInfo e clientDataHash dalla richiesta.
4. Estrai il valore accountId locale dall'extra per l'intent. Questa è un'app di esempio un'implementazione specifica e non è obbligatorio. Questo ID account può essere utilizzato per memorizzare questa credenziale in base a questo ID account specifico.
5. Convalida requestJson. L'esempio seguente utilizza classi di dati locali comePublicKeyCredentialCreationOptions per convertire il JSON di input in una classe strutturata in base alle specifiche WebAuthn. In qualità di fornitore di credenziali, puoi sostituire questa classe con il tuo parser.
6. Controlla l'attributo asset-link per l'app chiamante se la chiamata proviene da un'app Android nativa.
7. Viene visualizzata una richiesta di autenticazione. L'esempio riportato di seguito utilizza il comando Android API Biometric.
8. Se l'autenticazione ha esito positivo, genera un credentialId e un coppia di chiavi.
9. Salva la chiave privata nel tuo database locale su callingAppInfo.packageName.
10. Costruisci una risposta JSON dell'API Web Authentication che sia composta dalla chiave pubblica e da credentialId. L'esempio riportato di seguito utilizza classi di utilità locali come AuthenticatorAttestationResponse e FidoPublicKeyCredential che aiutano a creare un JSON in base alle specifiche sopra citate. In qualità di fornitore di credenziali, puoi sostituire queste classi con i tuoi builder.
11. Crea un CreatePublicKeyCredentialResponse con il codice JSON generato in alto.
12. Imposta CreatePublicKeyCredentialResponse come extra per un Intent tramite PendingIntentHander.setCreateCredentialResponse() e imposta questo intento sul risultato dell'attività.
13. Completa l'attività.

Questi passaggi sono descritti nell'esempio di codice riportato di seguito. Questo codice deve essere gestito in la tua classe Attività una volta richiamato 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 condizione all'interno del blocco di switch per gestire le richieste di password.
• Durante la costruzione di BeginCreateCredentialResponse, aggiungi il CreateEntries richiesto.
• Ogni CreateEntry deve corrispondere a un account in cui è possibile ottenere la credenziale salvato e deve avere un PendingIntent impostato insieme agli 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)
}

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

Quando l'utente seleziona un CreateEntry compilato, viene eseguito il corrispondente PendingIntent e viene visualizzata l'attività associata. Accedi al l'intent associato trasmesso in onCreate e lo passa alla 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 degli utenti viene gestito con i seguenti passaggi:

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

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

1. Sostituisci il metodo onBeginGetCredentialRequest() per gestire la richiesta. Tieni presente che se le tue credenziali sono bloccate, puoi impostare immediatamente un AuthenticationAction sulla 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())
       }
   }
   

   Fornitori che richiedono lo sblocco delle credenziali prima della restituzione qualsiasi credentialEntries, deve configurare un intent in attesa che naviga 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 nel selettore. Per le passkey, puoi impostare credentialId come extra sull'intent in modo da sapere quale credenziale a 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 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 aver inserito le credenziali, ora devi gestire fase di selezione delle credenziali selezionate dall'utente, che è una passkey o una password.

Gestione della selezione dell'utente per le passkey

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

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

   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'altra asserzione ). Lo snippet di codice riportato di seguito utilizza l'API Android Biometric.

7. Una volta completata l'autenticazione, crea una risposta JSON basata sul modello W3 la specifica Web Authentication Assertion. Nello snippet di codice di seguito, vengono utilizzate le classi di dati helper come AuthenticatorAssertionResponse prendere i parametri strutturati e convertirli nel file JSON richiesto formato. La risposta contiene una firma digitale dal chiave privata di una credenziale WebAuthn. Il server della terza parte attendibile può verificare questa firma per autenticare un utente prima dell'accesso.

8. Crea una PublicKeyCredential utilizzando il codice JSON generato sopra e impostalo su un GetCredentialResponse finale. Imposta questa risposta finale su il risultato di questa attività.

Il seguente esempio 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 della password

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

2. 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.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 una voce di azione di autenticazione

Come menzionato in precedenza, un fornitore di credenziali può impostare AuthenticationAction se le credenziali sono bloccate. Se l'utente seleziona questa opzione , l'attività corrispondente all'azione intent impostata nella PendingIntent è richiamato. I fornitori di credenziali possono quindi mostrare un flusso di autenticazione biometrica o un meccanismo simile per sbloccare le credenziali. In caso di esito positivo, il fornitore di credenziali deve creare un BeginGetCredentialResponse, in modo simile a come è descritto sopra il trattamento dell'accesso utente, poiché le credenziali sono ora sbloccate. Questa risposta deve quindi essere impostata tramite Metodo PendingIntentHandler.setBeginGetCredentialResponse() prima l'intent preparato viene impostato come risultato e l'attività è terminata.

Cancella richieste di credenziali

Un'app client potrebbe richiedere che qualsiasi stato mantenuto per la selezione delle credenziali debba essere cancellato, ad esempio un fornitore di credenziali potrebbe ricordare la credenziale selezionata in precedenza e restituirla solo la volta successiva. Un'app client chiama questa API prevede che la selezione persistente venga cancellata. Il servizio del provider di credenziali può gestire questa richiesta sostituendo il metodo onClearCredentialStateRequest():

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

Aggiungi la funzionalità di collegamento alla pagina delle impostazioni del tuo provider

Per consentire agli utenti di aprire le impostazioni del provider dalla schermata Password, passkey e Riempimento automatico, le app del provider di credenziali devono implementare l'attributo manifest credential-provider settingsActivity 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 fornitore nell'elenco di 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>

Figura 1: il pulsante Cambia apre la finestra di dialogo di selezione esistente, consentendo all'utente di selezionare il fornitore di credenziali preferito. Il pulsante Apri avvia l'attività di impostazioni definita nella modifica del file manifest e apre una pagina di impostazioni specifica per quel fornitore.

Nota: imposta settingsActivity in credential-provider anche se questo ha impostato in autofill-service.

Intenzioni relative alle impostazioni

Apri le impostazioni: la android.settings.CREDENTIAL_PROVIDER per intent viene visualizzata una schermata di impostazioni in cui l'utente può selezionare di altri provider di credenziali.

Figura 2: la schermata delle impostazioni di password, passkey e compilazione automatica.

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

Figura 3: la schermata Servizio preferito per password, passkey e impostazioni di compilazione automatica.

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

Per recuperare il token origin, l'app del provider di credenziali deve passare all'API androidx.credentials.provider.CallingAppInfo's getOrigin() un elenco di chiamanti privilegiati e attendibili. Questa lista consentita deve essere un oggetto JSON valido. origin viene restituito se packageName e gli hash del certificato ottenuti da signingInfo corrispondono a quelli di un'app trovata in privilegedAllowlist passata all'API getOrigin(). Dopo il È stato ottenuto il valore origin. L'app del provider deve considerarlo un privilegio chiama e imposta origin sui dati del client in AuthenticatorResponse, invece di calcolare il origin usa la firma dell'app per le chiamate.

Se recuperi un origin, utilizza il 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 affermazione. Gestore delle password di Google usa una lista consentita apertamente disponibile per chiamate a getOrigin(). In qualità di fornitore di credenziali, puoi utilizzare questo elenco o fornire il tuo nel formato JSON descritto dall'API. Spetta al provider per selezionare l'elenco da usare. Per ottenere l'accesso privilegiato con fornitori di credenziali di terze parti, consulta la documentazione fornita dalla terza parte.

Abilitare i fornitori su un dispositivo

Gli utenti devono attivare il provider tramite impostazioni del dispositivo > Password e Account > Il tuo fornitore > Attiva o disattiva.

Nota: i diversi OEM potrebbero aver implementato queste impostazioni in modo diverso. Su Android 14 o versioni successive, chiama il createSettingsPendingIntent(). per restituire un intent in attesa quando viene richiamata, mostra una schermata che consente a un utente per attivare il tuo provider Gestore delle credenziali.

fun createSettingsPendingIntent(): PendingIntent