Implementa una soluzione di identità con FedCM lato Relying Party

Le parti che fanno affidamento (RP) devono completare i seguenti passaggi per attivare FedCM sul proprio sito:

• Assicurati che gli endpoint FedCM siano consentiti sul sito del RP.
• Utilizza l'API JavaScript FedCM per avviare l'autenticazione degli utenti.
• Fornisci i relativi metadati (ad esempio gli URL delle norme sulla privacy e dei termini di servizio) al provider di identità (o a più provider di identità a partire da Chrome 136).
• [facoltativo] Personalizza l'esperienza utente scegliendo una modalità UX, fornendo suggerimenti per l'accesso o per il dominio, passando parametri personalizzati, richiedendo informazioni specifiche sull'utente, fornendo un messaggio di errore personalizzato o scegliendo come autenticare nuovamente gli utenti.

Chiama l'API FedCM sulla Relying Party

Una volta disponibili la configurazione dell'IdP e gli endpoint, le RP possono chiamare navigator.credentials.get() per richiedere di consentire a un utente di accedere alla RP con l'IdP.

Prima di chiamare l'API, devi verificare che FedCM sia disponibile sul browser dell'utente. Per verificare se FedCM è disponibile, racchiudi questo codice intorno all'implementazione di FedCM:

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

Per consentire a un utente di accedere all'IdP su una parte autorizzata utilizzando FedCM, la parte autorizzata può chiamare navigator.credentials.get(). A partire da Chrome 136, RP può supportare più IdP specificando un array di più provider di identità in una singola chiamata navigator.credentials.get(), ad esempio:

  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
    }

Prova la funzionalità di più IdP accedendo con IdP1 e IdP2.

Proprietà di contesto

Con la proprietà facoltativa context, RP può modificare la stringa nell'interfaccia utente della finestra di dialogo FedCM (ad esempio "Accedi a rp.example…", "Utilizza idp.example…") per adattarsi a contesti di autenticazione predefiniti, ad esempio. La proprietà context può avere i seguenti valori:

• signin (valore predefinito)
• signup
• use

Ad esempio, se imposti context su use, verrà visualizzato il seguente messaggio:

Il browser gestisce i casi d'uso di registrazione e accesso in modo diverso a seconda dell'esistenza di approved_clients nella risposta dell'endpoint dell'elenco degli account. Il browser non mostrerà il testo dell'informativa "Per continuare con..." se l'utente ha già eseguito la registrazione alla RP.
La proprietà providers accetta un array di oggetti IdentityProvider con le seguenti proprietà:

Proprietà Provider

La proprietà providers accetta un array di oggetti IdentityProvider che hanno le seguenti proprietà:

Modalità attiva

FedCM supporta diverse configurazioni della modalità UX. La modalità passiva è la modalità predefinita e gli sviluppatori non devono configurarla.

Per utilizzare FedCM in modalità attiva:

1. Controlla la disponibilità della funzionalità nel browser dell'utente.
2. Richiama l'API con un gesto dell'utente temporaneo, ad esempio un clic sul pulsante.
3. Passa il parametro mode alla chiamata 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'
      }
    });
  }

Prova la modalità attiva con questa demo.

Icona personalizzata in modalità attiva

La modalità attiva consente ai provider di identità di includere l'icona del logo ufficiale del relying party direttamente nella risposta dell'endpoint dei metadati del client. Il RP deve fornire in anticipo i dati del proprio brand.

Chiamare FedCM dall'interno di un iframe multiorigine

FedCM può essere richiamato da un iframe multiorigine utilizzando una policy delle autorizzazioni identity-credentials-get, se il frame principale lo consente. Per farlo, aggiungi l'attributo allow="identity-credentials-get" al tag iframe nel seguente modo:

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

Puoi vederlo in azione in un esempio.

(Facoltativo) Se il frame principale vuole limitare le origini per chiamare FedCM, invia un'intestazione Permissions-Policy con un elenco di origini consentite.

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

Puoi scoprire di più su come funziona la Permissions Policy in Controllo delle funzionalità del browser con la Permissions Policy.

API Login Hint

Utilizzando il suggerimento di accesso, il RP può consigliare all'utente con quale account accedere. Questo può essere utile per autenticare nuovamente gli utenti che non ricordano quale account hanno utilizzato in precedenza.

