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 usługa, która pozwala chronić prywatność jak w przypadku usług tożsamości sfederowanej (takich jak „Zaloguj się przez...”), gdzie użytkownicy mogą logować się do witryn bez udostępniania swoich danych osobowych usłudze tożsamości lub witrynie.

Aby dowiedzieć się więcej o przypadkach użycia FedCM, przepływach użytkowników i harmonogramie rozwoju interfejsów API, zapoznaj się z FedCM API.

Środowisko programistyczne FedCM

Potrzebujesz bezpiecznego kontekstu (HTTPS lub lokalnego hosta) u dostawcy tożsamości i RP w Chrome do korzystania z FedCM.

Kod debugowania w Chrome na Androida

Skonfiguruj i uruchom serwer lokalnie, aby debugować kod FedCM. Dostępne opcje dostęp do tego serwera w Chrome na urządzeniu z Androidem połączonym kablem USB z portem i przekierowaniach.

Za pomocą Narzędzi deweloperskich na komputerze możesz debugować Chrome na urządzeniu z Androidem. W tym celu wykonaj instrukcje w artykule Zdalne debugowanie Androida urządzenia.

Blokuj pliki cookie innych firm w Chrome

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

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

Aby zablokować pliki cookie innych firm, użyj opcji Incognito lub wybierz „Blokuj” pliki cookie innych firm” w ustawieniach pulpitu na chrome://settings/cookies lub wł. na urządzeniu mobilnym, otwierając Ustawienia > Ustawienia witryny > Pliki cookie.

Korzystanie z interfejsu FedCM API

Aby przeprowadzić integrację z FedCM, utwórz dobrze znany plik, plik konfiguracji i punkty końcowe dla kont listy, wystawianie ocen oraz opcjonalnie metadane klienta.

Później FedCM ujawnia interfejsy API JavaScript, których sprzedawcy mogą użyć do podpisywania kont. u u dostawcy tożsamości.

Utwórz dobrze znany plik

Aby zapobiec nadużywaniu tagów śledzenia przez lokalizatory API, znany plik musi być obsługuje: /.well-known/web-identity z eTLD+1 dostawcy tożsamości.

Jeśli na przykład punkty końcowe dostawcy tożsamości są obsługiwane w https://accounts.idp.example/, muszą udostępniać dobrze znany plik pod adresem https://idp.example/.well-known/web-identity oraz konfigurację 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ą dostawcy tożsamości pliku konfiguracji – adresy URL, które można określić jako część ścieżki configURL w navigator.credentials.get według RP. Liczba Ciąg adresów URL w tablicy jest ograniczony do jednego, ale może się to zmieniać po aby podzielić się z nami swoją opinią w przyszłości.

Utwórz plik konfiguracji dostawcy tożsamości i punkty końcowe

Plik konfiguracji dostawcy tożsamości zawiera listę punktów końcowych wymaganych przez przeglądarkę. IdPs będzie hostować ten plik konfiguracyjny oraz wymagane punkty końcowe i adresy URL. Cały plik JSON odpowiedzi muszą być udostępniane z parametrem content-type application/json.

Adres URL pliku konfiguracyjnego jest określany przez wartości podane w metodzie Wykonano wywołanie navigator.credentials.get 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 jako configURL. Kiedy Nazwa navigator.credentials.get() jest wywoływana w grupie RP, czyli przeglądarce. pobiera plik konfiguracyjny z żądaniem GET bez nagłówka Origin lub Nagłówek Referer. Żądanie nie zawiera plików cookie ani nie śledzi przekierowań. W efekcie dostawca tożsamości nie wie, kto wysłał żądanie i które z nich RP próbuje nawiązać połączenie. 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: właściwości:

