Logowanie użytkownika za pomocą Menedżera danych logowania

Menedżer danych logowania to interfejs Jetpack API, który obsługuje wiele metod logowania, takich jak nazwa użytkownika i hasło, klucze dostępu i rozwiązania logowania federacyjnego (np. Zaloguj się przez Google), w jednym interfejsie API, co upraszcza integrację dla deweloperów.

Ponadto Credential Manager ujednolica interfejs logowania niezależnie od metody uwierzytelniania, dzięki czemu użytkownicy mogą łatwiej i w bardziej przejrzysty sposób logować się w aplikacjach niezależnie od wybranej metody.

Na tej stronie wyjaśniamy pojęcie kluczy dostępu oraz przedstawiamy kroki, które należy wykonać, aby wdrożyć obsługę rozwiązań uwierzytelniania, w tym kluczy dostępu, po stronie klienta za pomocą interfejsu Credential Manager API. Jest też osobna strona z najczęstszymi pytaniami, na której znajdziesz odpowiedzi na bardziej szczegółowe pytania.

Twoja opinia jest kluczowa dla ulepszania interfejsu Credential Manager API. Udostępniaj znalezione problemy lub pomysły na ulepszenie interfejsu API za pomocą tego linku:

Przesyłanie opinii

Informacje o kluczach dostępu

Klucze dostępu to bezpieczniejsza i łatwiejsza alternatywa dla haseł. Dzięki kluczom dostępu użytkownicy mogą logować się w aplikacjach i na stronach internetowych za pomocą czujnika biometrycznego (np. odcisku palca lub rozpoznawania twarzy), kodu PIN lub wzoru. Dzięki temu logowanie jest płynne, a użytkownicy nie muszą pamiętać nazw użytkowników ani haseł.

Klucze dostępu opierają się na WebAuthn (uwierzytelnianiu w internecie), standardzie opracowanym wspólnie przez FIDO Alliance i World Wide Web Consortium (W3C). WebAuthn używa szyfrowania kluczem publicznym do uwierzytelniania użytkownika. Witryna lub aplikacja, do której użytkownik się loguje, może wyświetlać i przechowywać klucz publiczny, ale nigdy klucz prywatny. Klucz prywatny jest przechowywany w tajnych i bezpiecznych warunkach. Ponieważ klucz jest unikalny i powiązany z witryną lub aplikacją, nie można go przechwycić, co zwiększa bezpieczeństwo.

Menedżer danych logowania umożliwia użytkownikom tworzenie kluczy dostępu i przechowywanie ich w Menedżerze haseł Google.

Aby dowiedzieć się, jak wdrożyć płynne przepływy uwierzytelniania za pomocą kluczy dostępu za pomocą Menedżera danych logowania, przeczytaj artykuł Uwierzytelnianie użytkowników za pomocą kluczy dostępu.

Wymagania wstępne

Aby korzystać z Menedżera danych logowania, wykonaj czynności opisane w tej sekcji.

Używanie najnowszej wersji platformy

Menedżer danych logowania jest obsługiwany na Androidzie 4.4 (poziom interfejsu API 19) i nowszych.

Dodawanie zależności do aplikacji

Dodaj te zależności do skryptu kompilacji modułu aplikacji:

Kotlin

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

Odlotowe

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

Zachowanie klas w pliku ProGuard

Dodaj do pliku proguard-rules.pro modułu te dyrektywy:

-if class androidx.credentials.CredentialManager
-keep class androidx.credentials.playservices.** {
  *;
}

Dowiedz się więcej o skompresowaniu, zaciemnianiu i optymalizowaniu aplikacji.

Dodanie obsługi Digital Asset Links

