FedCM (federowane zarządzanie poświadczeniami) to podejście do federowanych usług tożsamości (takich jak „Zaloguj się za pomocą…”), które chroni prywatność użytkowników i umożliwia im logowanie się w witrynach bez udostępniania informacji osobistych usłudze tożsamości ani witrynie.
Wdrożenie FedCM obejmuje kilka podstawowych kroków zarówno w przypadku dostawcy tożsamości, jak i usługodawcy.
Aby wdrożyć FedCM, IdPs muszą wykonać te czynności:
- Utwórz plik well-known.
- Utwórz plik konfiguracyjny.
- Utwórz te punkty końcowe:
- Informowanie przeglądarki o stanie logowania użytkownika.
Aby włączyć FedCM w swojej witrynie, partnerzy handlowi muszą wykonać te czynności:
- Upewnij się, że punkty końcowe FedCM są dozwolone w witrynie RP.
- Aby zainicjować uwierzytelnianie użytkownika, użyj interfejsu FedCM JavaScript API.
- Prześlij metadane (np. adresy URL polityki prywatności i warunków korzystania z usługi) do dostawcy tożsamości.
- [Opcjonalnie] Dostosowywanie interfejsu użytkownika przez wybranie trybu UX, podanie loginu lub wskazówek dotyczących domeny, przekazanie parametrów niestandardowych, prośba o konkretne informacje o użytkowniku, podanie niestandardowego komunikatu o błędzie lub wybranie sposobu ponownego uwierzytelniania użytkowników.
Implementowanie FedCM jako dostawcy tożsamości
Dowiedz się więcej o tym, jak zaimplementować FedCM po stronie dostawcy tożsamości.
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.
Znajomy plik może zawierać te właściwości:
| Właściwość | Wymagane | Opis |
|---|---|---|
provider_urls
|
wymagane | Tablica ścieżek do plików konfiguracji dostawcy tożsamości. Ignorowana (ale nadal wymagana), jeśli określone są parametry accounts_endpoint i login_url. |
accounts_endpoint
|
zalecane, wymaga login_url |
Adres URL punktu końcowego kont. Umożliwia to obsługę wielu konfiguracji, o ile każdy plik konfiguracji używa tego samego adresu URL login_url i accounts_endpoint.Uwaga: parametr jest obsługiwany od wersji 132 Chrome. |
login_url
|
zalecane, wymaga accounts_endpoint |
Adres URL strony logowania, na której użytkownik może zalogować się w dostawcy tożsamości. Umożliwia to obsługę wielu konfiguracji, o ile każdy plik konfiguracji używa tych samych wartości login_url i accounts_endpoint.Uwaga: parametr jest obsługiwany od wersji 132 i nowszych. |
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"]
}
Dostawcy tożsamości mogą obsługiwać wiele plików konfiguracji, podając w pliku well-known wartości accounts_endpoint i login_url.
Ta funkcja może być przydatna w tych sytuacjach:
- IdP musi obsługiwać wiele różnych konfiguracji testowych i produkcyjnych.
- Dostawca tożsamości musi obsługiwać różne konfiguracje w poszczególnych regionach (np.
eu-idp.exampleius-idp.example).
Aby obsługiwać wiele konfiguracji (np. aby odróżnić środowisko testowe od produkcyjnego), dostawca tożsamości musi określić accounts_endpoint i login_url:
{
// This property is required, but will be ignored when IdP supports
// multiple configs (when `accounts_endpoint` and `login_url` are
// specified), as long as `accounts_endpoint` and `login_url` in
// that config file match those in the well-known file.
"provider_urls": [ "https://idp.example/fedcm.json" ],
// Specify accounts_endpoint and login_url properties to support
// multiple config files.
// Note: The accounts_endpoint and login_url must be identical
// across all config files. Otherwise,
// the configurations won't be supported.
"accounts_endpoint": "https://idp.example/accounts",
"login_url": "https://idp.example/login"
}
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
musi hostować co najmniej 1 plik konfiguracji oraz wymagane punkty końcowe i adresy URL. Wszystkie odpowiedzi JSON muszą być dostarczane 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;
RP przekaże adres URL pliku konfiguracji do wywołania interfejsu FedCM API, aby umożliwić użytkownikowi zalogowanie się:
// Executed on RP's side:
const credential = await navigator.credentials.get({
identity: {
context: 'signup',
providers: [{
// To allow users to sign in with an IdP using FedCM, RP specifies the IdP's config file URL:
configURL: 'https://accounts.idp.example/fedcm.json',
clientId: '********',
});
const { token } = credential;
Przeglądarka pobiera plik konfiguracji za pomocą żądania GET bez nagłówka Origin ani 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 uwierzytelniania 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
IdP musi zaimplementować punkt końcowy konfiguracji, który odpowiada w formacie JSON. Dane JSON zawierają te właściwości:
| Właściwość | Opis |
|---|---|
accounts_endpoint (wymagane) |
Adres URL punktu końcowego accounts. |
accounts.include (opcjonalnie)
|
Niestandardowy ciąg etykiety konta określający, które konta mają zostać zwrócone podczas używania tego pliku konfiguracji, np. "accounts": {"include": "developer"}.
Dostawca tożsamości może wdrożyć niestandardowe etykiety kont w ten sposób:
Na przykład dostawca tożsamości implementuje "https://idp.example/developer-config.json" plik konfiguracji z wartością "accounts": {"include": "developer"}. IdP oznacza też niektóre konta etykietą "developer" za pomocą parametru labels w punkcie końcowym accounts. Gdy RP wywołuje funkcję navigator.credentials.get() z wyznaczonym plikiem konfiguracji "https://idp.example/developer-config.json", zwracane są tylko konta z etykietą "developer".
|
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 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) |
Tablica obiektów ikony. Te ikony są wyświetlane w oknie logowania. Obiekt ikony ma 2 parametry:
|
modes |
Obiekt zawierający specyfikacje sposobu wyświetlania interfejsu FedCM w różnych trybach:
|
modes.active
|
Obiekt zawierający właściwości, które umożliwiają dostosowanie działania FedCM w określonym trybie. Zarówno modes.active, jak i modes.passive mogą zawierać ten parametr:
Uwaga: funkcja Użyj innego konta i tryb aktywny są obsługiwane od wersji Chrome 132. |
modes.passive
|
Oto przykład treści odpowiedzi uwierzytelniciela tożsamości:
{
"accounts_endpoint": "/accounts.example",
"client_metadata_endpoint": "/client_metadata.example",
"id_assertion_endpoint": "/assertion.example",
"disconnect_endpoint": "/disconnect.example",
"login_url": "/login",
// When RPs use this config file, only those accounts will be
//returned that include `developer` label in the accounts endpoint.
"accounts": {"include": "developer"},
"modes": {
"active": {
"supports_use_other_account": true,
}
},
"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:
Użyj innego konta
Użytkownicy mogą przełączyć się na inne konto niż to, na którym są obecnie zalogowani, jeśli dostawca tożsamości obsługuje wiele kont lub zastępuje istniejące konto.
Aby umożliwić użytkownikowi wybór innych kont, dostawca tożsamości musi określić tę funkcję w pliku konfiguracyjnym:
{
"accounts_endpoint" : "/accounts.example",
"modes": {
"active": {
// Allow the user to choose other account (false by default)
"supports_use_other_account": true
}
// "passive" mode can be configured separately
}
}
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 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.example HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
Po otrzymaniu żądania serwer powinien:
- Sprawdź, czy żądanie zawiera nagłówek HTTP
Sec-Fetch-Dest: webidentity. - Dopasuj pliki cookie sesji do identyfikatorów kont, na których użytkownik jest już zalogowany.
- 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. |
labels (opcjonalnie)
|
Tablica ciągów znaków z etykietami niestandardowych kont, z którymi powiązane jest konto. Dostawca tożsamości może wdrożyć niestandardowe etykiety kont w ten sposób:
Na przykład dostawca tożsamości implementuje plik konfiguracji https://idp.example/developer-config.json (config) z parametrem "accounts": {"include": "developer"}. IdP oznacza też niektóre konta etykietą "developer" za pomocą parametru labels w punkcie końcowym kont. Gdy RP wywołuje funkcję navigator.credentials.get() z wyznaczonym plikiem konfiguracji https://idp.example/developer-config.json, zwracane są tylko konta z etykietą "developer".Etykiety kont niestandardowych różnią się od podpowiedzi dotyczących logowania i podpowiedzi dotyczących domeny tym, że są w pełni obsługiwane przez serwer dostawcy tożsamości, a usługa uwierzytelniająca określa tylko plik konfiguracji, którego należy użyć. |
Przykładowa treść odpowiedzi:
{
"accounts": [{
"id": "1234",
"given_name": "John",
"name": "John Doe",
"email": "john_doe@idp.example",
"picture": "https://idp.example/profile/123",
// Ids of those RPs where this account can be used
"approved_clients": ["123", "456", "789"],
// This account has 'login_hints`. When an RP calls `navigator.credentials.get()`
// with a `loginHint` value specified, for example, `exampleHint`, only those
// accounts will be shown to the user whose 'login_hints' array contains the `exampleHint`.
"login_hints": ["demo1", "exampleHint"],
// This account is labelled. IdP can implement a specific config file for a
// label, for example, `https://idp.example/developer-config.json`. Like that
// RPs can filter out accounts by calling `navigator.credentials.get()` with
// `https://idp.example/developer-config.json` config file.
"labels": ["hr", "developer"]
}, {
"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"],
"domain_hints": ["@domain.example"]
}]
}
Jeśli użytkownik nie jest zalogowany, odpowiedz: HTTP 401 (Nieupoważniony).
Zwrócona lista kont jest wykorzystywana przez przeglądarkę i nie jest dostępna dla RP.
Punkt końcowy potwierdzenia tożsamości
Punkt końcowy oświadczenia tożsamości dostawcy tożsamości zwraca oświadczenie dotyczące 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 z wartością 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. |
disclosure_text_shown |
Wynikiem jest ciąg znaków "true" lub "false" (a nie wartość logiczna). Wynik jest "false" w tych przypadkach:
|
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. |
fields (opcjonalnie)
|
Tablica ciągów znaków określająca informacje o użytkowniku (np. „name”, „email”, „picture”), które RP musi udostępnić IdP. Przeglądarka wyśle fields, disclosure_text_shown i disclosure_shown_for, podając określone pola w żądaniu POST, jak w tym przykładzie.Uwaga: parametr Fields jest obsługiwany od wersji Chrome 132. |
params (opcjonalnie)
|
dowolny prawidłowy obiekt JSON, który umożliwia określenie dodatkowych niestandardowych parametrów klucz-wartość, np.:
params zostanie zserializowana do formatu JSON, a następnie zakodowana w formacie procentowym.Uwaga: interfejs Parameters API jest obsługiwany w Chrome 132 i nowszych wersjach. |
Przykład nagłówka HTTP:
POST /assertion.example HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
// disclosure_text_shown is set to 'false', as the 'name' field value is missing in 'fields' array
// params value is serialized to JSON and then percent-encoded.
account_id=123&client_id=client1234&disclosure_text_shown=false&is_auto_selected=true¶ms=%22%7B%5C%22nonce%5C%22%3A%5C%22nonce-value%5C%22%7D%22.%0D%0A4&disclosure_text_shown=true&fields=email,picture&disclosure_shown_for=email,picture
Po otrzymaniu żądania serwer powinien:
- Odpowiedz na żądanie za pomocą CORS (współdzielenie zasobów pomiędzy serwerami z różnych domen).
- Sprawdź, czy żądanie zawiera nagłówek HTTP
Sec-Fetch-Dest: webidentity. - Dopasuj nagłówek
Origindo źródła RP określonego przezclient_id. Odrzuć, jeśli się nie zgadzają. - Dopasuj
account_iddo identyfikatora konta, na którym jesteś już zalogowany. Odrzuć, jeśli nie pasują. - Odpowiedz za pomocą tokena. Jeśli żądanie zostanie odrzucone, odpowiedz za pomocą odpowiedzi na błąd.
IdP może decydować o sposobie wydawania tokena. Zwykle jest on podpisany za pomocą informacji takich jak identyfikator konta, identyfikator klienta, pochodzenie wystawcy i nonce, aby RP mógł zweryfikować autentyczność tokena.
Przeglądarka oczekuje odpowiedzi JSON zawierającej tę właściwość:
| Właściwość | Opis |
|---|---|
token |
Token to ciąg tekstowy zawierający oświadczenia dotyczące uwierzytelniania. |
continue_on |
Adres URL przekierowania umożliwiający wieloetapowy proces logowania. |
Zwrócony token jest przekazywany do RP przez przeglądarkę, aby RP mógł zweryfikować uwierzytelnianie.
{
// IdP can respond with a token to authenticate the user
"token": "***********"
}
Funkcja kontynuowania
Aby umożliwić wieloetapowy proces logowania, dostawca tożsamości może podać adres URL przekierowania w odpowiedzi punktu końcowego oświadczenia tożsamości. Jest to przydatne, gdy dostawca tożsamości musi poprosić o dodatkowe informacje lub uprawnienia, na przykład:
- Uprawnienia dostępu do zasobów po stronie serwera użytkownika.
- weryfikacja, czy informacje kontaktowe są aktualne;
- Kontrola rodzicielska.
Punkt końcowy potwierdzenia tożsamości może zwracać właściwość continue_on, która zawiera ścieżkę bezwzględną lub względną do punktu końcowego potwierdzenia tożsamości.
{
// In the id_assertion_endpoint, instead of returning a typical
// "token" response, the IdP decides that it needs the user to
// continue on a popup window:
"continue_on": "https://idp.example/continue_on_url"
}
Jeśli odpowiedź zawiera parametr continue_on, otwiera się nowe okno, które przekierowuje użytkownika do określonej ścieżki.
Po interakcji użytkownika ze stroną continue_on dostawca tożsamości powinien wywołać funkcję IdentityProvider.resolve(), przekazując jako argument token, aby można było rozwiązać obietnicę z pierwotnego wywołania funkcji navigator.credentials.get():
document.getElementById('example-button').addEventListener('click', async () => {
let accessToken = await fetch('/generate_access_token.cgi');
// Closes the window and resolves the promise (that is still hanging
// in the relying party's renderer) with the value that is passed.
IdentityProvider.resolve(accessToken);
});
Przeglądarka automatycznie zamknie wyskakujące okienko i zwróci token do wywołującego interfejs API. Wywołanie funkcji IdentityProvider.resolve() jest jedynym sposobem na komunikację między oknem nadrzędnym (RP) a oknem wyskakującym (IdP).
Jeśli użytkownik odrzuci prośbę, dostawca tożsamości może zamknąć okno, wywołując funkcję IdentityProvider.close().
IdentityProvider.close();
Aby działać, interfejs Continuation API wymaga wyraźnej interakcji użytkownika (kliknięć). Oto jak interfejs Continuation API działa w różnych trybach mediacji:
- W trybie pasywnym:
mediation: 'optional'(domyślnie): interfejs Continuation API działa tylko w reakcji na działanie użytkownika, np. kliknięcie przycisku na stronie lub w interfejsie FedCM. Gdy automatyczne ponowne uwierzytelnianie jest uruchamiane bez interakcji użytkownika, nie otwiera się wyskakujące okienko, a obietnica jest odrzucana.mediation: 'required': zawsze prosi użytkownika o działanie, więc interfejs Continuation API zawsze działa.
- W trybie aktywnym:
- Aktywacja użytkownika jest zawsze wymagana. Interfejs Continuation API jest zgodny.
Jeśli z jakiegoś powodu użytkownik zmienił konto w wyskakującym okienku (na przykład dostawca tożsamości oferuje funkcję „Użyj innego konta” lub w przypadku delegowania), wywołanie resolve przyjmuje opcjonalny drugi argument, który umożliwia takie działanie:
IdentityProvider.resolve(token, {accountId: '1234');
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_erroritemporarily_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 formie czytelnej dla człowieka, która zawiera informacje o błędzie, aby zapewnić użytkownikom dodatkowe informacje o nim. 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ściconfigURL.
// id_assertion_endpoint response
{
"error" : {
"code": "access_denied",
"url" : "https://idp.example/error?type=access_denied"
}
}
Etykiety własne konta
Dzięki niestandardowym etykietom kont dostawca tożsamości może dodawać do kont użytkowników etykiety, a usługodawca zewnętrzny może pobierać tylko konta z określonymi etykietami, podając configURL dla danej etykiety. Może to być przydatne, gdy RP musi odfiltrować konta według określonych kryteriów, np. aby wyświetlić tylko konta o określonych rolach, takie jak "developer" lub "hr".
Podobne filtrowanie jest możliwe za pomocą funkcji Domain Hint (Wskazówka dotycząca domeny) i Login Hint (Wskazówka dotycząca logowania), które należy określić w wywołaniu navigator.credentials.get(). Etykiety kont niestandardowych mogą jednak filtrować użytkowników przez określenie pliku konfiguracji, co jest szczególnie przydatne, gdy używasz wielu adresów URL konfiguracji. Etykiet niestandardowych kont różnią się też tym, że są dostarczane przez serwer dostawcy tożsamości, a nie przez dostawcę usług, tak jak wskazówki dotyczące logowania czy domeny.
Rozważ usługę uwierzytelniającą, która chce odróżnić konta "developer" i "hr". Aby to zrobić, dostawca tożsamości musi obsługiwać 2 adresy URL konfiguracji: "developer" i "hr".
- Plik konfiguracji dla dewelopera
https://idp.example/developer/fedcm.jsonma etykietę"developer", a plik konfiguracji dla przedsiębiorstwahttps://idp.example/hr/fedcm.jsonma etykietę"hr":
// The developer config file at `https://idp.example/developer/fedcm.json`
{
"accounts_endpoint": "https://idp.example/accounts",
"client_metadata_endpoint": "/client_metadata",
"login_url": "https://idp.example/login",
"id_assertion_endpoint": "/assertion",
"accounts": {
// Account label
"include": "developer"
}
}
// The hr config file at `https://idp.example/hr/fedcm.json`
{
"accounts_endpoint": "https://idp.example/accounts",
"client_metadata_endpoint": "/client_metadata",
"login_url": "https://idp.example/login",
"id_assertion_endpoint": "/assertion",
"accounts": {
// Account label
"include": "hr"
}
}
- W takim przypadku plik well-known powinien zawierać
accounts_endpointilogin_url, aby umożliwić użycie wielu adresów URL konfiguracji:
{
"provider_urls": [ "https://idp.example/fedcm.json" ],
"accounts_endpoint": "https://idp.example/accounts",
"login_url": "https://idp.example/login"
}
- Wspólny punkt końcowy IdP accounts (w tym przykładzie
https://idp.example/accounts) zwraca listę kont, która zawiera usługęlabelsz przypisanymi etykietami w tablicy dla każdego konta:
{
"accounts": [{
"id": "123",
"given_name": "John",
"name": "John Doe",
"email": "john_doe@idp.example",
"picture": "https://idp.example/profile/123",
"labels": ["developer"]
}], [{
"id": "4567",
"given_name": "Jane",
"name": "Jane Doe",
"email": "jane_doe@idp.example",
"picture": "https://idp.example/profile/4567",
"labels": ["hr"]
}]
}
Gdy RP chce zezwolić użytkownikom "hr" na logowanie, może podać adres URL konfiguracji https://idp.example/hr/fedcm.json w wywołaniu navigator.credentials.get():
let { token } = await navigator.credentials.get({
identity: {
providers: [{
clientId: '1234',
nonce: '234234',
configURL: 'https://idp.example/hr/fedcm.json',
},
}
});
W efekcie użytkownik może zalogować się tylko na konto 4567, którego identyfikator jest widoczny. Identyfikator konta 123 jest po cichu ukrywany przez przeglądarkę, aby użytkownik nie otrzymał konta, które nie jest obsługiwane przez dostawcę tożsamości w tej witrynie.
- Etykiety to ciągi znaków. Jeśli tablica
labelslub poleincludezawiera coś innego niż ciąg znaków, jest ono ignorowane. - Jeśli w parametry
configURLnie są określone żadne etykiety, w selektorze kont FedCM będą wyświetlane wszystkie konta. - Jeśli dla konta nie ma określonych etykiet, będzie ono wyświetlane w selektorze kont tylko wtedy, gdy
configURLteż nie ma etykiety. - Jeśli w trybie pasywnym nie ma konta pasującego do żądanej etykiety (podobnie jak w przypadku funkcji podpowiedzi dotyczącej domeny), w oknie FedCM wyświetla się monit logowania, który umożliwia użytkownikowi zalogowanie się na konto dostawcy tożsamości. W trybie aktywnym okienko logowania otwiera się bezpośrednio.
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.example 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:
- Odpowiedz na żądanie za pomocą CORS (współdzielenie zasobów pomiędzy serwerami z różnych domen).
- Sprawdź, czy żądanie zawiera nagłówek HTTP
Sec-Fetch-Dest: webidentity. - Dopasuj nagłówek
Origindo źródła RP określonego przezclient_id. Odrzuć, jeśli się nie zgadzają. - Dopasuj
account_hintdo identyfikatorów kont, na których użytkownicy są już zalogowani. - Odłącz konto użytkownika od RP.
- 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 "*".
Punkt końcowy metadanych klienta
Punkt końcowy metadanych klienta dostawcy tożsamości zwraca metadane strony korzystającej, takie jak polityka prywatności, warunki korzystania z usługi i ikony logo. 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.example?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:
- Określ RP dla
client_id. - 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. |
icons (opcjonalnie) |
tablica obiektów, np. [{ "url": "https://rp.example/rp-icon.ico", "size": 40}] |
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",
"icons": [{
"url": "https://rp.example/rp-icon.ico",
"size": 40
}]
}
Zwrócone metadane klienta są używane przez przeglądarkę i nie są dostępne dla RP.
URL logowania
Ten punkt końcowy służy do logowania użytkownika w systemie dostawcy tożsamości.
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.
Gdy użytkownik kliknie przycisk Dalej, przeglądarka otworzy okno logowania 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 się zaloguje, dostawca tożsamości powinien:
- Wyślij nagłówek
Set-Login: logged-inlub wywołaj interfejs APInavigator.login.setStatus("logged-in"), aby poinformować przeglądarkę, że użytkownik zalogował się. - Wybierz
IdentityProvider.close(), aby zamknąć okno.
Informowanie przeglądarki o stanie logowania użytkownika
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 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 (identyfikowanego za pomocą adresu URL konfiguracji) przeglądarka przechowuje zmienną o 3 stanach, która reprezentuje stan logowania z możliwymi wartościami:
logged-inlogged-outunknown(domyślnie)
| Stan logowania | Opis |
|---|---|
logged-in |
Gdy stan logowania użytkownika ma wartość 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 FedCM. |
logged-out |
Gdy stan logowania użytkownika to logged-out, wywołanie interfejsu FedCM kończy się niepowodzeniem bez wysłania żądania do punktu końcowego kont dostawcy tożsamości. |
unknown (domyślnie) |
Stan unknown jest ustawiany, zanim dostawca tożsamości wyśle sygnał za pomocą interfejsu Login Status API. Gdy stan to unknown, przeglądarka wysyła żądanie do punktu końcowego kont dostawcy tożsamości i aktualizuje stan na podstawie odpowiedzi z punktu końcowego kont. |
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ć metodę JavaScript navigator.login.setStatus('logged-in') w źródle dostawcy tożsamości w menu najwyższego poziomu:
navigator.login.setStatus('logged-in')
Stan logowania użytkownika zostanie ustawiony jako logged-in.
Aby zasygnalizować, że użytkownik wylogował się ze wszystkich kont, wyślij nagłówek HTTP Set-Login: logged-out w nawigacji najwyższego poziomu lub żądanie zasobu podrzędnego w tym samym miejscu u źródła 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')
Stan logowania użytkownika zostanie ustawiony jako logged-out.
Stan unknown jest ustawiany, zanim dostawca tożsamości wyśle sygnał za pomocą interfejsu Login Status API. Przeglądarka 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-ini otwórz okno FedCM, aby wyświetlić te konta. - Jeśli punkt końcowy nie zwróci żadnych kont, zaktualizuj stan na
logged-outi 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.
Implementowanie FedCM jako grupy objętej ograniczeniami
Gdy konfiguracja i punkty końcowe dostawcy tożsamości będą dostępne, dostawcy żądań mogą wywoływać funkcję navigator.credentials.get(), aby umożliwić użytkownikom logowanie się w dostawcy żądań za pomocą dostawcy tożsamości.
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
} else {
// FedCM is not supported, use a different identity solution
}
Aby umożliwić użytkownikom logowanie się w systemie dostawcy tożsamości za pomocą interfejsu FedCM, RP może wywołać funkcję navigator.credentials.get(), na przykład:
const credential = await navigator.credentials.get({
identity: {
context: 'signin',
providers: [{
configURL: 'https://accounts.idp.example/config.json',
clientId: '********',
mode: 'active',
params: {
nonce: '******'
}
}]
}
});
const { token } = credential;
Właściwość context
Opcjonalna właściwość context umożliwia RP modyfikowanie ciągu w interfejsie dialogowym FedCM (np. „Zaloguj się w rp.example…” lub „Użyj idp.example…”), aby uwzględnić na przykład wstępnie zdefiniowane konteksty uwierzytelniania. Właściwość context może mieć te wartości:
signin(domyślnie)signupuse
Na przykład ustawienie wartości context na use spowoduje wyświetlenie tego komunikatu:
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 tekstu „Aby kontynuować…”.
Właściwość providers przyjmuje tablicę obiektów IdentityProvider, które mają te właściwości:
Właściwość dostawcy
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 polegającym na odtwarzaniu pakietów danych. |
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) |
Po wybraniu jednej z wartości domain_hints udostępnionych przez punkty końcowe kont, w oknie FedCM wyświetlane jest wybrane konto. |
mode (opcjonalnie) |
Ciąg znaków określający tryb interfejsu FedCM. Może on przyjmować jedną z tych wartości:
Uwaga: parametr mode jest obsługiwany od wersji Chrome 132.
|
fields (opcjonalnie) |
Tablica ciągów znaków określająca informacje o użytkowniku (np. „name”, „email”, „picture”), które RP musi udostępnić IdP. Uwaga: interfejs Field API jest obsługiwany w Chrome 132 i nowszych wersjach. |
parameters (opcjonalnie) |
Obiekt niestandardowy, który umożliwia określenie dodatkowych parametrów klucz-wartość:
Uwaga: parameters jest obsługiwana od wersji Chrome 132.
|
Tryb aktywny
FedCM obsługuje różne konfiguracje trybu UX. Tryb pasywny jest trybem domyślnym i nie wymaga konfiguracji przez deweloperów.
Aby korzystać z FedCM w trybie aktywnym:
- Sprawdź dostępność funkcji w przeglądarce użytkownika.
- Wywołanie interfejsu API za pomocą tymczasowego gestu użytkownika, np. kliknięcia przycisku.
- Przekaż parametr
modedo wywołania interfejsu API:
let supportsFedCmMode = false;
try {
navigator.credentials.get({
identity: Object.defineProperty(
// Check if this Chrome version supports the Mode API.
{}, 'mode', {
get: function () { supportsFedCmMode = true; }
}
)
});
} catch(e) {}
if (supportsFedCmMode) {
// The button mode is supported. Call the API with mode property:
return await navigator.credentials.get({
identity: {
providers: [{
configURL: 'https://idp.example/config.json',
clientId: '123',
}],
// The 'mode' value defines the UX mode of FedCM.
// - 'active': Must be initiated by user interaction (e.g., clicking a button).
// - 'passive': Can be initiated without direct user interaction.
mode: 'active'
}
});
}
Ikona niestandardowa w trybie aktywnym
Tryb aktywny umożliwia dostawcom tożsamości dodanie oficjalnej ikony logo dostawcy RP bezpośrednio w odpowiedzi punktu końcowego metadanych klienta. RP musi wcześniej udostępnić dane dotyczące marki.
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 Zarządzanie funkcjami przeglądarki za pomocą zasad dotyczących uprawnień.
Login Hint API
Za pomocą wskazówki logowania RP może zalecić, na którym koncie użytkownik powinien się zalogować. Może to być przydatne w przypadku ponownego uwierzytelniania użytkowników, którzy nie są pewni, którego konta używali wcześniej.
RP mogą selektywnie wyświetlać konkretne konto, wywołując navigator.credentials.get() z uwzględnieniem 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',
// Accounts endpoint can specify a 'login_hints' array for an account.
// When RP specifies a 'exampleHint' value, only those accounts will be
// shown to the user whose 'login_hints' array contains the 'exampleHint'
// value
loginHint : 'exampleHint'
}]
}
});
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 podpowiedzi dotyczącej logowania i podpowiedzi dotyczącej domeny.
Domain Hint API
Reprezentanci mogą selektywnie wyświetlać tylko konta powiązane z określoną domeną. Może to być przydatne w przypadku RP, które są ograniczone do domeny firmowej.
Aby wyświetlić tylko konta w konkretnej domenie, RP powinien wywołać funkcję navigator.credentials.get() z właściwością domainHint zawierającą 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',
// Accounts endpoint can specify a 'domain_hints' array for an account.
// When RP specifies a '@domain.example' value, only those accounts will be
// shown to the user whose 'domain_hints' array contains the
// '@domain.example' value
domainHint : '@domain.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 podpowiedzi dotyczącej logowania i podpowiedzi dotyczącej domeny.
domainHint.Parametry niestandardowe
Funkcja parametrów niestandardowych umożliwia RP przekazywanie dodatkowych parametrów klucz-wartość do punktu końcowego potwierdzenia tożsamości. Dzięki interfejsowi Parameters API dostawcy usług rejestracji mogą przekazywać dodatkowe parametry dostawcy tożsamości, aby prosić o uprawnienia dotyczące zasobów wykraczających poza podstawowe logowanie. Przekazywanie dodatkowych parametrów może być przydatne w tych sytuacjach:
- RP musi żądać dodatkowych uprawnień, które IdP ma, takich jak adres rozliczeniowy lub dostęp do kalendarza. Użytkownik może autoryzować te uprawnienia za pomocą kontrolowanego przez dostawcę tożsamości procesu interfejsu użytkownika, który jest uruchamiany za pomocą funkcji Kontynuuj. Dostawca tożsamości udostępnia następnie te informacje.
Aby korzystać z interfejsu API, RP dodaje parametry do właściwości params jako obiekt w wywołaniu navigator.credentials.get():
let {token} = await navigator.credentials.get({
identity: {
providers: [{
clientId: '1234',
configURL: 'https://idp.example/fedcm.json',
// Key/value pairs that need to be passed from the
// RP to the IdP but that don't really play any role with
// the browser.
params: {
IDP_SPECIFIC_PARAM: '1',
foo: 'BAR'
}
},
}
});
Przeglądarka automatycznie przekształci to w żądanie POST do dostawcy tożsamości z parametrami jako pojedynczy obiekt JSON zakodowany w formacie URL:
// The assertion endpoint is drawn from the config file
POST /fedcm_assertion_endpoint HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
// params are translated into urlencoded version of `{"IDP_SPECIFIC_PARAM":"1","foo":"bar"}`
account_id=123&client_id=client1234¶ms=%22%7B%5C%22IDP_SPECIFIC_PARAM%5C%22%3A1%2C%5C%22foo%5C%22%3A%5C%22BAR%5C%22%7D%22.
Jeśli RP potrzebuje dodatkowych uprawnień, dostawca tożsamości może podać link przekierowania. Na przykład w node.js:
if (rpRequestsPermissions) {
// Response with a URL if the RP requests additional permissions
return res.json({
continue_on: '/example-redirect',
});
}
Pola
RP może określić informacje o użytkowniku (dowolną kombinację imienia i nazwiska, adresu e-mail i zdjęcia profilowego), które IdP musi udostępnić. Poproś o podanie informacji, które mają być uwzględnione w interfejsie FedCM. Jeśli użytkownik zdecyduje się na zalogowanie, zobaczy komunikat informujący, że idp.example udostępni rp.example żądane informacje.
Aby korzystać z funkcji pól, RP powinien dodać tablicę fields w wywołaniu navigator.credentials.get(). Pola mogą zawierać dowolną permutację wartości name, email i picture. W przyszłości możemy rozszerzyć tę listę o kolejne wartości.
Prośba z fields będzie wyglądać tak:
let { token } = await navigator.credentials.get({
identity: {
providers: [{
// RP requests the IdP to share only user email and profile picture
fields: [ 'email', 'picture'],
clientId: '1234',
configURL: 'https://idp.example/fedcm.json',
},
}
});
Przeglądarka automatycznie przekształci je w żądanie HTTP do punktu końcowego oświadczenia tożsamości, które zawiera parametr fields określony przez RP, z polami, które przeglądarka ujawniła użytkownikowi, w parametrze disclosure_shown_for. Ze względu na zgodność wsteczną przeglądarka wysyła też odpowiedź disclosure_text_shown=true, jeśli wyświetlono tekst informacyjny, a wśród żądanych pól znajdują się wszystkie 3 pola: 'name', 'email' i 'picture'.
POST /id_assertion_endpoint HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
// The RP only requested to share email and picture. The browser will send `disclosure_text_shown=false`, as the 'name' field value is missing
account_id=123&client_id=client1234&disclosure_text_shown=false&fields=email,picture&disclosure_shown_for=email,picture
Jeśli tablica fields jest pusta, klient użytkownika pominie interfejs wyświetlania informacji.
Dzieje się tak nawet wtedy, gdy odpowiedź z punktu końcowego accounts nie zawiera identyfikatora klienta pasującego do RP w approved_clients.
W tym przypadku wartość disclosure_text_shown wysłana do punktu końcowego oświadczenia o tożsamości jest w treści HTTP równa fałsz:
POST /id_assertion_endpoint HTTP/1.1
Host: 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=234234&disclosure_text_shown=false
wyświetlić komunikat o błędzie.
Czasami dostawca tożsamości może nie być w stanie wydać tokena z uzasadnionych przyczyn, np. gdy klient nie jest autoryzowany lub serwer jest tymczasowo niedostępny. Jeśli dostawca tożsamości zwróci odpowiedź „error”, dostawca aplikacji może ją przechwycić, a Chrome może powiadomić użytkownika, wyświetlając informacje o błędzie przesłane przez dostawcę tożsamości.
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 już wcześniej zaakceptował.
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. Działa tak samo 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, 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) lub bezproblemowe niepowodzenie (jeśli nie jest możliwe) bez konieczności interwencji. 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 automatyczne ponowne uwierzytelnianie odbywa się w ramach tych warunków:
- 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 nastąpiła 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.
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 Chrome i synchronizacja jest włączona.
Odłącz dostawcę tożsamości od RP
Jeśli użytkownik zalogował się wcześniej w 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.
- Nie udało się sprawdzić standardu Content Security Policy (CSP).
- 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.