Verificare i numeri di telefono con le credenziali digitali

Questa guida descrive in dettaglio come utilizzare l'API DigitalCredential per ottenere numeri di telefono verificati per i tuoi utenti. La procedura prevede due passaggi:

  1. Richiedi un TS.43 token: la tua app client (il "verificatore") richiede un token TS.43 temporaneo dal dispositivo dell'utente. TS.43 token è una credenziale emessa dall'operatore che rappresenta l'identità dell'utente.
  2. Scambia il token con un numero di telefono: il backend della tua app scambia il TS.43 token con un aggregatore o un operatore per ottenere il numero di telefono verificato dell'utente.

Prerequisiti

Per implementare la verifica del numero di telefono con l'API DigitalCredential, devi disporre di un account con un aggregatore. Un aggregatore interagisce con gli operatori e fornisce la superficie API necessaria per la tua app, di solito come endpoint API cloud fatturabile.

Devi anche aggiungere le seguenti dipendenze allo script di build Gradle:

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-alpha05")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-alpha05")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-alpha05"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-alpha05"
}

Implementazione

La procedura end-to-end in genere segue questi passaggi:

  1. Richiedi i parametri DCQL (Digital Credential Query Language) a un aggregatore: chiama uno o più aggregatori e richiedi un insieme di parametri DCQL. DCQL ti consente di specificare le credenziali digitali esatte che ti servono da ogni aggregatore.

  2. Crea la richiesta OpenID4VP: dal backend della tua app, crea la richiesta OpenID4VP, includendo i parametri DCQL dell'aggregatore. Quindi, invia la richiesta OpenID4VP alla tua app client.

  3. Chiama l'API Credential Manager: nella tua app client, utilizza l'API Credential Manager per inviare la richiesta OpenID4VP al sistema operativo. In risposta, ricevi un oggetto risposta OpenID4VP contenente TS.43 Digital Credential. Questa credenziale è criptata e può essere decriptata solo dall'aggregatore associato. Dopo aver ricevuto il token del corriere, invia la risposta dall'app client al backend dell'app.

  4. Convalida la risposta: nel backend della tua app, convalida la risposta OpenID4VP.

  5. Scambio con il numero di telefono: dal backend della tua app, invia TS.43 Digital Credential all'aggregatore. L'aggregatore convalida le credenziali e restituisce il numero di telefono verificato.

Immagine che mostra il flusso di una richiesta di verifica del numero di telefono
Figura 1. Il ciclo di vita di una richiesta di verifica del numero di telefono, a partire dal backend del verificatore che richiede i parametri a un aggregatore e termina con un numero di telefono verificato restituito.

Richiedere i parametri DCQL a un aggregatore

Dal backend della tua app, invia una richiesta all'aggregatore per un oggetto credenziale Digital Credential Query Language (DCQL). Assicurati di fornire un nonce e un ID richiesta nella tua richiesta. L'aggregatore restituisce l'oggetto delle credenziali DCQL, che ha una struttura simile alla seguente:

{
  // The credential ID is mapped to the request ID that is sent in your request to the aggregator.
  "id": "aggregator1",
  "format": "dc-authorization+sd-jwt",
  "meta": {
    "vct_values": [
      "number-verification/device-phone-number/ts43"
    ],
    "credential_authorization_jwt": "..."
  },
  "claims": [
    {
      "path": ["subscription_hint"],
      "values": [1]
    },
    {
      "path": ["phone_number_hint"],
      "values": ["+14155552671"]
    }
  ]
}

Crea la richiesta OpenID4VP

Innanzitutto, dal backend dell'app, crea un oggetto dcql_query inserendo l'oggetto delle credenziali DCQL in un array credentials nidificato all'interno di un oggetto dcql_query come mostrato nell'esempio seguente:

"dcql_query": {
  "credentials": [
      "id": "aggregator1",
      "format": "dc-authorization+sd-jwt",
      "meta": {
        "vct_values": [
          "number-verification/device-phone-number/ts43"
        ],
        "credential_authorization_jwt": "..."
      },
      "claims": [
        {
          "path": ["subscription_hint"],
          "values": [1]
        },
        {
          "path": ["phone_number_hint"],
          "values": ["+14155552671"]
        }
      ]
  ]
}

Quindi, crea una richiesta OpenID4VP con la seguente struttura:

