Przewodnik dla programistów poświęcony interfejsowi sfederowanego interfejsu Credential Management API

Dowiedz się, jak używać FedCM do federacji tożsamości chroniących prywatność.

FedCM (Federated Credential Management) to rozwiązanie chroniące prywatność usług sfederowanych usług tożsamości (np. „Zaloguj się przez...”), w których użytkownicy mogą logować się w witrynach bez udostępniania swoich danych osobowych usłudze tożsamości lub witrynie.

Więcej informacji o przypadkach użycia, przepływach użytkowników i planach działania FedCM znajdziesz we wprowadzeniu do FedCM API.

Środowisko programistyczne FedCM

Aby korzystać z FedCM, potrzebujesz bezpiecznego kontekstu (HTTPS lub localhost) zarówno u dostawcy tożsamości, jak i RP w Chrome.

Debugowanie kodu w Chrome na Androidzie

Skonfiguruj i uruchom serwer lokalnie, aby debugować kod FedCM. Możesz uzyskać dostęp do tego serwera w Chrome na urządzeniu z Androidem podłączonym kablem USB z przekierowaniem portów.

Aby debugować Chrome na urządzeniu z Androidem, możesz użyć Narzędzi deweloperskich na komputerze. Instrukcje znajdziesz w artykule Zdalne debugowanie urządzeń z Androidem.

Blokowanie plików cookie innych firm w Chrome

Symulowanie wycofania plików cookie innych firm przez skonfigurowanie ich w Chrome
Symuluj wycofanie plików cookie innych firm, konfigurując ich blokowanie w Chrome

Możesz sprawdzić, jak FedCM działa w Chrome bez plików cookie innych firm, zanim zostanie w pełni egzekwowane.

Aby zablokować pliki cookie innych firm, użyj trybu incognito lub wybierz „Blokuj pliki cookie innych firm” w ustawieniach komputera na chrome://settings/cookies albo na urządzeniu mobilnym, klikając Ustawienia > Ustawienia witryn > Pliki cookie.

Korzystanie z interfejsu FedCM API

Integrację z FedCM możesz przeprowadzić, tworząc dobrze znany plik, plik konfiguracji i punkty końcowe na potrzeby listy kont, tworzenia asercji i opcjonalnie metadanych klienta.

Następnie FedCM udostępnia interfejsy API JavaScript, których członkowie RP mogą używać do logowania się u dostawcy tożsamości.

Utwórz dobrze znany plik

Aby moduły śledzące nie nadużywały interfejsu API, musi być udostępniany dobrze znany plik z /.well-known/web-identity eTLD+1 dostawcy tożsamości.

Jeśli na przykład punkty końcowe dostawcy tożsamości są udostępniane w domenie https://accounts.idp.example/, muszą udostępniać dobrze znany plik pod adresem https://idp.example/.well-known/web-identity, a także plik konfiguracyjny dostawcy tożsamości. Oto przykład dobrze znanej zawartości pliku:

{
  "provider_urls": ["https://accounts.idp.example/config.json"]
}

Plik JSON musi zawierać właściwość provider_urls z tablicą adresów URL pliku konfiguracyjnego dostawcy tożsamości, które można określić jako część ścieżki configURL w navigator.credentials.get przez RP. Liczba ciągów adresów URL w tablicy jest ograniczona do jednego, ale w przyszłości może się to zmienić wraz z Twoją opinią.

Tworzenie pliku konfiguracyjnego dostawcy tożsamości i punktów końcowych

Plik konfiguracji dostawcy tożsamości zawiera listę punktów końcowych wymaganych dla przeglądarki. Dostawcy tożsamości będą hostować ten plik konfiguracyjny oraz wymagane punkty końcowe i adresy URL. Wszystkie odpowiedzi JSON muszą być udostępniane z typem treści application/json.

Adres URL pliku konfiguracji jest określany na podstawie wartości podanych w wywołaniu navigator.credentials.get wykonanego w grupie objętej ograniczeniami.

