Implementare la verifica email

Questa guida descrive come implementare il recupero dell'indirizzo email verificato utilizzando l'API Digital Credentials Verifier tramite una richiesta OpenID for Verifiable Presentations (OpenID4VP).

Aggiungi dipendenze

Nel file build.gradle dell'app, aggiungi le seguenti dipendenze per Gestore delle credenziali:

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha02")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha02")
}

Inizializza Gestore delle credenziali

Utilizza il contesto dell'app o dell'attività per creare un oggetto CredentialManager.

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

Crea la richiesta di credenziali digitali

Per richiedere un'email di verifica, crea un GetCredentialRequest contenente un GetDigitalCredentialOption. Questa opzione richiede una stringa requestJson formattata come richiesta OpenID for Verifiable Presentations (OpenID4VP).

Il JSON della richiesta OpenID4VP deve seguire una struttura specifica. Gli attuali provider supportano una struttura JSON con un wrapper esterno "digital": {"requests": […]}.

    val nonce = generateSecureRandomNonce()

    // This request follows the OpenID4VP spec
    val openId4vpRequest = """
{
  "requests": [
    {
      "protocol": "openid4vp-v1-unsigned",
      "data": {
        "response_type": "vp_token",
        "response_mode": "dc_api",
        "nonce": "$nonce",
        "dcql_query": {
          "credentials": [
            {
              "id": "user_info_query",
              "format": "dc+sd-jwt",
               "meta": {
                  "vct_values": ["UserInfoCredential"]
               },
              "claims": [
                {"path": ["email"]},
                {"path": ["name"]},  
                {"path": ["given_name"]},
                {"path": ["family_name"]},
                {"path": ["picture"]},
                {"path": ["hd"]},
                {"path": ["email_verified"]}
              ]
            }
          ]
        }
      }
    }
  ]
}
"""

    val getDigitalCredentialOption = GetDigitalCredentialOption(requestJson = openId4vpRequest)
    val request = GetCredentialRequest(listOf(getDigitalCredentialOption))

La richiesta contiene le seguenti informazioni chiave:

  • Query DCQL: dcql_query specifica il tipo di credenziale e le attestazioni richieste (email_verified). Puoi richiedere altre attestazioni per determinare il livello di verifica. Ecco alcune possibili rivendicazioni:
    • email_verified: nella risposta, si tratta di un valore booleano che indica se l'indirizzo email è verificato.
    • hd (dominio ospitato): nella risposta, questo campo è vuoto.
  • nonce: per ogni richiesta viene generato un valore casuale univoco e sicuro dal punto di vista crittografico. Questo è fondamentale per la sicurezza, in quanto impedisce gli attacchi di tipo replay.
  • UserInfoCredential: questo valore indica un tipo specifico di credenziale digitale che contiene gli attributi dell'utente. Includere questo elemento nella richiesta è fondamentale per distinguere il caso d'uso della verifica email.

Successivamente, inserisci il codice JSON openId4vpRequest in un GetDigitalCredentialOption, crea un GetCredentialRequest e chiama getCredential().

Presenta la richiesta all'utente

Presenta la richiesta all'utente utilizzando l'interfaccia utente integrata di Gestore delle credenziali.

try {
    // Requesting Digital Credential from user...
    val result = credentialManager.getCredential(activity, request)

    when (val credential = result.credential) {
        is DigitalCredential -> {
            val responseJsonString = credential.credentialJson

            // Successfully received digital credential response.

            // Next, parse this response and send it to your server.
            // ...
        }

        else -> {
            // handle Unexpected State() - Up to the developer
        }
    }
} catch (e: Exception) {
    // handle exceptions - Up to the developer
}

Analizza la risposta sul client

Dopo aver ricevuto la risposta, puoi eseguire un'analisi preliminare sul client. Questo è utile per aggiornare immediatamente la UI, ad esempio mostrando il nome dell'utente.

Il seguente codice estrae il JWT di divulgazione selettiva (SD-JWT) non elaborato e utilizza un helper per decodificare le relative rivendicazioni.

// 1. Parse the outer JSON wrapper to get the `vp_token`
val responseData = JSONObject(responseJsonString)
val vpToken = responseData.getJSONObject("vp_token")

// 2. Extract the raw SD-JWT string
val credentialId = vpToken.keys().next()
val rawSdJwt = vpToken.getJSONArray(credentialId).getString(0)

// 3. Use your parser to get the verified claims
// Server-side validation/parsing is highly recommended.

// Assumes a local parser like the one in our SdJwtParser.kt sample
val claims = SdJwtParser.parse(rawSdJwt)
Log.d("TAG", "Parsed Claims: ${claims.toString(2)}")

