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

Aby włączyć FedCM w swojej witrynie, usługodawcy zewnętrzni (UE) muszą wykonać te czynności:

• Upewnij się, że punkty końcowe FedCM są dozwolone na stronie RP.
• Aby zainicjować uwierzytelnianie użytkownika, użyj interfejsu FedCM JavaScript API.
• Prześlij dostawcy tożsamości metadane (np. adresy URL polityki prywatności i warunków korzystania z usługi).
• [Opcjonalnie] Dostosowywanie interakcji z użytkownikiem przez wybranie trybu UX, podanie loginu lub wskazówek dotyczących domeny, przekazanie parametrów niestandardowych, prośba o określone informacje o użytkowniku, podanie niestandardowego komunikatu o błędzie lub wybranie sposobu ponownego uwierzytelniania użytkowników.

Gdy konfiguracja i punkty końcowe dostawcy tożsamości będą dostępne, dostawcy żądań mogą wywoływać funkcję navigator.credentials.get(), aby umożliwić użytkownikom logowanie się do dostawcy żądań za pomocą dostawcy tożsamości.

Zanim wywołasz interfejs API, musisz sprawdzić, czy FedCM jest dostępny w przeglądarce użytkownika. Aby sprawdzić, czy FedCM jest dostępny, użyj tego kodu w implementacji FedCM:

  if ('IdentityCredential' in window) {
    // If the feature is available, take action
  } else {
    // FedCM is not supported, use a different identity solution
  }

Aby umożliwić użytkownikom logowanie się w systemie dostawcy tożsamości za pomocą interfejsu FedCM, dostawca żądań może wywołać funkcję navigator.credentials.get(), na przykład:

  const credential = await navigator.credentials.get({
    identity: {
      context: 'signin',
      providers: [{
        configURL: 'https://accounts.idp.example/config.json',
        clientId: '********',
        mode: 'active',
        params: {
          nonce: '******'
        }
      }]
    }
  });
  const { token } = credential;

Właściwość context

Opcjonalna właściwość context umożliwia RP modyfikowanie ciągu w interfejsie dialogowym FedCM (np. „Zaloguj się w rp.example…”, „Użyj idp.example…”) w celu uwzględnienia wstępnie zdefiniowanych kontekstów uwierzytelniania. Właściwość context może mieć te wartości:

• signin (domyślnie)
• signup
• use

Na przykład ustawienie wartości context na use spowoduje wyświetlenie tego komunikatu:

Przeglądarka obsługuje przypadki użycia rejestracji i logowania w różny sposób w zależności od tego, czy w odpowiedzi z punktu końcowego listy kont występuje wartość approved_clients. Jeśli użytkownik jest już zarejestrowany w programie RP, przeglądarka nie wyświetli tekstu „Aby kontynuować…”.
Właściwość providers przyjmuje tablicę obiektów IdentityProvider, które mają te właściwości:

Właściwość dostawcy

Właściwość providers przyjmuje tablicę obiektów IdentityProvider o tych właściwościach:

Tryb aktywny

FedCM obsługuje różne konfiguracje trybu UX. Tryb pasywny jest trybem domyślnym i nie wymaga konfiguracji przez deweloperów.

Aby korzystać z FedCM w trybie aktywnym:

1. Sprawdź dostępność funkcji w przeglądarce użytkownika.
2. Wywołanie interfejsu API za pomocą tymczasowego 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'
      }
    });
  }

Ikona niestandardowa w trybie aktywnym

Tryb aktywny umożliwia dostawcom tożsamości dodanie oficjalnej ikony logo dostawcy RP bezpośrednio w odpowiedzi punktu końcowego metadanych klienta. RP musi z wyprzedzeniem podać dane dotyczące marki.

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

FedCM może być wywoływany z poziomu ramki iframe w wielu domenach za pomocą zasady uprawnień identity-credentials-get, jeśli dozwoli na to element nadrzędny. Aby to zrobić, dodaj atrybut allow="identity-credentials-get" do tagu iframe w ten sposób:

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

