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

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

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.

Więcej informacji o przypadkach użycia FedCM, przepływach użytkowników i planach rozwoju interfejsu API znajdziesz we wprowadzeniu 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

Skonfiguruj i uruchom serwer lokalnie, aby debugować kod FedCM. 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 na komputerze, możesz użyć Narzędzi deweloperskich na komputerze, postępując zgodnie z instrukcjami na stronie Zdalne debugowanie urządzeń z Androidem.

Blokowanie plików cookie innych firm w Chrome

Symulowanie wycofania plików cookie innych firm przez skonfigurowanie ich blokowania w Chrome
Symulowanie wycofania plików cookie innych firm przez skonfigurowanie Chrome w celu ich zablokowania

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

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 przeprowadzasz, tworząc dobrze znany plik, plik konfiguracyjny i punkty końcowe dla listy kont, wystawiające testy i opcjonalnie metadane klienta.

Później FedCM udostępnia interfejsy API JavaScript, których usługi RP mogą używać do logowania się u dostawcy tożsamości.

Utwórz dobrze znany plik

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;

Podaj pełny adres URL lokalizacji pliku konfiguracji dostawcy tożsamości jako configURL. Gdy w RPA wywoływana jest funkcja navigator.credentials.get(), przeglądarka pobiera plik konfiguracyjny za pomocą żądania GET bez nagłówka Origin i nagłówka Referer. Żądanie nie zawiera plików cookie ani nie śledzi przekierowań. W ten sposób dostawca tożsamości nie wie, kto wysłał żądanie i z którą grupą eksperymentalną próbuje się połączyć. 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 odłączanego punktu końcowego.
login_url (wymagane) Adres URL strony logowania, pod którym użytkownik może zalogować się u dostawcy tożsamości.
branding (opcjonalnie) Obiekt zawierający różne opcje związane z marką.
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, 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 zakładane przez aplikację jako kwadratowe i o jednej rozdzielczości. Liczba musi być większa lub równa 25.

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

Stosowanie marki w oknie FedCM
Jak marka jest stosowana w dialogu FedCM

Oto 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 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 obecnie zalogowany u dostawcy tożsamości. Jeśli dostawca tożsamości obsługuje wiele kont, ten punkt końcowy zwraca wszystkie zalogowane konta.

Przeglądarka wysyła żądanie GET z plikami cookie z atrybutem SameSite=None, ale bez parametru client_id, nagłówka Origin ani nagłówka Referer. Dzięki temu zewnętrzny dostawca tożsamości nie dowie się, z którym dostawcą usług uwierzytelniania próbuje się zalogować użytkownik. 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ż zalogowany.
  3. Odpowiedz, podając listę kont.

Przeglądarka oczekuje odpowiedzi JSON, która zawiera właściwość accounts z tablicyą 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ę i nazwisko użytkownika.
picture (opcjonalnie) Adres URL obrazu awatara użytkownika.
approved_clients (opcjonalnie) Tablica identyfikatorów klienta RP, u których użytkownik się zarejestrował.
login_hints (opcjonalnie) Tablica wszystkich możliwych typów filtrów obsługiwanych przez dostawcę tożsamości, służąca do określenia konta. RP może wywołać navigator.credentials.get() z właściwością loginHint, aby selektywnie wyświetlić określone konto.
domain_hints (opcjonalnie) Tablica wszystkich domen powiązanych z kontem. RP może wywołać metodę navigator.credentials.get() za pomocą właściwości domainHint, aby przefiltrować 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 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 grupy objętej ograniczeniami.
terms_of_service_url (opcjonalnie) Adres 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ą przetwarzane przez przeglądarkę i nie będą dostępne dla grupy objętej ograniczeniami.

