Akceptowanie dokumentów tożsamości z Portfela Google

Online

Cyfrowe dokumenty tożsamości mogą być akceptowane zarówno w procesach w aplikacji, jak i w sieci. Aby zaakceptować dane logowania z Portfela Google, musisz:

  1. Integrację z użyciem aplikacji lub przeglądarki możesz przeprowadzić zgodnie z podanymi instrukcjami.
  2. Wypełnij ten formularz, aby poprosić o zaakceptowanie warunków korzystania z usługi dotyczących akceptowania danych logowania z Portfela Google.

Wymagania wstępne

Aby przetestować wyświetlanie identyfikatorów, musisz najpierw zarejestrować się w publicznym programie testów beta, używając odpowiedniego konta testowego. Następnie prześlij te informacje do przypisanej Ci osoby kontaktowej z Google.

  • Link do Warunków korzystania z usługi
  • Logo
  • Witryna
  • Identyfikator pakietu w Sklepie Play (w przypadku integracji z aplikacją na Androida)
  • identyfikator Gmaila użyty do dołączenia do wersji beta publicznej.

Obsługiwane formaty danych logowania

Istnieje kilka proponowanych standardów określających format danych cyfrowych dokumentów tożsamości. Dwa z nich zyskują na popularności w branży:

  1. mdocs – zdefiniowane przez ISO.
  2. Weryfikowalne dane logowania W3C – zdefiniowane przez W3C.

Menedżer danych uwierzytelniających na Androida obsługuje oba formaty, ale Cyfrowy portfel Google obsługuje obecnie tylko cyfrowe dokumenty tożsamości oparte na mdoc.

Interfejs użytkownika

Gdy aplikacja prosi o atrybuty tożsamości, następuje ten proces:

  1. Wyszukiwanie danych logowania: aplikacja wysyła zapytania do dostępnych portfeli, aby zidentyfikować dane logowania, które mogą spełnić żądanie. Android wyświetla selektor interfejsu użytkownika, w którym można wybrać informacje do udostępnienia. Dzięki temu użytkownik może podjąć świadomą decyzję, których danych logowania użyć.

  2. Wybór przez użytkownika i interakcja z Portfelem: użytkownik wybiera dane logowania, a Android wywołuje odpowiednią aplikację Portfela w celu zrealizowania transakcji. Aplikacja Portfel może wyświetlić własny ekran zgody lub wymagać potwierdzenia biometrycznego.

Wynik: jeśli użytkownik wyrazi zgodę, wybrane dane tożsamości zostaną udostępnione aplikacji, która wysłała żądanie. Jeśli użytkownik odmówi, zwrócony zostanie błąd.

W aplikacji

Aby poprosić aplikacje na Androida o potwierdzenie tożsamości:

Aktualizowanie zależności

W pliku build.gradle projektu zaktualizuj zależności, aby używać usługi Credential Manager (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")
}

Konfigurowanie Menedżera danych logowania

Aby skonfigurować i zainicjować obiekt CredentialManager, dodaj logikę podobną do tej:

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

Atrybuty żądania tożsamości

Zamiast podawać poszczególne parametry żądań tożsamości, aplikacja podaje je wszystkie jako ciąg JSON w opcji CredentialOption. Menedżer danych logowania przekazuje ten ciąg znaków JSON do dostępnych cyfrowych portfeli bez sprawdzania jego zawartości. Każdy portfel jest następnie odpowiedzialny za: – analizowanie ciągu JSON w celu zrozumienia żądania tożsamości. – Określanie, które z zapasowych danych logowania (jeśli w ogóle) spełniają żądanie.

Oczekuje się, że W3C formalnie określi strukturę tego żądania JSON w ramach specyfikacji interfejsu API internetowego. Pamiętaj jednak, że specyfikacja jest w postaci projektu i może ulec zmianie.

Na początku będziemy używać protokołu podglądu, aby uzyskać identyfikatory z Portfela Google. Pozwoli nam to rozpocząć integrację i testowanie, gdy specyfikacja interfejsu API będzie już gotowa.

Oto przykład pliku mdoc requestJson dla protokołu podglądu:

{
    "providers": [{
      "protocol": "preview",
      "request": "<request>"
    }]
}

request zawiera pola

{
  "selector": {
    "format": [
      "mdoc"
    ],
    "doctype": "org.iso.18013.5.1.mDL",
    "fields": [
      {
        "namespace": "org.iso.18013.5.1",
        "name": "family_name",
        "intentToRetain": false
      },
      {
        "namespace": "org.iso.18013.5.1",
        "name": "given_name",
        "intentToRetain": false
      },
      {
        "namespace": "org.iso.18013.5.1",
        "name": "age_over_21",
        "intentToRetain": false
      }
    ]
  },
  "nonce": "1234",
  "readerPublicKey": "<public_key>"
}