const credential = await navigator.credentials.get({
  identity: {
    context: 'signup',
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

Podaj pełny adres URL lokalizacji pliku konfiguracji dostawcy tożsamości w polu configURL. Po wywołaniu navigator.credentials.get() w RP przeglądarka pobiera plik konfiguracyjny z żądaniem GET bez nagłówka Origin ani nagłówka Referer. Żądanie nie ma plików cookie ani nie śledzi przekierowań. Dzięki temu dostawca tożsamości nie może się dowiedzieć, kto wysłał żądanie i które strony objęły próbę połączenia. Na przykład:

GET /config.json HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity

Przeglądarka oczekuje od dostawcy tożsamości odpowiedzi JSON, która zawiera te właściwości:

Właściwość Opis
accounts_endpoint (wymagane) URL punktu końcowego kont.
client_metadata_endpoint (opcjonalnie) URL punktu końcowego metadanych klienta.
id_assertion_endpoint (wymagane) URL punktu końcowego potwierdzenia identyfikatora.
disconnect (opcjonalnie) URL odłączanego punktu końcowego.
login_url (wymagane) Adres URL strony logowania, który umożliwia użytkownikowi zalogowanie się u dostawcy tożsamości.
branding (opcjonalnie) Obiekt zawierający różne opcje marki.
branding.background_color (opcjonalnie) Opcja marki, która ustawia kolor tła przycisku „Kontynuuj jako...”. Użyj odpowiedniej składni CSS: hex-color, hsl(), rgb() lub named-color.
branding.color (opcjonalnie) Opcja marki, która ustawia kolor tekstu przycisku „Kontynuuj jako...”. Użyj odpowiedniej składni CSS: hex-color, hsl(), rgb() lub named-color.
branding.icons (opcjonalnie) Opcja marki, która ustawia obiekt ikony wyświetlany w oknie logowania. Obiekt ikony to tablica z 2 parametrami:
  • url (wymagany): URL obrazu ikony. Obrazy SVG nie są obsługiwane.
  • size (opcjonalnie): wymiary ikony, przyjęte przez aplikację jako kwadrat i w jednej rozdzielczości. Ta liczba nie może być mniejsza niż 25.

RP może zmodyfikować ciąg w interfejsie okna FedCM za pomocą wartości identity.context dla navigator.credentials.get(), aby dostosować go do zdefiniowanych wstępnie kontekstów uwierzytelniania. Opcjonalną właściwością może być "signin" (domyślna), "signup", "use" lub "continue".

Stosowanie marki w oknie FedCM
Jak promowanie marki jest stosowane w oknie FedCM

Przykładowa treść odpowiedzi od dostawcy tożsamości:

{
  "accounts_endpoint": "/accounts.php",
  "client_metadata_endpoint": "/client_metadata.php",
  "id_assertion_endpoint": "/assertion.php",
  "disconnect_endpoint": "/disconnect.php",
  "login_url": "/login",
  "branding": {
    "background_color": "green",
    "color": "#FFEEAA",
    "icons": [{
      "url": "https://idp.example/icon.ico",
      "size": 25
    }]
  }
}

Gdy przeglądarka pobierze plik konfiguracyjny, wysyła kolejne żądania do punktów końcowych dostawcy tożsamości:

Punkty końcowe dostawcy tożsamości
Punkty końcowe dostawcy tożsamości

Punkt końcowy kont

Punkt końcowy kont dostawcy tożsamości zwraca listę kont, na których użytkownik jest obecnie zalogowany u dostawcy tożsamości. Jeśli dostawca tożsamości obsługuje wiele kont, ten punkt końcowy zwróci wszystkie zalogowane konta.

Przeglądarka wysyła żądanie GET z plikami cookie z elementem SameSite=None, ale bez parametru client_id, nagłówka Origin lub Referer. Dzięki temu dostawca tożsamości nie będzie mógł się dowiedzieć, do której grupy objętej ograniczeniami próbuje się zalogować. Na przykład:

GET /accounts.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

Po otrzymaniu żądania serwer powinien:

  1. Sprawdź, czy żądanie zawiera nagłówek HTTP Sec-Fetch-Dest: webidentity.
  2. Dopasuj pliki cookie sesji do identyfikatorów kont, na których jesteś już zalogowanym użytkownikiem.
  3. W odpowiedzi podaj listę kont.

Przeglądarka oczekuje odpowiedzi JSON, która będzie zawierać właściwość accounts z tablicą informacji o koncie o tych właściwościach:

Właściwość Opis
id (wymagane) Unikalny identyfikator użytkownika.
name (wymagane) Imię i nazwisko użytkownika.
email (wymagane) Adres e-mail użytkownika.
given_name (opcjonalnie) Imię użytkownika.
picture (opcjonalnie) Adres URL awatara użytkownika.
approved_clients (opcjonalnie) Tablica identyfikatorów klientów RP, za pomocą których użytkownik zarejestrował się.
login_hints (opcjonalnie) Tablica wszystkich możliwych typów filtrów obsługiwanych przez dostawcę tożsamości w celu określenia konta. Grupa z ograniczonym dostępem może wywołać navigator.credentials.get() z usługą loginHint, by wybiórczo wyświetlić określone konto.
domain_hints (opcjonalnie) Tablica ze wszystkimi domenami, z którymi powiązane jest konto. Grupa z ograniczonym dostępem może wywołać filtr navigator.credentials.get() za pomocą właściwości domainHint, by odfiltrować konta.

Przykładowa treść odpowiedzi:

{
  "accounts": [{
    "id": "1234",
    "given_name": "John",
    "name": "John Doe",
    "email": "john_doe@idp.example",
    "picture": "https://idp.example/profile/123",
    "approved_clients": ["123", "456", "789"],
    "login_hints": ["demo1", "demo1@idp.example"]
  }, {
    "id": "5678",
    "given_name": "Johnny",
    "name": "Johnny",
    "email": "johnny@idp.example",
    "picture": "https://idp.example/profile/456",
    "approved_clients": ["abc", "def", "ghi"],
    "login_hints": ["demo2", "demo2@idp.example"],
    "domain_hints": ["corp.example"]
  }]
}

Jeśli użytkownik nie jest zalogowany, w odpowiedzi prześlij kod HTTP 401 (Brak autoryzacji).

Zwrócona lista kont jest wykorzystywana przez przeglądarkę i nie jest dostępna dla grupy objętej ograniczeniami.

Punkt końcowy metadanych klienta

Punkt końcowy metadanych klienta dostawcy tożsamości zwraca metadane jednostki uzależnionej, takie jak polityka prywatności i warunki korzystania z usługi objętej ograniczeniami. Dostawcy tożsamości powinni z wyprzedzeniem udostępnić mu linki do swojej polityki prywatności i warunków korzystania z usługi. Te linki są wyświetlane w oknie logowania, gdy użytkownik nie zarejestrował się jeszcze w grupie objętej ograniczeniami u dostawcy tożsamości.

Przeglądarka wysyła żądanie GET, korzystając z metody client_id navigator.credentials.get bez plików cookie. Na przykład:

GET /client_metadata.php?client_id=1234 HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Accept: application/json
Sec-Fetch-Dest: webidentity

Po otrzymaniu żądania serwer powinien:

  1. Określ RP dla: client_id.
  2. W odpowiedzi użyj metadanych klienta.

Właściwości punktu końcowego metadanych klienta obejmują:

Właściwość Opis
privacy_policy_url (opcjonalnie) Adres URL polityki prywatności grupy objętej ograniczeniami.
terms_of_service_url (opcjonalnie) URL warunków korzystania z usługi objętej ograniczeniami.

Przeglądarka oczekuje odpowiedzi JSON z punktu końcowego:

{
  "privacy_policy_url": "https://rp.example/privacy_policy.html",
  "terms_of_service_url": "https://rp.example/terms_of_service.html",
}

Zwrócone metadane klienta są wykorzystywane przez przeglądarkę i nie będą dostępne dla grupy objętej ograniczeniami.

Punkt końcowy potwierdzenia identyfikatora

Punkt końcowy potwierdzenia identyfikatora dostawcy tożsamości zwraca potwierdzenie dla zalogowanego użytkownika. Gdy użytkownik loguje się w witrynie objętej ograniczeniami, korzystając z wywołania navigator.credentials.get(), przeglądarka wysyła do tego punktu końcowego żądanie POST z plikami cookie SameSite=None i typem treści application/x-www-form-urlencoded z tymi informacjami:

Właściwość Opis
client_id (wymagane) Identyfikator klienta strony objętej ograniczeniami.
account_id (wymagane) Unikalny identyfikator zalogowanego użytkownika.
nonce (opcjonalnie) Liczba jednorazowa żądania podana przez grupę z ograniczonym dostępem.
disclosure_text_shown Wynikiem jest ciąg "true" lub "false" (a nie wartość logiczna). Jeśli tekst oświadczenia nie został wyświetlony, otrzymasz wynik "false". Dzieje się tak, gdy identyfikator klienta grupy objętej ograniczeniami znajduje się na liście właściwości approved_clients w odpowiedzi z punktu końcowego konta lub jeśli w przeszłości przeglądarka zaobserwowała moment rejestracji w przeszłości z powodu braku wartości approved_clients.
is_auto_selected Jeśli w RPA wykonywane jest automatyczne ponowne uwierzytelnianie, is_auto_selected wskazuje "true". W przeciwnym razie "false". Dzięki temu będziemy mogli obsługiwać więcej funkcji związanych z bezpieczeństwem. Na przykład niektórzy użytkownicy mogą preferować wyższy poziom zabezpieczeń, który wymaga jawnego mediacji użytkowników podczas uwierzytelniania. Jeśli dostawca tożsamości otrzyma żądanie tokena bez zapośredniczenia, może je obsłużyć inaczej. Może to być na przykład zwrócenie kodu błędu, tak by grupa RP mogła ponownie wywołać interfejs FedCM API z parametrem mediation: required.

Przykładowy nagłówek HTTP:

POST /assertion.php HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true&is_auto_selected=true

Po otrzymaniu żądania serwer powinien:

  1. Odpowiedz na żądanie za pomocą funkcji CORS (Udostępnianie zasobów w różnych źródłach).
  2. Sprawdź, czy żądanie zawiera nagłówek HTTP Sec-Fetch-Dest: webidentity.
  3. Dopasuj nagłówek Origin do punktu początkowego RP określonego przez client_id. Odrzuć, jeśli nie pasują.
  4. Dopasuj adres account_id do identyfikatora konta, na którym jesteś już zalogowanym użytkownikiem. Odrzuć, jeśli nie pasują.
  5. Odpowiedz tokenem. Jeśli żądanie zostanie odrzucone, wyślij odpowiedź o błędzie.

Sposób przyznawania tokena zależy od dostawcy tożsamości, ale ogólnie jest on podpisany za pomocą takich informacji jak identyfikator konta, identyfikator klienta, źródło wydawcy nonce, dzięki czemu platforma z ograniczonym dostępem może zweryfikować autentyczność tokena.

Przeglądarka oczekuje odpowiedzi JSON, która będzie zawierać tę właściwość:

Właściwość Opis
token (wymagane) Token to ciąg znaków zawierający deklaracje dotyczące uwierzytelniania. 
{
  "token": "***********"
}

Zwrócony token jest przekazywany do grupy objętej ograniczeniami przez przeglądarkę, aby jej członkowie mogli zweryfikować uwierzytelnianie.

Zwracanie odpowiedzi o błędzie

id_assertion_endpoint może też zwrócić odpowiedź „błąd”, która ma 2 opcjonalne pola:

  • code: dostawca tożsamości może wybrać jeden ze znanych błędów z listy błędów określonej przez OAuth 2.0 (invalid_request, unauthorized_client, access_denied, server_error i temporarily_unavailable) lub użyć dowolnego ciągu znaków. Chrome renderuje wtedy interfejs błędu z ogólnym komunikatem o błędzie i przekazuje kod do RP.
  • url: identyfikuje czytelną dla człowieka stronę internetową z informacjami o błędzie, aby przekazać użytkownikom dodatkowe informacje o błędzie. To pole jest przydatne dla użytkowników, ponieważ przeglądarki nie zapewniają szczegółowych komunikatów o błędach w natywnym interfejsie użytkownika. Mogą to być na przykład linki do dalszych kroków, dane kontaktowe obsługi klienta itd. Jeśli użytkownik chce dowiedzieć się więcej o błędzie i sposobie jego naprawienia, może odwiedzić podaną stronę w interfejsie przeglądarki, aby uzyskać więcej informacji. Adres URL musi być w tej samej witrynie co dostawca tożsamości configURL.
// id_assertion_endpoint response
{
  "error" : {
     "code": "access_denied",
     "url" : "https://idp.example/error?type=access_denied"
  }
}

Odłącz punkt końcowy

Wywołując IdentityCredential.disconnect(), przeglądarka wysyła do tego rozłączonego punktu końcowego żądanie POST z innymi domenami z plikami cookie (SameSite=None i typem treści application/x-www-form-urlencoded) zawierające te informacje:

Właściwość Opis
account_hint Podpowiedź dotycząca konta dostawcy tożsamości...
client_id Identyfikator klienta strony objętej ograniczeniami. 
POST /disconnect.php HTTP/1.1
Host: idp.example
Origin: rp.example
Content-Type: application/x-www-form-urlencoded
Cookie: 0x123
Sec-Fetch-Dest: webidentity

account_hint=account456&client_id=rp123

Po otrzymaniu żądania serwer powinien:

  1. Odpowiedz na żądanie za pomocą funkcji CORS (Udostępnianie zasobów w różnych źródłach).
  2. Sprawdź, czy żądanie zawiera nagłówek HTTP Sec-Fetch-Dest: webidentity.
  3. Dopasuj nagłówek Origin do punktu początkowego RP określonego przez client_id. Odrzuć, jeśli nie pasują.
  4. Dopasuj account_hint do identyfikatorów kont, na których jesteś już zalogowanym użytkownikiem.
  5. Odłącz konto użytkownika od RP.
  6. Odpowiedz przeglądarce, podając zidentyfikowane informacje o koncie użytkownika w formacie JSON.

Przykładowy ładunek JSON odpowiedzi wygląda tak:

{
  "account_id": "account456"
}

Jeśli dostawca tożsamości chce, aby przeglądarka rozłączyła wszystkie konta powiązane z grupą objętych ograniczeniami, podaj ciąg znaków, który nie pasuje do żadnego identyfikatora konta, na przykład "*".

URL logowania

Za pomocą interfejsu Login Status API dostawca tożsamości musi informować o stanie logowania użytkownika w przeglądarce. Może on jednak być niezsynchronizowany, na przykład sesja wygasa. W takiej sytuacji przeglądarka może dynamicznie zezwolić użytkownikowi na logowanie się u dostawcy tożsamości za pomocą adresu URL strony logowania określonego w pliku login_url pliku konfiguracji dostawcy tożsamości.

W oknie FedCM pojawi się komunikat z sugestią zalogowania się, tak jak na ilustracji poniżej.

O
Okno FedCM z prośbą o zalogowanie się u dostawcy tożsamości.

Gdy użytkownik kliknie przycisk Dalej, w przeglądarce otworzy się wyskakujące okienko ze stroną logowania dostawcy tożsamości.

An
Przykładowe okno wyświetlane po kliknięciu przycisku logowania się przy użyciu przycisku dostawcy tożsamości.

Okno to zwykłe okno przeglądarki zawierające własne pliki cookie. Wszystko, co stanie się w oknie, zależy od dostawcy tożsamości. Żadne uchwyty okien nie są dostępne, aby wysłać żądanie komunikacji między domenami do strony RP. Po zalogowaniu się użytkownika dostawca tożsamości powinien:

  • Wyślij nagłówek Set-Login: logged-in lub wywołaj interfejs API navigator.login.setStatus("logged-in"), aby poinformować przeglądarkę o zalogowaniu użytkownika.
  • Wywołaj IdentityProvider.close(), aby zamknąć okno.
.
O
Użytkownik loguje się w grupie objętej ograniczeniami po zalogowaniu się u dostawcy tożsamości przy użyciu FedCM.

Informuj przeglądarkę o stanie logowania użytkownika u dostawcy tożsamości

Interfejs API stanu logowania to mechanizm, w ramach którego witryna, a zwłaszcza dostawca tożsamości, informuje przeglądarkę o stanie logowania użytkownika u dostawcy tożsamości. Dzięki temu interfejsowi przeglądarka może ograniczyć liczbę niepotrzebnych żądań wysyłanych do dostawcy tożsamości i łagodzić potencjalne ataki czasowe.

Dostawcy tożsamości mogą informować przeglądarkę o stanie logowania użytkownika, wysyłając nagłówek HTTP lub wywołując interfejs JavaScript API, gdy użytkownik jest zalogowany w tym dostawcy lub gdy użytkownik jest wylogowany ze wszystkich swoich kont dostawcy tożsamości. W przypadku każdego dostawcy tożsamości (identyfikowanego na podstawie adresu URL konfiguracji) przeglądarka przechowuje zmienną trójstanową reprezentującą stan logowania z możliwymi wartościami logged-in, logged-out i unknown. Stan domyślny to unknown.

Aby zasygnalizować, że użytkownik jest zalogowany, wyślij nagłówek HTTP Set-Login: logged-in w nawigacji najwyższego poziomu lub w żądaniu zasobu podrzędnego tej samej witryny w źródle dostawcy tożsamości:

Set-Login: logged-in

Możesz też wywołać JavaScript API navigator.login.setStatus("logged-in") ze źródła dostawcy tożsamości w nawigacji najwyższego poziomu:

navigator.login.setStatus("logged-in")

Te połączenia rejestrują stan logowania użytkownika jako logged-in. Gdy stan logowania użytkownika jest ustawiony na logged-in, FedCM wywołująca RP wysyła żądania do punktu końcowego konta dostawcy tożsamości i wyświetla użytkownikowi dostępne konta w oknie FedCM.

Aby zasygnalizować, że użytkownik jest wylogowany ze wszystkich kont, wyślij nagłówek HTTP Set-Login: logged-out w panelu nawigacyjnym najwyższego poziomu lub żądanie zasobu podrzędnego tej samej witryny w źródle dostawcy tożsamości:

Set-Login: logged-out

Możesz też wywołać JavaScript API navigator.login.setStatus("logged-out") ze źródła dostawcy tożsamości w nawigacji najwyższego poziomu:

navigator.login.setStatus("logged-out")

Te połączenia rejestrują stan logowania użytkownika jako logged-out. Jeśli stan logowania użytkownika to logged-out, wywołanie usługi FedCM nie powiedzie się bez wysyłania żądania do punktu końcowego konta dostawcy tożsamości.

Stan unknown jest ustawiany, zanim dostawca tożsamości wyśle sygnał za pomocą interfejsu Login Status API. Wprowadziliśmy Unknown w celu ułatwienia migracji, ponieważ użytkownik mógł już zalogować się u dostawcy tożsamości, gdy ten interfejs API został wysłany. Dostawca tożsamości może nie mieć możliwości zasygnalizowania tego do przeglądarki przed pierwszym wywołaniem FedCM. W takim przypadku Chrome wysyła żądanie do punktu końcowego konta dostawcy tożsamości i aktualizuje stan na podstawie odpowiedzi z punktu końcowego kont:

  • Jeśli punkt końcowy zwraca listę aktywnych kont, zmień stan na logged-in i otwórz okno FedCM, aby je wyświetlić.
  • Jeśli punkt końcowy nie zwraca żadnych kont, zaktualizuj stan na logged-out – w przeciwnym razie wywołanie FedCM się nie uda.

Umożliwienie użytkownikowi logowania się w ramach dynamicznego procesu logowania

Mimo że dostawca tożsamości stale informuje przeglądarkę o stanie logowania użytkownika, może ona nie być zsynchronizowana, na przykład o wygaśnięciu sesji. Gdy stan logowania to logged-in, przeglądarka próbuje wysłać do punktu końcowego konta żądanie danych uwierzytelniających, ale serwer nie zwraca żadnych kont, ponieważ sesja nie jest już dostępna. W takiej sytuacji przeglądarka może dynamicznie zezwolić użytkownikowi na logowanie się w dostawcy tożsamości przez wyskakujące okienko.

Zaloguj się na stronie uzależnionej przy użyciu dostawcy tożsamości

Gdy konfiguracja i punkty końcowe dostawcy tożsamości są dostępne, grupy objęte ograniczeniami mogą wywołać navigator.credentials.get(), aby poprosić użytkowników o zalogowanie się w tej usłudze z jej dostawcą.

Przed wywołaniem interfejsu API musisz potwierdzić, że usługa [FedCM jest dostępna w przeglądarce użytkownika]. Aby sprawdzić, czy usługa FedCM jest dostępna, otocz implementację FedCM tym kodem:

if ('IdentityCredential' in window) {
  // If the feature is available, take action
}

Aby poprosić użytkowników o umożliwienie logowania się do dostawcy tożsamości z grupy objętej ograniczeniami, wykonaj te czynności:

const credential = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

Właściwość providers pobiera tablicę IdentityProvider obiektów, które mają te właściwości:

Właściwość Opis
configURL (wymagane) Pełna ścieżka pliku konfiguracyjnego dostawcy tożsamości.
clientId (wymagane) Identyfikator klienta strony objętej ograniczeniami wystawiony przez dostawcę tożsamości.
nonce (opcjonalnie) Losowy ciąg znaków, który gwarantuje, że w przypadku tego konkretnego żądania zostanie wysłana odpowiedź. Zapobiega atakom metodą powtórzenia.
loginHint (opcjonalnie) Gdy określisz jedną z wartości login_hints podanych przez punkty końcowe konta, w oknie FedCM wyświetli się wybrane konto.
domainHint (opcjonalnie) Gdy określisz jedną z wartości domain_hints podanych przez punkty końcowe konta, w oknie FedCM wyświetli się wybrane konto.

Przeglądarka obsługuje przypadki rejestracji i logowania w różny sposób – w zależności od tego, czy w odpowiedzi z punktu końcowego listy kont występuje element approved_clients. Jeśli użytkownik zarejestrował się już w grupie objętej ograniczeniami, przeglądarka nie wyświetli komunikatu „Aby kontynuować...”.

Stan rejestracji zależy od tego, czy spełnione są te warunki:

  • Jeśli approved_clients obejmuje grupę objętą ograniczeniami: clientId.
  • jeśli przeglądarka pamięta, że użytkownik zarejestrował się już w grupie objętej ograniczeniami.
Użytkownik loguje się w grupie objętej ograniczeniami przy użyciu FedCM

Gdy grupa z ograniczonym dostępem wywołuje navigator.credentials.get(), wykonywane są te działania:

  1. Przeglądarka wysyła żądania i pobiera kilka dokumentów:
    1. Dobrze znany plik i plik konfiguracyjny dostawcy tożsamości, które deklarują punkty końcowe.
    2. Lista kont.
    3. Opcjonalnie: adresy URL polityki prywatności i warunków korzystania z usługi objętej ograniczeniami zostały pobrane z punktu końcowego metadanych klienta.
  2. Przeglądarka wyświetli listę kont, na których użytkownik może się zalogować, a także warunki korzystania z usługi i politykę prywatności (jeśli są dostępne).
  3. Gdy użytkownik wybierze konto, za pomocą którego ma się zalogować, do dostawcy tożsamości zostanie wysłane żądanie do punktu końcowego potwierdzenia identyfikatora w celu pobrania tokena.
  4. RP może zweryfikować token, by uwierzytelnić użytkownika.
wywołanie interfejsu API loginu
Wywołanie interfejsu Login API

RP powinny obsługiwać przeglądarki, które nie obsługują FedCM. Dlatego użytkownicy powinni mieć możliwość korzystania z dotychczasowego procesu logowania się z innego systemu niż FedCM. Dopóki pliki cookie innych firm nie zostaną całkowicie wycofane, nie powinno to stanowić problemu.

Gdy token zostanie zweryfikowany przez serwer RP, grupa z ograniczonym dostępem może zarejestrować użytkownika lub zezwolić mu na zalogowanie się i rozpoczęcie nowej sesji.

Interfejs API podpowiedzi logowania

Czasami po zalogowaniu się strona uzależniona (RP) prosi użytkownika o ponowne uwierzytelnienie. Użytkownik może jednak nie być pewny, z którego konta korzystał. Jeśli w grupie objętej ograniczeniami można określić konto, za pomocą którego ma się zalogować, użytkownik będzie łatwiej wybrać konto.

Grupy objęte ograniczeniami mogą wyświetlać określone konto, wywołując navigator.credentials.get() z właściwością loginHint z jedną z wartości login_hints pobranych z punktu końcowego listy kont, jak w tym przykładowym kodzie:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      nonce: nonce,
      loginHint : "demo1@example.com"
    }]
  }
});

