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

Online

Identyfikatory cyfrowe mogą być akceptowane zarówno w procesach w aplikacji, jak i w internecie. Aby zaakceptować dane logowania z Portfela Google, musisz:

  1. przeprowadzić integrację za pomocą aplikacji lub witryny, postępując zgodnie z podanymi instrukcjami;
  2. Wypełnij ten formularz, aby poprosić o warunki korzystania z usługi akceptowania danych logowania z Portfela Google i je zaakceptować.

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 (na potrzeby integracji aplikacji 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. Weryfikacja danych uwierzytelniających W3C - zdefiniowane przez organizację W3C.

Menedżer danych logowania na Androida obsługuje oba te formaty, ale Portfel Google obsługuje obecnie tylko cyfrowe dokumenty tożsamości w formacie 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ę o tym, których danych logowania użyje.

  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ć o dane logowania do tożsamości z aplikacji na Androida, wykonaj te czynnoś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-alpha05")
    // 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-alpha05")
}

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 = IdentityCredentialManager.Companion.getClient(context)

Atrybuty żądania tożsamości

// Retrieves the user's digital identites from wallet apps for your app.
val getIdentityCredentialOption = GetDigitalCredentialOption(
    requestJson = requestJson, // this is what partners needs to set, example JSON specified below
)
val result = credentialManager.getCredential(request = GetCredentialRequest(credentialOptions, ...)

Aplikacja wywołująca udostępnia wszystkie parametry żądania tożsamości jako ciąg JSON. Tutaj jest on reprezentowany jako parametr requestMatcher opcji CredentialOption. Menedżer danych logowania nie interesuje się zawartością pliku JSON. To żądanie JSON zostanie przekazane bezpośrednio do portfeli, które są odpowiedzialne za jego analizowanie i ustalanie, które dane logowania mogą spełnić żądanie. Pełną instrukcję implementacji znajdziesz w przykładowej aplikacji.

Spodziewamy się, że W3C zdefiniuje to żądanie JSON jako element interfejsu API sieci Web. Ta standaryzacja umożliwi przeglądarkom bezpośrednie przesyłanie żądań do Androida.

Oto przykładowa prośba mdoc:

{
  "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": "3cydsUF9xNFyBDAAWOct09hEeSqrFX2WB2r0G6f8Ol0=",
  "readerPublicKey": "BApmGdElal2-1dtafsdHVRa1EpAWZfhlQj_iof2I8L3V8_dCK1gVR0_12E4ZSQ2LcqXRd4zxVeKEqU1wUSgGWUU="
}

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 przetwarzania na serwerze

Po otrzymaniu tokenu tożsamości aplikacja powinna przekazać go do serwera aplikacji w celu weryfikacji. Pierwszym krokiem jest dekodowanie tokena z formatu base64. Otrzymana tablica bajtów reprezentuje dane CBOR, które są zgodne z poniższym 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 kroków, takich jak sprawdzenie, 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 zaakceptować dokumenty tożsamości z Portfela Google, wykonaj te czynności:

  • Utwórz lub pozyskaj czytnik do akceptowania identyfikatorów zgodnie z normą ISO 18013-5
  • Załaduj certyfikaty IACA do czytnika, aby mieć pewność, że akceptowane dokumenty są autentyczne
  • Testowanie rozwiązania
  • Zarejestruj aplikację 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. Do odczytu danych używają 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ż bezpośrednio wdrożyć tę funkcję.

Wskazówki dotyczące samodzielnego wdrażania tej funkcji znajdziesz w naszej aplikacji na Androida umożliwiającej korzystanie z czytników referencyjnych typu open source. Jest ona zgodna z normą 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.
  • Utwórz i uruchom środowisko docelowe 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 wraz z linkami do ich certyfikatów, które możesz wykorzystać do weryfikacji.

Testowanie rozwiązania

Aby przetestować swoje rozwiązanie, skompiluj i uruchom naszą aplikację na Androida ze źródłami otwartymi. Aby utworzyć i uruchomić aplikację na kartę referencyjną:

  • Skopiuj repozytorium aplikacji referencyjnych
  • Otwórz projekt w Android Studio.
  • Utwórz i uruchom środowisko docelowe appholder na urządzeniu z Androidem lub w emulatorze.

(Opcjonalnie) Zarejestruj aplikację w Portfelu Google

Zarejestruj swoje zgłoszenie w Portfelu Google, wypełniając ten formularz.