{
  "protocol": "openid4vp-v1-unsigned",
  "data": {
    "response_type": "vp_token",
    "response_mode": "dc_api",
    "nonce": "...",
    "dcql_query": { ... }
  }
}
  • protocol: deve essere impostato su openid4vp-v1-unsigned per le richieste di verifica del numero di telefono.
  • response_type e response_mode: costanti che indicano il formato della richiesta con valori fissi vp_token e dc_api, rispettivamente.
  • nonce: un valore univoco generato dal backend per ogni richiesta. Il nonce nell'oggetto delle credenziali DCQL dell'aggregatore deve corrispondere a questo nonce.
  • dcql_query: in questo caso, utilizza dcql_query per specificare che viene richiesto un TS.43 Digital Credential. Puoi anche richiedere altre credenziali digitali qui.

Quindi, racchiudi la richiesta OpenID4VP in un oggetto richiesta API DigitalCredential e invialo all'app client.

{
  "requests":
    [
      {
        "protocol": "openid4vp-v1-unsigned",
        "data": {
          "response_type": "vp_token",
          "response_mode": "dc_api",
          "nonce": "...",
          "dcql_query": { ... }
        }
      }
    ]
}

Il seguente snippet mostra come generare la richiesta dell'API DigitalCredential:

def GenerateDCRequest():
    credentials = []
    aggregator1_dcql = call_aggregator_endpoint(nonce, "aggregator1", additional_params)
    credentials.append(aggregator1_dcql) # You can optionally work with multiple
    # aggregators, or request other types of credentials

    val dc_request =
    {
      "requests":
        [
          {
            "protocol": "openid4vp-v1-unsigned",
            "data": {
              "response_type": "vp_token",
              "response_mode": "dc_api",
              "nonce": "...",
              "dcql_query": {"credentials": credentials}
            }
          }
        ]
    }
    return dc_request

Chiama l'API Credential Manager

Nella tua app client, effettua una chiamata all'API Credential Manager con la richiesta API DigitalCredential fornita dal backend della tua app.

val requestJson = generateTs43DigitalCredentialRequestFromServer()
val digiCredOption = GetDigitalCredentialOption(requestJson = requestJson)
val getCredRequest = GetCredentialRequest(
    listOf(digiCredOption)
)

coroutineScope.launch {
  try {
    val response = credentialManager.getCredential(
      context = activityContext,
      request = getCredRequest
    )
    val credential = response.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}")
      }
    }
  } catch (e : GetCredentialException) {
      // If user cancels the operation, the feature isn't available, or the
      // SIM doesn't support the feature, a GetCredentialCancellationException
      // will be returned. Otherwise, a GetCredentialUnsupportedException will
      // be returned with details in the exception message.
      handleFailure(e)
  }
}

La risposta dell'API DigitalCredential contiene la risposta OpenID4VP. Un tipico file JSON delle credenziali del risultato DigitalCredential è il seguente:

{
  "protocol": "openid4vp-v1-unsigned",

  "data": {
    "vp_token": {
      "aggregator1": ["eyJhbGciOiAiRVMy..."] # The encrypted TS.43 Digital
                                             # Credential in an array structure.
    }
  }
}

Dalla tua app client, invia la risposta dell'API DigitalCredential al server di backend, dove può essere convalidata e utilizzata per lo scambio con l'aggregatore del numero di telefono verificato.

Convalida la risposta della credenziale digitale

Di seguito è riportato un esempio di come analizzare la risposta ed eseguire il passaggio di convalida nel backend dell'app:

def processDigitalCredentialsResponse(response):
  # Step 1: Parse out the TS.43 Digital Credential from the response
  openId4VpResponse = response['data']

  ts43_digital_credential = response['vp_token']["aggregator1"][0]

  # Step 2: Perform response validation
  verifyResponse(ts43_digital_credential)

def verifyResponse(ts43_digital_credential):
  # The returned ts43_digital_credential is an SD-JWT-based Verifiable Credentials
  # (SD-JWT VC) as defined in this IETF spec. The section 3.4 of the specification
  # outlines how to validate the credential. At a high level, the steps involves
  # validating (1) the nonce in the response credential matches the one in the
  # request, (2) the integrity of the credential by checking the credential is
  # signed by the trusted issuer Android Telephony, and (3) other validity
  # properties associated with this credential, such as issue time and expiration
  # time

  # In most cases, you can use an SD-JWT VC library to perform these validations.

  # Some aggregators may also perform the validation logic for you. Check with your
  # aggregator to decide the exact scope of the validation required.

Scambio con numero di telefono

Dal backend della tua app, invia TS.43 Digital Credential convalidato all'endpoint dell'aggregatore per convalidare la credenziale e ricevere il numero di telefono verificato.

def processDigitalCredentialsResponse(response):
  # ... prior steps

  # Step 3: Call aggregator endpoint to exchange the verified phone number
  callAggregatorPnvEndpoint(ts43_digital_credential)