Implementeer een identiteitsoplossing met FedCM aan de kant van de Relying Party

Relying Parties (RPs) moeten de volgende stappen voltooien om FedCM op hun site in te schakelen:

• Zorg ervoor dat FedCM-eindpunten zijn toegestaan ​​op de site van de RP.
• Gebruik de FedCM JavaScript API om gebruikersauthenticatie te initiëren.
• Geef hun metagegevens (zoals URL's voor het privacybeleid en de servicevoorwaarden) door aan de IdP (of meerdere IdP's van Chrome 136).
• [optioneel] Pas de gebruikerservaring aan door een UX-modus te kiezen, inlog- of domeinhints te verstrekken, aangepaste parameters door te geven, specifieke gebruikersinformatie op te vragen, een aangepast foutbericht te verstrekken of te kiezen hoe gebruikers opnieuw moeten worden geverifieerd .

Roep FedCM API aan op de Relying Party

Zodra de configuratie en eindpunten van de IdP beschikbaar zijn, kunnen RP's navigator.credentials.get() aanroepen om aan te vragen of een gebruiker zich met de IdP bij de RP mag aanmelden.

Voordat u de API aanroept, moet u controleren of FedCM beschikbaar is in de browser van de gebruiker . Om te controleren of FedCM beschikbaar is, plaatst u deze code rond uw FedCM-implementatie:

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

Om een ​​gebruiker in staat te stellen zich aan te melden bij de IdP op een RP met behulp van FedCM, kan de RP navigator.credentials.get() aanroepen. Vanuit Chrome 136 kan RP meerdere IdP's ondersteunen door een reeks van meerdere identiteitsproviders op te geven in één navigator.credentials.get() -aanroep, bijvoorbeeld:

  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
    }

Probeer de functie voor meerdere IdP's uit door u aan te melden met IdP1 en IdP2 .

Contexteigenschap

Met de optionele context kan RP de tekenreeks in de FedCM-dialooginterface (bijvoorbeeld "Aanmelden bij rp.example...", "Gebruik idp.example...") aanpassen om bijvoorbeeld vooraf gedefinieerde authenticatiecontexten te accommoderen. De context kan de volgende waarden hebben:

• signin (standaard)
• signup
• use

Als u bijvoorbeeld context instelt op use , verschijnt het volgende bericht:

De browser verwerkt aanmeldings- en inlogcases verschillend, afhankelijk van de aanwezigheid van approved_clients in de respons van het eindpunt van de accountlijst . De browser geeft geen meldingstekst 'Doorgaan met ....' weer als de gebruiker zich al heeft aangemeld bij de RP.

De eigenschap providers gebruikt een reeks IdentityProvider -objecten met de volgende eigenschappen:

Eigendom van de aanbieders

De eigenschap providers gebruikt een reeks IdentityProvider -objecten met de volgende eigenschappen:

Actieve modus

FedCM ondersteunt verschillende UX-modusconfiguraties . De passieve modus is de standaardmodus en ontwikkelaars hoeven deze niet te configureren.

Om FedCM in de actieve modus te gebruiken:

1. Controleer de beschikbaarheid van de functie in de browser van de gebruiker.
2. Roep de API aan met een tijdelijk gebruikersgebaar, zoals een klik op een knop.
3. Geef de mode door aan de API-aanroep:

  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'
      }
    });
  }

Probeer de actieve modus met deze demo .

Aangepast pictogram in actieve modus

In de actieve modus kunnen IdP's het officiële logo van de RP rechtstreeks opnemen in de clientmetadata-endpointrespons . De RP moet hiervoor vooraf zijn merkgegevens aanleveren.

FedCM aanroepen vanuit een cross-origin iframe

FedCM kan worden aangeroepen vanuit een cross-origin iframe met behulp van een identity-credentials-get machtigingsbeleid, mits het bovenliggende frame dit toestaat. Voeg hiervoor het kenmerk allow="identity-credentials-get" als volgt toe aan de iframe-tag:

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

U kunt het in actie zien in dit voorbeeld .

Als het bovenliggende frame de oorsprongen wil beperken tot het aanroepen van FedCM, stuurt u optioneel een Permissions-Policy header met een lijst met toegestane oorsprongen.

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

Meer informatie over de werking van het machtigingsbeleid vindt u in Browserfuncties beheren met machtigingsbeleid .

Aanmeldingshint API