Właściwość Opis
accounts_endpoint (wymagane) Adres URL punktu końcowego kont.
client_metadata_endpoint (opcjonalnie) Adres URL punktu końcowego metadanych klienta.
id_assertion_endpoint (wymagane) Adres URL punktu końcowego potwierdzenia identyfikatora.
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 marki.
branding.background_color (opcjonalnie) Opcja marki, która ustawia kolor tła opcji „Kontynuuj jako...” Przycisk Użyj odpowiedniej składni CSS, tj. hex-color hsl(), rgb() lub named-color.
branding.color (opcjonalnie) Opcja marki, która ustawia kolor tekstu „Kontynuuj jako...” Przycisk Użyj odpowiedniej składni CSS, tj. hex-color hsl(), rgb() lub named-color.
branding.icons (opcjonalnie) Opcja marki, która ustawia obiekt ikony, wyświetlaną w oknie logowania. Obiekt icon to tablica z 2 parametrami:
  • url (wymagany): adres URL obrazu ikony. Obrazy SVG nie są obsługiwane.
  • size (opcjonalnie): wymiary ikony zakładane przez aplikację jako kwadratowe i o jednej rozdzielczości. Ta liczba nie może być mniejsza niż 25.

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

Stosowanie marki w oknie FedCM
Stosowanie marki w oknie 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
    }]
  }
}

Po pobraniu pliku konfiguracyjnego przeglądarka wysyła kolejne żądania do Punkty końcowe 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, które utworzył użytkownik Użytkownik jest obecnie zalogowany u dostawcy tożsamości. Jeśli dostawca tożsamości obsługuje wiele kont, Punkt końcowy zwróci wszystkie zalogowane konta.

Przeglądarka wysyła żądanie GET z plikami cookie z atrybutem SameSite=None, ale bez parametr client_id, nagłówek Origin lub nagłówek Referer. Ten skutecznie uniemożliwia dostawcy tożsamości poznanie, którą grupę objętą ograniczeniami próbuje podpisać 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. Wyślij odpowiedź, podając listę kont.

Przeglądarka oczekuje odpowiedzi JSON zawierającej właściwość accounts z tablicą informacji o koncie z następującymi 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 ze wszystkimi możliwymi typami filtrów, które dostawca tożsamości obsługuje konto. Grupa z ograniczonym dostępem może wywołać funkcję navigator.credentials.get() za pomocą właściwości loginHint do wybrane konto.
domain_hints (opcjonalnie) Tablica ze wszystkimi domenami, z którymi jest powiązane konto. RP może zadzwoń do: navigator.credentials.get(), domainHint, aby filtrować kont.

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 będzie dostępna dla: RP.

Punkt końcowy metadanych klienta

Punkt końcowy metadanych klienta dostawcy tożsamości zwraca metadane jednostki uzależnionej, takie jak polityce prywatności i warunkach korzystania z usługi RP. RP powinny zawierać linki do swoich politykę prywatności i warunki korzystania z usługi dostawcy tożsamości z wyprzedzeniem. Te linki są wyświetlane w oknie logowania, gdy użytkownik nie zarejestrował się w grupie objętej ograniczeniami z dostawcą tożsamości.

Przeglądarka wysyła żądanie GET za pomocą interfejsu client_id navigator.credentials.get bez plików cookie. Na przykład:

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

Po otrzymaniu żądania serwer powinien:

  1. Określ RP dla: client_id.
  2. W odpowiedzi podaj metadane 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) Adres URL warunków korzystania z usługi objętej ograniczeniami.

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

