Przewodnik dla programistów korzystających z interfejsu Federated Credential Management API

Dowiedz się, jak używać FedCM do federacji tożsamości z zachowaniem prywatności.

FedCM (Federated Credential Management) to podejście do usług tożsamości sfederowanej (takich jak „Zaloguj się przez…”), które chroni prywatność użytkowników. Dzięki niemu użytkownicy mogą logować się na stronach bez udostępniania swoich danych osobowych usłudze tożsamości ani stronie.

Aby dowiedzieć się więcej o przypadkach użycia FedCM, przepływach użytkownika i planie rozwoju interfejsu API, przeczytaj wprowadzenie do FedCM API.

Środowisko programistyczne FedCM

Aby korzystać z FedCM, musisz mieć bezpieczny kontekst (HTTPS lub localhost) zarówno w usłudze IdP, jak i RP w Chrome.

Kod debugowania w Chrome na Androida

Aby debugować kod FedCM, skonfiguruj i uruchom serwer lokalnie. Możesz dostępować do tego serwera w Chrome na urządzeniu z Androidem połączonym za pomocą kabla USB z przekierowaniem portów.

Aby debugować Chrome na Androidzie, możesz użyć Narzędzi deweloperskich na komputerze. Aby to zrobić, postępuj zgodnie z instrukcjami w artykule Zdalne debugowanie urządzeń z Androidem.

Blokowanie plików cookie innych firm w Chrome

Blokowanie plików cookie innych firm w ustawieniach Chrome
Blokowanie plików cookie innych firm w ustawieniach Chrome

Zanim wprowadzimy tę funkcję na stałe, możesz przetestować, jak działa FedCM bez plików cookie innych firm w Chrome.

