Digitalen Berechtigungsnachweis anfordern

Die Überprüfung digitaler Ausweise in Android-Apps kann verwendet werden, um die Identität eines Nutzers (z. B. einen amtlichen Ausweis), Eigenschaften dieses Nutzers (z. B. einen Führerschein, einen akademischen Grad oder Attribute wie Alter oder Adresse) oder andere Szenarien zu authentifizieren und zu autorisieren, in denen ein Ausweis ausgestellt und überprüft werden muss, um die Authentizität einer Entität zu bestätigen.

Die Verifier API wird ab Android 9 (API-Level 28) unterstützt.

Implementierung

So prüfen Sie digitale Ausweise in Ihrem Android-Projekt:

  1. Fügen Sie dem Build-Script Ihrer App Abhängigkeiten hinzu und initialisieren Sie eine CredentialManager-Klasse.
  2. Erstellen Sie eine Anfrage für digitale Anmeldedaten und verwenden Sie sie, um ein DigitalCredentialOption zu initialisieren. Erstellen Sie dann das GetCredentialRequest.
  3. Starten Sie den getCredential-Ablauf mit der erstellten Anfrage, um eine erfolgreiche GetCredentialResponse zu erhalten, oder behandeln Sie alle Ausnahmen, die auftreten können. Validieren Sie die Antwort nach dem erfolgreichen Abruf.

Abhängigkeiten hinzufügen und initialisieren

Fügen Sie Ihrem Gradle-Build-Script die folgenden Abhängigkeiten hinzu:

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

Initialisieren Sie als Nächstes eine Instanz der CredentialManager-Klasse.

val credentialManager = CredentialManager.create(context)

Anfrage für digitale Anmeldedaten erstellen

Erstellen Sie eine Anfrage für einen digitalen Berechtigungsnachweis und initialisieren Sie damit ein DigitalCredentialOption.

// The request in the JSON format to conform with
// the JSON-ified Credential Manager - Verifier 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)
)

Das folgende Beispiel zeigt eine OpenId4Vp1-Anfrage. Weitere Informationen zu den Feldern in dieser Anfrage finden Sie in der OpenID-Dokumentation.

{
  "requests": [
    {
      "protocol": "openid4vp-v1-unsigned",
      "data": {
        "response_type": "vp_token",
        "response_mode": "dc_api",
        "nonce": "OD8eP8BYfr0zyhgq4QCVEGN3m7C1Ht_No9H5fG5KJFk",
        "dcql_query": {
          "credentials": [
            {
              "id": "cred1",
              "format": "mso_mdoc",
              "meta": {
                "doctype_value": "org.iso.18013.5.1.mDL"
              },
              "claims": [
                {
                  "path": [
                    "org.iso.18013.5.1",
                    "family_name"
                  ]
                },
                {
                  "path": [
                    "org.iso.18013.5.1",
                    "given_name"
                  ]
                },
                {
                  "path": [
                    "org.iso.18013.5.1",
                    "age_over_21"
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Anmeldedaten abrufen

Starten Sie den getCredential-Ablauf mit der erstellten Anfrage. Sie erhalten entweder ein erfolgreiches GetCredentialResponse oder ein GetCredentialException, wenn die Anfrage fehlschlägt.

Der getCredential-Vorgang löst Android-Systemdialoge aus, um dem Nutzer die verfügbaren Anmeldedatenoptionen anzuzeigen und seine Auswahl zu erfassen. Als Nächstes werden in der Wallet-App, die die ausgewählte Ausweisoption enthält, Benutzeroberflächen angezeigt, um die Einwilligung einzuholen und die erforderlichen Aktionen auszuführen, um eine Antwort mit dem digitalen Ausweis zu generieren.

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.
        }
        else -> Log.w(TAG, "Unexpected exception type ${e::class.java}")
    }
}
Bild mit der Auswahl für digitale Ausweise, die beim Aufrufen von „getCredential“ angezeigt wird.
Abbildung 1. Die angezeigte Auswahl für digitale Anmeldedaten beim Aufrufen von „getCredential“.

Flexible Anfragen mit mehreren Berechtigungsnachweisen

Die Digital Credentials API unterstützt auch das Anfordern mehrerer Arten von Anmeldedaten gleichzeitig über OpenID4VP:

  • Gleichzeitige Anfragen: Fordern Sie mehrere Ausweise in einer einzigen Nutzertransaktion an. Eine Reise-App kann beispielsweise gleichzeitig eine Bordkarte und einen amtlichen Ausweis anfordern, sodass der Nutzer beide mit nur einem Tippen prüfen und genehmigen kann.
  • Flexible Erfüllung: Akzeptieren Sie einen von mehreren Berechtigungstypen oder Ausstellern. Beispielsweise kann bei einem Altersnachweis entweder ein Führerschein oder ein Reisepass akzeptiert werden, sodass Nutzer die Anfrage mit dem Ausweisdokument erfüllen können, das sie in ihrem Holder gespeichert haben.

Hier ein Beispiel für die Anforderung mehrerer Anmeldedaten in einer einzigen Anfrage:

{
  "credentials": [
    {
      "id": "gov_id1",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "org.iso.18013.5.1.mDL"
      },
      "claims": [
        {
          "path": [
            "org.iso.18013.5.1",
            "age_over_21"
          ]
        }
      ]
    },
    {
      "id": "boarding_pass1",
      "format": "dc+sd-jwt",
      "meta": {
        "vct_values": [
          "https://credentials.example.airline/boarding-pass"
        ]
      },
      "claims": [
        {
          "path": [
            "flight_number"
          ]
        },
        {
          "path": [
            "seat"
          ]
        }
      ]
    }
  ]
}
Bild, das die Auswahl für digitale Ausweise zeigt, wenn mehrere Arten von Ausweisen aufgerufen werden.
Abbildung 1. Die angezeigte Auswahl für digitale Ausweise, wenn mehrere Arten von Ausweisen aufgerufen werden.

Antwort verarbeiten

Nachdem Sie die Anfrage für die Anmeldedaten gestellt haben, verarbeiten Sie das von CredentialManager zurückgegebene GetCredentialResponse.

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

Ausnahmen behandeln

Deine App sollte Fehler verarbeiten, die auftreten können, z. B. wenn keine Anmeldedaten auf dem Gerät vorhanden sind oder der Nutzer den Vorgang abbricht:

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