Wdrożenie rozwiązania do obsługi tożsamości z użyciem FedCM po stronie podmiotu korzystającego

Podmioty polegające muszą wykonać te czynności, aby włączyć FedCM w swojej witrynie:

• Sprawdź, czy punkty końcowe FedCM są dozwolone w witrynie RP.
• Aby rozpocząć uwierzytelnianie użytkownika, użyj interfejsu FedCM JavaScript API.
• Przekazywanie metadanych (np. adresów URL polityki prywatności i warunków korzystania z usługi) do dostawcy tożsamości (lub wielu dostawców tożsamości w Chrome 136).
• [Opcjonalnie] Dostosuj środowisko użytkownika, wybierając tryb UX, podając wskazówki dotyczące logowania lub domeny, przekazując parametry niestandardowe, prosząc o konkretne informacje o użytkowniku, podając niestandardowy komunikat o błędzie lub wybierając sposób ponownego uwierzytelniania użytkowników.

Wywoływanie interfejsu FedCM API w usłudze Relying Party

Gdy konfiguracja dostawcy tożsamości i punkty końcowe będą dostępne, strony RP mogą wywoływać navigator.credentials.get(), aby poprosić o zezwolenie użytkownikowi na zalogowanie się na stronie RP za pomocą dostawcy tożsamości.

Zanim wywołasz interfejs API, musisz potwierdzić, że FedCM jest dostępny w przeglądarce użytkownika. Aby sprawdzić, czy FedCM jest dostępny, umieść ten kod wokół 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żytkownikowi zalogowanie się u dostawcy tożsamości na stronie zależnej za pomocą FedCM, strona zależna może wywołać navigator.credentials.get(). Od Chrome w wersji 136 RP może obsługiwać wielu dostawców tożsamości, określając tablicę wielu dostawców tożsamości w jednym wywołaniu navigator.credentials.get(), np.:

  const credential = await navigator.credentials.get({
      identity: {
        // Specify the IdP (or multiple IdPs, supported from Chrome 136) this Relying Party supports
        providers: [
        {
              configURL: 'https://accounts.idp-1.example/config.json',
              clientId: '********'
        },
        {
          configURL: 'https://accounts.idp-2.example/config.json',
          clientId: '********'
        }]
      }
    },
  );
  const { token } = credential;
  
  // Get the current IdP's configURL to identify which provider the user is signed in with
  const currentIdpConfigUrl = credential.configURL;
  if (currentIdpConfigUrl === 'https://idp1.example/foo.json') {
    // handle the case where the user signed in with idp1
  } else if (currentIdpConfigUrl === 'https://idp2.example/bar.json') {
    // handle the case where the user signed in with idp2
    }

Wypróbuj funkcję wielu dostawców tożsamości, logując się za pomocą IdP1 i IdP2.

Właściwość kontekstu

Za pomocą opcjonalnej właściwości context dostawca tożsamości może modyfikować ciąg znaków w interfejsie okna FedCM (np. „Zaloguj się w rp.example…” lub „Użyj idp.example…”), aby dostosować go do wstępnie zdefiniowanych kontekstów uwierzytelniania. Właściwość context może mieć te wartości:

• signin (domyślnie)
• signup
• use

Jeśli na przykład ustawisz wartość context na use, pojawi się ten komunikat:

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 approved_clients. Jeśli użytkownik zarejestrował się już w usłudze 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ść dostawców

Właściwość providers przyjmuje tablicę IdentityProvider obiektów, które mają te właściwości:

Tryb aktywny

FedCM obsługuje różne konfiguracje trybu UX. Tryb pasywny jest trybem domyślnym i deweloperzy nie muszą go konfigurować.

Aby używać FedCM w trybie aktywnym:

1. Sprawdź dostępność funkcji w przeglądarce użytkownika.
2. Wywołaj interfejs API za pomocą przejściowego gestu użytkownika, np. kliknięcia przycisku.
3. Przekaż parametr mode do 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'
      }
    });
  }

Wypróbuj tryb aktywny w tej prezentacji.

Ikona niestandardowa w trybie aktywnym

Tryb aktywny umożliwia dostawcom tożsamości umieszczanie oficjalnego logo dostawcy usług bezpośrednio w odpowiedzi punktu końcowego metadanych klienta. Wydawca musi z wyprzedzeniem podać dane dotyczące marki.

Wywoływanie FedCM z poziomu elementu iframe z innej domeny

FedCM można wywołać z poziomu ramki iframe z innej domeny za pomocą identity-credentials-getzasad uprawnień, jeśli ramka nadrzędna na to zezwala. W tym celu 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 ramka nadrzędna chce ograniczyć źródła, które mogą wywoływać FedCM, wyślij nagłówek Permissions-Policy z listą dozwolonych źródeł.

  Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")