Gdy żadne konto nie pasuje do loginHint, w oknie FedCM wyświetla się prośba o zalogowanie. Użytkownik może zalogować się na konto dostawcy tożsamości odpowiadające wskazówce wymaganej przez grupę objętą ograniczeniami. Gdy użytkownik kliknie tę prośbę, otworzy się wyskakujące okienko z adresem URL logowania określonym w pliku konfiguracyjnym. Do linku jest następnie dołączana wskazówka dotycząca logowania i parametry zapytania takie jak domena.

Interfejs API Site Hint

W niektórych przypadkach przedstawiciel RP wie, że w witrynie mogą się logować tylko konta powiązane z konkretną domeną. Jest to szczególnie częste w scenariuszach biznesowych, gdy dostęp do witryny jest ograniczony do domeny firmowej. Aby zwiększyć wygodę użytkowników, interfejs API FedCM pozwala na wyświetlanie tylko tych kont, za pomocą których można się do niej zalogować. Zapobiega to sytuacji, w której użytkownik próbuje zalogować się w grupie objętej ograniczeniami, używając konta spoza domeny firmowej. Komunikat o błędzie pojawia się później (lub gdy logowanie nie zadziałało), bo nie używa się odpowiedniego typu konta.

Grupy objęte ograniczeniami mogą wyświetlać tylko pasujące konta, wywołując navigator.credentials.get() z właściwością domainHint z jedną z wartości domain_hints pobranych z punktu końcowego listy kont, jak w tym przykładowym kodzie:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "abc",
      nonce: nonce,
      domainHint : "corp.example"
    }]
  }
});

