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

Om FedCM op hun site in te schakelen, moeten vertrouwende partijen (Relying Parties, RP's) de volgende stappen uitvoeren:

• Zorg ervoor dat FedCM-eindpunten zijn toegestaan ​​op de site van de RP.
• Gebruik de FedCM JavaScript API om gebruikersauthenticatie te starten.
• Verstrek hun metadata (zoals URL's naar het privacybeleid en de gebruiksvoorwaarden) aan de identiteitsprovider (of meerdere identiteitsproviders vanaf Chrome 136).
• [optioneel] Pas de gebruikerservaring aan door een UX-modus te kiezen, inlog- of domeinhints te geven, aangepaste parameters door te geven, specifieke gebruikersinformatie op te vragen, een aangepast foutbericht te geven of te kiezen hoe gebruikers opnieuw moeten worden geverifieerd .

Roep de 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 toestemming te vragen voor een gebruiker om zich bij de RP aan te melden met behulp van de IdP.

Voordat je de API aanroept, moet je controleren of FedCM beschikbaar is in de browser van de gebruiker . Om te controleren of FedCM beschikbaar is, voeg je deze code toe aan je 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 in te loggen bij de IdP op een RP met behulp van FedCM, kan de RP navigator.credentials.get() aanroepen. Vanaf Chrome 136 kan een RP meerdere IdP's ondersteunen door een array van meerdere identiteitsproviders op te geven in één enkele aanroep navigator.credentials.get() , 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
    }

Test de functie voor meerdere identiteitsproviders door in te loggen met IdP1 en IdP2 .

Context-eigenschap

Met de optionele context eigenschap kan RP de tekst in de FedCM-dialooginterface aanpassen (bijvoorbeeld "Meld u aan bij rp.example…", "Gebruik idp.example…") om vooraf gedefinieerde authenticatiecontexten te ondersteunen. De context eigenschap kan de volgende waarden hebben:

• signin (standaard)
• signup
• use

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

De browser behandelt aanmeld- en inlogscenario's anders, afhankelijk van de aanwezigheid van approved_clients in het antwoord van het accountlijst-endpoint . De browser zal geen melding "Om verder te gaan met..." weergeven als de gebruiker zich al heeft aangemeld bij de RP.

De eigenschap providers accepteert een array van IdentityProvider -objecten met de volgende eigenschappen:

Eigendom van de aanbieders

De eigenschap providers accepteert een array van 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 actieve modus te gebruiken:

1. Controleer of de functie beschikbaar is in de browser van de gebruiker.
2. Roep de API aan met een tijdelijke gebruikersactie, zoals een muisklik 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 uit met deze demo .

Aangepast pictogram in actieve modus

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

Roep FedCM aan vanuit een cross-origin iframe.

FedCM kan worden aangeroepen vanuit een cross-origin iframe met behulp van een identity-credentials-get permissiebeleid, mits het bovenliggende iframe dit toestaat. Voeg hiervoor het attribuut allow="identity-credentials-get" toe aan de iframe-tag, zoals hieronder weergegeven:

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

Je kunt het in actie zien in een voorbeeld .

Optioneel kan het hoofdframe, als het de oorsprongen wil beperken die FedCM mogen aanroepen, een Permissions-Policy header met een lijst van toegestane oorsprongen meesturen.

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

Meer informatie over hoe het machtigingsbeleid werkt, vindt u in Browserfuncties beheren met het machtigingsbeleid .

Login Hint API

Met behulp van de inloghint kan de RP aanbevelen met welk account een gebruiker moet inloggen. Dit kan handig zijn bij het opnieuw authenticeren van gebruikers die niet zeker weten welk account ze eerder hebben gebruikt.

Relying Partners (RP's) kunnen selectief een specifiek account weergeven door navigator.credentials.get() aan te roepen met de eigenschap loginHint , waarbij één van de login_hints waarden wordt gebruikt die zijn opgehaald via het endpoint voor de lijst met accounts , zoals weergegeven 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'
      }]
    }
  });

Als er geen accounts overeenkomen met de loginHint , toont het FedCM-dialoogvenster een inlogprompt 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 in het configuratiebestand is opgegeven. Aan de link worden vervolgens de inloghint en de queryparameters voor de domeinhint toegevoegd.

Domain Hint API

Relying Partners (RP's) kunnen selectief alleen accounts weergeven 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 de functie navigator.credentials.get() aanroepen met de eigenschap domainHint en een van de domain_hints waarden die zijn opgehaald via het `accounts list`-eindpunt , zoals 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'
      }]
    }
  });

Als er geen accounts overeenkomen met de domainHint , toont het FedCM-dialoogvenster een inlogprompt 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 klikt, wordt een dialoogvenster geopend met de inlog-URL die in het configuratiebestand is opgegeven. Aan de link worden vervolgens de inloghint en de queryparameters voor de domeinhint toegevoegd.