Więcej informacji o tym, jak działają zasady dotyczące uprawnień, znajdziesz w artykule Kontrolowanie funkcji przeglądarki za pomocą zasad dotyczących uprawnień.

Login Hint API

Korzystając z podpowiedzi logowania, dostawca tożsamości może zalecić użytkownikowi, na które konto powinien się zalogować. Może to być przydatne w przypadku ponownego uwierzytelniania użytkowników, którzy nie pamiętają, jakiego konta używali wcześniej.

Platformy wydawców mogą selektywnie wyświetlać konkretne konto, wywołując funkcję navigator.credentials.get() z właściwością loginHint o jednej 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 żadne konto nie pasuje do loginHint, w oknie FedCM wyświetli się prośba o zalogowanie, która umożliwi użytkownikowi zalogowanie się na konto dostawcy tożsamości pasujące do wskazówki żądanej przez RP. Gdy użytkownik kliknie prompt, otworzy się wyskakujące okienko z adresem URL logowania określonym w pliku konfiguracyjnym. Do linku zostaną następnie dodane parametry zapytania dotyczące wskazówki logowania i wskazówki domeny.

Domain Hint API

Dostawcy tożsamości mogą selektywnie wyświetlać tylko konta powiązane z określoną domeną. Może to być przydatne w przypadku dostawców tożsamości, którzy są ograniczeni do domeny firmowej.

Aby wyświetlać tylko konta w określonej domenie, dostawca tożsamości powinien wywołać funkcję navigator.credentials.get() z właściwością domainHint i 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 żadne konto nie pasuje do domainHint, w oknie FedCM wyświetli się prośba o zalogowanie, która umożliwi użytkownikowi zalogowanie się na konto dostawcy tożsamości pasujące do wskazówki żądanej przez RP. Gdy użytkownik kliknie prompt, otworzy się wyskakujące okienko z adresem URL logowania określonym w pliku konfiguracyjnym. Do linku zostaną następnie dodane parametry zapytania dotyczące wskazówki logowania i wskazówki domeny.

Więcej informacji znajdziesz w wersji demonstracyjnej.

Parametry niestandardowe

Funkcja parametrów niestandardowych umożliwia dostawcy tożsamości przekazywanie dodatkowych parametrów klucz-wartość do punktu końcowego potwierdzenia tożsamości. Za pomocą interfejsu Parameters API dostawcy usług mogą przekazywać dodatkowe parametry do dostawcy tożsamości, aby prosić o uprawnienia do zasobów wykraczające poza podstawowe logowanie. Przekazywanie dodatkowych parametrów może być przydatne w tych sytuacjach:

• Usługa RP musi dynamicznie prosić o dodatkowe uprawnienia, które ma dostawca tożsamości, np. adres rozliczeniowy lub dostęp do kalendarza. Użytkownik może autoryzować te uprawnienia w ramach procesu UX kontrolowanego przez dostawcę tożsamości, który jest uruchamiany za pomocą funkcji Kontynuuj. Dostawca tożsamości udostępnia następnie te informacje.

Aby użyć interfejsu API, dostawca tożsamości 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 przetłumaczy to na żądanie POST do dostawcy tożsamości z parametrami w postaci pojedynczego obiektu zakodowanego w formacie adresu URL i zserializowanego w formacie JSON:

  // 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&params=%22%7B%5C%22IDP_SPECIFIC_PARAM%5C%22%3A1%2C%5C%22foo%5C%22%3A%5C%22BAR%5C%22%7D%22.

Jeśli dostawca usług potrzebuje dodatkowych uprawnień, dostawca tożsamości może podać link do 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

Usługa RP może określić informacje o użytkowniku, które dostawca tożsamości ma jej udostępnić. Może to być dowolna kombinacja imienia i nazwiska, adresu e-mail, nazwy użytkownika, numeru telefonu i zdjęcia profilowego. Wymagane informacje zostaną uwzględnione w interfejsie ujawniania informacji w oknie FedCM.

Użytkownicy rejestrujący się w usłudze zobaczą komunikat informujący, że idp.example udostępni rp.example żądane informacje, jeśli użytkownik zdecyduje się zarejestrować. Jeśli odpowiedź z punktu końcowego kont nie zawiera pola, o które prosi RP, tekst ujawnienia nie będzie zawierać tego pola. Dostawca tożsamości pobierze wszystkie wymagane pola z punktu końcowego potwierdzenia tożsamości i zdecyduje, czy powinien poprosić użytkownika o dodatkowe uprawnienia.