{
  "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 są dostępnych dla grupy objętej ograniczeniami.

Punkt końcowy asercji identyfikatora

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

Właściwość Opis
client_id (wymagane) Identyfikator klienta grupy objętej ograniczeniami.
account_id (wymagane) Unikalny identyfikator zalogowanego użytkownika.
nonce (opcjonalnie) Liczba jednorazowa żądania podana przez grupę objętą ograniczeniami.
disclosure_text_shown daje wynik jako ciąg "true" lub "false" (a nie wartość logiczna). Jeśli tekst komunikatu wyświetlanego w reklamie nie został wyświetlony, wynik to "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 kont lub gdy przeglądarka zaobserwowała moment rejestracji w przeszłości, jeśli nie było 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. Na przykład niektórzy użytkownicy mogą preferować wyższy poziom zabezpieczeń, który wymaga wyraźnego zapośredniczenia użytkownika podczas uwierzytelniania. Jeśli dostawca tożsamości otrzyma żądanie tokena bez zapośredniczenia, może obsłużyć żądanie w inny sposób. 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ą CORS (zasobu Cross-Origin) Udostępnianie).
  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 są zgodne.
  4. Dopasuj account_id do identyfikatora konta, na które się logujesz. Odrzuć, jeśli które nie pasują do siebie.
  5. Odpowiedz tokenem. Jeśli żądanie zostanie odrzucone, prześlij w odpowiedzi komunikat o błędzie .
.

Sposób wystawiania tokena zależy od dostawcy tożsamości, ale zwykle jest on podpisany za pomocą takie jak identyfikator konta, identyfikator klienta, źródło wydawcy, nonce – dzięki temu RP może sprawdzić, czy token jest autentyczny.

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

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

Zwrócony token jest przekazywany do grupy objętej ograniczeniami przez przeglądarkę, dzięki czemu może i sprawdzić uwierzytelnianie.

Zwracanie odpowiedzi o błędzie

id_assertion_endpoint może też zwracać „błąd”. odpowiedź z 2 opcjonalnymi polami:

  • code: dostawca tożsamości może wybrać jeden ze znanych błędów z OAuth 2.0 określony błąd lista (invalid_request, unauthorized_client, access_denied, server_error i temporarily_unavailable) lub możesz użyć dowolnego ciągu. Jeśli to drugie, 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 na temat , aby przekazać użytkownikom dodatkowe informacje o tym błędzie. To pole jest przydatna dla użytkowników, ponieważ przeglądarki nie mogą wyświetlać szczegółowych komunikatów o błędach natywny interfejs użytkownika. Na przykład linki do kolejnych kroków, informacje kontaktowe działu obsługi klienta informacje i tak dalej. Jeśli użytkownik chce dowiedzieć się więcej o szczegółach błędu i jak go rozwiązać, mogą wejść na podaną 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łącz punkt końcowy

Wywołując funkcję IdentityCredential.disconnect(), przeglądarka wysyła zasoby z innych domen Żądanie POST z plikami cookie z atrybutem SameSite=None i typem treści: application/x-www-form-urlencoded do tego rozłączonego punktu końcowego z następujące informacje:

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 (zasobu Cross-Origin) Udostępnianie).
  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 są zgodne.
  4. Dopasuj account_hint do identyfikatorów kont, na których jesteś już zalogowany.
  5. Odłącz konto użytkownika od grupy objętej ograniczeniami.
  6. W odpowiedzi prześlij przeglądarce informacje o rozpoznanym koncie użytkownika w pliku JSON .
.

Przykładowa odpowiedź w postaci ładunku JSON wygląda tak:

{
  "account_id": "account456"
}

Zamiast tego, jeśli dostawca tożsamości chce, aby przeglądarka odłączyła wszystkie konta powiązane z RP, prześlij ciąg znaków, który nie pasuje do żadnego identyfikatora konta, np. "*".

URL logowania

W przypadku interfejsu Login Status API dostawca tożsamości musi informować stan logowania w przeglądarce. Stan może jednak być niezsynchronizowany: gdy sesja wygaśnie. W takim przypadku przeglądarka może dynamicznie zezwalać użytkownikowi na logowanie się u dostawcy tożsamości przez stronę logowania Adres URL określony za pomocą atrybutu login_url pliku konfiguracyjnego dostawcy tożsamości.

W oknie FedCM pojawi się komunikat sugerujący zalogowanie się, taki jak ten obraz.

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

Gdy użytkownik kliknie przycisk Dalej, przeglądarka otworzy wyskakujące okienko dla strony logowania dostawcy tożsamości.

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

Jest to zwykłe okno przeglądarki z własnymi plikami cookie. Cokolwiek odbywa się w oknie dialogowym należy do dostawcy tożsamości i nie są dostępne żadne uchwyty okien. aby wysłać żądanie komunikacji z innej domeny do strony RP. Gdy użytkownik zalogowany użytkownik, dostawca tożsamości powinien:

  • Wyślij nagłówek Set-Login: logged-in lub wywołaj navigator.login.setStatus("logged-in") interfejsu API, aby poinformować przeglądarkę, że Użytkownik został zalogowany.
  • Aby zamknąć okno, zadzwoń pod numer IdentityProvider.close().