Możesz zobaczyć, jak to działa, na przykładzie.

Opcjonalnie, jeśli element nadrzędny chce ograniczyć źródła wywołania FedCM, wyślij nagłówek Permissions-Policy z listą dozwolonych źródeł.

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

Więcej informacji o zasadach dotyczących uprawnień znajdziesz w artykule Zarządzanie funkcjami przeglądarki za pomocą zasad dotyczących uprawnień.

Login Hint API

Za pomocą wskazówki logowania RP może zalecić, na którym koncie użytkownik powinien się zalogować. Może to być przydatne w przypadku ponownego uwierzytelniania użytkowników, którzy nie są pewni, którego konta używali wcześniej.

RP mogą selektywnie wyświetlać konkretne konto, wywołując funkcję navigator.credentials.get() z uwzględnieniem właściwości loginHint i 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 nie ma kont pasujących do loginHint, w oknie FedCM wyświetla się prośba o logowanie, która umożliwia użytkownikowi zalogowanie się na konto dostawcy tożsamości pasujące do wskazówki przesłanej przez RP. Gdy użytkownik kliknie prompt, otworzy się wyskakujące okienko z adresem URL logowania określonym w pliku konfiguracji. Następnie do linku dodawane są parametry zapytania dotyczące podpowiedzi logowania i podpowiedzi dotyczącej domeny.

Interfejs API podpowiedzi dotyczących domen

Reprezentanci mogą selektywnie wyświetlać tylko konta powiązane z określoną domeną. Może to być przydatne w przypadku RP, które są ograniczone do domeny firmowej.

Aby wyświetlić tylko konta w konkretnej domenie, RP powinien wywołać funkcję navigator.credentials.get() z właściwością domainHint zawierającą jedną z wartości domain_hints pobranych z punktu końcowego listy kont, jak pokazano w tym przykładowym kodzie:

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: 'abc',
        // Accounts endpoint can specify a 'domain_hints' array for an account.
        // When RP specifies a '@domain.example' value, only those accounts will be
        // shown to the user whose 'domain_hints' array contains the
        // '@domain.example' value
        domainHint : '@domain.example'
      }]
    }
  });

Jeśli nie ma kont pasujących do domainHint, w oknie FedCM wyświetla się prośba o logowanie, która umożliwia użytkownikowi zalogowanie się na konto dostawcy tożsamości pasujące do wskazówki przesłanej przez RP. Gdy użytkownik kliknie prompt, otworzy się wyskakujące okienko z adresem URL logowania określonym w pliku konfiguracji. Następnie do linku dodawane są parametry zapytania dotyczące podpowiedzi logowania i podpowiedzi dotyczącej domeny.

Parametry niestandardowe

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

• 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 za pomocą kontrolowanego przez dostawcę tożsamości procesu interfejsu użytkownika, który jest uruchamiany za pomocą funkcji Kontynuuj. Dostawca tożsamości udostępnia następnie te informacje.