Aby włączyć obsługę kluczy dostępu w aplikacji na Androida, powiązać ją z witryną, której jest właścicielem. Aby zadeklarować to powiązanie, wykonaj te czynności:

  1. Utwórz plik JSON protokołu Digital Asset Links. Aby na przykład zadeklarować, że strona https://signin.example.com i aplikacja na Androida o nazwie pakietu com.example mogą udostępniać dane logowania, utwórz plik o nazwie assetlinks.json z treścią:

    [
  {
    "relation" : [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target" : {
      "namespace" : "android_app",
      "package_name" : "com.example.android",
      "sha256_cert_fingerprints" : [
        SHA_HEX_VALUE
      ]
    }
  }
]

    Pole relation to tablica co najmniej 1 ciągu znaków opisujących deklarowaną relację. Aby zadeklarować, że aplikacje i witryny udostępniają dane logowania, określ relacje jako delegate_permission/handle_all_urls i delegate_permission/common.get_login_creds.

    Pole target to obiekt określający zasób, którego dotyczy deklaracja. Te pola identyfikują witrynę:

    namespace web
    site

    Adres URL witryny w formacie https://domain[:optional_port], na przykład https://www.example.com.

    Wartość domain musi być w pełni kwalifikowana, a optional_port musi być pominięty, jeśli używasz portu 443 do HTTPS.

    Docelowy adres site może być tylko domeną główną: nie możesz ograniczyć powiązania aplikacji do konkretnego podkatalogu. Nie umieszczaj w adresie URL ścieżki, np. ukośnika na końcu.

    Subdomeny nie są uważane za dopasowanie: jeśli jako www.example.com podasz domain, domena www.counter.example.com nie będzie powiązana z Twoją aplikacją.

    Te pola identyfikują aplikację na Androida:

    namespace android_app
    package_name Nazwa pakietu zadeklarowana w manifeście aplikacji. Na przykład:com.example.android
    sha256_cert_fingerprints Odciski cyfrowe SHA-256 certyfikatu podpisywania aplikacji.

  2. Umieść plik JSON protokołu Digital Asset Links w tej lokalizacji w domenie logowania:

    https://domain[:optional_port]/.well-known/assetlinks.json

    Jeśli na przykład Twoja domena logowania to signin.example.com, umieść plik JSON pod adresem https://signin.example.com/.well-known/assetlinks.json.

    Typ MIME pliku Digital Asset Link musi być JSON. Upewnij się, że serwer wysyła nagłówek Content-Type: application/json w odpowiedzi.

  3. Upewnij się, że Twój host zezwala Google na pobranie pliku Digital Asset Link. Jeśli masz plik robots.txt, musi on zezwalać agentowi Googlebot na pobieranie informacji z pliku /.well-known/assetlinks.json. Większość witryn może zezwolić dowolnemu automatycznemu agentowi na pobieranie plików z ścieżki /.well-known/, aby inne usługi mogły uzyskać dostęp do metadanych w tych plikach:

    User-agent: *
Allow: /.well-known/

  4. Dodaj do pliku manifestu w sekcji <application> ten wiersz:

    <meta-data android:name="asset_statements" android:resource="@string/asset_statements" />

  5. Jeśli logujesz się za pomocą hasła w Menedżerze danych logowania, wykonaj te czynności, aby skonfigurować linkowanie zasobów cyfrowych w pliku manifestu. Ten krok nie jest wymagany, jeśli używasz tylko kluczy dostępu.

    Zadeklaruj powiązanie w aplikacji na Androida. Dodaj obiekt, który określa pliki assetlinks.json, które mają być wczytane. Musisz zmienić znaczenie wszystkich apostrofów i cudzysłów użytych w tym ciągu. Przykład:

    <string name="asset_statements" translatable="false">
[{
  \"include\": \"https://signin.example.com/.well-known/assetlinks.json\"
}]
</string>

    > GET /.well-known/assetlinks.json HTTP/1.1
> User-Agent: curl/7.35.0
> Host: signin.example.com

< HTTP/1.1 200 OK
< Content-Type: application/json

Konfigurowanie Menedżera danych logowania

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

Kotlin

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

Java

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

Wskazać pola danych logowania

W Androidzie 14 i nowszych można używać atrybutu isCredential do wskazywania pól danych logowania, takich jak pola nazwy użytkownika lub hasła. Ten atrybut wskazuje, że to pole jest polem danych uwierzytelniających, które ma współpracować z Menedżerem danych uwierzytelniających i zewnętrznymi dostawcami danych uwierzytelniających, a także pomaga usługom autouzupełniania w wyświetlaniu lepszych sugestii autouzupełniania. Gdy aplikacja korzysta z interfejsu API menedżera danych logowania, wyświetla się dolna karta menedżera danych logowania z dostępnymi danymi logowania. Nie trzeba już wyświetlać okna dialogowego autouzupełniania w przypadku nazwy użytkownika ani hasła. Podobnie nie musisz wyświetlać w przypadku haseł okna zapisywania danych autouzupełniania, ponieważ aplikacja poprosi o zapisanie danych za pomocą interfejsu Credential Manager API.