Aby zablokować pliki cookie innych firm, użyj trybu incognito lub wybierz „Blokuj pliki cookie innych firm” w ustawieniach na komputerze (chrome://settings/cookies) lub na urządzeniu mobilnym (Ustawienia > Ustawienia witryny > Pliki cookie).

Korzystanie z interfejsu FedCM API

Integrację z FedCM można przeprowadzić, tworząc znany plik, plik konfiguracyjny i punkty końcowe dla listy kont, wydawania oświadczeń oraz opcjonalnie metadanych klienta.

Następnie FedCM udostępnia interfejsy API JavaScript, których RP mogą używać do logowania się w usłudze uwierzytelniania.

Tworzenie pliku well-known

Aby zapobiec nadużywaniu interfejsu API przez śledzenie, plik well-known musi być udostępniany z /.well-known/web-identityeTLD+1 dostawcy tożsamości.

Jeśli na przykład punkty końcowe dostawcy tożsamości są obsługiwane pod adresem https://accounts.idp.example/, muszą one udostępniać plik well-known pod adresem https://idp.example/.well-known/web-identity, a także plik konfiguracji 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 IdP, które można określić jako część ścieżki configURL w elementach navigator.credentials.get przez RP. Liczba ciągów tekstowych adresów URL w tablicy jest ograniczona do 1, ale w przyszłości możemy uwzględnić Twoją opinię i zmienić to.

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

Plik konfiguracji dostawcy tożsamości zawiera listę wymaganych punktów końcowych dla przeglądarki. IdP będzie hostować ten plik konfiguracji 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 przez wartości podane do wywołania navigator.credentials.get wykonanego w RP.

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

W polu configURL podaj pełny adres URL lokalizacji pliku konfiguracji dostawcy tożsamości. Gdy wywołana zostanie funkcja navigator.credentials.get() w RP, przeglądarka pobiera plik konfiguracji za pomocą żądania GET bez nagłówka Origin ani nagłówka Referer. Żądanie nie zawiera plików cookie i nie podąża za przekierowaniami. Dzięki temu dostawca usług uwierzytelniania nie dowie się, kto wysłał żądanie i który dostawca usług w chwili próby 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 w formacie JSON, która zawiera te właściwości:

Właściwość Opis
accounts_endpoint (wymagane) Adres URL punktu końcowego accounts.
client_metadata_endpoint (opcjonalnie) Adres URL punktu końcowego metadanych klienta.
id_assertion_endpoint (wymagane) Adres URL punktu końcowego oświadczenia o tożsamości.
disconnect (opcjonalnie) Adres URL punktu końcowego do odłączenia.
login_url (wymagane) Adres URL strony logowania, na której użytkownik może zalogować się w dostawcy tożsamości.
branding (opcjonalnie) Obiekt zawierający różne opcje związane z marką.
branding.background_color (opcjonalnie) Opcja dotycząca marki, która ustawia kolor tła przycisku „Dalej jako…”. Użyj odpowiedniej składni CSS, czyli hex-color, hsl(), rgb() lub named-color.
branding.color (opcjonalnie) Opcja dotycząca marki, która ustawia kolor tekstu przycisku „Dalej jako…”. Użyj odpowiedniej składni CSS, czyli hex-color, hsl(), rgb() lub named-color.
branding.icons (opcjonalnie) Opcja dotycząca marki, która ustawia obiekt ikony wyświetlany w oknie logowania. Obiekt icon to tablica z 2 parametrami:
  • url (wymagana): adres URL obrazu ikony. Nie obsługuje obrazów SVG.
  • size (opcjonalnie): wymiary ikony, które aplikacja przyjmuje jako kwadratowe i w jednej rozdzielczości. Liczba musi być większa lub równa 25.

RP może zmodyfikować ciąg w interfejsie dialogowym FedCM, używając wartości identity.context dla navigator.credentials.get(), aby uwzględnić wstępnie zdefiniowane konteksty uwierzytelniania. Opcjonalna właściwość może mieć wartość "signin" (domyślna), "signup", "use" lub "continue".

Jak marka jest stosowana w dialogu FedCM
Jak marka jest stosowana w dialogu FedCM

Oto przykład treści odpowiedzi uwierzytelniania 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 konfiguracji, 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 zalogowany. 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 SameSite=None, ale bez parametru client_id, nagłówka Origin ani nagłówka Referer. Dzięki temu dostawca tożsamości nie dowie się, z którym RP użytkownik 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 użytkownik jest już zalogowany.
  3. Odpowiedz, podając listę kont.

Przeglądarka oczekuje odpowiedzi JSON zawierającej właściwość accounts z tablicą informacji o koncie z tymi właściwościami:

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 obrazu awatara użytkownika.
approved_clients (opcjonalnie) Tablica identyfikatorów klienta RP, z którymi użytkownik jest zarejestrowany.
login_hints (opcjonalnie) Tablica wszystkich możliwych typów filtrów obsługiwanych przez dostawcę tożsamości, aby określić konto. RP może wywołać navigator.credentials.get() z parametrem loginHint, aby wyświetlić wybrane konto.
domain_hints (opcjonalnie) Tablica wszystkich domen powiązanych z kontem. RP może wywołać funkcję navigator.credentials.get() z parametrem domainHint, aby 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, odpowiedz kodem HTTP 401 (Brak autoryzacji).

Zwrócona lista kont jest wykorzystywana przez przeglądarkę i nie jest dostępna dla RP.

Punkt końcowy metadanych klienta

Punkt końcowy metadanych klienta dostawcy tożsamości zwraca metadane strony korzystającej, takie jak polityka prywatności i warunki korzystania z usługi. Reprezentanci użytkowników powinni z wyprzedzeniem przekazać dostawcy tożsamości 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 jest jeszcze zarejestrowany w RP w systemie dostawcy tożsamości.

Przeglądarka wysyła żądanie GET przy użyciu 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. Odpowiedz, podając metadane klienta.

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

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

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ą używane przez przeglądarkę i nie są dostępne dla RP.

Punkt końcowy potwierdzenia tożsamości

Punkt końcowy oświadczenia tożsamości dostawcy tożsamości zwraca oświadczenie dla zalogowanego użytkownika. Gdy użytkownik loguje się w witrynie RP za pomocą 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, podając te informacje:

Właściwość Opis
client_id (wymagane) Identyfikator klienta RP.
account_id (wymagane) Unikalny identyfikator logującego się użytkownika.
nonce (opcjonalnie) Wartość jednorazowa żądania, dostarczona przez RP.
disclosure_text_shown Zwraca ciąg znaków "true" lub "false" (a nie wartość logiczną). Jeśli tekst informacji nie został wyświetlony, wynik to "false". Dzieje się tak, gdy identyfikator klienta RP został uwzględniony na liście właściwości approved_clients w odpowiedzi z punktu końcowego accounts lub gdy przeglądarka zarejestrowała w przeszłości moment rejestracji w braku parametru approved_clients.
is_auto_selected Jeśli automatyczna ponowna uwierzytelnianie jest wykonywane przez RP, is_auto_selected wskazuje "true". W przeciwnym razie "false". Jest to przydatne w przypadku obsługi większej liczby funkcji związanych z bezpieczeństwem. Niektórzy użytkownicy mogą na przykład preferować wyższy poziom zabezpieczeń, który wymaga wyraźnego uwierzytelnienia przez użytkownika. Jeśli dostawca tożsamości otrzyma żądanie tokena bez takiego zapośredniczenia, może obsłużyć je inaczej. Na przykład zwrócić kod błędu, aby RP mógł ponownie wywołać interfejs FedCM API za pomocą mediation: required.

Przykład nagłówka 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ą CORS (współdzielenie zasobów pomiędzy serwerami z różnych domen).
  2. Sprawdź, czy żądanie zawiera nagłówek HTTP Sec-Fetch-Dest: webidentity.
  3. Dopasuj nagłówek Origin do źródła RP określonego przez client_id. Odrzuć, jeśli nie pasują.
  4. Dopasuj account_id do identyfikatora konta, na którym jesteś już zalogowany. Odrzuć, jeśli nie pasują.
  5. Odpowiedz za pomocą tokena. Jeśli żądanie zostanie odrzucone, odpowiedz za pomocą odpowiedzi na błąd.

Sposób wydania tokenu zależy od dostawcy tożsamości, ale ogólnie jest on podpisywany informacjami takimi jak identyfikator konta, identyfikator klienta, pochodzenie wystawcy, nonce, aby RP mógł zweryfikować autentyczność tokenu.

Przeglądarka oczekuje odpowiedzi JSON zawierającej tę właściwość:

Właściwość Opis
token (wymagane) Token to ciąg tekstowy zawierający oświadczenia dotyczące uwierzytelniania. 
{
  "token": "***********"
}

Zwrócony token jest przekazywany do RP przez przeglądarkę, aby RP mógł zweryfikować uwierzytelnianie.

Zwracanie komunikatu o błędzie

id_assertion_endpoint może też zwracać odpowiedź „error”, która zawiera 2 opcjonalne pola:

  • code: dostawca tożsamości może wybrać jeden z znanych błędów z listy błędów protokołu OAuth 2.0 (invalid_request, unauthorized_client, access_denied, server_error i temporarily_unavailable) lub użyć dowolnego ciągu znaków. W takim przypadku Chrome renderuje interfejs błędu z ogólnym komunikatem o błędzie i przekazuje kod do RP.
  • url: identyfikuje stronę internetową w czytelnej dla człowieka postaci, na której znajdują się informacje o błędzie. Pozwala to użytkownikom uzyskać dodatkowe informacje o błędzie. To pole jest przydatne dla użytkowników, ponieważ przeglądarki nie mogą wyświetlać szczegółowych komunikatów o błędach w wbudowanym interfejsie. Na przykład: linki do dalszych czynności lub informacje kontaktowe obsługi klienta. Jeśli użytkownik chce dowiedzieć się więcej o błędzie i sposobie jego naprawienia, może otworzyć odpowiednią stronę w interfejsie przeglądarki. Adres URL musi należeć do tej samej witryny co dostawca tożsamości configURL.
// id_assertion_endpoint response
{
  "error" : {
     "code": "access_denied",
     "url" : "https://idp.example/error?type=access_denied"
  }
}

Odłączanie punktu końcowego

Gdy wywołasz IdentityCredential.disconnect(), przeglądarka wysyła żądanie POST z plikami cookie SameSite=None i typem treści application/x-www-form-urlencoded do tego punktu końcowego z wyłączeniem z tymi informacjami:

Właściwość Opis
account_hint Wskazówka dotycząca konta dostawcy tożsamości.
client_id Identyfikator klienta RP. 
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ą CORS (współdzielenie zasobów pomiędzy serwerami z różnych domen).
  2. Sprawdź, czy żądanie zawiera nagłówek HTTP Sec-Fetch-Dest: webidentity.
  3. Dopasuj nagłówek Origin do źródła RP określonego przez client_id. Odrzuć, jeśli nie pasują.
  4. Dopasuj account_hint do identyfikatorów kont, na których użytkownicy są już zalogowani.
  5. Odłącz konto użytkownika od RP.
  6. Prześlij do przeglądarki informacje o zidentyfikowanym 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 reprezentantem, prześlij ciąg znaków, który nie pasuje do żadnego identyfikatora konta, na przykład "*".

URL logowania

W przypadku korzystania z interfejsu Login Status API dostawca tożsamości musi przekazać przeglądarce stan logowania użytkownika. Stan może być jednak nieaktualny, na przykład gdy sesja wygasa. W takim przypadku przeglądarka może dynamicznie umożliwić użytkownikowi zalogowanie się w usłudze dostawcy tożsamości za pomocą adresu URL strony logowania określonego w pliku konfiguracji dostawcy tożsamości (login_url).

W oknie FedCM wyświetla się wiadomość z prośbą o zalogowanie, jak pokazano na poniższym obrazku.

A
Okno dialogowe FedCM z prośbą o zalogowanie się w dostawcy tożsamości.

Gdy użytkownik kliknie przycisk Dalej, przeglądarka otworzy okno logowania dostawcy tożsamości.

Przykład okna FedCM
Przykład okna wyświetlanego po kliknięciu przycisku logowania w dostawcy tożsamości

To zwykłe okno przeglądarki z własnymi plikami cookie. To, co dzieje się w dialogu, zależy od dostawcy tożsamości. Nie ma żadnych uchwytów okna, które umożliwiałyby wysyłanie żądań komunikacji między domenami do strony RP. Gdy użytkownik zaloguje się na konto, 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ę, że użytkownik zalogował się.
  • Aby zamknąć okno, wybierz IdentityProvider.close().
Użytkownik loguje się w usłudze RP po zalogowaniu się w dostawcy tożsamości za pomocą FedCM.

Informowanie przeglądarki o stanie logowania użytkownika w usługach dostawcy tożsamości

Interfejs API stanu logowania to mechanizm, w którym witryna, zwłaszcza dostawca tożsamości, informuje przeglądarkę o stanie logowania użytkownika w dostawcy tożsamości. Dzięki temu interfejsowi API przeglądarka może ograniczyć liczbę niepotrzebnych żądań do dostawcy tożsamości i zmniejszyć ryzyko potencjalnych ataków czasowych.

Dostawcy tożsamości mogą sygnalizować stan logowania użytkownika w przeglądarce, wysyłając nagłówek HTTP lub wywołując interfejs JavaScript API, gdy użytkownik jest zalogowany w dostawcy tożsamości lub gdy jest wylogowany ze wszystkich kont dostawcy tożsamości. W przypadku każdego dostawcy tożsamości (identyfikowanego za pomocą adresu URL konfiguracji) przeglądarka przechowuje zmienną o 3 stanach, która reprezentuje stan logowania. Możliwe wartości to logged-in, logged-out i unknown. Stan domyślny to unknown.

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

Set-Login: logged-in

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

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

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

Aby zasygnalizować, że użytkownik wylogował się ze wszystkich kont, wyślij nagłówek Set-Login: logged-out HTTP w nawigacji najwyższego poziomu lub żądaniu zasobu podrzędnego w tym samym miejscu pochodzenia w źródle dostawcy tożsamości:

Set-Login: logged-out

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

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

Te wywołania rejestrują stan logowania użytkownika jako logged-out. Gdy stan logowania użytkownika to logged-out, wywołanie interfejsu FedCM kończy się po cichu niepowodzeniem bez wysłania żądania do punktu końcowego kont dostawcy tożsamości.

Stan unknown jest ustawiany, zanim dostawca tożsamości wyśle sygnał za pomocą interfejsu API stanu logowania. Unknown został wprowadzony, aby ułatwić przejście, ponieważ użytkownik mógł już zalogować się w dostawcy tożsamości, gdy udostępniono to API. Dostawca tożsamości może nie mieć możliwości zasygnalizowania tego przeglądarce w momencie pierwszego wywołania FedCM. W tym przypadku Chrome wysyła żądanie do punktu końcowego kont dostawcy tożsamości i aktualizuje stan na podstawie odpowiedzi z punktu końcowego kont:

  • Jeśli punkt końcowy zwróci listę aktywnych kont, zmień stan na logged-in i otwórz okno FedCM, aby wyświetlić te konta.
  • Jeśli punkt końcowy nie zwróci żadnych kont, zaktualizuj stan na logged-out i zakończ wywołanie FedCM.

Zezwalanie użytkownikowi na logowanie się w ramach dynamicznego procesu logowania

Mimo że dostawca tożsamości przekazuje przeglądarce stan logowania użytkownika, może on być niezsynchronizowany, np. gdy sesja wygaśnie. Gdy stan logowania to logged-in, przeglądarka próbuje wysłać żądanie z danymi logowania do punktu końcowego kont, ale serwer nie zwraca żadnych kont, ponieważ sesja nie jest już dostępna. W takim przypadku przeglądarka może umożliwić użytkownikowi zalogowanie się w usłudze dostawcy tożsamości za pomocą wyskakującego okienka.

Zaloguj się w usługach strony uwierzytelniającej u dostawcy tożsamości

Gdy konfiguracja i punkty końcowe dostawcy tożsamości będą dostępne, dostawcy RP mogą wywoływać funkcję navigator.credentials.get(), aby poprosić dostawcę tożsamości o zezwolenie na logowanie się użytkowników w ich usługach.

Zanim wywołasz interfejs API, musisz sprawdzić, czy FedCM jest dostępny w przeglądarce użytkownika. Aby sprawdzić, czy FedCM jest dostępny, użyj tego kodu w implementacji FedCM:

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

Aby poprosić RP o zezwolenie na logowanie się użytkowników w usługach uwierzytelniania, wykonaj te czynności: na przykład:

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

Właściwość providers przyjmuje tablicę obiektów IdentityProvider o tych właściwościach:

Właściwość Opis
configURL (wymagane) Pełna ścieżka do pliku konfiguracji dostawcy tożsamości.
clientId (wymagane) Identyfikator klienta RP wydany przez dostawcę tożsamości.
nonce (opcjonalnie) losowy ciąg znaków, który ma zapewnić, że odpowiedź zostanie wydana w odpowiedzi na to konkretne żądanie; Zapobiega atakom typu replay.
loginHint (opcjonalnie) Po wybraniu jednej z wartości login_hints udostępnionych przez punkty końcowe kont, w oknie FedCM wyświetlane jest wybrane konto.
domainHint (opcjonalnie) Określając jedną z wartości domain_hints udostępnianych przez punkty końcowe kont, możesz wybrać, aby w oknie FedCM wyświetlało się tylko określone konto.

Przeglądarka obsługuje przypadki użycia 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 wartość approved_clients. Jeśli użytkownik jest już zarejestrowany w programie RP, przeglądarka nie wyświetli komunikatu „Aby kontynuować…”.

Stan rejestracji jest określany na podstawie tego, czy są spełnione poniższe warunki:

  • Jeśli approved_clients zawiera clientId RP.
  • Jeśli przeglądarka zapamięta, że użytkownik jest już zarejestrowany w RP.
Użytkownik loguje się na stronie RP za pomocą FedCM.

Gdy RP wywołuje funkcję navigator.credentials.get(), wykonuje te czynności:

  1. Przeglądarka wysyła żądania i pobiera kilka dokumentów:
    1. Plik well-known i plik konfiguracji dostawcy tożsamości, który deklaruje punkty końcowe.
    2. Lista kont.
    3. Opcjonalnie: adresy URL polityki prywatności i Warunków korzystania z usługi RP, pobrane z punktu końcowego metadanych klienta.
  2. Przeglądarka wyświetla listę kont, których użytkownik może użyć do zalogowania się, a także warunki korzystania z usługi i politykę prywatności (jeśli są dostępne).
  3. Gdy użytkownik wybierze konto, na którym chce się zalogować, do dostawcy tożsamości zostanie wysłane żądanie do punktu końcowego oświadczenia tożsamości w celu pobrania tokena.
  4. RP może zweryfikować token, aby uwierzytelnić użytkownika.
wywołanie interfejsu API logowania;
Wywołanie interfejsu API logowania

Usługodawcy reklamy powinni obsługiwać przeglądarki, które nie obsługują FedCM, dlatego użytkownicy powinni mieć możliwość korzystania z dotychczasowego procesu logowania, który nie wykorzystuje FedCM. Dopóki pliki cookie innych firm nie zostaną usunięte z przeglądarek, nie powinno to stanowić problemu.

Gdy token zostanie zweryfikowany przez serwer RP, RP może zarejestrować użytkownika lub pozwolić mu zalogować się i rozpocząć nową sesję.

Login Hint API

Po zalogowaniu się użytkownik może zostać poproszony przez stronę pobierającą o ponowne uwierzytelnienie. Użytkownik może jednak nie być pewien, którego konta używał. Jeśli RP może określić, na którym koncie ma się zalogować, użytkownik łatwiej wybierze konto.

RP mogą selektywnie wyświetlać konkretne konto, wywołując navigator.credentials.get() z użyciem właściwości loginHint z jedną z wartości login_hints pobranych z punktu końcowego listy kont, jak pokazano 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"
    }]
  }
});