Aby korzystać z interfejsu API, RP dodaje parametry do właściwości params jako obiekt w wywołaniu navigator.credentials.get():

  let {token} = await navigator.credentials.get({
    identity: {
      providers: [{
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',
        // Key/value pairs that need to be passed from the
        // RP to the IdP but that don't really play any role with
        // the browser.
        params: {
          IDP_SPECIFIC_PARAM: '1',
          foo: 'BAR'
        }
      },
    }
  });

Przeglądarka automatycznie przekształci to w żądanie POST do dostawcy tożsamości z parametrami jako pojedynczy obiekt JSON zakodowany w formacie URL:

  // The assertion endpoint is drawn from the config file
  POST /fedcm_assertion_endpoint HTTP/1.1
  Host: idp.example
  Origin: https://rp.example/
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

  // params are translated into urlencoded version of `{"IDP_SPECIFIC_PARAM":"1","foo":"bar"}`
  account_id=123&client_id=client1234&params=%22%7B%5C%22IDP_SPECIFIC_PARAM%5C%22%3A1%2C%5C%22foo%5C%22%3A%5C%22BAR%5C%22%7D%22.

Jeśli RP potrzebuje dodatkowych uprawnień, dostawca tożsamości może podać link przekierowania. Na przykład w node.js:

  if (rpRequestsPermissions) {
    // Response with a URL if the RP requests additional permissions
    return res.json({
      continue_on: '/example-redirect',
    });
  }

Pola

RP może określić informacje o użytkowniku (dowolną kombinację imienia i nazwiska, adresu e-mail i zdjęcia profilowego), które IdP musi udostępnić. Poproś o podanie informacji, które mają być uwzględnione w interfejsie FedCM. Jeśli użytkownik zdecyduje się na zalogowanie, zobaczy komunikat informujący, że idp.example udostępni rp.example żądane informacje.

Aby korzystać z funkcji pól, RP powinien dodać tablicę fields w wywołaniu navigator.credentials.get(). Pola mogą zawierać dowolną permutację wartości name, email i picture. W przyszłości możemy go rozszerzyć o kolejne wartości. Prośba z fields będzie wyglądać tak:

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

      },
    }
  });

Przeglądarka automatycznie przekształci je w żądanie HTTP do punktu końcowego oświadczenia o tożsamości, które zawiera parametr fields określony przez RP, z polami, które przeglądarka ujawniła użytkownikowi, w parametrze disclosure_shown_for. Ze względu na zgodność wsteczną przeglądarka wysyła też odpowiedź disclosure_text_shown=true, jeśli wyświetlono tekst informacyjny, a wśród żądanych pól znajdują się wszystkie 3 pola: 'name', 'email' i 'picture'.

  POST /id_assertion_endpoint HTTP/1.1
  Host: idp.example
  Origin: https://rp.example/
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

  // The RP only requested to share email and picture. The browser will send `disclosure_text_shown=false`, as the 'name' field value is missing
  account_id=123&client_id=client1234&disclosure_text_shown=false&fields=email,picture&disclosure_shown_for=email,picture

Jeśli tablica fields jest pusta, klient użytkownika pominie interfejs wyświetlania informacji.

Dzieje się tak nawet wtedy, gdy odpowiedź z punktu końcowego accounts nie zawiera identyfikatora klienta pasującego do RP w approved_clients.

W tym przypadku wartość disclosure_text_shown wysłana do punktu końcowego potwierdzenia tożsamości jest w treści HTTP równa fałsz:

  POST /id_assertion_endpoint HTTP/1.1
  Host: idp.example
  Origin: https://rp.example/
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

  account_id=123&client_id=client1234&nonce=234234&disclosure_text_shown=false

wyświetlić komunikat o błędzie.

Czasami dostawca tożsamości może nie być w stanie wydać tokena z uzasadnionych przyczyn, np. gdy klient nie jest autoryzowany lub serwer jest tymczasowo niedostępny. Jeśli dostawca tożsamości zwróci odpowiedź „error”, dostawca aplikacji może ją przechwycić, a Chrome może powiadomić użytkownika, wyświetlając interfejs przeglądarki z informacjami o błędzie dostarczonymi przez dostawcę tożsamości.

  try {
    const cred = await navigator.credentials.get({
      identity: {
        providers: [
          {
            configURL: 'https://idp.example/manifest.json',
            clientId: '1234',
          },
        ],
      }
    });
  } catch (e) {
    const code = e.code;
    const url = e.url;
  }

automatyczne ponowne uwierzytelnianie użytkowników po początkowym uwierzytelnieniu,

