Accepting IDs from Google Wallet

Online

Digital IDs can be accepted both in-app and web flows. To accept credentials from Google Wallet you will need to:

Integrate using app or web following the provided instructions and
Fill out this form to request and agree to the terms of service of accepting credentials from Google Wallet.

Prerequisites

To test presentation of IDs, you must first enroll in the public beta program using the intended test account. Subsequently, furnish the ensuing details to your designated Google contact.

Terms of Service link
Logo
Website
Play Store package ID (for Android app integrations)
Gmail ID that was used to join the public beta

Supported Credential Formats

Several proposed standards exist that define the data format of digital identity documents, with two gaining significant industry traction:

mdocs - defined by ISO.
W3C Verifiable Credentials - defined by the W3C.

While the Android Credential Manager supports both the formats, Google Wallet supports only mdoc based Digital IDs at the moment.

User experience

When an application requests identity attributes, the following process occurs:

Credential Discovery: The application queries available wallets to identify credentials that can satisfy the request. Android then presents a system UI selector, displaying the information to be shared. This allows the user to make an informed decision about which credential to use.
User Selection and Wallet Interaction: The user selects a credential, and Android invokes the corresponding wallet app to complete the transaction. The wallet app may present its own consent screen or require biometric confirmation.

Outcome: If the user consents, the selected identity credentials are shared with the requesting application. If the user declines, an error is returned.

In App

To request identity credentials from your Android apps follow these steps:

Update dependencies

In your project's build.gradle, update your dependencies to use Credential Manager (beta):

dependencies {
    implementation("androidx.credentials:credentials:1.5.0-alpha05")
    // 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-alpha05")
}

Configure the Credential Manager

To configure and initialize a CredentialManager object, add logic similar to the following:

// Use your app or activity context to instantiate a client instance of CredentialManager.
val credentialManager = IdentityCredentialManager.Companion.getClient(context)

Request Identity attributes

// Retrieves the user's digital identites from wallet apps for your app.
val getIdentityCredentialOption = GetDigitalCredentialOption(
    requestJson = requestJson, // this is what partners needs to set, example JSON specified below
)
val result = credentialManager.getCredential(request = GetCredentialRequest(credentialOptions, ...)

The app caller provides all the IdentityRequest parameters as a JSON string. Here it is represented as requestMatcher param of CredentialOption. Credential Manager does not concern itself with the contents of that json. This json request will be passed directly to the wallets, which are then responsible for parsing it and deciding which credentials can fulfill the request. The full implementation can be found in the sample app.

We anticipate that the W3C will define this JSON request as a component of the web API. This standardization will enable browsers to directly transmit the request to Android.

To provide a flavor of what that request might look like, here is a sample of an mdoc request:

{
  "selector": {
    "format": [
      "mdoc"
    ],
    "doctype": "org.iso.18013.5.1.mDL",
    "fields": [
      {
        "namespace": "org.iso.18013.5.1",
        "name": "family_name",
        "intentToRetain": false
      },
      {
        "namespace": "org.iso.18013.5.1",
        "name": "given_name",
        "intentToRetain": false
      },
      {
        "namespace": "org.iso.18013.5.1",
        "name": "age_over_21",
        "intentToRetain": false
      }
    ]
  },
  "nonce": "3cydsUF9xNFyBDAAWOct09hEeSqrFX2WB2r0G6f8Ol0=",
  "readerPublicKey": "BApmGdElal2-1dtafsdHVRa1EpAWZfhlQj_iof2I8L3V8_dCK1gVR0_12E4ZSQ2LcqXRd4zxVeKEqU1wUSgGWUU="
}

The response returns an identityToken (json string), defined by the W3C. The Wallet app is responsible for crafting this response.

Example:

{
    "token": "<base64 encoded response>"
}

Send token and process on the server

Upon receiving the identityToken, your application should transmit it to your application server for verification. The initial step involves decoding the token from base64 format. The resulting byte array represents the CBOR data, which adheres to the following CDDL.

CredentialDocument = {
  "version": tstr,       // Set to "ANDROID-HPKE-v1"
  "pkEm": bstr,          // Public key, in uncompressed form
  "cipherText": bstr     // The encrypted data
}

The next step is to calculate the SessionTranscript from ISO/IEC 18013-5:2021 with an Android-specific Handover structure:

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
]

The cipherText is encrypted using HPKE encryption. To decrypt it, use SessionTranscript as the Additional Authenticated Data, along with the EC private key that was generated previously, and the following settings:

KEM: DHKEM(P-256, HKDF-SHA256)
KDF: HKDF-SHA256
AEAD: AES-128-GCM

The resulting cleartext is the DeviceResponse CBOR bytes as defined in ISO/IEC 18013-5:2021. DeviceResponse must be validated according to ISO/IEC 18013-5:2021 clause 9. This includes several steps, such as verifying that the mdoc originates from a trusted issuer and that the response is signed by the intended device. The DeviceResponseParser class from the OpenWallet Foundation Identity Credential project can be used for part of this validation process.

Web

To request Identity Credentials using the Digital Credentials API on Chrome, you'll need to sign up for the Digital Credentials API origin trial.

In Person

Accepting IDs from Google Wallet requires the following steps:

Build or acquire a reader to accept IDs as defined by ISO 18013-5
Load IACA certificates into the reader to ensure accepted IDs are authentic
Test your solution
Register your application with Google Wallet

Build or acquire a reader to accept IDs as defined by ISO 18013-5

IDs in Wallet are implemented according to the ISO 18013-5 standard for mobile drivers licenses. They use NFC-based or QR code engagement along with BLE as the data transfer mechanism - so any device which can implement those aspects of the standard can act as a reader, even a mobile application. As the standard is open there are several 3rd party implementations available on the market. As well, you can implement the functionality directly if needed.

For guidance on how to implement the functionality yourself, see our open source reference reader Android app, which implements the ISO standard and can accept mDLs from Google Wallet.

You can get started by building and running the reference reader app:

Clone the reference apps repository
Open the project on Android Studio
Build and run the appverifier target on your Android device or emulator.

Load IACA certificates into the reader to ensure accepted IDs are authentic

Validating a real credential requires you to have an ID in wallet from a supported issuer. A list of issuers that are supported by Google Wallet is provided below along with links to their certificates for verification.

Test your solution

To test your solution, build and run our open source reference holder Android application. Here are the steps to build and run the reference holder app:

Clone the reference apps repository
Open the project on Android Studio
Build and run the appholder target on your Android device or emulator.