Jeśli nie ma kont pasujących do loginHint, okno FedCM wyświetla monit logowania, który umożliwia użytkownikowi zalogowanie się na konto dostawcy tożsamości pasujące do wskazówki przesłanej przez RP. Gdy użytkownik kliknie prompt, otworzy się wyskakujące okienko z adresem URL logowania określonym w pliku konfiguracji. Następnie do linku dodawane są parametry zapytania dotyczące podpowiedzi logowania i podpowiedzi domeny.

Interfejs API podpowiedzi dotyczących domen

W niektórych przypadkach RP wie już, że tylko konta powiązane z określoną domeną mogą się zalogować w witrynie. Jest to szczególnie typowe w sytuacjach korporacyjnych, gdy dostęp do witryny jest ograniczony do domeny firmowej. Aby zapewnić lepsze wrażenia użytkownika, interfejs API FedCM umożliwia RP wyświetlanie tylko tych kont, które mogą służyć do logowania się w RP. Zapobiega to sytuacjom, w których użytkownik próbuje zalogować się do RP, używając konta spoza domeny firmowej, a potem wyświetla mu się komunikat o błędzie (lub nie wyświetla się nic, ponieważ logowanie się nie zadziałało), ponieważ nie został użyty odpowiedni typ konta.

RP mogą selektywnie wyświetlać tylko pasujące konta, wywołując funkcję navigator.credentials.get() z właściwością domainHint z jedną z wartości domain_hints pobranych z punktu końcowego listy kont, jak pokazano w tym przykładzie kodu:

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