Automatyczne ponowne uwierzytelnianie w FedCM (w skrócie „automatyczne ponowne uwierzytelnianie”) umożliwia użytkownikom automatyczne ponowne uwierzytelnianie się, gdy powrócą do aplikacji po początkowym uwierzytelnieniu za pomocą FedCM. „Pierwsze uwierzytelnianie” oznacza, że użytkownik tworzy konto lub loguje się na stronie RP, klikając przycisk „Dalej jako…” w oknie logowania FedCM po raz pierwszy w tej samej instancji przeglądarki.

Chociaż wyświetlanie wyraźnego komunikatu ma sens, zanim użytkownik utworzy konto federacyjne, aby zapobiec śledzeniu (co jest jednym z głównych celów FedCM), jest ono niepotrzebnie uciążliwe, gdy użytkownik już raz je przeczytał. Po udzieleniu przez użytkownika zgody na komunikację między RP a IdP nie ma już potrzeby wymuszania kolejnego wyraźnego potwierdzenia przez użytkownika czegoś, co zostało już wcześniej zaakceptowane.

W przypadku automatycznej ponownej autoryzacji przeglądarka zmienia swoje działanie w zależności od opcji określonej dla mediation podczas wywołania navigator.credentials.get().

  const cred = await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/fedcm.json',
        clientId: '1234',
      }],
    },
    mediation: 'optional', // this is the default
  });

  // `isAutoSelected` is `true` if auto-reauthn was performed.
  const isAutoSelected = cred.isAutoSelected;

mediation to właściwość w interfejsie API do zarządzania danymi logowania. Działa tak samo jak w przypadku PasswordCredential i FederatedCredential, a także jest częściowo obsługiwana przez PublicKeyCredential. Właściwość ta akceptuje 4 wartości:

• 'optional' (domyślnie): automatyczne ponowne uwierzytelnianie (jeśli to możliwe) lub wymaganie uwierzytelniania (w przeciwnym razie). Zalecamy wybranie tej opcji na stronie logowania.
• 'required': zawsze wymaga interwencji, np. kliknięcia przycisku „Dalej” w interfejsie. Wybierz tę opcję, jeśli użytkownicy mają przyznawać uprawnienia wyraźnie za każdym razem, gdy trzeba ich uwierzytelnić.
• 'silent': automatyczne ponowne uwierzytelnianie (jeśli to możliwe) lub bezproblemowe niepowodzenie (jeśli nie jest możliwe) bez konieczności interwencji. Zalecamy wybranie tej opcji na stronach innych niż strona logowania, na których chcesz, aby użytkownicy pozostawali zalogowani. Może to być na przykład strona produktu w witrynie firmy spedycyjnej lub strona artykułu w witrynie z wiadomościami.
• 'conditional': służy do uwierzytelniania w ramach WebAuthn i obecnie nie jest dostępna w ramach FedCM.

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

• Dostępna jest usługa FedCM. Użytkownik nie wyłączył FedCM ani globalnie, ani w ustawieniach RP.
• Użytkownik zalogował się na stronie w tym przeglądarce tylko za pomocą jednego konta z FedCM API.
• Użytkownik jest zalogowany w systemie dostawcy tożsamości przy użyciu tego konta.
• Automatyczna ponowna autoryzacja nie nastąpiła w ciągu ostatnich 10 minut.
• RP nie zadzwonił navigator.credentials.preventSilentAccess() po poprzednim zalogowaniu.

Gdy te warunki zostaną spełnione, próba automatycznego ponownego uwierzytelnienia użytkownika rozpoczyna się, gdy tylko wywołana zostanie usługa FedCM navigator.credentials.get().

Gdy mediation: optional, automatyczne uwierzytelnianie może być niedostępne z powodów znanych tylko przeglądarce. Usługodawca może sprawdzić, czy automatyczne uwierzytelnianie zostało wykonane, badając właściwość isAutoSelected.