I RP possono mostrare selettivamente un account specifico richiamando navigator.credentials.get() con la proprietà loginHint con uno dei valori login_hints recuperati dall'endpoint dell'elenco degli account, come mostrato nel seguente esempio di codice:

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

Quando nessun account corrisponde a loginHint, la finestra di dialogo FedCM mostra una richiesta di accesso, che consente all'utente di accedere a un account IdP corrispondente al suggerimento richiesto dalla RP. Quando l'utente tocca il prompt, si apre una finestra popup con l'URL di accesso specificato nel file di configurazione. Il link viene quindi aggiunto con i parametri di query del suggerimento di accesso e del suggerimento di dominio.

API Domain Hint

I RP possono mostrare in modo selettivo solo gli account associati a un determinato dominio. Questa opzione può essere utile per i RP limitati a un dominio aziendale.

Per visualizzare solo account di domini specifici, RP deve chiamare navigator.credentials.get() con la proprietà domainHint con uno dei valori domain_hints recuperati da endpoint dell'elenco degli account, come mostrato nel seguente esempio di codice:

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

Quando nessun account corrisponde a domainHint, la finestra di dialogo FedCM mostra una richiesta di accesso, che consente all'utente di accedere a un account IdP corrispondente al suggerimento richiesto dalla RP. Quando l'utente tocca il prompt, si apre una finestra popup con l'URL di accesso specificato nel file di configurazione. Il link viene quindi aggiunto con i parametri di query del suggerimento di accesso e del suggerimento di dominio.

Per maggiori dettagli, guarda la demo.

Parametri personalizzati

La funzionalità Parametri personalizzati consente al RP di fornire parametri chiave-valore aggiuntivi all'endpoint di asserzione dell'ID. Con l'API Parameters, le RP possono trasmettere parametri aggiuntivi al fornitore di identità per richiedere autorizzazioni per risorse oltre all'accesso di base. Il passaggio di parametri aggiuntivi può essere utile in questi scenari:

• Il RP deve richiedere dinamicamente autorizzazioni aggiuntive di cui dispone l'IdP, come l'indirizzo di fatturazione o l'accesso al calendario. L'utente può autorizzare queste autorizzazioni tramite un flusso UX controllato dall'IdP avviato utilizzando la funzionalità Continua su e l'IdP condividerà queste informazioni.

Per utilizzare l'API, il RP aggiunge parametri alla proprietà params come oggetto nella chiamata 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'
        }
      },
    }
  });

Il browser lo traduce automaticamente in una richiesta POST all'IdP con i parametri come un singolo oggetto JSON serializzato con codifica 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.

Se il RP ha bisogno di autorizzazioni aggiuntive, l'IdP può fornire un link di reindirizzamento. Ad esempio, in Node.js:

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

Campi

Il RP può specificare le informazioni utente che vuole che l'IdP condivida con lui. Queste informazioni possono includere qualsiasi combinazione di nome, indirizzo email, nome utente, numero di telefono e immagine del profilo. Le informazioni richieste verranno incluse nell'interfaccia utente di divulgazione della finestra di dialogo FedCM.

Gli utenti che si registrano visualizzeranno un messaggio che li informa che idp.example condividerà le informazioni richieste con rp.example se l'utente sceglie di registrarsi. Se la risposta dell'endpoint account non include un campo richiesto dal RP, il testo dell'informativa non includerà questo campo. Il fornitore di servizi apprenderà tutti i campi richiesti dall'endpoint di asserzione dell'ID e deciderà se raccogliere ulteriori autorizzazioni dell'utente per procedere.

Per utilizzare la funzionalità Campi, RP deve aggiungere un array fields nella chiamata navigator.credentials.get(). I campi possono contenere proprietà come name, email, tel, username o picture. In futuro, questo elenco potrebbe essere ampliato per includere altri valori. Una richiesta con fields avrebbe questo aspetto:

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