Gdy żadne konto nie pasuje do domainHint, w oknie FedCM wyświetla się prośba o zalogowanie. Użytkownik może zalogować się na konto dostawcy tożsamości odpowiadające wskazówce wymaganej przez grupę objętą ograniczeniami. Gdy użytkownik kliknie tę prośbę, otworzy się wyskakujące okienko z adresem URL logowania określonym w pliku konfiguracyjnym. Do linku jest następnie dołączana wskazówka dotycząca logowania i parametry zapytania takie jak domena.

Przykładowy komunikat o logowaniu, gdy żadne konto nie jest zgodne z wskazówką domainHint.
Przykładowy komunikat o zalogowaniu się, gdy żadne konto nie jest zgodne z polem domainHint.

Pokaż komunikat o błędzie

Czasami dostawca tożsamości może nie być w stanie wystawić tokena z uzasadnionych powodów, na przykład gdy klient jest autoryzowany, serwer jest tymczasowo niedostępny. Jeśli dostawca tożsamości zwróci odpowiedź „error” (błąd), witryna z ograniczonym dostępem może ją przechwycić, a Chrome powiadomi użytkownika o tym, wyświetlając interfejs przeglądarki z informacjami o błędach podanymi przez dostawcę tożsamości.

O
Okno FedCM z wyświetlonym komunikatem o błędzie po nieudanej próbie zalogowania się użytkownika. Ciąg jest powiązany z typem błędu.
try {
  const cred = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: "https://idp.example/manifest.json",
          clientId: "1234",
        },
      ],
    }
  });
} catch (e) {
  const code = e.code;
  const url = e.url;
}