Aby używać atrybutu isCredential, dodaj go do odpowiednich widoków:

<TextView
   android:layout_width="match_parent"
   android:layout_height="wrap_content"
   android:isCredential="true"
...
 />

Logowanie użytkownika

Aby pobrać wszystkie opcje kluczy dostępu i haseł powiązane z kontem użytkownika:

  1. Aby skonfigurować opcje uwierzytelniania za pomocą hasła i klucza:

    Kotlin

    // Retrieves the user's saved password for your app from their
// password provider.
val getPasswordOption = GetPasswordOption()

// Get passkey from the user's public key credential provider.
val getPublicKeyCredentialOption = GetPublicKeyCredentialOption(
    requestJson = requestJson
)

    Java

    // Retrieves the user's saved password for your app from their
// password provider.
GetPasswordOption getPasswordOption = new GetPasswordOption();

// Get passkey from the user's public key credential provider.
GetPublicKeyCredentialOption getPublicKeyCredentialOption =
        new GetPublicKeyCredentialOption(requestJson);

  2. Użyj opcji pobranych z poprzedniego kroku, aby utworzyć żądanie logowania.

    Kotlin

    val getCredRequest = GetCredentialRequest(
    listOf(getPasswordOption, getPublicKeyCredentialOption)
)

    Java

    GetCredentialRequest getCredRequest = new GetCredentialRequest.Builder()
    .addCredentialOption(getPasswordOption)
    .addCredentialOption(getPublicKeyCredentialOption)
    .build();

  3. Rozpocznij proces logowania:

    Kotlin

    coroutineScope.launch {
    try {
        val result = credentialManager.getCredential(
            // Use an activity-based context to avoid undefined system UI
            // launching behavior.
            context = activityContext,
            request = getCredRequest
        )
        handleSignIn(result)
    } catch (e : GetCredentialException) {
        handleFailure(e)
    }
}

fun handleSignIn(result: GetCredentialResponse) {
    // Handle the successfully returned credential.
    val credential = result.credential

    when (credential) {
        is PublicKeyCredential -> {
            val responseJson = credential.authenticationResponseJson
            // Share responseJson i.e. a GetCredentialResponse on your server to
            // validate and  authenticate
        }
        is PasswordCredential -> {
            val username = credential.id
            val password = credential.password
            // Use id and password to send to your server to validate
            // and authenticate
        }
      is CustomCredential -> {
          // If you are also using any external sign-in libraries, parse them
          // here with the utility functions provided.
          if (credential.type == ExampleCustomCredential.TYPE)  {
          try {
              val ExampleCustomCredential = ExampleCustomCredential.createFrom(credential.data)
              // Extract the required credentials and complete the authentication as per
              // the federated sign in or any external sign in library flow
              } catch (e: ExampleCustomCredential.ExampleCustomCredentialParsingException) {
                  // Unlikely to happen. If it does, you likely need to update the dependency
                  // version of your external sign-in library.
                  Log.e(TAG, "Failed to parse an ExampleCustomCredential", e)
              }
          } else {
            // Catch any unrecognized custom credential type here.
            Log.e(TAG, "Unexpected type of credential")
          }
        } else -> {
            // Catch any unrecognized credential type here.
            Log.e(TAG, "Unexpected type of credential")
        }
    }
}

    Java

    credentialManager.getCredentialAsync(
    // Use activity based context to avoid undefined
    // system UI launching behavior
    activity,
    getCredRequest,
    cancellationSignal,
    <executor>,
    new CredentialManagerCallback<GetCredentialResponse, GetCredentialException>() {
        @Override
        public void onResult(GetCredentialResponse result) {
            handleSignIn(result);
        }

        @Override
        public void onError(GetCredentialException e) {
            handleFailure(e);
        }
    }
);