Met behulp van de Login Hint kan de RP aanbevelen met welk account een gebruiker zich moet aanmelden. Dit kan handig zijn bij het opnieuw verifiëren van gebruikers die niet zeker weten welk account ze eerder hebben gebruikt.

RP's kunnen selectief een specifiek account weergeven door navigator.credentials.get() aan te roepen met de eigenschap loginHint met een van de login_hints waarden die zijn opgehaald uit het eindpunt van de accountlijst , zoals wordt getoond in het volgende codevoorbeeld:

  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'
      }]
    }
  });

Wanneer geen enkel account overeenkomt met de loginHint , toont het FedCM-dialoogvenster een aanmeldprompt waarmee de gebruiker kan inloggen op een IdP-account dat overeenkomt met de hint die door de RP is aangevraagd. Wanneer de gebruiker op de prompt tikt, wordt een dialoogvenster geopend met de inlog-URL die is opgegeven in het configuratiebestand . De link wordt vervolgens toegevoegd met de aanmeldhint en de queryparameters voor de domeinhint.

Domein Hint API

RP's kunnen selectief alleen accounts tonen die aan een bepaald domein zijn gekoppeld. Dit kan handig zijn voor RP's die beperkt zijn tot een bedrijfsdomein.

Om alleen specifieke domeinaccounts weer te geven, moet RP navigator.credentials.get() aanroepen met de eigenschap domainHint met een van domain_hints waarden die zijn opgehaald uit het eindpunt van de accountlijst , zoals wordt weergegeven in het volgende codevoorbeeld:

  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'
      }]
    }
  });

Wanneer geen enkel account overeenkomt met de domainHint , toont het FedCM-dialoogvenster een aanmeldprompt waarmee de gebruiker kan inloggen op een IdP-account dat overeenkomt met de hint die door de RP is aangevraagd. Wanneer de gebruiker op de prompt tikt, wordt een dialoogvenster geopend met de inlog-URL die is opgegeven in het configuratiebestand . De link wordt vervolgens toegevoegd met de aanmeldhint en de queryparameters voor de domeinhint.

Bekijk de demo voor meer informatie.

Aangepaste parameters

Met de functie Aangepaste parameters kan de RP extra sleutel-waardeparameters aan het ID-assertie-eindpunt verstrekken. Met de Parameters API kunnen RP's extra parameters aan de IdP doorgeven om machtigingen aan te vragen voor resources die verder gaan dan alleen de standaardaanmelding. Het doorgeven van extra parameters kan nuttig zijn in de volgende scenario's:

• De RP moet dynamisch aanvullende rechten aanvragen die de IdP heeft, zoals toegang tot een factuuradres of agenda. De gebruiker kan deze rechten autoriseren via een door de IdP aangestuurde UX-flow die wordt gestart met de functie 'Doorgaan' , waarna de IdP deze informatie deelt.

Om de API te gebruiken, voegt de RP parameters toe aan de eigenschap params als een object in de aanroep 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'
        }
      },
    }
  });

De browser vertaalt dit automatisch naar een POST-verzoek aan de IdP met parameters als één enkel URL-gecodeerd JSON-geserialiseerd object:

  // 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.

Als de RP aanvullende rechten nodig heeft, kan de IdP een redirect-link aanbieden. Bijvoorbeeld in node.js:

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

Velden

De RP kan de gebruikersinformatie specificeren die de IdP met hem moet delen. Dit kan elke combinatie zijn van naam, e-mailadres, gebruikersnaam, telefoonnummer en profielfoto. De gevraagde informatie wordt opgenomen in de gebruikersinterface van het FedCM-dialoogvenster.

Aanmeldende gebruikers zien een bericht dat idp.example de gevraagde informatie deelt met rp.example als de gebruiker zich aanmeldt. Als het antwoord van het account-eindpunt een veld niet bevat dat de RP heeft aangevraagd, wordt dit veld niet opgenomen in de openbaarmakingstekst. De IdP leert alle gevraagde velden van het id-assertie-eindpunt en beslist of er meer gebruikersrechten moeten worden verzameld om door te gaan.

Om de functie Velden te gebruiken, moet RP een fields toevoegen aan de navigator.credentials.get() aanroep. De velden kunnen eigenschappen bevatten zoals name , email , tel , username of picture . Dit kan in de toekomst worden uitgebreid met meer waarden. Een aanvraag met fields ziet er als volgt uit:

   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',
      },
    }
  });