Jeśli nie ma kont pasujących do domainHint, okno FedCM wyświetla monit logowania, który umożliwia użytkownikowi zalogowanie się na konto dostawcy tożsamości pasujące do wskazówki przesłanej przez RP. Gdy użytkownik kliknie prompt, otworzy się wyskakujące okienko z adresem URL logowania określonym w pliku konfiguracji. Następnie do linku dodawane są parametry zapytania dotyczące podpowiedzi logowania i podpowiedzi domeny.

Przykładowy komunikat logowania, gdy żadne konta nie pasują do domeny
Przykładowy komunikat logowania, gdy żadne konto nie pasuje do domainHint.

wyświetlić komunikat o błędzie.

Czasami dostawca tożsamości może nie być w stanie wydać tokena z uzasadnionych powodów, np. gdy klient nie ma uprawnień lub serwer jest tymczasowo niedostępny. Jeśli dostawca tożsamości zwróci odpowiedź „error”, RP może ją przechwycić, a Chrome powiadomi użytkownika, wyświetlając interfejs przeglądarki z informacjami o błędzie dostarczonymi przez dostawcę tożsamości.

A
Okno FedCM wyświetlające komunikat o błędzie po nieudanej próbie zalogowania 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 początkowym uwierzytelnieniu,

Automatyczne ponowne uwierzytelnianie w FedCM (w skrócie „automatyczne ponowne uwierzytelnianie”) umożliwia użytkownikom automatyczne ponowne uwierzytelnianie się, gdy powrócą do aplikacji po początkowym uwierzytelnieniu za pomocą FedCM. „Pierwsze uwierzytelnianie” oznacza, że użytkownik tworzy konto lub loguje się na stronie RP, klikając przycisk „Dalej jako…” w oknie logowania FedCM po raz pierwszy w tym samym wystąpieniu przeglądarki.