public void handleSignIn(GetCredentialResponse result) {
    // Handle the successfully returned credential.
    Credential credential = result.getCredential();
    if (credential instanceof PublicKeyCredential) {
        String responseJson = ((PublicKeyCredential) credential).getAuthenticationResponseJson();
        // Share responseJson i.e. a GetCredentialResponse on your server to validate and authenticate
    } else if (credential instanceof PasswordCredential) {
        String username = ((PasswordCredential) credential).getId();
        String password = ((PasswordCredential) credential).getPassword();
        // Use id and password to send to your server to validate and authenticate
    } else if (credential instanceof CustomCredential) {
        if (ExampleCustomCredential.TYPE.equals(credential.getType())) {
            try {
                ExampleCustomCredential customCred = ExampleCustomCredential.createFrom(customCredential.getData());
                // Extract the required credentials and complete the
                // authentication as per the federated sign in or any external
                // sign in library flow
            } catch (ExampleCustomCredential.ExampleCustomCredentialParsingException e) {
                // Unlikely to happen. If it does, you likely need to update the
                // dependency version of your external sign-in library.
                Log.e(TAG, "Failed to parse an ExampleCustomCredential", e);
            }
        } else {
            // Catch any unrecognized custom credential type here.
            Log.e(TAG, "Unexpected type of credential");
        }
    } else {
        // Catch any unrecognized credential type here.
        Log.e(TAG, "Unexpected type of credential");
    }
}

Ten przykład pokazuje, jak sformatować żądanie JSON, gdy otrzymasz klucz dostępu:

{
  "challenge": "T1xCsnxM2DNL2KdK5CLa6fMhD7OBqho6syzInk_n-Uo",
  "allowCredentials": [],
  "timeout": 1800000,
  "userVerification": "required",
  "rpId": "credential-manager-app-test.glitch.me"
}

Poniższy przykład pokazuje, jak może wyglądać odpowiedź JSON po uzyskaniu danych logowania z kluczem publicznym:

{
  "id": "KEDetxZcUfinhVi6Za5nZQ",
  "type": "public-key",
  "rawId": "KEDetxZcUfinhVi6Za5nZQ",
  "response": {
    "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiVDF4Q3NueE0yRE5MMktkSzVDTGE2Zk1oRDdPQnFobzZzeXpJbmtfbi1VbyIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOk1MTHpEdll4UTRFS1R3QzZVNlpWVnJGUXRIOEdjVi0xZDQ0NEZLOUh2YUkiLCJhbmRyb2lkUGFja2FnZU5hbWUiOiJjb20uZ29vZ2xlLmNyZWRlbnRpYWxtYW5hZ2VyLnNhbXBsZSJ9",
    "authenticatorData": "j5r_fLFhV-qdmGEwiukwD5E_5ama9g0hzXgN8thcFGQdAAAAAA",
    "signature": "MEUCIQCO1Cm4SA2xiG5FdKDHCJorueiS04wCsqHhiRDbbgITYAIgMKMFirgC2SSFmxrh7z9PzUqr0bK1HZ6Zn8vZVhETnyQ",
    "userHandle": "2HzoHm_hY0CjuEESY9tY6-3SdjmNHOoNqaPDcZGzsr0"
  }
}

Obsługa wyjątków, gdy nie ma dostępnych danych logowania

W niektórych przypadkach użytkownik może nie mieć żadnych danych uwierzytelniających lub nie wyrazić zgody na użycie dostępnych danych. Jeśli wywołana zostanie funkcja getCredential() i nie zostanie znaleziony żaden identyfikator, zwracany jest parametr NoCredentialException. W takiej sytuacji Twój kod powinien obsłużyć NoCredentialExceptionprzypadki.

Kotlin

try {
  val credential = credentialManager.getCredential(credentialRequest)
} catch (e: NoCredentialException) {
  Log.e("CredentialManager", "No credential available", e)
}

Java

try {
  Credential credential = credentialManager.getCredential(credentialRequest);
} catch (NoCredentialException e) {
  Log.e("CredentialManager", "No credential available", e);
}

W Androidzie 14 lub nowszym możesz skrócić opóźnienie wyświetlania selektora kont, używając metody prepareGetCredential() przed wywołaniem metody getCredential().

Kotlin

val response = credentialManager.prepareGetCredential(
  GetCredentialRequest(
    listOf(
      <getPublicKeyCredentialOption>,
      <getPasswordOption>
    )
  )
}

Java

GetCredentialResponse response = credentialManager.prepareGetCredential(
  new GetCredentialRequest(
    Arrays.asList(
      new PublicKeyCredentialOption(),
      new PasswordOption()
    )
  )
);

Metoda prepareGetCredential() nie wywołuje elementów interfejsu. Pomaga tylko w przygotowaniu się do dalszych działań, aby można było później uruchomić pozostałe operacje dotyczące pobierania danych logowania (które wymagają interfejsu użytkownika) za pomocą interfejsu API getCredential().

