Dowiedz się, jak używać FedCM do federacji tożsamości chroniących prywatność.
FedCM (Federated Credential Management) to rozwiązanie chroniące prywatność usług sfederowanych usług tożsamości (np. „Zaloguj się przez...”), w których użytkownicy mogą logować się w witrynach bez udostępniania swoich danych osobowych usłudze tożsamości lub witrynie.
Więcej informacji o przypadkach użycia, przepływach użytkowników i planach działania FedCM znajdziesz we wprowadzeniu do FedCM API.
Środowisko programistyczne FedCM
Aby korzystać z FedCM, potrzebujesz bezpiecznego kontekstu (HTTPS lub localhost) zarówno u dostawcy tożsamości, jak i RP w Chrome.
Debugowanie kodu w Chrome na Androidzie
Skonfiguruj i uruchom serwer lokalnie, aby debugować kod FedCM. Możesz uzyskać dostęp do tego serwera w Chrome na urządzeniu z Androidem podłączonym kablem USB z przekierowaniem portów.
Aby debugować Chrome na urządzeniu z Androidem, możesz użyć Narzędzi deweloperskich na komputerze. Instrukcje znajdziesz w artykule Zdalne debugowanie urządzeń z Androidem.
Blokowanie plików cookie innych firm w Chrome
Możesz sprawdzić, jak FedCM działa w Chrome bez plików cookie innych firm, zanim zostanie w pełni egzekwowane.
Aby zablokować pliki cookie innych firm, użyj trybu incognito lub wybierz „Blokuj pliki cookie innych firm” w ustawieniach komputera na chrome://settings/cookies
albo na urządzeniu mobilnym, klikając Ustawienia > Ustawienia witryn > Pliki cookie.
Korzystanie z interfejsu FedCM API
Integrację z FedCM możesz przeprowadzić, tworząc dobrze znany plik, plik konfiguracji i punkty końcowe na potrzeby listy kont, tworzenia asercji i opcjonalnie metadanych klienta.
Następnie FedCM udostępnia interfejsy API JavaScript, których członkowie RP mogą używać do logowania się u dostawcy tożsamości.
Utwórz dobrze znany plik
Aby moduły śledzące nie nadużywały interfejsu API, musi być udostępniany dobrze znany plik z /.well-known/web-identity
eTLD+1 dostawcy tożsamości.
Jeśli na przykład punkty końcowe dostawcy tożsamości są udostępniane w domenie https://accounts.idp.example/
, muszą udostępniać dobrze znany plik pod adresem https://idp.example/.well-known/web-identity
, a także plik konfiguracyjny dostawcy tożsamości. Oto przykład dobrze znanej zawartości pliku:
{
"provider_urls": ["https://accounts.idp.example/config.json"]
}
Plik JSON musi zawierać właściwość provider_urls
z tablicą adresów URL pliku konfiguracyjnego dostawcy tożsamości, które można określić jako część ścieżki configURL
w navigator.credentials.get
przez RP. Liczba ciągów adresów URL w tablicy jest ograniczona do jednego, ale w przyszłości może się to zmienić wraz z Twoją opinią.
Tworzenie pliku konfiguracyjnego dostawcy tożsamości i punktów końcowych
Plik konfiguracji dostawcy tożsamości zawiera listę punktów końcowych wymaganych dla przeglądarki. Dostawcy tożsamości będą hostować ten plik konfiguracyjny oraz wymagane punkty końcowe i adresy URL. Wszystkie odpowiedzi JSON muszą być udostępniane z typem treści application/json
.
Adres URL pliku konfiguracji jest określany na podstawie wartości podanych w wywołaniu navigator.credentials.get
wykonanego w grupie objętej ograniczeniami.
const credential = await navigator.credentials.get({
identity: {
context: 'signup',
providers: [{
configURL: 'https://accounts.idp.example/config.json',
clientId: '********',
nonce: '******'
}]
}
});
const { token } = credential;
Podaj pełny adres URL lokalizacji pliku konfiguracji dostawcy tożsamości w polu configURL
. Po wywołaniu navigator.credentials.get()
w RP przeglądarka pobiera plik konfiguracyjny z żądaniem GET
bez nagłówka Origin
ani nagłówka Referer
. Żądanie nie ma plików cookie ani nie śledzi przekierowań.
Dzięki temu dostawca tożsamości nie może się dowiedzieć, kto wysłał żądanie i które strony objęły próbę połączenia. Na przykład:
GET /config.json HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity
Przeglądarka oczekuje od dostawcy tożsamości odpowiedzi JSON, która zawiera te właściwości:
Właściwość | Opis |
---|---|
accounts_endpoint (wymagane) |
URL punktu końcowego kont. |
client_metadata_endpoint (opcjonalnie) |
URL punktu końcowego metadanych klienta. |
id_assertion_endpoint (wymagane) |
URL punktu końcowego potwierdzenia identyfikatora. |
disconnect (opcjonalnie) |
URL odłączanego punktu końcowego. |
login_url (wymagane) |
Adres URL strony logowania, który umożliwia użytkownikowi zalogowanie się u dostawcy tożsamości. |
branding (opcjonalnie) |
Obiekt zawierający różne opcje marki. |
branding.background_color (opcjonalnie) |
Opcja marki, która ustawia kolor tła przycisku „Kontynuuj jako...”. Użyj odpowiedniej składni CSS: hex-color , hsl() , rgb() lub named-color . |
branding.color (opcjonalnie) |
Opcja marki, która ustawia kolor tekstu przycisku „Kontynuuj jako...”. Użyj odpowiedniej składni CSS: hex-color , hsl() , rgb() lub named-color . |
branding.icons (opcjonalnie) |
Opcja marki, która ustawia obiekt ikony wyświetlany w oknie logowania. Obiekt ikony to tablica z 2 parametrami:
|
RP może zmodyfikować ciąg w interfejsie okna FedCM za pomocą wartości identity.context
dla navigator.credentials.get()
, aby dostosować go do zdefiniowanych wstępnie kontekstów uwierzytelniania. Opcjonalną właściwością może być "signin"
(domyślna), "signup"
, "use"
lub "continue"
.
Przykładowa treść odpowiedzi od dostawcy tożsamości:
{
"accounts_endpoint": "/accounts.php",
"client_metadata_endpoint": "/client_metadata.php",
"id_assertion_endpoint": "/assertion.php",
"disconnect_endpoint": "/disconnect.php",
"login_url": "/login",
"branding": {
"background_color": "green",
"color": "#FFEEAA",
"icons": [{
"url": "https://idp.example/icon.ico",
"size": 25
}]
}
}
Gdy przeglądarka pobierze plik konfiguracyjny, wysyła kolejne żądania do punktów końcowych dostawcy tożsamości:
Punkt końcowy kont
Punkt końcowy kont dostawcy tożsamości zwraca listę kont, na których użytkownik jest obecnie zalogowany u dostawcy tożsamości. Jeśli dostawca tożsamości obsługuje wiele kont, ten punkt końcowy zwróci wszystkie zalogowane konta.
Przeglądarka wysyła żądanie GET
z plikami cookie z elementem SameSite=None
, ale bez parametru client_id
, nagłówka Origin
lub Referer
. Dzięki temu dostawca tożsamości nie będzie mógł się dowiedzieć, do której grupy objętej ograniczeniami próbuje się zalogować. Na przykład:
GET /accounts.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
Po otrzymaniu żądania serwer powinien:
- Sprawdź, czy żądanie zawiera nagłówek HTTP
Sec-Fetch-Dest: webidentity
. - Dopasuj pliki cookie sesji do identyfikatorów kont, na których jesteś już zalogowanym użytkownikiem.
- W odpowiedzi podaj listę kont.
Przeglądarka oczekuje odpowiedzi JSON, która będzie zawierać właściwość accounts
z tablicą informacji o koncie o tych właściwościach:
Właściwość | Opis |
---|---|
id (wymagane) |
Unikalny identyfikator użytkownika. |
name (wymagane) |
Imię i nazwisko użytkownika. |
email (wymagane) |
Adres e-mail użytkownika. |
given_name (opcjonalnie) |
Imię użytkownika. |
picture (opcjonalnie) |
Adres URL awatara użytkownika. |
approved_clients (opcjonalnie) |
Tablica identyfikatorów klientów RP, za pomocą których użytkownik zarejestrował się. |
login_hints (opcjonalnie) |
Tablica wszystkich możliwych typów filtrów obsługiwanych przez dostawcę tożsamości w celu określenia konta. Grupa z ograniczonym dostępem może wywołać navigator.credentials.get() z usługą loginHint , by wybiórczo wyświetlić określone konto. |
domain_hints (opcjonalnie) |
Tablica ze wszystkimi domenami, z którymi powiązane jest konto. Grupa z ograniczonym dostępem może wywołać filtr navigator.credentials.get() za pomocą właściwości domainHint , by odfiltrować konta. |
Przykładowa treść odpowiedzi:
{
"accounts": [{
"id": "1234",
"given_name": "John",
"name": "John Doe",
"email": "john_doe@idp.example",
"picture": "https://idp.example/profile/123",
"approved_clients": ["123", "456", "789"],
"login_hints": ["demo1", "demo1@idp.example"]
}, {
"id": "5678",
"given_name": "Johnny",
"name": "Johnny",
"email": "johnny@idp.example",
"picture": "https://idp.example/profile/456",
"approved_clients": ["abc", "def", "ghi"],
"login_hints": ["demo2", "demo2@idp.example"],
"domain_hints": ["corp.example"]
}]
}
Jeśli użytkownik nie jest zalogowany, w odpowiedzi prześlij kod HTTP 401 (Brak autoryzacji).
Zwrócona lista kont jest wykorzystywana przez przeglądarkę i nie jest dostępna dla grupy objętej ograniczeniami.
Punkt końcowy metadanych klienta
Punkt końcowy metadanych klienta dostawcy tożsamości zwraca metadane jednostki uzależnionej, takie jak polityka prywatności i warunki korzystania z usługi objętej ograniczeniami. Dostawcy tożsamości powinni z wyprzedzeniem udostępnić mu linki do swojej polityki prywatności i warunków korzystania z usługi. Te linki są wyświetlane w oknie logowania, gdy użytkownik nie zarejestrował się jeszcze w grupie objętej ograniczeniami u dostawcy tożsamości.
Przeglądarka wysyła żądanie GET
, korzystając z metody client_id
navigator.credentials.get
bez plików cookie. Na przykład:
GET /client_metadata.php?client_id=1234 HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Accept: application/json
Sec-Fetch-Dest: webidentity
Po otrzymaniu żądania serwer powinien:
- Określ RP dla:
client_id
. - W odpowiedzi użyj metadanych klienta.
Właściwości punktu końcowego metadanych klienta obejmują:
Właściwość | Opis |
---|---|
privacy_policy_url (opcjonalnie) |
Adres URL polityki prywatności grupy objętej ograniczeniami. |
terms_of_service_url (opcjonalnie) |
URL warunków korzystania z usługi objętej ograniczeniami. |
Przeglądarka oczekuje odpowiedzi JSON z punktu końcowego:
{
"privacy_policy_url": "https://rp.example/privacy_policy.html",
"terms_of_service_url": "https://rp.example/terms_of_service.html",
}
Zwrócone metadane klienta są wykorzystywane przez przeglądarkę i nie będą dostępne dla grupy objętej ograniczeniami.
Punkt końcowy potwierdzenia identyfikatora
Punkt końcowy potwierdzenia identyfikatora dostawcy tożsamości zwraca potwierdzenie dla zalogowanego użytkownika.
Gdy użytkownik loguje się w witrynie objętej ograniczeniami, korzystając z wywołania navigator.credentials.get()
, przeglądarka wysyła do tego punktu końcowego żądanie POST
z plikami cookie SameSite=None
i typem treści application/x-www-form-urlencoded
z tymi informacjami:
Właściwość | Opis |
---|---|
client_id (wymagane) |
Identyfikator klienta strony objętej ograniczeniami. |
account_id (wymagane) |
Unikalny identyfikator zalogowanego użytkownika. |
nonce (opcjonalnie) |
Liczba jednorazowa żądania podana przez grupę z ograniczonym dostępem. |
disclosure_text_shown |
Wynikiem jest ciąg "true" lub "false" (a nie wartość logiczna). Jeśli tekst oświadczenia nie został wyświetlony, otrzymasz wynik "false" . Dzieje się tak, gdy identyfikator klienta grupy objętej ograniczeniami znajduje się na liście właściwości approved_clients w odpowiedzi z punktu końcowego konta lub jeśli w przeszłości przeglądarka zaobserwowała moment rejestracji w przeszłości z powodu braku wartości approved_clients . |
is_auto_selected |
Jeśli w RPA wykonywane jest automatyczne ponowne uwierzytelnianie, is_auto_selected wskazuje "true" . W przeciwnym razie "false" . Dzięki temu będziemy mogli obsługiwać więcej funkcji związanych z bezpieczeństwem. Na przykład niektórzy użytkownicy mogą preferować wyższy poziom zabezpieczeń, który wymaga jawnego mediacji użytkowników podczas uwierzytelniania. Jeśli dostawca tożsamości otrzyma żądanie tokena bez zapośredniczenia, może je obsłużyć inaczej. Może to być na przykład zwrócenie kodu błędu, tak by grupa RP mogła ponownie wywołać interfejs FedCM API z parametrem mediation: required . |
Przykładowy nagłówek HTTP:
POST /assertion.php HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true&is_auto_selected=true
Po otrzymaniu żądania serwer powinien:
- Odpowiedz na żądanie za pomocą funkcji CORS (Udostępnianie zasobów w różnych źródłach).
- Sprawdź, czy żądanie zawiera nagłówek HTTP
Sec-Fetch-Dest: webidentity
. - Dopasuj nagłówek
Origin
do punktu początkowego RP określonego przezclient_id
. Odrzuć, jeśli nie pasują. - Dopasuj adres
account_id
do identyfikatora konta, na którym jesteś już zalogowanym użytkownikiem. Odrzuć, jeśli nie pasują. - Odpowiedz tokenem. Jeśli żądanie zostanie odrzucone, wyślij odpowiedź o błędzie.
Sposób przyznawania tokena zależy od dostawcy tożsamości, ale ogólnie jest on podpisany za pomocą takich informacji jak identyfikator konta, identyfikator klienta, źródło wydawcy nonce
, dzięki czemu platforma z ograniczonym dostępem może zweryfikować autentyczność tokena.
Przeglądarka oczekuje odpowiedzi JSON, która będzie zawierać tę właściwość:
Właściwość | Opis |
---|---|
token (wymagane) |
Token to ciąg znaków zawierający deklaracje dotyczące uwierzytelniania. |
{
"token": "***********"
}
Zwrócony token jest przekazywany do grupy objętej ograniczeniami przez przeglądarkę, aby jej członkowie mogli zweryfikować uwierzytelnianie.
Zwracanie odpowiedzi o błędzie
id_assertion_endpoint
może też zwrócić odpowiedź „błąd”, która ma 2 opcjonalne pola:
code
: dostawca tożsamości może wybrać jeden ze znanych błędów z listy błędów określonej przez OAuth 2.0 (invalid_request
,unauthorized_client
,access_denied
,server_error
itemporarily_unavailable
) lub użyć dowolnego ciągu znaków. Chrome renderuje wtedy interfejs błędu z ogólnym komunikatem o błędzie i przekazuje kod do RP.url
: identyfikuje czytelną dla człowieka stronę internetową z informacjami o błędzie, aby przekazać użytkownikom dodatkowe informacje o błędzie. To pole jest przydatne dla użytkowników, ponieważ przeglądarki nie zapewniają szczegółowych komunikatów o błędach w natywnym interfejsie użytkownika. Mogą to być na przykład linki do dalszych kroków, dane kontaktowe obsługi klienta itd. Jeśli użytkownik chce dowiedzieć się więcej o błędzie i sposobie jego naprawienia, może odwiedzić podaną stronę w interfejsie przeglądarki, aby uzyskać więcej informacji. Adres URL musi być w tej samej witrynie co dostawca tożsamościconfigURL
.
// id_assertion_endpoint response
{
"error" : {
"code": "access_denied",
"url" : "https://idp.example/error?type=access_denied"
}
}
Odłącz punkt końcowy
Wywołując IdentityCredential.disconnect()
, przeglądarka wysyła do tego rozłączonego punktu końcowego żądanie POST
z innymi domenami z plikami cookie (SameSite=None
i typem treści application/x-www-form-urlencoded
) zawierające te informacje:
Właściwość | Opis |
---|---|
account_hint |
Podpowiedź dotycząca konta dostawcy tożsamości... |
client_id |
Identyfikator klienta strony objętej ograniczeniami. |
POST /disconnect.php HTTP/1.1
Host: idp.example
Origin: rp.example
Content-Type: application/x-www-form-urlencoded
Cookie: 0x123
Sec-Fetch-Dest: webidentity
account_hint=account456&client_id=rp123
Po otrzymaniu żądania serwer powinien:
- Odpowiedz na żądanie za pomocą funkcji CORS (Udostępnianie zasobów w różnych źródłach).
- Sprawdź, czy żądanie zawiera nagłówek HTTP
Sec-Fetch-Dest: webidentity
. - Dopasuj nagłówek
Origin
do punktu początkowego RP określonego przezclient_id
. Odrzuć, jeśli nie pasują. - Dopasuj
account_hint
do identyfikatorów kont, na których jesteś już zalogowanym użytkownikiem. - Odłącz konto użytkownika od RP.
- Odpowiedz przeglądarce, podając zidentyfikowane informacje o koncie użytkownika w formacie JSON.
Przykładowy ładunek JSON odpowiedzi wygląda tak:
{
"account_id": "account456"
}
Jeśli dostawca tożsamości chce, aby przeglądarka rozłączyła wszystkie konta powiązane z grupą objętych ograniczeniami, podaj ciąg znaków, który nie pasuje do żadnego identyfikatora konta, na przykład "*"
.
URL logowania
Za pomocą interfejsu Login Status API dostawca tożsamości musi informować o stanie logowania użytkownika w przeglądarce. Może on jednak być niezsynchronizowany, na przykład sesja wygasa. W takiej sytuacji przeglądarka może dynamicznie zezwolić użytkownikowi na logowanie się u dostawcy tożsamości za pomocą adresu URL strony logowania określonego w pliku login_url
pliku konfiguracji dostawcy tożsamości.
W oknie FedCM pojawi się komunikat z sugestią zalogowania się, tak jak na ilustracji poniżej.
Gdy użytkownik kliknie przycisk Dalej, w przeglądarce otworzy się wyskakujące okienko ze stroną logowania dostawcy tożsamości.
Okno to zwykłe okno przeglądarki zawierające własne pliki cookie. Wszystko, co stanie się w oknie, zależy od dostawcy tożsamości. Żadne uchwyty okien nie są dostępne, aby wysłać żądanie komunikacji między domenami do strony RP. Po zalogowaniu się użytkownika dostawca tożsamości powinien:
- Wyślij nagłówek
Set-Login: logged-in
lub wywołaj interfejs APInavigator.login.setStatus("logged-in")
, aby poinformować przeglądarkę o zalogowaniu użytkownika. - Wywołaj
IdentityProvider.close()
, aby zamknąć okno.
Informuj przeglądarkę o stanie logowania użytkownika u dostawcy tożsamości
Interfejs API stanu logowania to mechanizm, w ramach którego witryna, a zwłaszcza dostawca tożsamości, informuje przeglądarkę o stanie logowania użytkownika u dostawcy tożsamości. Dzięki temu interfejsowi przeglądarka może ograniczyć liczbę niepotrzebnych żądań wysyłanych do dostawcy tożsamości i łagodzić potencjalne ataki czasowe.
Dostawcy tożsamości mogą informować przeglądarkę o stanie logowania użytkownika, wysyłając nagłówek HTTP lub wywołując interfejs JavaScript API, gdy użytkownik jest zalogowany w tym dostawcy lub gdy użytkownik jest wylogowany ze wszystkich swoich kont dostawcy tożsamości. W przypadku każdego dostawcy tożsamości (identyfikowanego na podstawie adresu URL konfiguracji) przeglądarka przechowuje zmienną trójstanową reprezentującą stan logowania z możliwymi wartościami logged-in
, logged-out
i unknown
. Stan domyślny to unknown
.
Aby zasygnalizować, że użytkownik jest zalogowany, wyślij nagłówek HTTP Set-Login: logged-in
w nawigacji najwyższego poziomu lub w żądaniu zasobu podrzędnego tej samej witryny w źródle dostawcy tożsamości:
Set-Login: logged-in
Możesz też wywołać JavaScript API navigator.login.setStatus("logged-in")
ze źródła dostawcy tożsamości w nawigacji najwyższego poziomu:
navigator.login.setStatus("logged-in")
Te połączenia rejestrują stan logowania użytkownika jako logged-in
. Gdy stan logowania użytkownika jest ustawiony na logged-in
, FedCM wywołująca RP wysyła żądania do punktu końcowego konta dostawcy tożsamości i wyświetla użytkownikowi dostępne konta w oknie FedCM.
Aby zasygnalizować, że użytkownik jest wylogowany ze wszystkich kont, wyślij nagłówek HTTP Set-Login:
logged-out
w panelu nawigacyjnym najwyższego poziomu lub żądanie zasobu podrzędnego tej samej witryny w źródle dostawcy tożsamości:
Set-Login: logged-out
Możesz też wywołać JavaScript API navigator.login.setStatus("logged-out")
ze źródła dostawcy tożsamości w nawigacji najwyższego poziomu:
navigator.login.setStatus("logged-out")
Te połączenia rejestrują stan logowania użytkownika jako logged-out
. Jeśli stan logowania użytkownika to logged-out
, wywołanie usługi FedCM nie powiedzie się bez wysyłania żądania do punktu końcowego konta dostawcy tożsamości.
Stan unknown
jest ustawiany, zanim dostawca tożsamości wyśle sygnał za pomocą interfejsu Login Status API. Wprowadziliśmy Unknown
w celu ułatwienia migracji, ponieważ użytkownik mógł już zalogować się u dostawcy tożsamości, gdy ten interfejs API został wysłany. Dostawca tożsamości może nie mieć możliwości zasygnalizowania tego do przeglądarki przed pierwszym wywołaniem FedCM. W takim przypadku Chrome wysyła żądanie do punktu końcowego konta dostawcy tożsamości i aktualizuje stan na podstawie odpowiedzi z punktu końcowego kont:
- Jeśli punkt końcowy zwraca listę aktywnych kont, zmień stan na
logged-in
i otwórz okno FedCM, aby je wyświetlić. - Jeśli punkt końcowy nie zwraca żadnych kont, zaktualizuj stan na
logged-out
– w przeciwnym razie wywołanie FedCM się nie uda.
Umożliwienie użytkownikowi logowania się w ramach dynamicznego procesu logowania
Mimo że dostawca tożsamości stale informuje przeglądarkę o stanie logowania użytkownika, może ona nie być zsynchronizowana, na przykład o wygaśnięciu sesji. Gdy stan logowania to logged-in
, przeglądarka próbuje wysłać do punktu końcowego konta żądanie danych uwierzytelniających, ale serwer nie zwraca żadnych kont, ponieważ sesja nie jest już dostępna. W takiej sytuacji przeglądarka może dynamicznie zezwolić użytkownikowi na logowanie się w dostawcy tożsamości przez wyskakujące okienko.
Zaloguj się na stronie uzależnionej przy użyciu dostawcy tożsamości
Gdy konfiguracja i punkty końcowe dostawcy tożsamości są dostępne, grupy objęte ograniczeniami mogą wywołać navigator.credentials.get()
, aby poprosić użytkowników o zalogowanie się w tej usłudze z jej dostawcą.
Przed wywołaniem interfejsu API musisz potwierdzić, że usługa [FedCM jest dostępna w przeglądarce użytkownika]. Aby sprawdzić, czy usługa FedCM jest dostępna, otocz implementację FedCM tym kodem:
if ('IdentityCredential' in window) {
// If the feature is available, take action
}
Aby poprosić użytkowników o umożliwienie logowania się do dostawcy tożsamości z grupy objętej ograniczeniami, wykonaj te czynności:
const credential = await navigator.credentials.get({
identity: {
providers: [{
configURL: 'https://accounts.idp.example/config.json',
clientId: '********',
nonce: '******'
}]
}
});
const { token } = credential;
Właściwość providers
pobiera tablicę IdentityProvider
obiektów, które mają te właściwości:
Właściwość | Opis |
---|---|
configURL (wymagane) |
Pełna ścieżka pliku konfiguracyjnego dostawcy tożsamości. |
clientId (wymagane) |
Identyfikator klienta strony objętej ograniczeniami wystawiony przez dostawcę tożsamości. |
nonce (opcjonalnie) |
Losowy ciąg znaków, który gwarantuje, że w przypadku tego konkretnego żądania zostanie wysłana odpowiedź. Zapobiega atakom metodą powtórzenia. |
loginHint (opcjonalnie) |
Gdy określisz jedną z wartości login_hints podanych przez punkty końcowe konta, w oknie FedCM wyświetli się wybrane konto. |
domainHint (opcjonalnie) |
Gdy określisz jedną z wartości domain_hints podanych przez punkty końcowe konta, w oknie FedCM wyświetli się wybrane konto. |
Przeglądarka obsługuje przypadki rejestracji i logowania w różny sposób – w zależności od tego, czy w odpowiedzi z punktu końcowego listy kont występuje element approved_clients
. Jeśli użytkownik zarejestrował się już w grupie objętej ograniczeniami, przeglądarka nie wyświetli komunikatu „Aby kontynuować...”.
Stan rejestracji zależy od tego, czy spełnione są te warunki:
- Jeśli
approved_clients
obejmuje grupę objętą ograniczeniami:clientId
. - jeśli przeglądarka pamięta, że użytkownik zarejestrował się już w grupie objętej ograniczeniami.
Gdy grupa z ograniczonym dostępem wywołuje navigator.credentials.get()
, wykonywane są te działania:
- Przeglądarka wysyła żądania i pobiera kilka dokumentów:
- Dobrze znany plik i plik konfiguracyjny dostawcy tożsamości, które deklarują punkty końcowe.
- Lista kont.
- Opcjonalnie: adresy URL polityki prywatności i warunków korzystania z usługi objętej ograniczeniami zostały pobrane z punktu końcowego metadanych klienta.
- Przeglądarka wyświetli listę kont, na których użytkownik może się zalogować, a także warunki korzystania z usługi i politykę prywatności (jeśli są dostępne).
- Gdy użytkownik wybierze konto, za pomocą którego ma się zalogować, do dostawcy tożsamości zostanie wysłane żądanie do punktu końcowego potwierdzenia identyfikatora w celu pobrania tokena.
- RP może zweryfikować token, by uwierzytelnić użytkownika.
RP powinny obsługiwać przeglądarki, które nie obsługują FedCM. Dlatego użytkownicy powinni mieć możliwość korzystania z dotychczasowego procesu logowania się z innego systemu niż FedCM. Dopóki pliki cookie innych firm nie zostaną całkowicie wycofane, nie powinno to stanowić problemu.
Gdy token zostanie zweryfikowany przez serwer RP, grupa z ograniczonym dostępem może zarejestrować użytkownika lub zezwolić mu na zalogowanie się i rozpoczęcie nowej sesji.
Interfejs API podpowiedzi logowania
Czasami po zalogowaniu się strona uzależniona (RP) prosi użytkownika o ponowne uwierzytelnienie. Użytkownik może jednak nie być pewny, z którego konta korzystał. Jeśli w grupie objętej ograniczeniami można określić konto, za pomocą którego ma się zalogować, użytkownik będzie łatwiej wybrać konto.
Grupy objęte ograniczeniami mogą wyświetlać określone konto, wywołując navigator.credentials.get()
z właściwością loginHint
z jedną z wartości login_hints
pobranych z punktu końcowego listy kont, jak w tym przykładowym kodzie:
return await navigator.credentials.get({
identity: {
providers: [{
configURL: "https://idp.example/manifest.json",
clientId: "123",
nonce: nonce,
loginHint : "demo1@example.com"
}]
}
});
Gdy żadne konto nie pasuje do loginHint
, w oknie FedCM wyświetla się prośba o zalogowanie. Użytkownik może zalogować się na konto dostawcy tożsamości odpowiadające wskazówce wymaganej przez grupę objętą ograniczeniami. Gdy użytkownik kliknie tę prośbę, otworzy się wyskakujące okienko z adresem URL logowania określonym w pliku konfiguracyjnym. Do linku jest następnie dołączana wskazówka dotycząca logowania i parametry zapytania takie jak domena.
Interfejs API Site Hint
W niektórych przypadkach przedstawiciel RP wie, że w witrynie mogą się logować tylko konta powiązane z konkretną domeną. Jest to szczególnie częste w scenariuszach biznesowych, gdy dostęp do witryny jest ograniczony do domeny firmowej. Aby zwiększyć wygodę użytkowników, interfejs API FedCM pozwala na wyświetlanie tylko tych kont, za pomocą których można się do niej zalogować. Zapobiega to sytuacji, w której użytkownik próbuje zalogować się w grupie objętej ograniczeniami, używając konta spoza domeny firmowej. Komunikat o błędzie pojawia się później (lub gdy logowanie nie zadziałało), bo nie używa się odpowiedniego typu konta.
Grupy objęte ograniczeniami mogą wyświetlać tylko pasujące konta, wywołując navigator.credentials.get()
z właściwością domainHint
z jedną z wartości domain_hints
pobranych z punktu końcowego listy kont, jak w tym przykładowym kodzie:
return await navigator.credentials.get({
identity: {
providers: [{
configURL: "https://idp.example/manifest.json",
clientId: "abc",
nonce: nonce,
domainHint : "corp.example"
}]
}
});
Gdy żadne konto nie pasuje do domainHint
, w oknie FedCM wyświetla się prośba o zalogowanie. Użytkownik może zalogować się na konto dostawcy tożsamości odpowiadające wskazówce wymaganej przez grupę objętą ograniczeniami. Gdy użytkownik kliknie tę prośbę, otworzy się wyskakujące okienko z adresem URL logowania określonym w pliku konfiguracyjnym. Do linku jest następnie dołączana wskazówka dotycząca logowania i parametry zapytania takie jak domena.
Pokaż komunikat o błędzie
Czasami dostawca tożsamości może nie być w stanie wystawić tokena z uzasadnionych powodów, na przykład gdy klient jest autoryzowany, serwer jest tymczasowo niedostępny. Jeśli dostawca tożsamości zwróci odpowiedź „error” (błąd), witryna z ograniczonym dostępem może ją przechwycić, a Chrome powiadomi użytkownika o tym, wyświetlając interfejs przeglądarki z informacjami o błędach podanymi przez dostawcę tożsamości.
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 pierwszym uwierzytelnieniu
Automatyczne ponowne uwierzytelnianie w FedCM (w skrócie „automatyczne ponowne uwierzytelnianie”) umożliwia użytkownikom automatyczne ponowne uwierzytelnianie, gdy wracają po pierwszym uwierzytelnieniu za pomocą FedCM. „Wstępne uwierzytelnienie” oznacza, że użytkownik tworzy konto lub loguje się na stronie RP, klikając przycisk „Kontynuuj jako...” w oknie logowania FedCM w tej samej instancji przeglądarki.
Wrażenia użytkownika powinny mieć sens jeszcze przed utworzeniem sfederowanego konta i uniemożliwiać śledzenie (co jest jednym z głównych celów FedCM). Jednak gdy użytkownik już raz je przeczyta, takie działania są niepotrzebnie niewygodne: gdy użytkownik udzieli zgody na komunikację między grupą objętą usługą a dostawcą tożsamości, nie spowoduje to żadnych korzyści w zakresie prywatności ani bezpieczeństwa wymuszonego już wcześniej innego użytkownika, który potwierdził już wcześniej coś, co zostało wcześniej potwierdzone.
Gdy włączone jest automatyczne ponowne uwierzytelnianie, przeglądarka zmienia swoje działanie w zależności od opcji określonej dla mediation
podczas wywoływania funkcji navigator.credentials.get()
.
const cred = await navigator.credentials.get({
identity: {
providers: [{
configURL: "https://idp.example/fedcm.json",
clientId: "1234",
}],
},
mediation: 'optional', // this is the default
});
// `isAutoSelected` is `true` if auto-reauthn was performed.
const isAutoSelected = cred.isAutoSelected;
Element mediation
jest właściwością interfejsu Credential Management API. Działa w taki sam sposób jak w przypadku elementów PasswordCredential i FederatedCredential oraz jest częściowo obsługiwana przez funkcję PublicKeyCredential. Właściwość może przyjmować te 4 wartości:
'optional'
(ustawienie domyślne): jeśli to możliwe, automatyczne ponowne uwierzytelnianie. Jeśli nie jest, wymagane jest zapośredniczenie. Zalecamy wybranie tej opcji na stronie logowania.'required'
: kontynuowanie zawsze wymaga zapośredniczenia, np. przez kliknięcie przycisku „Dalej” w interfejsie. Wybierz tę opcję, jeśli użytkownicy mają przyznawać uprawnienia bezpośrednio za każdym razem, gdy muszą zostać uwierzytelnieni.'silent'
: w miarę możliwości automatyczne ponowne uwierzytelnianie. Jeśli nie jest wymagane zapośredniczenie, kończy się to niepowodzeniem. Zalecamy wybranie tej opcji na innych stronach niż strona logowania, ale na których chcesz nie wylogowywać użytkowników. Może to być na przykład strona produktu w witrynie wysyłkowej lub strona z artykułem w witrynie z wiadomościami.'conditional'
: używana na potrzeby WebAuthn, a w tej chwili niedostępna w FedCM.
W przypadku tego wywołania automatyczne ponowne uwierzytelnianie odbywa się w tych warunkach:
- Usługa FedCM jest dostępna. Na przykład użytkownik nie wyłączył FedCM zarówno globalnie, ani dla RP w ustawieniach.
- Użytkownik użył tylko jednego konta z interfejsem FedCM API, aby zalogować się na stronie w tej przeglądarce.
- Użytkownik jest zalogowany u dostawcy tożsamości przy użyciu tego konta.
- Automatyczne ponowne uwierzytelnianie nie miało miejsca w ciągu ostatnich 10 minut.
- Grupa z ograniczonym dostępem nie wywołała jeszcze
navigator.credentials.preventSilentAccess()
po poprzednim zalogowaniu.
Gdy te warunki są spełnione, próba automatycznego ponownego uwierzytelnienia użytkownika rozpoczyna się zaraz po wywołaniu funkcji navigator.credentials.get()
w FedCM.
Jeśli ustawiona jest wartość mediation: optional
, automatyczne ponowne uwierzytelnianie może być niedostępne z powodów, o których wie tylko przeglądarka. RPA może sprawdzić, czy automatyczne ponowne uwierzytelnianie jest wykonywane, sprawdzając właściwość isAutoSelected
.
Pozwala to ocenić wydajność interfejsu API i odpowiednio poprawić wygodę użytkowników.
Poza tym gdy ta wartość jest niedostępna, użytkownik może zobaczyć prośbę o zalogowanie się w ramach zapośredniczenia użytkownika, które jest realizowane w ramach mediation: required
.
Egzekwuj zapośredniczenie na koncie preventSilentAccess()
Automatyczne ponowne uwierzytelnianie użytkowników natychmiast po tym, jak się wylogują, nie zapewniłoby im wygodnej obsługi. Dlatego po automatycznym uwierzytelnieniu usługa FedCM stosuje 10-minutowy okres bez powiadomień, aby temu zapobiec. Oznacza to, że automatyczne ponowne uwierzytelnianie odbywa się co najwyżej raz na 10 minut, chyba że użytkownik zaloguje się ponownie w ciągu 10 minut. Grupa z ograniczonym dostępem powinna wywołać navigator.credentials.preventSilentAccess()
, by wprost zażądać od przeglądarki wyłączenia automatycznego ponownego uwierzytelniania, gdy użytkownik wyraźnie wyloguje się z grupy objętej ograniczeniami, na przykład przez kliknięcie przycisku wylogowania.
function signout() {
navigator.credentials.preventSilentAccess();
location.href = '/signout';
}
Użytkownicy mogą zrezygnować z automatycznego ponownego uwierzytelniania w ustawieniach
Użytkownicy mogą zrezygnować z automatycznego ponownego uwierzytelniania w menu ustawień:
- W przeglądarce Chrome na komputerze kliknij
chrome://password-manager/settings
> Loguj automatycznie. - W Chrome na Androidzie otwórz Ustawienia > Menedżer haseł > kliknij ikonę koła zębatego w prawym górnym rogu > Automatyczne logowanie.
Gdy wyłączysz przełącznik, użytkownik będzie mógł zrezygnować z automatycznego ponownego uwierzytelniania. To ustawienie jest przechowywane i synchronizowane między urządzeniami, jeśli użytkownik jest zalogowany na konto Google w instancji Chrome i ma włączoną synchronizację.
Odłącz dostawcę tożsamości od RP
Jeśli użytkownik wcześniej zalogował się w grupie objętej ograniczeniami przy użyciu dostawcy tożsamości w FedCM, przeglądarka zapisze relację z nią lokalnie na liście połączonych kont. Grupa z ograniczonym dostępem może zainicjować rozłączenie przez wywołanie funkcji IdentityCredential.disconnect()
. Tę funkcję można wywołać z klatki RP najwyższego poziomu. Aby dostawca tożsamości został odłączony, strona z grupą obwodową musi zweryfikować configURL
, clientId
używany u dostawcy tożsamości oraz accountHint
. Wskazówka dotycząca konta może być dowolnym ciągiem znaków, o ile punkt końcowy odłączania może zidentyfikować konto. Może to być na przykład adres e-mail lub identyfikator użytkownika, który niekoniecznie musi odpowiadać identyfikatorowi konta dostarczonemu przez punkt końcowy listy kont:
// Disconnect an IdP account "account456" from the RP "https://idp.com/". This is invoked on the RP domain.
IdentityCredential.disconnect({
configURL: "https://idp.com/config.json",
clientId: "rp123",
accountHint: "account456"
});
IdentityCredential.disconnect()
zwraca wartość Promise
. Ta obietnica może stanowić wyjątek z tych powodów:
- Użytkownik nie zalogował się w grupie objętej ograniczeniami przy użyciu dostawcy tożsamości w FedCM.
- Interfejs API jest wywoływany z elementu iframe bez zasady uprawnień FedCM.
- Element configURL jest nieprawidłowy lub nie ma punktu końcowego odłączenia.
- Test Content Security Policy (CSP) kończy się niepowodzeniem.
- Masz oczekujące żądanie rozłączenia.
- Użytkownik wyłączył FedCM w ustawieniach przeglądarki.
Gdy punkt końcowy odłączenia dostawcy tożsamości zwraca odpowiedź, RP i dostawca tożsamości w przeglądarce rozłączą się, a obietnica zostanie zrealizowana. Identyfikatory odłączonych kont są określone w odpowiedzi z punktu końcowego rozłączenia.
Wywoływanie FedCM z międzyźródłowego elementu iframe
Funkcja FedCM może zostać wywołana z elementu iframe z innych domen za pomocą zasady uprawnień identity-credentials-get
, jeśli pozwala na to ramka nadrzędna. Aby to zrobić, dołącz do tagu iframe atrybut allow="identity-credentials-get"
w ten sposób:
<iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>
Przykład możesz zobaczyć w przykładzie.
Opcjonalnie, jeśli ramka nadrzędna chce ograniczyć źródła do wywoływania FedCM, możesz wysłać nagłówek Permissions-Policy
z listą dozwolonych źródeł.
Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")
Więcej informacji o działaniu zasady uprawnień znajdziesz w artykule Kontrolowanie funkcji przeglądarki za pomocą zasady uprawnień.