Aceptando IDs de la Billetera de Google

En línea

Los IDs digitales se pueden aceptar en los flujos en la aplicación y web. Para aceptar credenciales de la Billetera de Google, deberás hacer lo siguiente:

  1. Realiza la integración a través de la app o la Web siguiendo las instrucciones proporcionadas.
  2. Completa este formulario para solicitar y aceptar las condiciones del servicio de aceptación de credenciales de la Billetera de Google.

Requisitos previos

Para probar la presentación de los IDs, primero debes inscribirte en el programa de versión beta pública con la cuenta de prueba prevista. Luego, proporciona los siguientes detalles a tu contacto de Google designado.

  • Vínculo a las Condiciones del Servicio
  • Logotipo
  • Sitio web
  • ID de paquete de Play Store (para integraciones de apps para Android)
  • El ID de Gmail que se usó para unirse a la versión beta pública

Formatos de credenciales compatibles

Existen varios estándares propuestos que definen el formato de datos de los documentos de identidad digitales, y dos de ellos están ganando una gran aceptación en la industria:

  1. mdocs: Se define según la norma ISO.
  2. Credenciales verificables del W3C: Definidas por el W3C.

Si bien el Administrador de credenciales de Android admite ambos formatos, por el momento, la Billetera de Google solo admite IDs digitales basados en mdoc.

Experiencia del usuario

Cuando una aplicación solicita atributos de identidad, se produce el siguiente proceso:

  1. Descubrimiento de credenciales: La aplicación consulta las billeteras disponibles para identificar las credenciales que pueden satisfacer la solicitud. Luego, Android presenta un selector de IU del sistema que muestra la información que se compartirá. Esto permite que el usuario tome una decisión fundamentada sobre cuál credencial usar.

  2. Selección del usuario y la interacción con la billetera: El usuario selecciona una credencial y Android invoca la app de la billetera correspondiente para completar la transacción. Es posible que la app de la billetera presente su propia pantalla de consentimiento o requiera una confirmación biométrica.

Resultado: Si el usuario da su consentimiento, las credenciales de identidad seleccionadas se comparten con la aplicación solicitante. Si el usuario rechaza la solicitud, se muestra un error.

En la app

Para solicitar credenciales de identidad desde tus apps para Android, sigue estos pasos:

Actualiza las dependencias

En el archivo build.gradle de tu proyecto, actualiza las dependencias para usar el Administrador de credenciales (beta):

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

Cómo configurar el Administrador de credenciales

Para configurar e inicializar un objeto CredentialManager, agrega una lógica similar a la siguiente:

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

Solicita atributos de identidad

En lugar de especificar parámetros individuales para las solicitudes de identidad, la app los proporciona todos juntos como una cadena JSON dentro de CredentialOption. El Administrador de credenciales pasa esta cadena JSON a las billeteras digitales disponibles sin examinar su contenido. Cada billetera es responsable de lo siguiente: - Analizar la cadena JSON para comprender la solicitud de identidad. - Determinar cuáles de sus credenciales almacenadas, si las hay, satisfacen la solicitud

Se espera que el W3C defina formalmente la estructura de esta solicitud JSON como parte de la especificación de la API web. Sin embargo, es importante recordar que la especificación está en forma de borrador y está sujeta a cambios.

Inicialmente, usaremos el protocolo de vista previa para obtener IDs de la Billetera de Google. Esto nos permite comenzar la integración y las pruebas mientras se finaliza la especificación de la API web.

Este es un ejemplo de un requestJson de mdoc para el protocolo de vista previa:

{
  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 respuesta muestra un identityToken (cadena JSON) definido por el W3C. La app de Wallet es responsable de crear esta respuesta.

Ejemplo:

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

Envía el token y procésalo en el servidor

Cuando recibas el identityToken, tu aplicación debería transmitirlo a tu servidor de aplicaciones para su verificación. El paso inicial consiste en decodificar el token del formato base64. El array de bytes resultante representa los datos CBOR, que se adhieren al siguiente CDDL.

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

El siguiente paso es calcular el SessionTranscript de la norma ISO/IEC 18013-5:2021 con una estructura de transferencia específica de 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
]

El cipherText se encripta con la encriptación HPKE. Para desencriptarla, usa SessionTranscript como los datos autenticados adicionales, junto con la clave privada de EC que se generó anteriormente y la siguiente configuración:

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

El texto simple resultante son los bytes CBOR de DeviceResponse, como se define en la norma ISO/IEC 18013-5:2021. DeviceResponse se debe validar de acuerdo con el artículo 9 de la norma ISO/IEC 18013-5:2021. Esto incluye varios pasos, como verificar que el mdoc provenga de un emisor de confianza y que la respuesta esté firmada por el dispositivo previsto. La clase DeviceResponseParser del proyecto de credenciales de identidad de OpenWallet Foundation se puede usar para parte de este proceso de validación.

Web

Para solicitar credenciales de identidad con la API de credenciales digitales en Chrome, deberás registrarte en la prueba de origen de la API de credenciales digitales.

Presencial

Para aceptar IDs de la Billetera de Google, debes seguir estos pasos:

  • Compila o adquiere un lector para aceptar los IDs según se define en la norma ISO 18013-5.
  • Carga los certificados de la IACA en el lector para asegurarte de que los IDs aceptados sean auténticos.
  • Prueba tu solución
  • Registra tu aplicación en la Billetera de Google

Compila o adquiere un lector para aceptar los IDs según se define en la norma ISO 18013-5.

Los IDs de la Billetera se implementan de acuerdo con el estándar ISO 18013-5 para licencias de conducir en dispositivos móviles. Usan la interacción basada en NFC o códigos QR junto con BLE como mecanismo de transferencia de datos, por lo que cualquier dispositivo que pueda implementar esos aspectos del estándar puede actuar como lector, incluso una aplicación para dispositivos móviles. Como el estándar es abierto, hay varias implementaciones de terceros disponibles en el mercado. Además, puedes implementar la funcionalidad directamente si es necesario.

Si deseas obtener orientación para implementar la funcionalidad por tu cuenta, consulta nuestra app de lector de referencia de código abierto para Android, que implementa el estándar ISO y puede aceptar licencias de conducir digitales de la Billetera de Google.

Para comenzar, compila y ejecuta la app de lector de referencias:

  • Clona el repositorio de apps de referencia
  • Abre el proyecto en Android Studio.
  • Compila y ejecuta el destino appverifier en tu dispositivo Android o emulador.

Carga los certificados de la IACA en el lector para asegurarte de que los IDs aceptados sean auténticos.

Para validar una credencial real, debes tener un ID en la billetera de un emisor compatible. A continuación, se proporciona una lista de las entidades emisoras compatibles con la Billetera de Google, junto con vínculos a sus certificados para su verificación.

Prueba tu solución

Para probar tu solución, compila y ejecuta nuestra aplicación para Android de referencia de código abierto. Estos son los pasos para compilar y ejecutar la app del contenedor de referencia:

  • Clona el repositorio de apps de referencia
  • Abre el proyecto en Android Studio.
  • Compila y ejecuta el destino appholder en tu dispositivo Android o emulador.

(Opcional) Registra tu aplicación en la Billetera de Google

Completa este formulario para registrar tu aplicación en la Billetera de Google.