Aby korzystać z funkcji Fields, platforma RP powinna dodać tablicę fields w wywołaniu navigator.credentials.get(). Pola mogą zawierać takie właściwości jak name, email, tel, username lub picture. W przyszłości możemy dodać do tej listy więcej wartości. Żądanie z parametrem fields będzie wyglądać tak:

   let { token } = await navigator.credentials.get({
    identity: {
      providers: [{
        // RP requests the IdP to share only username and profile picture
        fields: [ 'username', 'picture'],
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',
      },
    }
  });

Przeglądarka automatycznie przetłumaczy go na żądanie HTTP do punktu końcowego potwierdzenia tożsamości, które zawiera parametr fields określony przez dostawcę tożsamości, oraz pola, które przeglądarka ujawniła użytkownikowi w parametrze disclosure_shown_for. Aby zachować zgodność wsteczną, przeglądarka wyśle też parametr disclosure_text_shown=true, jeśli wyświetlono tekst ujawnienia informacji, a żądane pola obejmują wszystkie 3 pola: 'name', 'email' i 'picture'. Od Chrome 141 wartość disclosure_text_shown nie wskazuje, czy tekst informacji został faktycznie wyświetlony użytkownikowi.

  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 fields jest pustą tablicą, klient użytkownika pominie interfejs użytkownika z informacjami.

Dzieje się tak nawet wtedy, gdy odpowiedź z punktu końcowego kont nie zawiera identyfikatora klienta, który pasuje do RP w approved_clients.

W tym przypadku wartość disclosure_text_shown wysłana do punktu końcowego potwierdzenia tożsamości jest fałszywa w treści żądania HTTP:

  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świetlanie komunikatu o błędzie

Czasami dostawca tożsamości może nie być w stanie wydać tokena z uzasadnionych powodów, np. gdy klient nie jest autoryzowany lub serwer jest tymczasowo niedostępny. Jeśli dostawca tożsamości zwróci odpowiedź „error”, strona RP może ją przechwycić, a Chrome może powiadomić użytkownika, wyświetlając interfejs przeglądarki z informacjami o błędzie 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 początkowym uwierzytelnieniu

Automatyczne ponowne uwierzytelnianie w FedCM (w skrócie „auto-reauthn”) umożliwia użytkownikom automatyczne ponowne uwierzytelnianie. Aby automatycznie ponownie uwierzytelnić użytkownika, muszą być spełnione te warunki:

• Użytkownik przeprowadził już wstępne uwierzytelnianie za pomocą FedCM. „Początkowa autentykacja” oznacza, że użytkownik tworzy konto lub loguje się w witrynie RP, klikając przycisk „Kontynuuj jako…” w oknie logowania FedCM po raz pierwszy w tej samej instancji przeglądarki.
• Użytkownik ma tylko jedno konto powracającego klienta. Jeśli istniejące konta powracających użytkowników są powiązane z kilkoma dostawcami tożsamości, użytkownik nie zostanie automatycznie ponownie uwierzytelniony.

Wyraźne potwierdzenie przez użytkownika ma sens, zanim utworzy on konto federacyjne, aby zapobiec śledzeniu (co jest jednym z głównych celów FedCM). Jednak po utworzeniu konta jest ono niepotrzebnie uciążliwe: gdy użytkownik zezwoli na komunikację między RP a IdP, nie ma żadnych korzyści związanych z prywatnością ani bezpieczeństwem, które uzasadniałyby wymuszanie 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 parametru 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;

mediation to właściwość w interfejsie Credential Management API, która działa tak samo jak w przypadku PasswordCredential i FederatedCredential. Jest też częściowo obsługiwana przez PublicKeyCredential. Właściwość przyjmuje te 4 wartości:

• 'optional'(domyślnie): automatyczne ponowne uwierzytelnianie, jeśli to możliwe. Jeśli nie, wymagane jest zapośredniczenie. Zalecamy wybranie tej opcji na stronie logowania.
• 'required': zawsze wymaga mediacji, np. kliknięcia przycisku „Dalej” w interfejsie. Wybierz tę opcję, jeśli użytkownicy mają wyraźnie przyznawać uprawnienia za każdym razem, gdy muszą się uwierzytelnić.
• 'silent': automatyczne ponowne uwierzytelnianie, jeśli to możliwe, w przeciwnym razie ciche niepowodzenie bez konieczności zapośredniczenia. Zalecamy wybranie tej opcji na stronach innych niż strona logowania, na których chcesz, aby użytkownicy pozostali zalogowani. Może to być np. strona produktu w witrynie przewoźnika lub strona artykułu w witrynie z wiadomościami.
• 'conditional': używane w przypadku WebAuthn, obecnie niedostępne w przypadku FedCM.

W przypadku tego wywołania automatyczne ponowne uwierzytelnianie następuje w tych warunkach:

• FedCM jest dostępny. Na przykład użytkownik nie wyłączył FedCM globalnie ani w ustawieniach dla RP.
• Użytkownik użył tylko jednego konta z interfejsem FedCM API, aby zalogować się w witrynie w tej przeglądarce.
• Użytkownik jest zalogowany w systemie dostawcy tożsamości przy użyciu tego konta.
• Automatyczne ponowne uwierzytelnianie nie nastąpiło w ciągu ostatnich 10 minut.
• RP nie wywołał(a) funkcji navigator.credentials.preventSilentAccess() po poprzednim zalogowaniu.

Gdy te warunki zostaną spełnione, próba automatycznego ponownego uwierzytelnienia użytkownika rozpocznie się natychmiast po wywołaniu interfejsu FedCM navigator.credentials.get().

Gdy mediation: optional, automatyczne ponowne uwierzytelnianie może być niedostępne z przyczyn znanych tylko przeglądarce. Strona RP może sprawdzić, czy automatyczne ponowne uwierzytelnianie zostało przeprowadzone, sprawdzając właściwość isAutoSelected.

Pomaga to ocenić wydajność interfejsu API i odpowiednio poprawić UX. Gdy jest niedostępna, użytkownik może zostać poproszony o zalogowanie się za pomocą wyraźnego pośrednictwa użytkownika, czyli procesu z mediation: required.

Wymuszanie zapośredniczenia za pomocą preventSilentAccess()

Automatyczne ponowne uwierzytelnianie użytkowników natychmiast po wylogowaniu nie zapewni im dobrego komfortu korzystania z usługi. Dlatego po automatycznym ponownym uwierzytelnieniu FedCM ma 10-minutowy okres ciszy, aby zapobiec takiemu zachowaniu. Oznacza to, że automatyczne ponowne uwierzytelnianie następuje co najwyżej raz na 10 minut, chyba że użytkownik ponownie zaloguje się w ciągu 10 minut. RP powinien wywołać navigator.credentials.preventSilentAccess(), aby wyraźnie poprosić przeglądarkę o wyłączenie automatycznego ponownego uwierzytelniania, gdy użytkownik wyraźnie wyloguje się z RP, na przykład klikając przycisk 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 Androidzie otwórz Ustawienia > Menedżer haseł > kliknij ikonę koła zębatego w prawym górnym rogu > Automatyczne logowanie.

Wyłączenie przełącznika spowoduje, że użytkownik zrezygnuje z automatycznego ponownego uwierzytelniania. To ustawienie jest przechowywane i synchronizowane na różnych urządzeniach, jeśli użytkownik jest zalogowany na konto Google w instancji Chrome i synchronizacja jest włączona.

Odłączanie dostawcy tożsamości od dostawcy usług

Jeśli użytkownik zalogował się wcześniej w RP za pomocą dostawcy tożsamości przez FedCM, przeglądarka zapamiętuje lokalnie tę relację jako listę połączonych kont. Podmiot polegający może zainicjować rozłączenie, wywołując funkcję IdentityCredential.disconnect(). Tę funkcję można wywołać z ramki RP najwyższego poziomu. Aby odłączyć dostawcę tożsamości, dostawca usług musi przekazać configURL, clientId używany przez dostawcę tożsamości i 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, np. adres e-mail lub identyfikator użytkownika, który nie musi być zgodny 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. Obietnica może zgłosić wyjątek z tych powodów:

• Użytkownik nie zalogował się w stronie zależnej za pomocą dostawcy tożsamości w ramach FedCM.
• Interfejs API jest wywoływany z elementu iframe bez zasad uprawnień FedCM.
• Adres configURL jest nieprawidłowy lub brakuje w nim punktu końcowego odłączania.
• Sprawdzanie standardu Content Security Policy (CSP) nie powiodło się.
• Oczekuje prośba o odłączenie.
• Użytkownik wyłączył FedCM w ustawieniach przeglądarki.

Gdy punkt końcowy rozłączania dostawcy tożsamości zwróci odpowiedź, dostawca tożsamości i RP zostaną rozłączone w przeglądarce, a obietnica zostanie spełniona. Identyfikatory odłączonych kont są podane w odpowiedzi z punktu końcowego odłączania.

Dalsze kroki

Wdrożenie FedCM po stronie dostawcy tożsamości

Dowiedz się, jak wdrożyć rozwiązanie dotyczące tożsamości z FedCM po stronie dostawcy tożsamości.

Personalizacja i rezygnacja

Dowiedz się, jak użytkownicy i deweloperzy mogą zarządzać udziałem w FedCM, w tym wyrażać zgodę lub wycofywać ją na różnych platformach i w różnych witrynach.