Dane z pamięci podręcznej są zwracane w obiekcie PrepareGetCredentialResponse. Jeśli istnieją już dane logowania, wyniki zostaną zapisane w pamięci podręcznej. Później możesz uruchomić pozostałą część interfejsu API getCredential(), aby wyświetlić selektor kont z danymi z pamięci podręcznej.

Procesy rejestracji

Użytkownik może zarejestrować się do uwierzytelniania za pomocą klucza dostępu lub hasła.

Utwórz klucz dostępu

Aby umożliwić użytkownikom rejestrowanie kluczy dostępu i używanie ich do ponownego uwierzytelniania, zarejestruj dane uwierzytelniające użytkownika za pomocą obiektu CreatePublicKeyCredentialRequest.

Kotlin

fun createPasskey(requestJson: String, preferImmediatelyAvailableCredentials: Boolean) {
    val createPublicKeyCredentialRequest = CreatePublicKeyCredentialRequest(
        // Contains the request in JSON format. Uses the standard WebAuthn
        // web JSON spec.
        requestJson = requestJson,
        // Defines whether you prefer to use only immediately available
        // credentials, not hybrid credentials, to fulfill this request.
        // This value is false by default.
        preferImmediatelyAvailableCredentials = preferImmediatelyAvailableCredentials,
    )

    // Execute CreateCredentialRequest asynchronously to register credentials
    // for a user account. Handle success and failure cases with the result and
    // exceptions, respectively.
    coroutineScope.launch {
        try {
            val result = credentialManager.createCredential(
                // Use an activity-based context to avoid undefined system
                // UI launching behavior
                context = activityContext,
                request = createPublicKeyCredentialRequest,
            )
            handlePasskeyRegistrationResult(result)
        } catch (e : CreateCredentialException){
            handleFailure(e)
        }
    }
}

fun handleFailure(e: CreateCredentialException) {
    when (e) {
        is CreatePublicKeyCredentialDomException -> {
            // Handle the passkey DOM errors thrown according to the
            // WebAuthn spec.
            handlePasskeyError(e.domError)
        }
        is CreateCredentialCancellationException -> {
            // The user intentionally canceled the operation and chose not
            // to register the credential.
        }
        is CreateCredentialInterruptedException -> {
            // Retry-able error. Consider retrying the call.
        }
        is CreateCredentialProviderConfigurationException -> {
            // Your app is missing the provider configuration dependency.
            // Most likely, you're missing the
            // "credentials-play-services-auth" module.
        }
        is CreateCredentialUnknownException -> ...
        is CreateCredentialCustomException -> {
            // You have encountered an error from a 3rd-party SDK. If you
            // make 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.name}")
    }
}

Java

public void createPasskey(String requestJson, boolean preferImmediatelyAvailableCredentials) {
    CreatePublicKeyCredentialRequest createPublicKeyCredentialRequest =
            // `requestJson` contains the request in JSON format. Uses the standard
            // WebAuthn web JSON spec.
            // `preferImmediatelyAvailableCredentials` defines whether you prefer
            // to only use immediately available credentials, not  hybrid credentials,
            // to fulfill this request. This value is false by default.
            new CreatePublicKeyCredentialRequest(
                requestJson, preferImmediatelyAvailableCredentials);

    // Execute CreateCredentialRequest asynchronously to register credentials
    // for a user account. Handle success and failure cases with the result and
    // exceptions, respectively.
    credentialManager.createCredentialAsync(
        // Use an activity-based context to avoid undefined system
        // UI launching behavior
        requireActivity(),
        createPublicKeyCredentialRequest,
        cancellationSignal,
        executor,
        new CredentialManagerCallback<CreateCredentialResponse, CreateCredentialException>() {
            @Override
            public void onResult(CreateCredentialResponse result) {
                handleSuccessfulCreatePasskeyResult(result);
            }

            @Override
            public void onError(CreateCredentialException e) {
                if (e instanceof CreatePublicKeyCredentialDomException) {
                    // Handle the passkey DOM errors thrown according to the
                    // WebAuthn spec.
                    handlePasskeyError(((CreatePublicKeyCredentialDomException)e).getDomError());
                } else if (e instanceof CreateCredentialCancellationException) {
                    // The user intentionally canceled the operation and chose not
                    // to register the credential.
                } else if (e instanceof CreateCredentialInterruptedException) {
                    // Retry-able error. Consider retrying the call.
                } else if (e instanceof CreateCredentialProviderConfigurationException) {
                    // Your app is missing the provider configuration dependency.
                    // Most likely, you're missing the
                    // "credentials-play-services-auth" module.
                } else if (e instanceof CreateCredentialUnknownException) {
                } else if (e instanceof CreateCredentialCustomException) {
                    // You have encountered an error from a 3rd-party SDK. If
                    // you make 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.getClass().getName());
                }
            }
        }
    );
}

Formatowanie żądania JSON

Po utworzeniu klucza dostępu musisz powiązać go z kontem użytkownika i zapisać klucz publiczny klucza na serwerze. Poniższy przykład kodu pokazuje, jak sformatować żądanie JSON podczas tworzenia klucza dostępu.

W tym poście na blogu na temat płynnego uwierzytelniania w aplikacjach znajdziesz informacje o sformatowaniu żądania JSON podczas tworzenia kluczy dostępu i uwierzytelniania za ich pomocą. Dowiesz się też, dlaczego hasła nie są skutecznym rozwiązaniem uwierzytelniania, jak wykorzystać istniejące dane biometryczne, jak powiązać aplikację z witryną, jak tworzyć klucze dostępu i jak uwierzytelniać się za ich pomocą.

{
  "challenge": "abc123",
  "rp": {
    "name": "Credential Manager example",
    "id": "credential-manager-test.example.com"
  },
  "user": {
    "id": "def456",
    "name": "helloandroid@gmail.com",
    "displayName": "helloandroid@gmail.com"
  },
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    },
    {
      "type": "public-key",
      "alg": -257
    }
  ],
  "timeout": 1800000,
  "attestation": "none",
  "excludeCredentials": [
    {"id": "ghi789", "type": "public-key"},
    {"id": "jkl012", "type": "public-key"}
  ],
  "authenticatorSelection": {
    "authenticatorAttachment": "platform",
    "requireResidentKey": true,
    "residentKey": "required",
    "userVerification": "required"
  }
}