.
A
Użytkownik loguje się w RPA po zalogowaniu się u dostawcy tożsamości za pomocą FedCM.

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

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

Dostawcy tożsamości mogą informować przeglądarkę o stanie logowania użytkownika, wysyłając nagłówek HTTP lub przez wywołanie interfejsu JavaScript API, gdy użytkownik jest zalogowany u dostawcy tożsamości. użytkownik został wylogowany ze wszystkich kont dostawcy tożsamości. Dla każdego dostawcy tożsamości (określanego przez config URL), przeglądarka przechowuje zmienną tristate reprezentującą stan logowania. z możliwymi wartościami logged-in, logged-out i unknown. Stan domyślny jest 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 w tej samej witrynie u dostawcy tożsamości pochodzenie:

Set-Login: logged-in

Możesz też wywołać interfejs 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")

W tych wywołaniach stan logowania użytkownika jest rejestrowany jako logged-in. Gdy użytkownik się loguje stan jest ustawiony na logged-in, program RP wywołujący FedCM wysyła żądania do dostawcy tożsamości punktu końcowego kont i wyświetla dostępne konta użytkownikowi w 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 w zasobie podrzędnym w tej samej witrynie do punktu początkowego 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")

W tych wywołaniach stan logowania użytkownika jest rejestrowany jako logged-out. Gdy użytkownik stan logowania to logged-out, co oznacza, że dyskretne wywołanie FedCM kończy się niepowodzeniem bez tworzenia do punktu końcowego kont dostawcy tożsamości.

Stan unknown jest ustawiany, zanim dostawca tożsamości wyśle sygnał za pomocą stanu logowania. API. Usługa Unknown została wprowadzona w celu ułatwienia przejścia na nową wersję, ponieważ użytkownik mógł użytkownik był już zalogowany u dostawcy tożsamości, gdy ten interfejs API został wysłany. Dostawca tożsamości może nie mieć zasygnalizuje to przeglądarce przed wywołaniem FedCM. W tym Chrome wysyła żądanie do punktu końcowego kont dostawcy tożsamości i aktualizuje stanu na podstawie odpowiedzi z 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 zwraca żadnych kont, zaktualizuj stan na logged-out i nie powiedzie się w FedCM.
.

Zezwalaj użytkownikowi na logowanie się za pomocą dynamicznego procesu logowania

Mimo że dostawca tożsamości informuje przeglądarkę o stanie logowania użytkownika, może nie być zsynchronizowana, np. gdy sesja wygaśnie. Przeglądarka próbuje wyślij żądanie z danymi logowania do punktu końcowego kont, gdy stan logowania to logged-in, ale serwer nie zwraca żadnych kont, ponieważ sesja nie została już zrealizowana i dostępności informacji. W takim przypadku przeglądarka może dynamicznie zezwolić użytkownikowi na zalogowanie się dostawcy tożsamości w wyskakującym okienku.

Zaloguj się do jednostki uzależnionej przy użyciu dostawcy tożsamości

Gdy konfiguracja i punkty końcowe dostawcy tożsamości są dostępne, RP mogą wywoływać metodę navigator.credentials.get(), aby poprosić o zezwolenie użytkownikom na logowanie się w grupie objętej ograniczeniami z dostawcą tożsamości.

Zanim wywołasz ten interfejs API, musisz potwierdzić, że [FedCM jest dostępny na przeglądarki użytkownika]. Aby sprawdzić, czy usługa FedCM jest dostępna, opakuj ten kod Wdrożenie FedCM:

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 te czynności: np.:

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ę typu IdentityProvider , które mają tych właściwości:

Właściwość Opis
configURL (wymagane) Pełna ścieżka pliku konfiguracji dostawcy tożsamości.
clientId (wymagane) Identyfikator klienta RP wystawiany przez dostawcę tożsamości.
nonce (opcjonalnie) Losowy ciąg znaków zapewniający, że odpowiedź na to konkretne żądanie zostanie wysłana. Zapobiega atakom metodą powtórzenia.
loginHint (opcjonalnie) Przez określenie jednej z login_hints wartości podanych przez funkcję punktów końcowych kont, FedCM selektywnie wyświetla określone konto.
domainHint (opcjonalnie) Przez określenie jednej z domain_hints wartości podanych przez funkcję punktów końcowych kont, FedCM wybrane konto.