Bekijk de demo voor meer details.

Aangepaste parameters

Met de functie 'Aangepaste parameters' kan de Relying Party (RP) extra sleutel-waardeparen doorgeven aan het ID-assertie-eindpunt . Via de Parameters API kunnen RP's extra parameters aan de Identity Provider (IdP) doorgeven om machtigingen voor resources aan te vragen die verder gaan dan de standaard aanmelding. Het doorgeven van extra parameters kan nuttig zijn in de volgende scenario's:

• De Relying Party (RP) moet dynamisch aanvullende machtigingen aanvragen die de Identity Provider (IdP) heeft, zoals toegang tot het factuuradres of de agenda. De gebruiker kan deze machtigingen autoriseren via een door de IdP beheerde 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 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 Relying Party (RP) aanvullende machtigingen nodig heeft, kan de Identity Provider (IdP) een omleidingslink verstrekken. 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 specificeren welke gebruikersinformatie de IdP met hen moet delen. Dit kan elke combinatie van naam, e-mailadres, gebruikersnaam, telefoonnummer en profielfoto omvatten. De gevraagde informatie wordt opgenomen in de gebruikersinterface voor openbaarmaking van het FedCM-dialoogvenster.

Gebruikers die zich registreren, zien een bericht waarin staat dat de idp.example de gevraagde informatie met de rp.example zal delen als de gebruiker zich registreert. Als het antwoord van het accounts-eindpunt een veld niet bevat dat de RP heeft opgevraagd, zal dit veld niet in de openbaarmakingstekst worden opgenomen. De IdP ontvangt alle gevraagde velden van het id-assertie-eindpunt en besluit of er verdere toestemming van de gebruiker nodig is om verder te gaan.

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

   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 naar het ID-assertie-eindpunt , inclusief de door RP gespecificeerde fields , met de velden die de browser aan de gebruiker heeft getoond in een disclosure_shown_for parameter. Voor compatibiliteit met oudere versies stuurt de browser ook disclosure_text_shown=true als de openbaarmakingstekst is getoond en de gevraagde velden alle drie de velden bevatten: 'name' , 'email' en 'picture' . Vanaf Chrome 141 geeft de waarde van disclosure_text_shown niet meer aan of de openbaarmakingstekst daadwerkelijk aan de gebruiker is getoond.

  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 is, slaat de user agent de gebruikersagent de informatie-interface over.

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

In dit geval is de waarde van 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&disclosure_text_shown=false&params=%22%7B%5C%22nonce%5C%22%3A%5C%22234234%5C%22%7D%22.%0D%0A

Een foutmelding weergeven

Als een identiteitsprovider (IdP) geen token kan uitgeven (bijvoorbeeld omdat een client niet geautoriseerd is of de server niet beschikbaar is), stuurt deze een foutmelding terug. De Relying Party (RP) kan deze fout vervolgens opvangen, waarna Chrome de gebruiker via een browserinterface op de hoogte kan stellen met de foutmelding die de IdP heeft verstrekt.

