Credential Manager - API Holder

L'API Credential Manager - Holder consente alle app per Android di gestire e presentare credenziali digitali ai verificatori.

Inizia

Per utilizzare l'API Credential Manager - Holder, aggiungi le seguenti dipendenze allo script di build del modulo dell'app:

// In your app module's build.gradle:
dependencies {
    implementation(libs.androidx.registry.provider)
    implementation(libs.androidx.registry.provider.play.services)
}

// In libs.versions.toml:
registryDigitalCredentials = "1.0.0-alpha01"

androidx-registry-provider = { module = "androidx.credentials.registry:registry-provider", version.ref = "registryDigitalCredentials" }
androidx-registry-provider-play-services = { module = "androidx.credentials.registry:registry-provider-play-services", version.ref = "registryDigitalCredentials" }

Registrare le credenziali con Gestore delle credenziali

Un wallet deve registrare i metadati delle credenziali in modo che Credential Manager possa filtrarli e visualizzarli nel selettore delle credenziali quando viene ricevuta una richiesta.

Figura 1. L'interfaccia utente delle credenziali digitali.

UI del selettore del gestore delle credenziali

Il formato di questi metadati viene passato a un RegisterCredentialsRequest. Crea un [RegistryManager][1] e registra le credenziali:

In questo esempio, i metadati vengono compilati da un database di voci delle credenziali. Puoi trovare un riferimento nel nostro portafoglio di esempio che registra i metadati al caricamento dell'app. In futuro, la composizione del database delle credenziali sarà supportata dall'API Jetpack. A questo punto, puoi registrare i metadati delle credenziali come strutture di dati ben definite.

Il registro viene mantenuto anche dopo i riavvii del dispositivo. La nuova registrazione dello stesso registro dello stesso ID + tipo sovrascriverà il record di registrazione precedente. Pertanto, dovrai registrarti di nuovo solo quando i dati delle credenziali sono cambiati.

(Facoltativo) Crea un matcher

Credential Manager è indipendente dal protocollo. Tratta il registro dei metadati come un blob opaco e non ne verifica né controlla i contenuti. Pertanto, il wallet deve fornire un matcher, un binario eseguibile in grado di elaborare i propri dati e generare i metadati di visualizzazione in base a una richiesta in entrata. Credential Manager eseguirà il matcher in un ambiente sandbox senza accesso alla rete o al disco, in modo che nulla venga divulgato a un wallet prima che la UI venga visualizzata all'utente.

L'API Credential Manager fornirà matcher per i protocolli più diffusi, oggi OpenID4VP. Non è ancora stato rilasciato ufficialmente, quindi per ora utilizza il nostro matcher di esempio per il protocollo OpenID4VP.

Gestire una credenziale selezionata

A questo punto, il wallet deve gestire la selezione di una credenziale da parte dell'utente. Puoi definire un'attività che ascolti il filtro per intent androidx.credentials.registry.provider.action.GET_CREDENTIAL. Il nostro portafoglio di esempio mostra questa procedura.

L'intent che avvia l'attività conterrà la richiesta del verificatore e l'origine della chiamata, che può essere estratta con la funzione PendingIntentHandler.retrieveProviderGetCredentialRequest. L'API restituisce un ProviderGetCredentialRequest contenente tutte le informazioni associate alla richiesta di verifica specificata. Esistono tre componenti chiave:

• L'app che ha effettuato la richiesta. Puoi recuperarlo con getCallingAppInfo.
• La credenziale selezionata. Puoi ottenere informazioni sul candidato scelto dall'utente tramite il metodo di estensione selectedEntryId. In questo modo, l'ID credenziale registrato verrà abbinato.
• Eventuali richieste specifiche effettuate dal verificatore. Puoi ottenerlo dal metodo getCredentialOptions. In questo caso, dovresti trovare un GetDigitalCredentialOption in questo elenco, contenente la richiesta di credenziali digitali.

Nella maggior parte dei casi, il verificatore effettuerà una richiesta di presentazione delle credenziali digitali, in modo che tu possa elaborarla con il seguente esempio di codice:

request.credentialOptions.forEach { option ->
    if (option is GetDigitalCredentialOption) {
        Log.i(TAG, "Got DC request: ${option.requestJson}")
        processRequest(option.requestJson)
    }
}

Puoi vedere un esempio nel nostro portafoglio di esempio.

Eseguire il rendering della UI del wallet

Una volta selezionata la credenziale, viene richiamato il wallet e l'utente viene guidato attraverso la sua UI. Nell'esempio, si tratta di una richiesta biometrica.

Restituisce la risposta delle credenziali

Quando il portafoglio è pronto per restituire il risultato, puoi farlo completando l'attività con la risposta delle credenziali:

PendingIntentHandler.setGetCredentialResponse(
    resultData,
    GetCredentialResponse(DigitalCredential(response.responseJson))
)
setResult(RESULT_OK, resultData)
finish()

Se esiste un'eccezione, puoi inviare in modo analogo l'eccezione delle credenziali:

PendingIntentHandler.setGetCredentialException(
    resultData,
    GetCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

Consulta l'app di esempio per un esempio di come restituire la risposta delle credenziali nel contesto.