Przeglądarka różnie obsługuje przypadki użycia związane z rejestracją i logowaniem w zależności od obecność konta approved_clients w odpowiedzi z listy kont punktu końcowego. Przeglądarka nie wyświetli komunikatu tekst „Aby kontynuować z...”, jeśli użytkownik zarejestrował się już w grupie objętej ograniczeniami.

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

  • Jeśli approved_clients zawiera wartość 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 w grupie objętej ograniczeniami nastąpi wywołanie navigator.credentials.get(), następujące działania będą podejmowane miejsce:

  1. Przeglądarka wysyła żądania i pobiera kilka dokumentów:
    1. Dobrze znany plik i konfiguracja dostawcy tożsamości , który deklaruje punkty końcowe.
    2. Listę kont.
    3. Opcjonalnie: adresy URL polityki prywatności i warunków korzystania z grupy objętej ograniczeniami; pobrane z punktu końcowego metadanych klienta.
  2. Przeglądarka wyświetli listę kont, za pomocą których użytkownik może się zalogować. a także warunki korzystania z usługi i politykę prywatności, jeśli są dostępne.
  3. Gdy użytkownik wybierze konto, za pomocą którego będzie się logować, żądanie identyfikatora punkt końcowy asercji jest wysyłany do dostawcy tożsamości w celu pobrania token.
  4. RP może zweryfikować token, aby uwierzytelnić użytkownika.
.
wywołanie interfejsu API logowania
wywołanie interfejsu API logowania
.

Powinny być obsługiwane przeglądarki, które nie obsługują FedCM. użytkownicy powinni mieć możliwość korzystania z istniejącego procesu logowania się poza FedCM. Do pliki cookie innych firm zostały całkowicie wycofane, nie sprawiają problemów.

Po zweryfikowaniu tokena przez serwer RP może on zarejestrować użytkownika lub pozwól mu się zalogować i rozpocząć nową sesję.

Interfejs API podpowiedzi dotyczących logowania

Czasami po zalogowaniu się przez użytkownika strona uzależniona może go poprosić o przeprowadzić ponowne uwierzytelnianie. Użytkownik może jednak nie być pewny, którego konta używa. Jeśli w grupie z ograniczonym dostępem można określić, na które konto się zalogować, będzie łatwiej użytkownik wybierze konto.

Odpowiedzi na żądania objęte ograniczeniami mogą być selektywne, ponieważ wywołują określone konto. navigator.credentials.get() z właściwością loginHint z jedną z wartości Liczba wartości pobranych z listy kont: login_hints punktu końcowego zgodnie z tym przykładowym kodem:

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 spełnia warunków loginHint, w oknie FedCM pojawia się prośba o zalogowanie. która pozwala użytkownikowi zalogować się na konto dostawcy tożsamości zgodne z żądaną wskazówką RP. Gdy użytkownik kliknie prompt, otworzy się wyskakujące okienko z adresu URL logowania określonego w pliku konfiguracyjnym. Link jest wtedy z instrukcją logowania i parametrami zapytania ze wskazówką dotyczącą domeny.

Interfejs API Hint

W niektórych przypadkach grupy objętej ograniczeniami już wiedzą, że tylko konta powiązane z określone domeny mogą logować się w witrynie. Jest to szczególnie typowe dla w sytuacjach, gdy dostęp do witryny jest ograniczony do firmowego w Twojej domenie. Aby zapewnić użytkownikom lepsze wrażenia, interfejs FedCM API zezwala na grupy objęte ograniczeniami zawierają konta, których można użyć do zalogowania się w tej sekcji. Zapobiega to scenariuszom użytkownik próbuje zalogować się w grupie objętej ograniczeniami przy użyciu konta spoza firmy; domeny, tylko później z komunikatem o błędzie (lub wyciszysz, gdy logowanie nie zadziałało), ponieważ nie został użyty odpowiedni typ konta.