Ustawianie wartości atrybutu authenticatorAttachment

Parametr authenticatorAttachment można ustawić tylko podczas tworzenia danych logowania. Możesz podać wartość platform, cross-platform lub nie podawać żadnej wartości. W większości przypadków zalecana jest wartość 0.

  • platform: aby zarejestrować aktualne urządzenie użytkownika lub poprosić użytkownika o przejście na klucze dostępu po zalogowaniu się, ustaw wartość authenticatorAttachment na platform.
  • cross-platform: ta wartość jest często używana podczas rejestrowania danych logowania wieloskładnikowych i nie jest używana w kontekście klucza dostępu.
  • Brak wartości: aby zapewnić użytkownikom elastyczność w tworzeniu kluczy dostępu na preferowanych urządzeniach (np. w ustawieniach konta), parametr authenticatorAttachment nie powinien być określony, gdy użytkownik zdecyduje się dodać klucz dostępu. W większości przypadków najlepszym rozwiązaniem jest pozostawienie parametru bez określenia.

zapobieganie tworzeniu powielonych kluczy dostępu.

Wyświetl identyfikatory danych logowania w opcjonalnym tablicy excludeCredentials, aby zapobiec tworzeniu nowego klucza dostępu, jeśli istnieje już klucz dostępu tego samego dostawcy.

Obsługa odpowiedzi JSON

Ten fragment kodu przedstawia przykładową odpowiedź JSON dotyczącą utworzenia danych logowania z kluczem publicznym. Dowiedz się więcej o zwrotnym obiekcie tożsamości z kluczem publicznym.