Automatyczne ponowne uwierzytelnianie użytkowników po uzyskaniu pierwszej zgody

Automatyczne ponowne uwierzytelnianie w FedCM (w skrócie „automatyczne ponowne uwierzytelnianie”) umożliwia użytkownikom automatyczne ponowne uwierzytelnianie, gdy wracają po pierwszym uwierzytelnieniu za pomocą FedCM. „Wstępne uwierzytelnienie” oznacza, że użytkownik tworzy konto lub loguje się na stronie RP, klikając przycisk „Kontynuuj jako...” w oknie logowania FedCM w tej samej instancji przeglądarki.

Wrażenia użytkownika powinny mieć sens jeszcze przed utworzeniem sfederowanego konta i uniemożliwiać śledzenie (co jest jednym z głównych celów FedCM). Jednak gdy użytkownik już raz je przeczyta, takie działania są niepotrzebnie niewygodne: gdy użytkownik udzieli zgody na komunikację między grupą objętą usługą a dostawcą tożsamości, nie spowoduje to żadnych korzyści w zakresie prywatności ani bezpieczeństwa wymuszonego już wcześniej innego użytkownika, który potwierdził już wcześniej coś, co zostało wcześniej potwierdzone.

Gdy włączone jest automatyczne ponowne uwierzytelnianie, przeglądarka zmienia swoje działanie w zależności od opcji określonej dla mediation podczas wywoływania funkcji navigator.credentials.get().