// 4. Create your VerifiedUserInfo object with REAL data
val userInfo = VerifiedUserInfo(
    email = claims.getString("email"),
    displayName = claims.optString("name", claims.getString("email"))
)

Gestisci la risposta

L'API Credential Manager restituirà una risposta DigitalCredential.

Di seguito è riportato un esempio dell'aspetto del responseJsonString non elaborato e delle rivendicazioni dopo l'analisi dell'SD-JWT interno, dove ottieni anche metadati aggiuntivi insieme all'indirizzo email verificato:

/*
// Example of the raw JSON response from credential.credentialJson:
{
  "vp_token": {
    // This key matches the 'id' you set in your dcql_query
    "user_info_query": [
      // The SD-JWT string (Issuer JWT ~ Disclosures ~ Key Binding JWT)
      "eyJhbGciOiJ...~WyI...IiwgImVtYWlsIiwgInVzZXJAZXhhbXBsZS5jb20iXQ~...~eyJhbGciOiJ..."
    ]
  }
}

// Example of the parsed and verified claims from the SD-JWT on your server:
{
  "cnf": {
    "jwk": {..}
  },
  "exp": 1775688222,
  "iat": 1775083422,
  "iss": "https://verifiablecredentials-pa.googleapis.com",
  "vct": "UserInfoCredential",
  "email": "jane.doe.246745@gmail.com",
  "email_verified": true,
  "given_name": "Jane",
  "family_name": "Doe",
  "name": "Jane Doe",
  "picture": "http://example.com/janedoe/me.jpg",
  "hd": ""
}
 */

Convalida lato server per la creazione dell'account

Poiché l'indirizzo email recuperato viene verificato in modo crittografico, puoi omettere il passaggio di verifica dell'OTP via email, riducendo in modo significativo l'attrito della registrazione e aumentando potenzialmente le conversioni. Questa procedura viene gestita al meglio sul tuo server. Il client invia la risposta non elaborata (contenente vp_token) e il nonce originale a un nuovo endpoint del server.

Per la verifica, l'applicazione deve inviare l'intero responseJsonString al tuo server per la convalida crittografica prima di creare un account o di far accedere l'utente.

La credenziale digitale fornisce due livelli di verifica fondamentali per il tuo server:

  • Autenticità dei dati: la verifica dell'URL dell'emittente (iss) e della firma SD-JWT dimostra che un'autorità attendibile ha emesso questi dati.
  • Identità del presentatore: la verifica del campo cnf e della firma Key Binding (kb) conferma che la credenziale viene condivisa dallo stesso dispositivo a cui è stata originariamente emessa, impedendo che venga intercettata o utilizzata su un altro dispositivo.

La convalida sul server deve ottenere quanto segue:

  • Verifica l'emittente: assicurati che il campo iss (emittente) corrisponda a https://verifiablecredentials-pa.googleapis.com.
  • Verifica la firma: controlla la firma dell'SD-JWT utilizzando le chiavi pubbliche (JWK) disponibili all'indirizzo https://verifiablecredentials-pa.googleapis.com/.well-known/vc-public-jwks.

Per una sicurezza completa, assicurati di convalidare anche il nonce per evitare attacchi di tipo replay.

Combinando questi passaggi, il tuo server può convalidare sia l'autenticità dei dati sia l'identità del presentatore, assicurando che la credenziale non sia stata intercettata o falsificata prima del provisioning del nuovo account.

try {
    // Send the raw credential response and the original nonce to your server.
    // Your server must validate the response. createAccountWithVerifiedCredentials
    // is a custom implementation per each RP for server side verification and account creation.
    val serverResponse = createAccountWithVerifiedCredentials(responseJsonString, nonce)

    // Server returns the new account info (e.g., email, name)
    val claims = JSONObject(serverResponse.json)

    val userInfo = VerifiedUserInfo(
        email = claims.getString("email"),
        displayName = claims.optString("name", claims.getString("email"))
    )

    // handle response - Up to the developer
} catch (e: Exception) {
    // handle exceptions - Up to the developer
}

Creazione di passkey

Un passaggio facoltativo, ma vivamente consigliato, dopo il provisioning di un account è creare immediatamente una passkey per l'account. In questo modo, l'utente può accedere in modo sicuro e senza password. Questo flusso è identico a una registrazione standard della passkey.

Supporto di WebView

Affinché il flusso funzioni su un WebView, gli sviluppatori devono implementare un bridge JavaScript (bridge JS) per facilitare l'handoff. Questo bridge consente all'oggetto WebView di inviare un segnale all'app nativa, che può quindi eseguire la chiamata effettiva all'API Credential Manager.

Vedi anche