Odpowiedzi na żądania objęte ograniczeniami mogą być selektywnie wyświetlane tylko przez pasujące konta za pomocą wywołania navigator.credentials.get() z właściwością domainHint z jedną z wartości Liczba wartości pobranych z listy kont: domain_hints punktu końcowego zgodnie z tym przykładowym kodem:

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

Gdy żadne konto nie spełnia warunków domainHint, w oknie FedCM pojawia się prośba o zalogowanie. która pozwala użytkownikowi zalogować się na konto dostawcy tożsamości zgodne z żądaną wskazówką RP. Gdy użytkownik kliknie prompt, otworzy się wyskakujące okienko z adresu URL logowania określonego w pliku konfiguracyjnym. Link jest wtedy z instrukcją logowania i parametrami zapytania ze wskazówką dotyczącą domeny.

Przykładowy monit logowania się, gdy żadne konto nie jest zgodne z podpowiedzią o domenie.
Przykładowy prośbę o zalogowanie się, gdy żadne konto nie pasuje do konta domainHint.

Pokaż komunikat o błędzie

Czasami dostawca tożsamości może nie być w stanie wygenerować tokena z uzasadnionych powodów, takich jak , tak jak w przypadku nieautoryzowanego klienta, serwer jest tymczasowo niedostępny. Jeśli dostawca tożsamości zwraca błąd odpowiedź na pytanie będzie w stanie wykryć, tak jak Chrome. powiadamia użytkownika, wyświetlając interfejs przeglądarki z informacjami o błędach podanymi przez dostawcy tożsamości.

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

Automatyczne ponowne uwierzytelnianie w FedCM (w skrócie „auto-reauthn”) pozwala użytkownikom automatycznie ponownie uwierzytelniać się, po zakończeniu wstępnego uwierzytelnienia przy użyciu FedCM. „Początkowa wartość uwierzytelnianie”. oznacza, że użytkownik utworzył konto w grupie objętej ograniczeniami lub loguje się kliknij przycisk „Kontynuuj jako...” w oknie logowania w FedCM. pierwszy raz w tej samej przeglądarce.

Chociaż konkretne wrażenia użytkownika mają sens, zanim utworzy on konta sfederowanego w celu zapobiegania śledzeniu (co jest jednym z głównych celów FedCM), jest niepotrzebnie uciążliwe, gdy użytkownik przejrzy ją raz: użytkownik przyznaje uprawnienia do komunikacji między stroną docelową a dostawcą tożsamości, nie niesie ze sobą korzyści związanych z prywatnością ani bezpieczeństwem w celu wymuszania na innym użytkowniku potwierdzenia w przypadku czegoś, co użytkownik już wcześniej uznał.

Po włączeniu automatycznego ponownego uwierzytelniania przeglądarka zmienia swoje działanie w zależności od wybranej opcji określić dla funkcji mediation przy wywoływaniu 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;

mediation to właściwość w Zarządzaniu danymi logowania API działa w taki sam sposób droga tak jak w przypadku PasswordCredential oraz FederatedCredential Jest częściowo obsługiwana przez PublicKeyCredential . Właściwość akceptuje te 4 wartości:

  • 'optional'(domyślnie): w miarę możliwości automatyczne ponowne uwierzytelnianie; w przeciwnym razie wymaga zapośredniczenia. Śr zalecamy wybranie tej opcji na stronie logowania.
  • 'required': aby kontynuować, wymagane jest zapośredniczenie, np. kliknięcie przycisku „Dalej” w interfejsie. Wybierz tę opcję, jeśli użytkownicy powinni jawnie przyznać uprawnienie za każdym razem, gdy konieczne jest uwierzytelnienie.
  • 'silent': automatyczne ponowne uwierzytelnianie, jeśli to możliwe, dyskretne uwierzytelnienie bez konieczności mediacji, jeśli nie. Zalecamy wybranie tej opcji na stronach innych niż dedykowanej strony logowania, ale na której chcesz utrzymać zainteresowanie użytkowników – np. strona produktu w witrynie dostawy lub strona z artykułem witryny.
  • 'conditional': używany w przypadku WebAuthn, ale obecnie nie jest dostępny dla FedCM.

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

  • Usługa FedCM jest dostępna. Na przykład użytkownik nie wyłączył FedCM. globalnie lub dla RP w ustawieniach.
  • Użytkownik zalogował się w witrynie na tym koncie tylko z jednego konta z interfejsem FedCM API przeglądarki.
  • Użytkownik jest zalogowany w dostawcy tożsamości za pomocą tego konta.
  • Automatyczne ponowne uwierzytelnianie nie miało miejsca w ciągu ostatnich 10 minut.
  • RP nie zadzwonił później navigator.credentials.preventSilentAccess() przy użyciu poprzedniego logowania.