const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/fedcm.json",
      clientId: "1234",
    }],
  },
  mediation: 'optional', // this is the default
});

// `isAutoSelected` is `true` if auto-reauthn was performed.
const isAutoSelected = cred.isAutoSelected;

Element mediation jest właściwością interfejsu Credential Management API. Działa w taki sam sposób jak w przypadku elementów PasswordCredential i FederatedCredential oraz jest częściowo obsługiwana przez funkcję PublicKeyCredential. Właściwość może przyjmować te 4 wartości:

  • 'optional'(ustawienie domyślne): jeśli to możliwe, automatyczne ponowne uwierzytelnianie. Jeśli nie jest, wymagane jest zapośredniczenie. Zalecamy wybranie tej opcji na stronie logowania.
  • 'required': kontynuowanie zawsze wymaga zapośredniczenia, np. przez kliknięcie przycisku „Dalej” w interfejsie. Wybierz tę opcję, jeśli użytkownicy mają przyznawać uprawnienia bezpośrednio za każdym razem, gdy muszą zostać uwierzytelnieni.
  • 'silent': w miarę możliwości automatyczne ponowne uwierzytelnianie. Jeśli nie jest wymagane zapośredniczenie, kończy się to niepowodzeniem. Zalecamy wybranie tej opcji na innych stronach niż strona logowania, ale na których chcesz nie wylogowywać użytkowników. Może to być na przykład strona produktu w witrynie wysyłkowej lub strona z artykułem w witrynie z wiadomościami.
  • 'conditional': używana na potrzeby WebAuthn, a w tej chwili niedostępna w FedCM.