try {
    const cred = await navigator.credentials.get({
      identity: {
        providers: [
          {
            configURL: 'https://idp.example/manifest.json',
            clientId: '1234',
          },
        ],
      }
    });
  } catch (e) {
    // Note:    In Chrome 142 and earlier, the IdentityCredentialError.error property was named IdentityCredentialError.code.
    const error = e.error;
    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. De volgende voorwaarden moeten worden voldaan om de gebruiker automatisch opnieuw te authenticeren:

• De gebruiker heeft eerder de initiële authenticatie via FedCM uitgevoerd. "Initiële authenticatie" betekent hier dat de gebruiker een account aanmaakt of zich aanmeldt bij de website van de RP door voor de eerste keer in dezelfde browserinstantie op de knop "Doorgaan als..." in het aanmeldingsvenster van FedCM te tikken.
• De gebruiker heeft slechts één terugkerend account. Als er terugkerende accounts bestaan ​​voor meerdere identiteitsproviders (IdP's), wordt de gebruiker niet automatisch opnieuw geverifieerd.

Hoewel de expliciete gebruikerservaring zinvol is voordat de gebruiker het gefedereerde account heeft aangemaakt om tracking te voorkomen (wat een van de belangrijkste doelen van FedCM is), is het onnodig omslachtig nadat de gebruiker het eenmaal heeft doorlopen: nadat de gebruiker toestemming heeft gegeven voor communicatie tussen de RP en de IdP, biedt het geen privacy- of beveiligingsvoordeel meer om opnieuw een expliciete gebruikersbevestiging te eisen voor iets dat de gebruiker al eerder heeft erkend.

Bij automatische herauthenticatie past de browser zijn gedrag aan op basis van de optie die je opgeeft voor de mediation bij het aanroepen van 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;

De mediation is een eigenschap in de Credential Management API . Deze gedraagt ​​zich op dezelfde manier als PasswordCredential en FederatedCredential en wordt gedeeltelijk ook ondersteund door PublicKeyCredential . De eigenschap accepteert de volgende vier waarden:

• 'optional' (standaard): Automatisch opnieuw authenticeren indien mogelijk, anders is een tussenkomst vereist. We raden aan deze optie te selecteren op de inlogpagina.
• 'required' : Er is altijd een tussenkomst vereist om verder te gaan, bijvoorbeeld door op de knop 'Doorgaan' in de gebruikersinterface te klikken. Kies deze optie als van uw gebruikers wordt verwacht dat ze elke keer dat ze moeten worden geauthenticeerd, expliciet toestemming geven.
• 'silent' : Automatisch opnieuw authenticeren indien mogelijk, stilzwijgend afwijzen zonder tussenkomst als dit niet mogelijk is. We raden aan deze optie te kiezen voor pagina's die niet de officiële inlogpagina zijn, maar waar u gebruikers wel ingelogd wilt houden – bijvoorbeeld een productpagina op een verzendwebsite of een artikelpagina op een nieuwswebsite.
• 'conditional' : Wordt gebruikt voor WebAuthn en is momenteel niet beschikbaar voor FedCM.

Bij dit gesprek vindt automatische herauthenticatie plaats onder de volgende voorwaarden:

• FedCM is beschikbaar voor gebruik. De gebruiker heeft FedCM bijvoorbeeld niet uitgeschakeld, noch globaal , noch voor de RP in de instellingen.
• De gebruiker heeft slechts één account met de FedCM API gebruikt om in te loggen op de website via deze browser.
• De gebruiker is met dat account ingelogd bij de identiteitsprovider.
• De automatische herauthenticatie heeft de afgelopen 10 minuten niet plaatsgevonden.
• De RP heeft na de vorige aanmelding geen aanroep gedaan naar navigator.credentials.preventSilentAccess() .

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

Wanneer mediation: optional , kan automatische herauthenticatie om redenen die alleen de browser kent, niet beschikbaar zijn; de RP kan controleren of automatische herauthenticatie wordt uitgevoerd door de eigenschap isAutoSelected te onderzoeken.

Dit is nuttig om de API-prestaties te evalueren en de gebruikerservaring dienovereenkomstig te verbeteren. Als de API niet beschikbaar is, kan de gebruiker bovendien worden gevraagd om in te loggen met expliciete gebruikersbemiddeling, een procedure met mediation: required .

Dwing bemiddeling af met preventSilentAccess()

Automatisch opnieuw authenticeren van gebruikers direct nadat ze uitloggen, zou geen goede gebruikerservaring opleveren. Daarom heeft FedCM een stille periode van 10 minuten na een automatische herauthenticatie om dit gedrag te voorkomen. Dit betekent dat automatische herauthenticatie maximaal één keer per 10 minuten plaatsvindt, tenzij de gebruiker binnen 10 minuten opnieuw inlogt. De Relying Party (RP) moet navigator.credentials.preventSilentAccess() aanroepen om de browser expliciet te verzoeken 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 herverificatie.

Gebruikers kunnen zich via het instellingenmenu afmelden voor automatische herauthenticatie.

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

Door de schakelaar uit te schakelen, kan de gebruiker het automatisch opnieuw authenticeren volledig uitschakelen. Deze instelling wordt opgeslagen en gesynchroniseerd tussen apparaten, mits de gebruiker is aangemeld bij een Google-account in Chrome en synchronisatie is ingeschakeld.

Ontkoppel de IdP van de RP.

Als een gebruiker zich eerder via FedCM bij de RP heeft aangemeld met behulp van de IdP, wordt de relatie lokaal door de browser opgeslagen als een lijst met verbonden accounts. De RP kan een ontkoppeling 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 onder de IdP wordt gebruikt, en een accountHint voor de IdP waarmee de verbinding wordt verbroken, doorgeven. Een accounthint kan een willekeurige tekenreeks zijn, zolang het ontkoppelings-eindpunt het account maar kan identificeren, bijvoorbeeld een e-mailadres of gebruikers-ID die niet noodzakelijkerwijs overeenkomt met de account-ID die het accountlijst-eindpunt heeft verstrekt.

  // 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 aangemeld bij de RP via de IdP via FedCM.
• De API wordt aangeroepen vanuit een iframe zonder FedCM-toegangsbeleid.
• De configURL is ongeldig of het eindpunt voor de ontkoppeling ontbreekt.
• De controle van het Content Security Policy (CSP) mislukt.
• Er is een verzoek tot verbreking van de verbinding in behandeling.
• De gebruiker heeft FedCM uitgeschakeld in de browserinstellingen.

Wanneer het disconnect-eindpunt van de IdP een reactie retourneert , worden de RP en de IdP in de browser losgekoppeld en wordt de promise afgehandeld. De ID's van de losgekoppelde accounts worden in de reactie van het disconnect-eindpunt vermeld.