Punkt końcowy asercji identyfikatora

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 grupy objętej ograniczeniami.
account_id (wymagane) Unikalny identyfikator zalogowanego użytkownika.
nonce (opcjonalnie) Wartość jednorazowa żądania, dostarczona przez RP.
disclosure_text_shown daje wynik jako ciąg "true" lub "false" (a nie wartość logiczna). 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 w RPA zostanie wykonane automatyczne ponowne uwierzytelnianie, wartość is_auto_selected będzie wskazywać "true". W przeciwnym razie "false". Pomoże to w obsłudze 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. Zwróć na przykład kod błędu, aby podmiot zarządzający kierowaniem mógł ponownie wywołać interfejs FedCM API za pomocą polecenia 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ą udostępniania zasobów mię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 się nie zgadzają.
  4. Dopasuj account_id do identyfikatora konta, na które się logujesz. Odrzucaj, jeśli nie są zgodne.
  5. Odpowiedz za pomocą tokena. W przypadku odrzucenia żądania prześlij odpowiedź o błędzie.

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 odpowiedzi 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 ze znanych błędów z listy błędów określonej przez OAuth 2.0 (invalid_request, unauthorized_client, access_denied, server_error itemporarily_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 czytelną dla człowieka stronę internetową z informacjami o błędzie, aby zapewnić użytkownikom dodatkowe informacje o błędzie. To pole jest przydatne dla użytkowników, ponieważ przeglądarki nie mogą wyświetlać rozszerzonych komunikatów o błędach w natywnym interfejsie. Może to być na przykład link do dalszych czynności lub informacje kontaktowe obsługi klienta. Jeśli użytkownik chce dowiedzieć się więcej o szczegółach błędu i sposobie jego naprawienia, może wejść na 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 grupy 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ą 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 jesteś już zalogowany.
  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 interfejsu Login Status API dostawca tożsamości musi przekazać przeglądarce stan logowania użytkownika. Stan może jednak być niezsynchronizowany, np. 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 FedCM z prośbą o zalogowanie się u dostawcy tożsamości.

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

Przykładowe okno FedCM.
Przykładowe okno wyświetlane po kliknięciu przycisku logowania do dostawcy tożsamości.

To zwykłe okno przeglądarki z własnymi plikami cookie. Wszystko, co dzieje się w oknie, zależy od dostawcy tożsamości i nie są dostępne żadne uchwyty okien, które umożliwiają wysłanie żądania komunikacji z innej domeny do strony RP. Gdy użytkownik się zaloguje, 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 RP po zalogowaniu się u dostawcy tożsamości za pomocą FedCM.

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

Interfejs Login Status API to mechanizm, dzięki któremu 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 API przeglądarka może ograniczyć liczbę niepotrzebnych żądań do dostawcy tożsamości i zmniejszyć ryzyko potencjalnych ataków związanych z czasem.

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 (określanego za pomocą 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, prześlij nagłówek HTTP Set-Login: logged-in w nawigacji najwyższego poziomu lub żądanie zasobu podrzędnego w tej samej witrynie 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 poziomu punktu początkowego dostawcy tożsamości w menu najwyższego poziomu:

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

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

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

Set-Login: logged-out

Możesz też wywołać interfejs 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 wywołania rejestrują stan logowania użytkownika jako logged-out. Gdy stan logowania użytkownika to logged-out, wywoływanie FedCM w trybie dyskretnym kończy się niepowodzeniem bez wysył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 to interfejs API został udostępniony. Dostawca tożsamości może nie być w stanie zasygnalizować tego przeglądarce przed pierwszym wywołaniem FedCM. W takim przypadku Chrome wysyła żądanie do punktu końcowego kont dostawcy tożsamości i aktualizuje stan na podstawie odpowiedzi z tego punktu końcowego konta:

  • Jeśli punkt końcowy zwraca 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 interfejsu FedCM.

Zezwalaj użytkownikowi na logowanie się za pomocą 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 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 dynamicznie zezwolić użytkownikowi na logowanie się w systemie 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 są dostępne, dostawcy tożsamości mogą wywołać navigator.credentials.get(), aby poprosić użytkowników o umożliwienie użytkownikom logowania się w tej usłudze.

Zanim wywołasz interfejs API, musisz potwierdzić, że usługa FedCM jest dostępna w przeglądarce użytkownika. Aby sprawdzić, czy usługa FedCM jest dostępna, opakuj swoją implementację FedCM za pomocą tego kodu:

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

Aby poprosić użytkowników o pozwolenie na logowanie się do dostawcy tożsamości z RP, wykonaj na przykład 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 przyjmuje tablicę IdentityProvider obiektów, które mają te właściwości:

Właściwość Opis
configURL (wymagane) Pełna ścieżka do pliku konfiguracji dostawcy tożsamości.
clientId (wymagane) Identyfikator klienta RP wystawiany 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) Gdy określisz jedną z wartości login_hints podanych przez punkty końcowe kont, w oknie FedCM w sposób selektywny wyświetli się określone 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 na różne sposoby w zależności od obecności elementu approved_clients w odpowiedzi z punktu końcowego listy kont. Jeśli użytkownik zarejestrował się już w programie objętym ograniczeniami, przeglądarka nie wyświetli komunikatu „Aby kontynuować z ...”.

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

  • Jeśli approved_clients zawiera clientId RP.
  • Jeśli przeglądarka zapamięta, że użytkownik już zarejestrował się w RPA.
Użytkownik loguje się w grupie objętej ograniczeniami przy użyciu FedCM.

Gdy RP wywołuje funkcję navigator.credentials.get(), wykonywane są 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 usługi grupy objętej ograniczeniami 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, za pomocą którego będzie się logować, do punktu końcowego pomiaru identyfikatora zostanie wysłane żądanie pobrania tokena do dostawcy tożsamości.
  4. RP może zweryfikować token, aby uwierzytelnić użytkownika.
wywołanie interfejsu API logowania;
Wywołanie interfejsu API logowania

Reguły RP powinny obsługiwać przeglądarki, które nie obsługują FedCM. W związku z tym użytkownicy powinni mieć możliwość korzystania z dotychczasowego procesu logowania się poza FedCM. Dopóki pliki cookie innych firm nie zostaną całkowicie wycofane, nie powinno to stanowić problemów.

Po zweryfikowaniu tokena przez serwer RP może on zarejestrować użytkownika lub zezwolić mu na zalogowanie się i rozpoczęcie nowej sesji.

Login Hint API

Czasami, gdy użytkownik się zaloguje, strona uzależniona prosi go o ponowne uwierzytelnienie. Użytkownik może jednak nie być pewien, którego konta używał. Jeśli w grupie objętej ograniczeniami można określić konto, na które będzie się logować, użytkownik będzie mógł łatwiej wybrać odpowiednie 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"
    }]
  }
});