Il browser lo traduce automaticamente in una richiesta HTTP all'endpoint di asserzione ID che include il parametro fields specificato dal RP, con i campi che il browser ha comunicato all'utente in un parametro disclosure_shown_for. Per la compatibilità con le versioni precedenti, il browser invierà anche disclosure_text_shown=true se è stato mostrato il testo dell'informativa e i campi richiesti includono tutti e tre i campi: 'name', 'email' e 'picture'. A partire da Chrome 141, il valore di disclosure_text_shown non indica se il testo dell'informativa è stato effettivamente mostrato all'utente.

  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

Se fields è un array vuoto, lo user agent ignorerà l'interfaccia utente di divulgazione.

Questo vale anche se la risposta dell'endpoint accounts non contiene un ID client che corrisponda alla parte richiedente in approved_clients.

In questo caso, il valore disclosure_text_shown inviato all'endpoint di asserzione dell'ID è false nel corpo 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

Mostrare un messaggio di errore

A volte, il provider di identità potrebbe non essere in grado di emettere un token per motivi legittimi, ad esempio quando il client non è autorizzato o il server non è temporaneamente disponibile. Se il fornitore di identità restituisce una risposta "errore", il relying party può rilevarla e Chrome può notificare l'utente mostrando l'interfaccia utente del browser con le informazioni sull'errore fornite dal fornitore di identità.

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

Eseguire nuovamente l'autenticazione degli utenti dopo l'autenticazione iniziale

La riautenticazione automatica FedCM (in breve "riautenticazione automatica") può consentire agli utenti di eseguire nuovamente l'autenticazione automaticamente. Per l'autenticazione automatica dell'utente devono essere soddisfatte le seguenti condizioni:

• L'utente ha già eseguito l'autenticazione iniziale utilizzando FedCM. Per "autenticazione iniziale" si intende la creazione di un account o l'accesso al sito web del RP toccando il pulsante "Continua come…" nella finestra di dialogo di accesso di FedCM per la prima volta nella stessa istanza del browser.
• L'utente ha un solo account di ritorno. Se esistono account di ritorno per più IdP, l'utente non verrà riautenticato automaticamente.

Sebbene l'esperienza utente esplicita abbia senso prima che l'utente abbia creato l'account federato per impedire il monitoraggio (uno degli obiettivi principali di FedCM), è inutilmente macchinosa dopo che l'utente l'ha già sperimentata: dopo che l'utente ha concesso l'autorizzazione per consentire la comunicazione tra il RP e l'IdP, non c'è alcun vantaggio in termini di privacy o sicurezza nell'imporre un'altra conferma esplicita dell'utente per qualcosa che ha già riconosciuto in precedenza.

Con la riautenticazione automatica, il browser cambia il suo comportamento a seconda dell'opzione specificata per mediation quando viene chiamato 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 è una proprietà nell'API Credential Management, si comporta allo stesso modo di PasswordCredential e FederatedCredential ed è parzialmente supportata anche da PublicKeyCredential. La proprietà accetta i seguenti quattro valori:

• 'optional'(impostazione predefinita): riautenticazione automatica, se possibile, altrimenti richiede una mediazione. Ti consigliamo di scegliere questa opzione nella pagina di accesso.
• 'required': richiede sempre una mediazione per procedere, ad esempio facendo clic sul pulsante "Continua" nell'interfaccia utente. Scegli questa opzione se i tuoi utenti devono concedere esplicitamente l'autorizzazione ogni volta che devono essere autenticati.
• 'silent': Eseguire l'autenticazione automatica, se possibile, in caso contrario non riuscire in modo silenzioso senza richiedere una mediazione. Ti consigliamo di scegliere questa opzione nelle pagine diverse dalla pagina di accesso dedicata, ma in cui vuoi mantenere gli utenti connessi, ad esempio una pagina di articoli su un sito web di notizie.
• 'conditional': utilizzato per WebAuthn e al momento non disponibile per FedCM.

Con questa chiamata, la riautenticazione automatica si verifica nelle seguenti condizioni:

• FedCM è disponibile per l'uso. Ad esempio, l'utente non ha disattivato FedCM a livello globale o per il RP nelle impostazioni.
• L'utente ha utilizzato un solo account con l'API FedCM per accedere al sito web su questo browser.
• L'utente ha eseguito l'accesso all'IdP con questo account.
• La riautenticazione automatica non è avvenuta negli ultimi 10 minuti.
• L'RP non ha chiamato navigator.credentials.preventSilentAccess() dopo l'accesso precedente.