Chociaż wyświetlanie wyraźnego komunikatu ma sens, zanim użytkownik utworzy konto federacyjne, aby zapobiec śledzeniu (co jest jednym z głównych celów FedCM), jest ono niepotrzebnie uciążliwe, gdy użytkownik już raz je przeczytał. Po udzieleniu przez użytkownika zgody na komunikację między RP a IdP nie ma już potrzeby wymuszania kolejnego wyraźnego potwierdzenia przez użytkownika czegoś, co zostało już wcześniej zaakceptowane.

W przypadku automatycznej ponownej autoryzacji przeglądarka zmienia swoje działanie w zależności od opcji określonej dla mediation podczas wywołania 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;

mediation to właściwość w interfejsie API do zarządzania danymi logowania. Zachowuje się w taki sam sposób jak w przypadku PasswordCredential i FederatedCredential, a także jest częściowo obsługiwana przez PublicKeyCredential. Właściwość ta akceptuje 4 wartości:

  • 'optional' (domyślnie): automatyczne ponowne uwierzytelnianie (jeśli to możliwe) lub wymaganie uwierzytelniania (w przeciwnym razie). Zalecamy wybranie tej opcji na stronie logowania.
  • 'required': zawsze wymaga interwencji moderatora, np. kliknięcia przycisku „Dalej” w interfejsie. Wybierz tę opcję, jeśli użytkownicy mają przyznawać uprawnienia wyraźnie za każdym razem, gdy trzeba ich uwierzytelnić.
  • 'silent': automatyczne ponowne uwierzytelnianie (jeśli to możliwe), bez konieczności zapośredniczenia, jeśli nie jest to możliwe. Zalecamy wybranie tej opcji na stronach innych niż strona logowania, na których chcesz, aby użytkownicy pozostawali zalogowani. Może to być na przykład strona produktu w witrynie firmy spedycyjnej lub strona artykułu w witrynie z wiadomościami.
  • 'conditional': służy do uwierzytelniania w ramach WebAuthn i obecnie nie jest dostępna w ramach FedCM.