{
  "id": "KEDetxZcUfinhVi6Za5nZQ",
  "type": "public-key",
  "rawId": "KEDetxZcUfinhVi6Za5nZQ",
  "response": {
    "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoibmhrUVhmRTU5SmI5N1Z5eU5Ka3ZEaVh1Y01Fdmx0ZHV2Y3JEbUdyT0RIWSIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOk1MTHpEdll4UTRFS1R3QzZVNlpWVnJGUXRIOEdjVi0xZDQ0NEZLOUh2YUkiLCJhbmRyb2lkUGFja2FnZU5hbWUiOiJjb20uZ29vZ2xlLmNyZWRlbnRpYWxtYW5hZ2VyLnNhbXBsZSJ9",
    "attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViUj5r_fLFhV-qdmGEwiukwD5E_5ama9g0hzXgN8thcFGRdAAAAAAAAAAAAAAAAAAAAAAAAAAAAEChA3rcWXFH4p4VYumWuZ2WlAQIDJiABIVgg4RqZaJyaC24Pf4tT-8ONIZ5_Elddf3dNotGOx81jj3siWCAWXS6Lz70hvC2g8hwoLllOwlsbYatNkO2uYFO-eJID6A"
  }
}

Weryfikacja pochodzenia w pliku danych klienta JSON

Wartość origin reprezentuje aplikację lub witrynę, z której pochodzi żądanie. Jest ona używana przez klucze dostępu do ochrony przed atakami phishingowymi. Serwer aplikacji musi sprawdzać źródło danych klienta na liście dozwolonych aplikacji i witryn. Jeśli serwer otrzyma żądanie z nierozpoznanego źródła, powinien je odrzucić.

W przypadku przeglądarki origin odzwierciedla to samo źródło witryny, w której zalogowano się przy użyciu danych logowania. Na przykład, jeśli adres URL to https://www.example.com:8443/store?category=shoes#athletic , wartość atrybutu origin to https://www.example.com:8443.

W przypadku aplikacji na Androida agent użytkownika automatycznie ustawia parametr origin na podpis aplikacji wywołującej. Ten podpis powinien zostać zweryfikowany jako pasujący na Twoim serwerze, aby zweryfikować wywołującego interfejs API klucza dostępu. Nazwa Androida origin to identyfikator URI utworzony na podstawie hasza SHA-256 certyfikatu podpisywania pliku APK, np.:

android:apk-key-hash:<sha256_hash-of-apk-signing-cert>

Aby znaleźć wartości skrótów SHA-256 certyfikatów podpisujących w magazynie kluczy, uruchom to polecenie w terminalu:

keytool -list -keystore <path-to-apk-signing-keystore>

Identyfikatory SHA-256 są w formacie szesnastkowym rozdzielanym dwukropkiem (91:F7:CB:F9:D6:81…), a wartości origin na Androidzie są zakodowane w formacie base64url. Ten przykładowy kod w Pythonie pokazuje, jak przekonwertować format szyfrowania na zgodny format szesnastkowy rozdzielany dwukropkiem:

import binascii
import base64
fingerprint = '91:F7:CB:F9:D6:81:53:1B:C7:A5:8F:B8:33:CC:A1:4D:AB:ED:E5:09:C5'
print("android:apk-key-hash:" + base64.urlsafe_b64encode(binascii.a2b_hex(fingerprint.replace(':', ''))).decode('utf8').replace('=', ''))

Zastąp wartość fingerprint własną wartością. Oto przykładowy wynik:

android:apk-key-hash:kffL-daBUxvHpY-4M8yhTavt5QnFEI2LsexohxrGPYU

Następnie możesz dopasować ten ciąg znaków jako dozwolone pochodzenie na serwerze. Jeśli masz wiele certyfikatów podpisywania, np. certyfikatów do debugowania i wydania, lub wiele aplikacji, powtórz proces i zaakceptuj wszystkie te źródła jako prawidłowe na serwerze.

Zapisywanie hasła użytkownika

Jeśli użytkownik poda nazwę użytkownika i hasło w ramach procesu uwierzytelniania w aplikacji, możesz zarejestrować dane logowania użytkownika, których można użyć do jego uwierzytelnienia. Aby to zrobić, utwórz obiekt CreatePasswordRequest:

Kotlin

fun registerPassword(username: String, password: String) {
    // Initialize a CreatePasswordRequest object.
    val createPasswordRequest =
            CreatePasswordRequest(id = username, password = password)

    // Create credential and handle result.
    coroutineScope.launch {
        try {
            val result =
                credentialManager.createCredential(
                    // Use an activity based context to avoid undefined
                    // system UI launching behavior.
                    activityContext,
                    createPasswordRequest
                  )
            handleRegisterPasswordResult(result)
        } catch (e: CreateCredentialException) {
            handleFailure(e)
        }
    }
}

Java