Gdy żadne konta nie pasują do loginHint, w oknie FedCM pojawi się prośba o zalogowanie się, która pozwoli użytkownikowi zalogować się na konto dostawcy tożsamości pasujące do podpowiedzi żądanej przez RP. Gdy użytkownik kliknie prompt, otworzy się wyskakujące okienko z adresem URL logowania określonym w pliku konfiguracji. Następnie do tego linku dołączana jest wskazówka dotycząca logowania i parametry zapytania dotyczące wskazówki dotyczącej domeny.

Domain Hint API

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 częste w sytuacjach, 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 scenariuszom, w których użytkownik próbuje zalogować się w RPA przy użyciu konta spoza domeny firmowej, a potem powoduje wyświetlenie komunikatu o błędzie (lub wyciszenia, gdy logowanie się nie powiodło) z powodu braku odpowiedniego typu konta.

RP mogą wyświetlać tylko pasujące konta przez wywołanie 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ładowym kodzie:

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 potwierdzenie, otworzy się wyskakujące okienko z adresem URL logowania podanym w pliku konfiguracyjnym. Następnie do linku dodawane są parametry zapytania podpowiedzi dotyczącej logowania i podpowiedzi dotyczącej domeny.

Przykładowy komunikat logowania, gdy żadne konta nie pasują do domeny
Przykładowy prośbę o zalogowanie się, gdy żadne konto nie jest zgodne z wartością domainHint.

wyświetlić komunikat o błędzie.

Czasami dostawca tożsamości może nie być w stanie wygenerować tokena z uzasadnionych powodów, np. gdy klient jest nieautoryzowany, serwer jest tymczasowo niedostępny. Jeśli dostawca tożsamości zwróci odpowiedź „błąd”, RP może ją wyłapać, a Chrome powiadomi użytkownika, wyświetlając interfejs przeglądarki z informacjami o błędach podanymi przez dostawcę tożsamości.