W ramach tego wywołania automatyczna ponowna autoryzacja odbywa się w tych warunkach:

  • Dostępna jest usługa FedCM. Użytkownik nie wyłączył FedCM ani globalnie, ani w ustawieniach RP.
  • Użytkownik zalogował się na stronie w tym przeglądarce tylko za pomocą jednego konta z FedCM API.
  • Użytkownik loguje się w systemie dostawcy tożsamości przy użyciu tego konta.
  • Automatyczna ponowna autoryzacja nie miała miejsca w ciągu ostatnich 10 minut.
  • RP nie zadzwonił navigator.credentials.preventSilentAccess() po poprzednim zalogowaniu się.

Gdy te warunki zostaną spełnione, próba automatycznego ponownego uwierzytelnienia użytkownika rozpoczyna się, gdy tylko wywołana zostanie usługa FedCM navigator.credentials.get().

Gdy mediation: optional, automatyczne uwierzytelnianie może być niedostępne z powodów znanych tylko przeglądarce. Usługodawca może sprawdzić, czy automatyczne uwierzytelnianie zostało wykonane, badając właściwość isAutoSelected.

Pomoże to ocenić wydajność interfejsu API i odpowiednio poprawić wrażenia użytkownika. Jeśli nie jest ona dostępna, użytkownik może zostać poproszony o zalogowanie się z użyciem pośrednictwa użytkownika, czyli procesu z użyciem mediation: required.