De browser vertaalt dit automatisch naar een HTTP-verzoek aan het ID-assertie-eindpunt , inclusief de door RP gespecificeerde fields , met de velden die de browser aan de gebruiker heeft vrijgegeven in een disclosure_shown_for parameter. Voor achterwaartse compatibiliteit verzendt de browser ook disclosure_text_shown=true als de openbaarmakingstekst is weergegeven en de opgevraagde velden alle drie de velden bevatten: 'name' , 'email' en 'picture' . Vanaf Chrome 141 geeft de waarde van disclosure_text_shown niet aan of de openbaarmakingstekst daadwerkelijk aan de gebruiker is weergegeven.

  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

Als fields een lege array zijn, slaat de gebruikersagent de openbaarmakingsinterface over.

Dit is zelfs het geval als het antwoord van het accounteindpunt geen client-ID bevat die overeenkomt met de RP in approved_clients .

In dit geval is de disclosure_text_shown die naar het ID-assertie-eindpunt wordt verzonden, onwaar in de HTTP-body:

  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

Een foutmelding weergeven

Soms kan de IdP om legitieme redenen geen token uitgeven, bijvoorbeeld wanneer de client niet geautoriseerd is of de server tijdelijk niet beschikbaar is. Als de IdP een "fout"-melding retourneert, kan de RP dit opvangen en kan Chrome de gebruiker hiervan op de hoogte stellen door de browserinterface te tonen met de door de IdP verstrekte foutinformatie.

  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;
  }

Gebruikers automatisch opnieuw authenticeren na de eerste authenticatie

Met FedCM-automatische herauthenticatie (kortweg "auto-reauthn") kunnen gebruikers zich automatisch opnieuw authenticeren. Aan de volgende voorwaarden moet worden voldaan om de gebruiker automatisch opnieuw te authenticeren:

• De gebruiker heeft eerder de initiële authenticatie uitgevoerd met behulp van FedCM. "De initiële authenticatie" betekent in dit geval dat de gebruiker een account aanmaakt of zich aanmeldt op de website van de RP door voor het eerst in dezelfde browser op de knop "Doorgaan als..." in het aanmeldvenster van FedCM te tikken.
• De gebruiker heeft slechts één terugkerend account. Als er terugkerende accounts voor meerdere IdP's bestaan, wordt de gebruiker niet automatisch opnieuw geauthenticeerd.

De expliciete gebruikerservaring is weliswaar zinvol voordat de gebruiker een federatief account heeft aangemaakt om tracking te voorkomen (een van de hoofddoelen van FedCM), maar is onnodig omslachtig nadat de gebruiker dit al een keer heeft gedaan: nadat de gebruiker toestemming heeft gegeven voor communicatie tussen de RP en de IdP, biedt het geen privacy- of beveiligingsvoordeel meer om een ​​andere expliciete gebruikersbevestiging af te dwingen voor iets dat deze gebruiker al eerder heeft bevestigd.

Met automatische herauthenticatie verandert het gedrag van de browser afhankelijk van de optie die u opgeeft voor de mediation wanneer u navigator.credentials.get() aanroept.

  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 is een eigenschap in de Credential Management API . Het gedraagt ​​zich op dezelfde manier als PasswordCredential en FederatedCredential en wordt gedeeltelijk ondersteund door PublicKeyCredential . De eigenschap accepteert de volgende vier waarden:

• 'optional' (standaard): Automatische herauthenticatie indien mogelijk, bemiddeling vereist indien niet. We raden aan deze optie te kiezen op de aanmeldpagina.
• 'required' : Vereist altijd een tussenkomst om door te gaan, bijvoorbeeld door op de knop 'Doorgaan' in de gebruikersinterface te klikken. Kies deze optie als van uw gebruikers wordt verwacht dat ze expliciet toestemming verlenen telkens wanneer ze zich moeten authenticeren.
• 'silent' : Automatische herauthenticatie indien mogelijk, stilletjes mislukken zonder tussenkomst indien niet mogelijk. We raden aan deze optie te kiezen op andere pagina's dan de speciale aanmeldpagina, maar waar u gebruikers aangemeld wilt houden, bijvoorbeeld een artikelpagina op een verzendwebsite of een artikelpagina op een nieuwswebsite.
• 'conditional' : Gebruikt voor WebAuthn en op dit moment niet beschikbaar voor FedCM.

Met deze aanroep vindt automatische herauthenticatie plaats onder de volgende voorwaarden:

