En ligne
Les pièces d'identité numériques peuvent être acceptées à la fois dans les flux d'application et dans les flux Web. Pour accepter les identifiants Google Wallet, vous devez:
- Intégrez l'API à l'aide de l'application ou du Web en suivant les instructions fournies.
- Remplissez ce formulaire pour demander à accepter les identifiants Google Wallet et accepter les conditions d'utilisation.
Prérequis
Pour tester la présentation des pièces d'identité, vous devez d'abord vous inscrire au programme bêta public à l'aide du compte de test prévu. Fournissez ensuite les informations suivantes à votre contact Google désigné.
- Lien vers les conditions d'utilisation
- Logo
- Site Web
- ID de package Play Store (pour les intégrations d'applications Android)
- ID Gmail utilisé pour rejoindre la version bêta publique
Formats d'identifiants compatibles
Plusieurs normes proposées définissent le format de données des documents d'identité numériques, dont deux gagnent en popularité dans le secteur:
- mdocs : définis par l'ISO.
- Identifiants vérifiables du W3C : définis par le W3C.
Bien que le Gestionnaire d'identifiants Android accepte les deux formats, Google Wallet n'est pour le moment compatible qu'avec les pièces d'identité numériques basées sur mdoc.
Expérience utilisateur
Lorsqu'une application demande des attributs d'identité, le processus suivant se produit:
Découverte des identifiants:l'application interroge les portefeuilles disponibles pour identifier les identifiants pouvant répondre à la requête. Android présente ensuite un sélecteur d'interface utilisateur du système, qui affiche les informations à partager. Cela permet à l'utilisateur de prendre une décision éclairée sur les identifiants à utiliser.
Sélection de l'utilisateur et interaction avec le portefeuille:l'utilisateur sélectionne des identifiants, et Android appelle l'application de portefeuille correspondante pour effectuer la transaction. L'application Wallet peut présenter son propre écran d'autorisation ou nécessiter une confirmation biométrique.
Résultat:Si l'utilisateur donne son consentement, les identifiants d'identité sélectionnés sont partagés avec l'application à l'origine de la demande. Si l'utilisateur refuse, une erreur est renvoyée.
Dans l'application
Pour demander des identifiants d'identité à vos applications Android, procédez comme suit:
Mettre à jour les dépendances
Dans le fichier build.gradle de votre projet, mettez à jour vos dépendances pour utiliser le Gestionnaire d'identifiants (bêta):
dependencies {
implementation("androidx.credentials:credentials:1.5.0-beta01")
// optional - needed for credentials support from play services, for devices running Android 13 and below.
implementation("androidx.credentials:credentials-play-services-auth:1.5.0-beta01")
}
Configurer le Gestionnaire d'identifiants
Pour configurer et initialiser un objet CredentialManager, ajoutez une logique semblable à celle-ci:
// Use your app or activity context to instantiate a client instance of CredentialManager.
val credentialManager = CredentialManager.create(context)
Attributs d'identité de la requête
Au lieu de spécifier des paramètres individuels pour les requêtes d'identité, l'application les fournit tous ensemble sous forme de chaîne JSON dans CredentialOption. Le Gestionnaire d'identifiants transmet cette chaîne JSON aux portefeuilles numériques disponibles sans examiner son contenu. Chaque portefeuille est ensuite responsable des éléments suivants : - Analyser la chaîne JSON pour comprendre la requête d'identité. - Déterminer les identifiants stockés, le cas échéant, qui répondent à la requête.
Le W3C devrait définir officiellement la structure de cette requête JSON dans le cadre de la spécification de l'API Web. Toutefois, il est important de se rappeler que la spécification est sous forme de projet et susceptible d'être modifiée.
Au départ, nous utiliserons le protocole Preview pour obtenir des pièces d'identité dans Google Wallet. Cela nous permet de commencer l'intégration et les tests pendant que la spécification de l'API Web est finalisée.
Voici un exemple de requestJson mdoc pour le protocole Preview:
{
identity: {
providers: [{
holder: {
selector: {
format: ['mdoc'],
type: 'org.iso.18013.5.1.mDL',
fields: [
'org.iso.18013.5.1.family_name',
'org.iso.18013.5.1.portrait',
]
},
params: {
nonce: '1234',
readerPublicKey: '<public_key>',
extraParamAsNeededByWallets: true,
},
},
}]
}
}
// The request in the JSON format to conform with
// the JSON-ified Digital Credentials API request definition.
val requestJson = generateRequestFromServer()
val digitalCredentialOption =
GetDigitalCredentialOption(requestJson = requestJson)
// Use the option from the previous step to build the `GetCredentialRequest`.
val getCredRequest = GetCredentialRequest(
listOf(digitalCredentialOption)
)
coroutineScope.launch {
try {
val result = credentialManager.getCredential(
context = activityContext,
request = getCredRequest
)
verifyResult(result)
} catch (e : GetCredentialException) {
handleFailure(e)
}
}
// Handle the successfully returned credential.
fun verifyResult(result: GetCredentialResponse) {
val credential = result.credential
when (credential) {
is DigitalCredential -> {
val responseJson = credential.credentialJson
validateResponseOnServer(responseJson)
}
else -> {
// Catch any unrecognized credential type here.
Log.e(TAG, "Unexpected type of credential ${credential.type}")
}
}
}
// Handle failure.
fun handleFailure(e: GetCredentialException) {
when (e) {
is GetCredentialCancellationException -> {
// The user intentionally canceled the operation and chose not
// to share the credential.
}
is GetCredentialInterruptedException -> {
// Retry-able error. Consider retrying the call.
}
is NoCredentialException -> {
// No credential was available.
}
is CreateCredentialUnknownException -> {
// An unknown, usually unexpected, error has occurred. Check the
// message error for any additional debugging information.
}
is CreateCredentialCustomException -> {
// You have encountered a custom error thrown by the wallet.
// If you made the API call with a request object that's a
// subclass of CreateCustomCredentialRequest using a 3rd-party SDK,
// then you should check for any custom exception type constants
// within that SDK to match with e.type. Otherwise, drop or log the
// exception.
}
else -> Log.w(TAG, "Unexpected exception type ${e::class.java}")
}
}
La réponse renvoie un identityToken (chaîne JSON), défini par le W3C. L'application Wallet est chargée de créer cette réponse.
Exemple :
{
"token": "<base64 encoded response>"
}
Envoyer le jeton et le traiter sur le serveur
Une fois le identityToken reçu, votre application doit le transmettre à votre serveur d'application pour validation. La première étape consiste à décoder le jeton au format base64. L'array d'octets obtenu représente les données CBOR, qui respectent la CDDL suivante.
CredentialDocument = {
"version": tstr, // Set to "ANDROID-HPKE-v1"
"pkEm": bstr, // Public key, in uncompressed form
"cipherText": bstr // The encrypted data
}
L'étape suivante consiste à calculer le SessionTranscript à partir de la norme ISO/CEI 18013-5:2021 avec une structure de transfert spécifique à Android:
SessionTranscript = [
null, // DeviceEngagementBytes not available
null, // EReaderKeyBytes not available
AndroidHandover // Defined below
]
AndroidHandover = [
"AndroidHandoverv1", // Version number
nonce, // nonce that comes from request
appId, // RP package name
pkRHash, // The SHA256 hash of the recipient public key
]
cipherText est chiffré à l'aide du chiffrement HPKE. Pour le déchiffrer, utilisez SessionTranscript comme données authentifiées supplémentaires, ainsi que la clé privée EC générée précédemment et les paramètres suivants:
- KEM: DHKEM(P-256, HKDF-SHA256)
- KDF: HKDF-SHA256
- AEAD: AES-128-GCM
Le texte clair obtenu correspond aux octets CBOR de DeviceResponse, comme défini dans la norme ISO/CEI 18013-5:2021. DeviceResponse doit être validé conformément à la clause 9 de la norme ISO/CEI 18013-5:2021. Cette procédure comprend plusieurs étapes, comme vérifier que le mdoc provient d'un émetteur de confiance et que la réponse est signée par l'appareil prévu. La classe DeviceResponseParser du projet d'identifiants d'identité de l'OpenWallet Foundation peut être utilisée pour une partie de ce processus de validation.
Web
Pour demander des identifiants d'identité à l'aide de l'API Digital Credentials sur Chrome, vous devez vous inscrire à la phase d'évaluation de l'API Digital Credentials.
En personne
Pour accepter les pièces d'identité issues de Google Wallet, suivez les étapes suivantes:
- Créer ou acquérir un lecteur pour accepter les pièces d'identité comme défini dans la norme ISO 18013-5
- Charger les certificats IACA dans le lecteur pour vous assurer que les pièces d'identité acceptées sont authentiques
- Tester votre solution
- Enregistrer votre application auprès de Google Wallet
Créer ou acquérir un lecteur pour accepter les pièces d'identité comme défini dans la norme ISO 18013-5
Les pièces d'identité dans Wallet sont implémentées conformément à la norme ISO 18013-5 pour les permis de conduire mobiles. Elles utilisent le NFC ou les codes QR ainsi que le BLE comme mécanisme de transfert de données. Ainsi, tout appareil capable d'implémenter ces aspects de la norme peut servir de lecteur, même une application mobile. Puisque la norme est ouverte, plusieurs implémentations tierces sont disponibles sur le marché. Vous pouvez également implémenter la fonctionnalité directement si nécessaire.
Pour obtenir des conseils sur l'implémentation de cette fonctionnalité, consultez l'application Android pour les lecteurs de référence Open Source, qui implémente la norme ISO et peut accepter des mDL issus de Google Wallet.
Pour commencer, compilez et exécutez l'application pour les lecteurs de référence:
- Clonez le dépôt des applications de référence.
- Ouvrez le projet dans Android Studio.
- Créez et exécutez la cible
appverifiersur votre appareil Android ou votre émulateur.
Charger les certificats IACA dans le lecteur pour vous assurer que les pièces d'identité acceptées sont authentiques
Pour valider des identifiants réels, vous devez disposer d'une pièce d'identité d'un émetteur accepté dans Wallet. Vous trouverez ci-dessous la liste des émetteurs acceptés par Google Wallet, ainsi que des liens vers leurs certificats pour validation.
Tester votre solution
Pour tester votre solution, compilez et exécutez notre application Android pour titulaire de référence Open Source. Pour compiler et exécuter l'application du titulaire de référence, procédez comme suit:
- Clonez le dépôt des applications de référence.
- Ouvrez le projet dans Android Studio.
- Créez et exécutez la cible
appholdersur votre appareil Android ou votre émulateur.
(Facultatif) Enregistrer votre application auprès de Google Wallet
Enregistrez votre application auprès de Google Wallet en remplissant ce formulaire.