Użytkownik automatycznie uwierzytelnia się za pomocą FedCM.

Wymuszanie zapośredniczenia w przypadku preventSilentAccess()

Automatyczne uwierzytelnianie użytkowników tuż po wylogowaniu nie sprzyja dobremu odbiorowi. Dlatego FedCM ma 10-minutowy okres ciszy po automatycznym uwierzytelnieniu, aby zapobiec takiemu zachowaniu. Oznacza to, że automatyczne ponowne uwierzytelnianie odbywa się maksymalnie raz na 10 minut, chyba że użytkownik zaloguje się ponownie w ciągu 10 minut. RP powinien wywołać funkcję navigator.credentials.preventSilentAccess(), aby wyraźnie poprosić przeglądarkę o wyłączenie automatycznego ponownego uwierzytelniania, gdy użytkownik wyloguje się z RP, na przykład przez kliknięcie przycisku wylogowania.

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

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

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

  • W Chrome na komputery kliknij chrome://password-manager/settings > Zaloguj się automatycznie.
  • W Chrome na Androidzie otwórz Ustawienia > Menedżer haseł > kliknij kółko w prawym górnym rogu > Logowanie automatyczne.

Wyłączenie przełącznika powoduje, że użytkownik może całkowicie zrezygnować z automatycznego uwierzytelniania. To ustawienie jest przechowywane i synchronizowane na różnych urządzeniach, jeśli użytkownik zaloguje się na konto Google w pliku programu Chrome i synchronizacja jest włączona.

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