void registerPassword(String username, String password) {
    // Initialize a CreatePasswordRequest object.
    CreatePasswordRequest createPasswordRequest =
        new CreatePasswordRequest(username, password);

    // Register the username and password.
    credentialManager.createCredentialAsync(
        // Use an activity-based context to avoid undefined
        // system UI launching behavior
        requireActivity(),
        createPasswordRequest,
        cancellationSignal,
        executor,
        new CredentialManagerCallback<CreateCredentialResponse, CreateCredentialException>() {
            @Override
            public void onResult(CreateCredentialResponse result) {
                handleResult(result);
            }

            @Override
            public void onError(CreateCredentialException e) {
                handleFailure(e);
            }
        }
    );
}

Pomoc dotycząca odzyskiwania danych logowania

Jeśli użytkownik nie ma już dostępu do urządzenia, na którym były przechowywane jego dane logowania, może być konieczne przywrócenie danych z bezpiecznej kopii zapasowej online. Aby dowiedzieć się więcej o tym, jak obsługiwać proces odzyskiwania danych logowania, przeczytaj sekcję „Odzyskiwanie dostępu lub dodawanie nowych urządzeń” w tym poście na blogu: Bezpieczeństwo kluczy dostępu w menedżerze haseł Google.

Dodanie obsługi narzędzi do zarządzania hasłami za pomocą znanych adresów URL punktów końcowych kluczy dostępu

Aby zapewnić płynną integrację i przyszłą zgodność z narzędziami do zarządzania hasłami i danymi logowania, zalecamy dodanie obsługi znanych adresów URL punktów końcowych kluczy dostępu. Jest to otwarty protokół, który umożliwia stronom formalnie reklamowanie obsługi kluczy dostępu i zapewnia bezpośrednie linki do rejestracji i zarządzania kluczami dostępu.

  1. W przypadku strony https://example.com, która ma stronę internetową oraz aplikacje na Androida i iOS, znany adres URL to https://example.com/.well-known/passkey-endpoints.

  2. Gdy zapytanie dotyczy adresu URL, odpowiedź powinna być zgodna z tym schematem:

    {
  "enroll": "https://example.com/account/manage/passkeys/create"
  "manage": "https://example.com/account/manage/passkeys"
}

  3. Aby link otwierał się bezpośrednio w aplikacji, a nie w przeglądarce, użyj linków do aplikacji na Androida.

  4. Więcej informacji znajdziesz w artykule passkey endpoints well-known URL na GitHub.

Pomagaj użytkownikom w zarządzaniu kluczami dostępu, pokazując, który dostawca je utworzył

Jednym z wyzwań, z którymi użytkownicy mierzą się podczas zarządzania wieloma kluczami powiązanymi z danym programem, jest identyfikacja właściwego klucza do edycji lub usunięcia. Aby pomóc w rozwiązaniu tego problemu, zalecamy, aby aplikacje i witryny zawierały dodatkowe informacje, takie jak nazwa dostawcy, data utworzenia i data ostatniego użycia na liście kluczy dostępu na ekranie ustawień aplikacji.Informacje o dostawcy można uzyskać, analizując identyfikator AAGUID powiązany z odpowiednim kluczem dostępu. Identyfikator AAGUID można znaleźć w danych uwierzytelniania klucza dostępu.

Jeśli na przykład użytkownik utworzy klucz dostępu na urządzeniu z Androidem za pomocą Menedżera haseł Google, RP otrzyma identyfikator AAGUID, który wygląda mniej więcej tak: „ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4”. Uwierzyciel może dodać adnotację do klucza dostępu na liście kluczy dostępu, aby wskazać, że został on utworzony za pomocą Menedżera haseł Google.

Aby zmapować identyfikator AAGUID do dostawcy kluczy dostępu, dostawcy kluczy dostępu mogą skorzystać z repozytorium AAGUID udostępnionego przez społeczność. Aby znaleźć nazwę i ikonę dostawcy kluczy dostępu, wyszukaj identyfikator AAGUID na liście.

Dowiedz się więcej o integracji z AAGUID.

Rozwiązywanie typowych problemów

Więcej informacji o typowych kodach błędów, ich opisie i przyczynach znajdziesz w przewodniku dotyczącym rozwiązywania problemów z Menedżerem poświadczeń.

Dodatkowe materiały

Więcej informacji o interfejsie Credential Manager API i kluczach dostępu znajdziesz w tych materiałach: