E‑Mail-Bestätigung mit der Digital Credentials API implementieren

Übersicht

Abhängigkeiten hinzufügen

Fügen Sie der Datei build.gradle Ihrer App die folgenden Abhängigkeiten für Credential Manager hinzu:

Kotlin

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

Groovy

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

Credential Manager initialisieren

Erstellen Sie mit dem App- oder Aktivitätskontext ein CredentialManager-Objekt.

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

Anfrage für digitale Anmeldedaten erstellen

Wenn Sie eine bestätigte E‑Mail-Adresse anfordern möchten, erstellen Sie eine GetCredentialRequest die eine GetDigitalCredentialOptionenthält. Für diese Option ist ein requestJson-String erforderlich, der als OpenID for Verifiable Presentations-Anfrage (OpenID4VP) formatiert ist.

Die OpenID4VP-Anfrage-JSON muss einer bestimmten Struktur folgen. Die aktuellen Anbieter unterstützen eine JSON-Struktur mit einem äußeren "digital": {"requests": [...]} Wrapper.

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

Umschließen Sie als Nächstes die openId4vpRequest-JSON in einer GetDigitalCredentialOption, erstellen Sie eine GetCredentialRequest und rufen Sie getCredential() auf.

Anfrage für den Nutzer präsentieren

Präsentieren Sie dem Nutzer die Anfrage über die integrierte Benutzeroberfläche von Credential Manager.

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
}

Antwort auf dem Client parsen

Nachdem Sie die Antwort erhalten haben, können Sie auf dem Client eine vorläufige Analyse durchführen. Das ist nützlich, um die Benutzeroberfläche sofort zu aktualisieren, z. B. indem Sie den Namen des Nutzers anzeigen.

Der folgende Code extrahiert das unformatierte SD-JWT (Selective Disclosure JWT) und verwendet eine Hilfsfunktion, um die Claims zu decodieren.

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

Antwort verarbeiten

Die Credential Manager API gibt eine DigitalCredential Antwort zurück.

Im Folgenden sehen Sie ein Beispiel dafür, wie der unformatierte responseJsonString aussieht und wie die Claims nach dem Parsen des inneren SD-JWT aussehen. Neben der bestätigten E‑Mail-Adresse erhalten Sie auch zusätzliche Metadaten:

/*
// 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": ""
}
 */

Serverseitige Validierung für die Kontoerstellung

Zur Bestätigung muss Ihre Anwendung den vollständigen responseJsonString zur kryptografischen Validierung an Ihren Server senden, bevor ein Konto erstellt oder der Nutzer angemeldet wird.

  • Authentizität der Daten: Durch die Bestätigung der Aussteller-URL (iss) und der SD-JWT Signatur wird nachgewiesen, dass diese Daten von einer vertrauenswürdigen Stelle ausgestellt wurden.

Die Validierung auf dem Server muss Folgendes umfassen:

  • Aussteller bestätigen: Prüfen Sie, ob das Feld iss (Aussteller) mit https://verifiablecredentials-pa.googleapis.com übereinstimmt.
  • Signatur bestätigen: Prüfen Sie die Signatur des SD-JWT mit den öffentlichen Schlüsseln (JWKs), die unter https://verifiablecredentials-pa.googleapis.com/.well-known/vc-public-jwks verfügbar sind.

Für maximale Sicherheit sollten Sie auch die nonce bestätigen, um Wiederholungsversuche zu verhindern.

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
}

Ein optionaler, aber sehr empfehlenswerter nächster Schritt nach der Bereitstellung eines Kontos ist das sofortige Erstellen eines Passkeys für dieses Konto. So kann sich der Nutzer sicher und ohne Passwort anmelden. Dieser Ablauf ist identisch mit einer Standard-Passkey-Registrierung.

Damit der Ablauf in einer WebView funktioniert, sollten Entwickler eine JavaScript-Bridge (JS-Bridge) implementieren, um die Übergabe zu erleichtern. Mit dieser Bridge kann das WebView-Objekt die systemeigene App benachrichtigen, die dann den eigentlichen Aufruf der Credential Manager API ausführen kann.