Jeśli użytkownik zalogował się wcześniej w usłudze RP za pomocą dostawcy tożsamości przez FedCM, przeglądarka zapamięta tę relację lokalnie jako listę połączonych kont. RP może zainicjować rozłączenie, wywołując funkcję IdentityCredential.disconnect(). Tę funkcję można wywołać z ramki RP najwyższego poziomu. RP musi przekazać configURL, clientId, którego używa w ramach dostawcy tożsamości, oraz accountHint, aby można było odłączyć dostawcę tożsamości. Wskazówka dotycząca konta może być dowolnym ciągiem znaków, o ile punkt końcowy funkcji rozłączania może zidentyfikować konto, na przykład adres e-mail lub identyfikator użytkownika, który nie musi być identyczny z identyfikatorem konta podanym 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 spowodować wyjątek z tych powodów:

  • Użytkownik nie zalogował się w usłudze RP, korzystając z dostawcy tożsamości przez FedCM.
  • Interfejs API jest wywoływany z poziomu elementu iframe bez zasad uprawnień FedCM.
  • Adres URL konfiguracji jest nieprawidłowy lub nie ma punktu końcowego odłączenia.
  • Sprawdzanie zgodności ze standardem Content Security Policy (CSP) zakończyło się niepowodzeniem.
  • Istnieje oczekująca prośba o rozłączenie.
  • Użytkownik wyłączył FedCM w ustawieniach przeglądarki.

Gdy punkt końcowy usługi IdP do rozłączania zwraca odpowiedź, RP i IdP są rozłączane w przeglądarce, a obietnica jest realizowana. Identyfikatory rozłączonych kont są podane w odpowiedzi z punktu końcowego funkcji disconnect.

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

FedCM może być wywoływany z poziomu ramki iframe w wielu domenach za pomocą zasady uprawnień identity-credentials-get, jeśli dozwoli na to element nadrzędny. Aby to zrobić, dodaj atrybut allow="identity-credentials-get" do tagu iframe w ten sposób:

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

Możesz zobaczyć, jak to działa, na przykładzie.

Opcjonalnie, jeśli element nadrzędny chce ograniczyć źródła wywołania FedCM, wyślij 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 zasadach dotyczących uprawnień znajdziesz w artykule Kontrolowanie funkcji przeglądarki za pomocą zasad dotyczących uprawnień.