Pomoże to ocenić wydajność interfejsu API i odpowiednio poprawić wrażenia użytkownika. Jeśli nie jest ona dostępna, użytkownik może zostać poproszony o logowanie się z użyciem pośrednictwa użytkownika, czyli procesu z użyciem mediation: required.

Wymuś zapośredniczenie za pomocą preventSilentAccess()

Automatyczne uwierzytelnianie użytkowników tuż po wylogowaniu nie sprzyja wygodzie użytkowników. Dlatego FedCM ma 10-minutowy okres ciszy po automatycznym uwierzytelnieniu, aby zapobiec takiemu zachowaniu. Oznacza to, że automatyczne ponowne uwierzytelnianie odbywa się maksymalnie raz na 10 minut, chyba że użytkownik zaloguje się ponownie w ciągu 10 minut. RP powinien wywołać funkcję navigator.credentials.preventSilentAccess(), aby wyraźnie poprosić przeglądarkę o wyłączenie automatycznego ponownego uwierzytelniania, gdy użytkownik wyloguje się z RP, na przykład przez kliknięcie przycisku wylogowania.

  function signout() {
    navigator.credentials.preventSilentAccess();
    location.href = '/signout';
  }

Użytkownicy mogą zrezygnować z automatycznego uwierzytelniania w ustawieniach

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

• W Chrome na komputerze kliknij chrome://password-manager/settings > Zaloguj się automatycznie.
• W Chrome na Androidzie otwórz Ustawienia > Menedżer haseł > kliknij kółko zębate w prawym górnym rogu > Logowanie automatyczne.

Wyłączenie przełącznika powoduje, że użytkownik może całkowicie zrezygnować z automatycznego uwierzytelniania. To ustawienie jest przechowywane i synchronizowane na różnych urządzeniach, jeśli użytkownik zaloguje się na konto Google w Chrome i synchronizacja jest włączona.

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

Jeśli użytkownik zalogował się wcześniej w aplikacji RP za pomocą dostawcy tożsamości przez FedCM, przeglądarka zapamięta tę relację lokalnie jako listę połączonych kont. RP może zainicjować rozłączenie, wywołując funkcję IdentityCredential.disconnect(). Tę funkcję można wywołać z ramki RP najwyższego poziomu. RP musi przekazać configURL, clientId, którego używa w ramach dostawcy tożsamości, oraz accountHint, aby można było odłączyć dostawcę tożsamości. Wskazówka dotycząca konta może być dowolnym ciągiem znaków, o ile punkt końcowy funkcji rozłączania może zidentyfikować konto, na przykład adres e-mail lub identyfikator użytkownika, który nie musi być identyczny z identyfikatorem konta podanym przez punkt końcowy listy kont:

  // Disconnect an IdP account 'account456' from the RP 'https://idp.com/'. This is invoked on the RP domain.
  IdentityCredential.disconnect({
    configURL: 'https://idp.com/config.json',
    clientId: 'rp123',
    accountHint: 'account456'
  });

IdentityCredential.disconnect() zwraca wartość Promise. Ta obietnica może spowodować wyjątek z tych powodów:

• Użytkownik nie zalogował się w usłudze RP, korzystając z dostawcy tożsamości przez FedCM.
• Interfejs API jest wywoływany z poziomu elementu iframe bez zasad uprawnień FedCM.
• Adres URL konfiguracji jest nieprawidłowy lub nie ma punktu końcowego odłączenia.
• Nie udało się sprawdzić standardu Content Security Policy (CSP).
• Istnieje oczekująca prośba o rozłączenie.
• Użytkownik wyłączył FedCM w ustawieniach przeglądarki.

Gdy punkt końcowy usługi IdP do rozłączania zwraca odpowiedź, RP i IdP są rozłączane w przeglądarce, a obietnica jest realizowana. Identyfikatory rozłączonych kont są podane w odpowiedzi z punktu końcowego funkcji disconnect.

Dalsze kroki