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 definiujących format danych cyfrowych dokumentów tożsamości. Dwa z nich zyskują na znaczeniu 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 identyfikatory 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 dokumenty 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 inicjializować 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 tożsamości żądania

Zamiast podawać poszczególne parametry żądań tożsamości, aplikacja podaje je wszystkie razem 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:

{
  identity: {
    providers: [{
      holder: {
        selector: {
          format: ['mdoc'],
          type: 'org.iso.18013.5.1.mDL',
          fields: [
            'org.iso.18013.5.1.family_name',
            'org.iso.18013.5.1.portrait',
          ]
        },
        params: {
          nonce: '1234',
          readerPublicKey: '<public_key>',
          extraParamAsNeededByWallets: true,
        },
      },
    }]
  }
}

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

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 kluczem prywatnym EC wygenerowanym wcześniej 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 technologii NFC lub kodów QR wraz z BLE jako mechanizmu przesyłania danych. 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ę, zapoznaj się z naszą aplikacją 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 swoim 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.