• FedCM is beschikbaar voor gebruik. De gebruiker heeft FedCM bijvoorbeeld niet globaal of voor de RP in de instellingen uitgeschakeld .
• De gebruiker heeft slechts één account met FedCM API gebruikt om zich via deze browser aan te melden bij de website.
• De gebruiker is met dat account aangemeld bij de IdP.
• De automatische herauthenticatie heeft niet plaatsgevonden in de laatste 10 minuten.
• De RP heeft navigator.credentials.preventSilentAccess() niet aangeroepen na de vorige aanmelding.

Wanneer aan deze voorwaarden is voldaan, wordt er een poging gedaan om de gebruiker automatisch opnieuw te verifiëren zodra FedCM navigator.credentials.get() wordt aangeroepen.

Wanneer mediation: optional , is automatisch opnieuw authenticeren mogelijk niet beschikbaar om redenen die alleen de browser kent. De RP kan controleren of automatisch opnieuw authenticeren wordt uitgevoerd door de eigenschap isAutoSelected te onderzoeken.

Dit is handig om de API-prestaties te evalueren en de UX dienovereenkomstig te verbeteren. Wanneer de API niet beschikbaar is, kan de gebruiker bovendien worden gevraagd om in te loggen met expliciete gebruikersbemiddeling, wat een flow is met mediation: required .

Mediatie afdwingen met preventSilentAccess()

Het automatisch opnieuw authenticeren van gebruikers direct na het afmelden zou niet bijdragen aan een goede gebruikerservaring. Daarom hanteert FedCM een stilteperiode van 10 minuten na een automatische herauthenticatie om dit gedrag te voorkomen. Dit betekent dat de automatische herauthenticatie maximaal één keer per 10 minuten plaatsvindt, tenzij de gebruiker zich binnen 10 minuten opnieuw aanmeldt. De RP moet navigator.credentials.preventSilentAccess() aanroepen om de browser expliciet te vragen de automatische herauthenticatie uit te schakelen wanneer een gebruiker zich expliciet afmeldt bij de RP, bijvoorbeeld door op een afmeldknop te klikken.

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

Gebruikers kunnen zich in de instellingen afmelden voor automatische herauthenticatie

Gebruikers kunnen zich via het instellingenmenu afmelden voor automatische herauthenticatie:

• Ga in Chrome op uw desktop naar chrome://password-manager/settings > Automatisch aanmelden.
• Open in Android Chrome Instellingen > Wachtwoordbeheer > Tik op het tandwiel in de rechterbovenhoek > Automatisch aanmelden.

Door de schakelaar uit te schakelen, kan de gebruiker zich volledig afmelden voor automatisch opnieuw authenticeren. Deze instelling wordt opgeslagen en gesynchroniseerd op alle apparaten, mits de gebruiker is aangemeld bij een Google-account op de Chrome-instantie en synchronisatie is ingeschakeld.

Koppel de IdP los van de RP

Als een gebruiker zich eerder via FedCM bij de RP heeft aangemeld met de IdP, wordt de relatie lokaal door de browser opgeslagen als de lijst met verbonden accounts. De RP kan een verbindingsverbreking initiëren door de functie IdentityCredential.disconnect() aan te roepen. Deze functie kan worden aangeroepen vanuit een RP-frame op het hoogste niveau. De RP moet een configURL , de clientId die hij onder de IdP gebruikt, en een accountHint doorgeven om de verbinding met de IdP te verbreken. Een accounthint kan een willekeurige tekenreeks zijn, zolang het eindpunt voor de verbindingsverbreking het account maar kan identificeren, bijvoorbeeld een e-mailadres of gebruikers-ID die niet noodzakelijkerwijs overeenkomt met de account-ID die het eindpunt voor de accountlijst heeft opgegeven:

  // 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() retourneert een Promise . Deze promise kan om de volgende redenen een uitzondering genereren:

• De gebruiker heeft zich niet via FedCM aangemeld bij de RP met behulp van de IdP.
• De API wordt aangeroepen vanuit een iframe zonder FedCM-machtigingsbeleid.
• De configURL is ongeldig of het verbindingseindpunt ontbreekt.
• Controle van Content Security Policy (CSP) mislukt.
• Er is een verzoek tot verbreken van de verbinding in behandeling.
• De gebruiker heeft FedCM uitgeschakeld in de browserinstellingen.

Wanneer het disconnect-eindpunt van de IdP een respons retourneert , worden de RP en de IdP losgekoppeld in de browser en wordt de belofte opgelost. De ID's van de losgekoppelde accounts worden gespecificeerd in de respons van het disconnect-eindpunt .