użyjesz funkcji requestJson, która składa się z funkcji request w wywołaniu funkcji GetDigitalCredentialOption()

// 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.
        }
        else -> Log.w(TAG, "Unexpected exception type ${e::class.java}")
    }
}

Odpowiedź zwraca identityToken (ciąg znaków JSON) zdefiniowany przez W3C. Za tworzenie tej odpowiedzi odpowiada aplikacja Portfel.

Przykład:

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

Wysyłanie tokena i przetwarzanie na serwerze

Po otrzymaniu identityToken aplikacja powinna przekazać go do serwera aplikacji w celu weryfikacji. Pierwszym krokiem jest dekodowanie tokena z formatu base64. Wynikowa tablica bajtów reprezentuje dane CBOR, które są zgodne z podanym niżej formatem CDDL.

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

Następnym krokiem jest obliczenie SessionTranscript na podstawie ISO/IEC 18013-5:2021 z uwzględnieniem specyficznej dla Androida struktury przekazywania:

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
]

Wartość cipherText jest szyfrowana za pomocą szyfrowania HPKE. Aby go odszyfrować, użyj SessionTranscript jako dodatkowych danych uwierzytelnionych wraz z wygenerowanym wcześniej kluczem prywatnym EC i tymi ustawieniami:

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

Wynikający z tego tekst jawny to bajty CBOR DeviceResponse zgodnie z normą ISO/IEC 18013-5:2021. Odpowiedź urządzenia musi zostać zweryfikowana zgodnie z klauzulą 9 normy ISO/IEC 18013-5:2021. Obejmuje to kilka etapów, takich jak weryfikacja, czy mdoc pochodzi od zaufanego wydawcy i czy odpowiedź jest podpisana przez odpowiednie urządzenie. W ramach tego procesu weryfikacji można użyć klasy DeviceResponseParser z projektu OpenWallet Foundation Identity Credential.

Sieć

Aby poprosić o dane logowania za pomocą interfejsu Digital Credentials API w Chrome, musisz zarejestrować się w testowaniu origin interfejsu Digital Credentials API.

Na żywo

Aby akceptować dokumenty tożsamości w Portfelu Google, wykonaj te czynności:

  • Stworzyć lub kupić czytnik, który akceptuje identyfikatory zdefiniowane w normie ISO 18013-5.
  • Załaduj certyfikaty IACA do czytnika, aby mieć pewność, że akceptowane dokumenty są autentyczne
  • Testowanie rozwiązania
  • Rejestrowanie aplikacji w Portfelu Google

Stworzyć lub kupić czytnik, który akceptuje identyfikatory zdefiniowane w normie ISO 18013-5.

Dokumenty tożsamości w Portfelu są implementowane zgodnie ze standardem ISO 18013-5 dotyczącym mobilnych praw jazdy. Używają one mechanizmu przesyłania danych opartego na technologii NFC lub kodów QR oraz BLE. Oznacza to, że czytnik może działać na dowolnym urządzeniu, które obsługuje te aspekty standardu, nawet na aplikacji mobilnej. Ponieważ jest to standard otwarty, na rynku dostępnych jest kilka implementacji innych firm. W razie potrzeby możesz też zaimplementować tę funkcję bezpośrednio.

Aby dowiedzieć się, jak samodzielnie wdrożyć tę funkcję, skorzystaj z naszej aplikacji do odczytu referencyjnego na Androida, która korzysta ze standardu ISO i może akceptować mDL z Portfela Google.

Aby rozpocząć, skompiluj i uruchom aplikację czytnika referencyjnego:

  • Klonowanie repozytorium aplikacji referencyjnych
  • Otwórz projekt w Android Studio.
  • Skompiluj i uruchom docelowe urządzenie appverifier na urządzeniu z Androidem lub w emulatorze.

Załaduj certyfikaty IACA do czytnika, aby mieć pewność, że akceptowane dokumenty są autentyczne

Aby potwierdzić prawdziwe dane logowania, musisz mieć w portfelu dokument tożsamości wydany przez obsługiwanego wystawcę. Poniżej znajdziesz listę wydawców obsługiwanych przez Google Wallet oraz linki do ich certyfikatów, które możesz wykorzystać do weryfikacji.

Aby przetestować swoje rozwiązanie, skompiluj i uruchom na urządzeniu aplikację na Androida, która jest dostępna na licencji open source. Aby utworzyć i uruchomić aplikację na kartę referencyjną:

  • Klonowanie repozytorium aplikacji referencyjnych
  • Otwórz projekt w Android Studio.
  • Skompiluj i uruchom docelowe urządzenie appholder na urządzeniu z Androidem lub w emulatorze.

(Opcjonalnie) Zarejestruj aplikację w Portfelu Google

Aby zarejestrować aplikację w Portfelu Google, wypełnij ten formularz.