Quando queste condizioni vengono soddisfatte, viene avviato un tentativo di riautenticazione automatica dell'utente non appena viene richiamato FedCM navigator.credentials.get().

Quando mediation: optional, la riautenticazione automatica potrebbe non essere disponibile per motivi che solo il browser conosce; la RP può verificare se la riautenticazione automatica viene eseguita esaminando la proprietà isAutoSelected.

Ciò è utile per valutare le prestazioni dell'API e migliorare di conseguenza l'esperienza utente. Inoltre, quando non è disponibile, all'utente potrebbe essere richiesto di accedere con una mediazione esplicita, ovvero un flusso con mediation: required.

Imporre la mediazione con preventSilentAccess()

La riautenticazione automatica degli utenti immediatamente dopo la disconnessione non offrirebbe un'esperienza utente molto positiva. Per questo motivo, FedCM prevede un periodo di inattività di 10 minuti dopo una riautenticazione automatica per impedire questo comportamento. Ciò significa che la riautenticazione automatica avviene al massimo una volta ogni 10 minuti, a meno che l'utente non acceda di nuovo entro 10 minuti. La RP deve chiamare navigator.credentials.preventSilentAccess() per richiedere esplicitamente al browser di disattivare la riautenticazione automatica quando un utente si disconnette dalla RP in modo esplicito, ad esempio facendo clic su un pulsante di disconnessione.

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

Gli utenti possono disattivare la riautenticazione automatica nelle impostazioni.

Gli utenti possono disattivare la riautenticazione automatica dal menu delle impostazioni:

• Nella versione desktop di Chrome, vai a chrome://password-manager/settings > Accedi automaticamente.
• Su Chrome per Android, apri Impostazioni > Gestore delle password > tocca un ingranaggio nell'angolo in alto a destra > Accesso automatico.

Se disattiva il pulsante di attivazione/disattivazione, l'utente può disattivare completamente il comportamento di riautenticazione automatica. Questa impostazione viene memorizzata e sincronizzata su tutti i dispositivi se l'utente ha eseguito l'accesso a un Account Google nell'istanza di Chrome e la sincronizzazione è attivata.

Scollega l'IdP dal RP

Se un utente ha eseguito l'accesso alla parte autorizzata utilizzando l'IdP tramite FedCM, la relazione viene memorizzata localmente dal browser come elenco di account collegati. Il RP può avviare una disconnessione richiamando la funzione IdentityCredential.disconnect(). Questa funzione può essere chiamata da un frame RP di primo livello. Il RP deve trasmettere un configURL, il clientId che utilizza nell'ambito dell'IdP e un accountHint per la disconnessione dell'IdP. Un suggerimento per l'account può essere una stringa arbitraria, purché l'endpoint di disconnessione possa identificare l'account, ad esempio un indirizzo email o un ID utente che non corrisponde necessariamente all'ID account fornito dall'endpoint dell'elenco degli account:

  // 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() restituisce un Promise. Questa promessa potrebbe generare un'eccezione per i seguenti motivi:

• L'utente non ha eseguito l'accesso alla parte autorizzata utilizzando l'IdP tramite FedCM.
• L'API viene richiamata dall'interno di un iframe senza il criterio delle autorizzazioni FedCM.
• L'URL di configurazione non è valido o manca l'endpoint di disconnessione.
• Il controllo CSP (Content Security Policy) non riesce.
• È presente una richiesta di disconnessione in attesa.
• L'utente ha disattivato FedCM nelle impostazioni del browser.

Quando l'endpoint di disconnessione del fornitore di identità restituisce una risposta, la parte che fa affidamento e il fornitore di identità vengono disconnessi sul browser e la promessa viene risolta. Gli ID degli account scollegati sono specificati nella risposta dell'endpoint di disconnessione.

Passaggi successivi

Implementa FedCM lato IdP

Scopri come implementare la tua soluzione di gestione delle identità con FedCM lato provider di identità.

Personalizzazione e disattivazione

Scopri in che modo utenti e sviluppatori possono gestire la partecipazione a FedCM, inclusa l'attivazione o la disattivazione, su piattaforme e siti.