W przypadku tego wywołania automatyczne ponowne uwierzytelnianie odbywa się w tych warunkach:

  • Usługa FedCM jest dostępna. Na przykład użytkownik nie wyłączył FedCM zarówno globalnie, ani dla RP w ustawieniach.
  • Użytkownik użył tylko jednego konta z interfejsem FedCM API, aby zalogować się na stronie w tej przeglądarce.
  • Użytkownik jest zalogowany u dostawcy tożsamości przy użyciu tego konta.
  • Automatyczne ponowne uwierzytelnianie nie miało miejsca w ciągu ostatnich 10 minut.
  • Grupa z ograniczonym dostępem nie wywołała jeszcze navigator.credentials.preventSilentAccess() po poprzednim zalogowaniu.

Gdy te warunki są spełnione, próba automatycznego ponownego uwierzytelnienia użytkownika rozpoczyna się zaraz po wywołaniu funkcji navigator.credentials.get() w FedCM.

Jeśli ustawiona jest wartość mediation: optional, automatyczne ponowne uwierzytelnianie może być niedostępne z powodów, o których wie tylko przeglądarka. RPA może sprawdzić, czy automatyczne ponowne uwierzytelnianie jest wykonywane, sprawdzając właściwość isAutoSelected.

Pozwala to ocenić wydajność interfejsu API i odpowiednio poprawić wygodę użytkowników. Poza tym gdy ta wartość jest niedostępna, użytkownik może zobaczyć prośbę o zalogowanie się w ramach zapośredniczenia użytkownika, które jest realizowane w ramach mediation: required.