W przypadku spełnienia tych warunków próba automatycznego ponownego uwierzytelnienia użytkownik zaczyna od razu po wywołaniu funkcji navigator.credentials.get() w FedCM.

Gdy mediation: optional, automatyczne ponowne uwierzytelnianie może być niedostępny z tych powodów: wie tylko przeglądarka; RP może sprawdzić, czy automatyczne ponowne uwierzytelnianie analizując właściwość isAutoSelected.

Pomoże Ci to ocenić wydajność interfejsu API i odpowiednio poprawić wygodę użytkowników. Oprócz tego, gdy jest ona niedostępna, użytkownik może zostać poproszony o zalogowanie się przy użyciu zapośredniczenie użytkowników, które jest dostępne w ramach mediation: required.

Użytkownik automatycznie ponownie uwierzytelnia się przez FedCM.

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

Automatyczne ponowne uwierzytelnianie użytkowników natychmiast po wylogowaniu nie sprawi, że bardzo dobre wrażenia użytkowników. Dlatego FedCM odczeka 10-minutową przerwę automatycznego ponownego uwierzytelniania, aby zapobiec takim działaniom. Oznacza to, że następuje automatyczne ponowne uwierzytelnianie co najwyżej raz na 10 minut, chyba że użytkownik zaloguje się ponownie 10 minut. RP musi wywołać metodę navigator.credentials.preventSilentAccess() do jawnie zażądaj od przeglądarki wyłączenia automatycznego ponownego uwierzytelniania, gdy użytkownik wyloguje się z jawnie w grupie 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 Chrome na komputerze kliknij chrome://password-manager/settings > Zaloguj się automatycznie.
  • W Chrome na Androida otwórz Ustawienia > Menedżer haseł > Kliknij koło zębate w prawym górnym rogu > Automatyczne logowanie.

Po wyłączeniu tego przełącznika użytkownik może zrezygnować z automatycznego ponownego uwierzytelniania razem. To ustawienie jest przechowywane i synchronizowane między urządzeniami, jeśli użytkownik zalogujesz się na konto Google w wystąpieniu Chrome, a synchronizacja to .

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 w FedCM, jest zapamiętywana przez przeglądarkę lokalnie jako lista połączonych kont. RP może zainicjować rozłączenie przez wywołanie metody IdentityCredential.disconnect(). Tę funkcję można wywołać z ramki RP najwyższego poziomu. RP musi przejść kontrolę: configURL, clientId, którego używa u dostawcy tożsamości i accountHint dla dostawcy, który ma zostać odłączony. Konto podpowiedź może być dowolnym ciągiem znaków, o ile punkt końcowy odłączania może zidentyfikować np. adresu e-mail lub identyfikatora użytkownika, zgodne 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 następujących 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.
  • Test zgodności ze standardem 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łączania dostawcy tożsamości zwraca błąd , punkt dostępu i dostawca tożsamości zostaną odłączone i zostaje rozwiązana. Identyfikatory rozłączonych kont to określone w odpowiedzi na odłączenie .

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

FedCM można wywołać z międzyźródłowego elementu iframe za pomocą tagu Zasada uprawnień identity-credentials-get, jeśli zezwala na to ramka nadrzędna. Do dołącz atrybut allow="identity-credentials-get" do tagu iframe w następujący sposób:

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

Działanie tej funkcji widać na przykładzie.

Opcjonalnie: jeśli ramka nadrzędna chce ograniczyć źródła tak, aby wywoływały 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 na stronie Kontrola funkcje przeglądarki z Uprawnieniami Zasady.