A
Okno FedCM wyświetlające komunikat o błędzie po nieudanej próbie zalogowania użytkownika. Ciąg znaków 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 FedCM (w skrócie „automatyczne ponowne uwierzytelnianie”) umożliwia automatyczne ponowne uwierzytelnianie użytkownika, gdy wracają po pierwszym uwierzytelnieniu z użyciem 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ż konkretne doświadczenia użytkownika mają sens, zanim użytkownik utworzy konto sfederowane, aby zapobiec śledzeniu (co jest jednym z głównych celów FedCM), jest to niepotrzebnie uciążliwe po przejściu przez użytkownika: gdy wyrazi on zgodę na umożliwienie komunikacji między RP a dostawcą tożsamości, wymuszanie przez użytkownika jednoznacznie potwierdzonego potwierdzonego wcześniej potwierdzenia przez użytkownika nie ma sensu.

W przypadku automatycznego ponownego uwierzytelniania 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': aby kontynuować, wymagane jest zawsze zapośredniczenie, np. kliknięcie 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 w miarę możliwości; jeśli to możliwe, dyskretny błąd bez konieczności zapośredniczenia. Zalecamy wybranie tej opcji na innych stronach niż strona logowania, ale na których chcesz utrzymać zainteresowanie użytkowników – np. na stronie produktu w witrynie dostawy lub na stronie z artykułem w witrynie z wiadomościami.
  • 'conditional': używany w przypadku WebAuthn, ale obecnie nie jest dostępny dla FedCM.

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

  • Usługa FedCM jest dostępna. Na przykład użytkownik nie wyłączył FedCM globalnie ani dla RP w ustawieniach.
  • Użytkownik zalogował się w witrynie w tej przeglądarce tylko z jednego konta z interfejsem FedCM API.
  • Użytkownik jest zalogowany w dostawcy tożsamości za pomocą tego konta.
  • Automatyczna ponowna autoryzacja nie nastąpiła w ciągu ostatnich 10 minut.
  • Grupa z ograniczonym dostępem nie wywołała navigator.credentials.preventSilentAccess() po poprzednim zalogowaniu.

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 ponowne uwierzytelnianie może być niedostępne z powodów, o których wie tylko przeglądarka. RP może sprawdzić, czy jest wykonywane automatyczne ponowne uwierzytelnianie, sprawdzając właściwość isAutoSelected.

Pomoże to ocenić wydajność interfejsu API i odpowiednio poprawić wrażenia użytkownika. Gdy jest ono niedostępne, użytkownik może zostać poproszony o zalogowanie się za pomocą jawnego zapośredniczenia użytkownika (mediation: required).

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

Wymuś zapośredniczenie, używając preventSilentAccess()

Automatyczne uwierzytelnianie użytkowników zaraz po wylogowaniu nie jest zbyt wygodne. Dlatego po automatycznym ponownym uwierzytelnieniu FedCM stosuje 10-minutowy okres bez powiadomień, aby zapobiec takim sytuacjom. 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 ponownego uwierzytelniania w ustawieniach

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

  • W Chrome na komputerze 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 między urządzeniami, jeśli użytkownik jest zalogowany na konto Google w instancji Chrome i włączona jest synchronizacja.

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

Jeśli użytkownik wcześniej zalogował się w RPA przy użyciu dostawcy tożsamości przez FedCM, przeglądarka zapisuje lokalnie tę relację jako listę połączonych kont. RP może zainicjować odłączenie przez wywołanie funkcji 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 RP przy użyciu dostawcy tożsamości w FedCM.
  • Interfejs API jest wywoływany z elementu iframe bez zasady uprawnień FedCM.
  • Adres configURL jest nieprawidłowy lub nie ma punktu końcowego odłączania.
  • Sprawdzanie zgodności ze standardem Content Security Policy (CSP) zakończyło się niepowodzeniem.
  • Masz oczekujące żądanie rozłączenia.
  • Użytkownik wyłączył FedCM w ustawieniach przeglądarki.

Gdy punkt końcowy odłączania dostawcy tożsamości zwraca odpowiedź, RP i dostawca tożsamości są rozłączone w przeglądarce, a obietnica jest zrealizowana. Identyfikatory rozłączonych kont są podane w odpowiedzi z punktu końcowego funkcji disconnect.

Wywołaj FedCM z 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ć, dołącz 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 ramka nadrzędna chce ograniczyć źródła tak, aby mogły wywoływać 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 działaniu zasad dotyczących uprawnień znajdziesz w artykule Kontrolowanie funkcji przeglądarki za pomocą zasad uprawnień.