Automatyczne uwierzytelnianie użytkownika przez FedCM.

Egzekwuj zapośredniczenie na koncie preventSilentAccess()

Automatyczne ponowne uwierzytelnianie użytkowników natychmiast po tym, jak się wylogują, nie zapewniłoby im wygodnej obsługi. Dlatego po automatycznym uwierzytelnieniu usługa FedCM stosuje 10-minutowy okres bez powiadomień, aby temu zapobiec. Oznacza to, że automatyczne ponowne uwierzytelnianie odbywa się co najwyżej raz na 10 minut, chyba że użytkownik zaloguje się ponownie w ciągu 10 minut. Grupa z ograniczonym dostępem powinna wywołać navigator.credentials.preventSilentAccess(), by wprost zażądać od przeglądarki wyłączenia automatycznego ponownego uwierzytelniania, gdy użytkownik wyraźnie wyloguje się z grupy objętej ograniczeniami, na przykład przez kliknięcie przycisku wylogowania.

function signout() {
  navigator.credentials.preventSilentAccess();
  location.href = '/signout';
}

Użytkownicy mogą zrezygnować z automatycznego ponownego uwierzytelniania w ustawieniach

Użytkownicy mogą zrezygnować z automatycznego ponownego uwierzytelniania w menu ustawień:

  • W przeglądarce Chrome na komputerze kliknij chrome://password-manager/settings > Loguj automatycznie.
  • W Chrome na Androidzie otwórz Ustawienia > Menedżer haseł > kliknij ikonę koła zębatego w prawym górnym rogu > Automatyczne logowanie.

Gdy wyłączysz przełącznik, użytkownik będzie mógł zrezygnować z automatycznego ponownego uwierzytelniania. To ustawienie jest przechowywane i synchronizowane między urządzeniami, jeśli użytkownik jest zalogowany na konto Google w instancji Chrome i ma włączoną synchronizację.

Odłącz dostawcę tożsamości od RP

Jeśli użytkownik wcześniej zalogował się w grupie objętej ograniczeniami przy użyciu dostawcy tożsamości w FedCM, przeglądarka zapisze relację z nią lokalnie na liście połączonych kont. Grupa z ograniczonym dostępem może zainicjować rozłączenie przez wywołanie funkcji IdentityCredential.disconnect(). Tę funkcję można wywołać z klatki RP najwyższego poziomu. Aby dostawca tożsamości został odłączony, strona z grupą obwodową musi zweryfikować configURL, clientId używany u dostawcy tożsamości oraz accountHint. Wskazówka dotycząca konta może być dowolnym ciągiem znaków, o ile punkt końcowy odłączania może zidentyfikować konto. Może to być na przykład adres e-mail lub identyfikator użytkownika, który niekoniecznie musi odpowiadać identyfikatorowi konta dostarczonemu przez punkt końcowy listy kont:

// Disconnect an IdP account "account456" from the RP "https://idp.com/". This is invoked on the RP domain.
IdentityCredential.disconnect({
  configURL: "https://idp.com/config.json",
  clientId: "rp123",
  accountHint: "account456"
});

IdentityCredential.disconnect() zwraca wartość Promise. Ta obietnica może stanowić wyjątek z tych powodów:

  • Użytkownik nie zalogował się w grupie objętej ograniczeniami przy użyciu dostawcy tożsamości w FedCM.
  • Interfejs API jest wywoływany z elementu iframe bez zasady uprawnień FedCM.
  • Element configURL jest nieprawidłowy lub nie ma punktu końcowego odłączenia.
  • Test Content Security Policy (CSP) kończy się niepowodzeniem.
  • Masz oczekujące żądanie rozłączenia.
  • Użytkownik wyłączył FedCM w ustawieniach przeglądarki.

Gdy punkt końcowy odłączenia dostawcy tożsamości zwraca odpowiedź, RP i dostawca tożsamości w przeglądarce rozłączą się, a obietnica zostanie zrealizowana. Identyfikatory odłączonych kont są określone w odpowiedzi z punktu końcowego rozłączenia.

Wywoływanie FedCM z międzyźródłowego elementu iframe

Funkcja FedCM może zostać wywołana z elementu iframe z innych domen za pomocą zasady uprawnień identity-credentials-get, jeśli pozwala na to ramka nadrzędna. Aby to zrobić, dołącz do tagu iframe atrybut allow="identity-credentials-get" w ten sposób:

<iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>

Przykład możesz zobaczyć w przykładzie.

Opcjonalnie, jeśli ramka nadrzędna chce ograniczyć źródła do wywoływania FedCM, możesz wysłać nagłówek Permissions-Policy z listą dozwolonych źródeł.

Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")

Więcej informacji o działaniu zasady uprawnień znajdziesz w artykule Kontrolowanie funkcji przeglądarki za pomocą zasady uprawnień.