Implementare una soluzione di identità con FedCM

FedCM (Federated Credential Management) è un approccio che tutela la privacy per i servizi di identità federati (ad esempio "Accedi con…") che consente agli utenti di accedere ai siti senza condividere le proprie informazioni personali con il servizio di identità o con il sito.

L'implementazione di FedCM include diversi passaggi fondamentali sia per l'IdP (Identity Provider) sia per la RP (Relying Party).

Le IdPs devono completare i seguenti passaggi per implementare FedCM:

Per attivare la funzionalità FedCM sul proprio sito, i RP devono completare i seguenti passaggi:

Implementare FedCM come IdP

Scopri di più sulla procedura per implementare FedCM lato IdP.

Creare un file well-known

Per impedire ai tracker di abusare dell'API, un file well-known deve essere fornito da /.well-known/web-identity di eTLD+1 dell'IdP.

Il file noto può includere le seguenti proprietà:

Proprietà Obbligatorio Descrizione
provider_urls di provisioning. Array di percorsi dei file di configurazione dell'IdP. Viene ignorato (ma è comunque obbligatorio) se sono specificati accounts_endpoint e login_url.
accounts_endpoint consigliato, richiede login_url
 URL dell'endpoint degli account. Ciò consente il supporto di più configurazioni, a condizione che ogni file di configurazione utilizzi gli stessi URL login_url e accounts_endpoint.

Nota: il parametro è supportato a partire da Chrome 132.
login_url consigliato, richiede accounts_endpoint L'URL della pagina di accesso per consentire all'utente di accedere all'IdP. Ciò consente il supporto di più configurazioni, a condizione che ogni file di configurazione utilizzi gli stessi login_url e accounts_endpoint.

Nota: il parametro è supportato a partire da Chrome 132 e versioni successive.

Ad esempio, se gli endpoint dell'IdP vengono pubblicati in https://accounts.idp.example/, devono pubblicare un file well-known in https://accounts.idp.example/ e un file di configurazione dell'IdP.https://idp.example/.well-known/web-identity Ecco un esempio di contenuti di file noti:

  {
    "provider_urls": ["https://accounts.idp.example/config.json"]
  }

Gli IdP possono supportare più file di configurazione per un IdP, specificando accounts_endpoint e login_url nel file well-known.
Questa funzionalità può essere utile nei seguenti casi:

  • Un provider di identità deve supportare più configurazioni di test e produzione diverse.
  • Un provider di identità deve supportare configurazioni diverse per regione (ad esempio eu-idp.example e us-idp.example).

Per supportare più configurazioni (ad esempio, per distinguere l'ambiente di test da quello di produzione), l'IdP deve specificare accounts_endpoint e login_url:

  {
    // This property is required, but will be ignored when IdP supports
    // multiple configs (when `accounts_endpoint` and `login_url` are
    // specified), as long as `accounts_endpoint` and `login_url` in
    // that config file match those in the well-known file.
    "provider_urls": [ "https://idp.example/fedcm.json" ],

    // Specify accounts_endpoint and login_url properties to support
    // multiple config files.
    // Note: The accounts_endpoint and login_url must be identical
    // across all config files. Otherwise,
    // the configurations won't be supported.
    "accounts_endpoint": "https://idp.example/accounts",
    "login_url": "https://idp.example/login"
  }

Crea un file di configurazione e gli endpoint dell'identità provider

Il file di configurazione dell'identità provider fornisce un elenco di endpoint richiesti per il browser. Gli IdP devono ospitare uno o più file di configurazione, nonché gli endpoint e gli URL richiesti. Tutte le risposte JSON devono essere pubblicate con il tipo di contenuto application/json.

L'URL del file di configurazione è determinato dai valori forniti alla chiamata navigator.credentials.get() eseguita su un RP.

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

L'RP passerà l'URL del file di configurazione alla chiamata dell'API FedCM per consentire all'utente di accedere:

  // Executed on RP's side:
  const credential = await navigator.credentials.get({
    identity: {
      context: 'signup',
      providers: [{
        // To allow users to sign in with an IdP using FedCM, RP specifies the IdP's config file URL:
        configURL: 'https://accounts.idp.example/fedcm.json',
        clientId: '********',
  });
  const { token } = credential;

Il browser recupererà il file di configurazione con una richiesta GET senza l'intestazione Origin o l'intestazione Referer. La richiesta non contiene cookie e non segue i reindirizzamenti. In questo modo, l'IDP non può sapere chi ha effettuato la richiesta e quale RP sta tentando di connettersi. Ad esempio:

  GET /config.json HTTP/1.1
  Host: accounts.idp.example
  Accept: application/json
  Sec-Fetch-Dest: webidentity

L'IdP deve implementare un endpoint di configurazione che risponda con un JSON. Il JSON include le seguenti proprietà:

Proprietà Descrizione
accounts_endpoint (campo obbligatorio) URL per l'endpoint account.
accounts.include (facoltativo) Stringa dell'etichetta dell'account personalizzata che determina quali account devono essere restituiti quando viene utilizzato questo file di configurazione, ad esempio: "accounts": {"include": "developer"}.
Un provider di identità può implementare l'etichettatura degli account personalizzata nel seguente modo:
  • Crea un file di configurazione associato a etichette specifiche (utilizzando questo parametro accounts.include).
  • Specifica le etichette nell'endpoint account.

Ad esempio, un IdP implementa il file di configurazione "https://idp.example/developer-config.json" con "accounts": {"include": "developer"} specificato. L'SP contrassegna inoltre alcuni account con l'etichetta "developer" utilizzando il parametro labels nell'endpoint account. Quando un RP chiama navigator.credentials.get() con il file di configurazione "https://idp.example/developer-config.json" specificato, vengono restituiti solo gli account con l'etichetta "developer".
client_metadata_endpoint (facoltativo) URL dell'endpoint dei metadati client.
id_assertion_endpoint (campo obbligatorio) URL dell'endpoint di affermazione dell'ID.
disconnect (facoltativo) URL dell'endpoint di disconnessione.
login_url (campo obbligatorio) L'URL della pagina di accesso per consentire all'utente di accedere all'IdP.
branding (facoltativo) Oggetto che contiene varie opzioni di branding.
branding.background_color (facoltativo) Opzione di branding che imposta il colore di sfondo del pulsante "Continua come…". Utilizza la sintassi CSS pertinente, ovvero hex-color, hsl(), rgb() o named-color.
branding.color (facoltativo) Opzione di branding che imposta il colore del testo del pulsante "Continua come…". Utilizza la sintassi CSS pertinente, ovvero hex-color, hsl(), rgb() o named-color.
branding.icons (facoltativo) Array di oggetti icona. Queste icone vengono visualizzate nella finestra di dialogo di accesso. L'oggetto icon ha due parametri:
  • url (obbligatorio): URL dell'immagine dell'icona. Le immagini SVG non sono supportate.
  • size (facoltativo): dimensioni dell'icona, che l'applicazione presume essere quadrate e con una sola risoluzione. Questo numero deve essere maggiore o uguale a 25 pixel in modalità passiva e maggiore o uguale a 40 pixel in modalità attiva.
modes Oggetto che contiene le specifiche su come l'interfaccia utente di FedCM verrà visualizzata in diverse modalità:
  • active
  • passive
modes.active Oggetto contenente proprietà che consentono di personalizzare il comportamento di FedCM in una modalità specifica. Sia modes.active che modes.passive possono contenere il seguente parametro:
  • supports_use_other_account: valore booleano che specifica se l'utente può accedere con un account diverso da quello con cui ha eseguito l'accesso (se l'IDP supporta più account).

Nota: la funzionalità Utilizza un altro account e la modalità attiva sono supportate da Chrome 132.
modes.passive

Ecco un esempio di corpo della risposta dell'identità provider:

  {
    "accounts_endpoint": "/accounts.example",
    "client_metadata_endpoint": "/client_metadata.example",
    "id_assertion_endpoint": "/assertion.example",
    "disconnect_endpoint": "/disconnect.example",
    "login_url": "/login",
    // When RPs use this config file, only those accounts will be
    //returned that include `developer` label in the accounts endpoint.
    "accounts": {"include": "developer"},
    "modes": {
        "active": {
          "supports_use_other_account": true,
        }
    },
    "branding": {
      "background_color": "green",
      "color": "#FFEEAA",
      "icons": [{
        "url": "https://idp.example/icon.ico",
        "size": 25
      }]
    }
  }

Una volta recuperato il file di configurazione, il browser invia le richieste successive agli endpoint della piattaforma di identità:

Endpoint IdP
Endpoint del provider di identità

Utilizza un altro account

Gli utenti possono passare a un account diverso da quello con cui hanno eseguito l'accesso, se l'IDP supporta più account o se sostituisce l'account esistente.

Per consentire all'utente di scegliere altri account, l'IdP deve specificare questa funzionalità nel file di configurazione:

  {
    "accounts_endpoint" : "/accounts.example",
    "modes": {
      "active": {
        // Allow the user to choose other account (false by default)
        "supports_use_other_account": true
      }
      // "passive" mode can be configured separately
    }
  }

Endpoint Account

L'endpoint account dell'IdP restituisce un elenco di account a cui l'utente ha eseguito l'accesso nell'IdP. Se l'IDP supporta più account, questo endpoint restituirà tutti gli account con accesso eseguito.

Il browser invia una richiesta GET con cookie con SameSite=None, ma senza un parametro client_id, l'intestazione Origin o l'intestazione Referer. In questo modo, l'IdP non può sapere a quale RP l'utente sta tentando di accedere. Ad esempio:

  GET /accounts.example HTTP/1.1
  Host: accounts.idp.example
  Accept: application/json
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

Al ricevimento della richiesta, il server deve:

  1. Verifica che la richiesta contenga un'intestazione HTTP Sec-Fetch-Dest: webidentity.
  2. Associa i cookie di sessione agli ID degli account che hanno già eseguito l'accesso.
  3. Rispondi con l'elenco degli account.

Il browser si aspetta una risposta JSON che includa una proprietà accounts con un array di dati dell'account con le seguenti proprietà:

Proprietà Descrizione
id (campo obbligatorio) ID univoco dell'utente.
name (campo obbligatorio) Nome e cognome dell'utente.
email (campo obbligatorio) Indirizzo email dell'utente.
given_name (facoltativo) Nome dell'utente.
picture (facoltativo) URL dell'immagine dell'avatar dell'utente.
approved_clients (facoltativo) Un array di ID cliente RP con cui l'utente si è registrato.
login_hints (facoltativo) Un array di tutti i possibili tipi di filtri supportati dall'IDP per specificare un account. L'RP può richiamare navigator.credentials.get() con la proprietà loginHint per mostrare selettivamente l'account specificato.
domain_hints (facoltativo) Un array di tutti i domini a cui è associato l'account. L'RP può chiamare navigator.credentials.get() con una proprietà domainHint per filtrare gli account.
labels (facoltativo) Array di stringhe di etichette account personalizzate a cui è associato un account.
Un provider di identità può implementare l'etichettatura degli account personalizzata nel seguente modo:
  • Specifica le etichette degli account nell'endpoint account (utilizzando questo parametro labels).
  • Crea un file di configurazione per ogni etichetta specifica.

Ad esempio, un IdP implementa il file di configurazione https://idp.example/developer-config.json con "accounts": {"include": "developer"} specificato. L'SP contrassegna inoltre alcuni account con l'etichetta "developer" utilizzando il parametro labels nell' endpoint account. Quando un RP chiama navigator.credentials.get() con il file di configurazione https://idp.example/developer-config.json specificato, vengono restituiti solo gli account con l'etichetta "developer".

Le etichette account personalizzate sono diverse dall'indizio di accesso e dall'indizio di dominio in quanto sono completamente gestite dal server dell'IDP e l'RP specifica solo il file di configurazione da utilizzare.

Esempio di testo della risposta:

  {
    "accounts": [{
      "id": "1234",
      "given_name": "John",
      "name": "John Doe",
      "email": "john_doe@idp.example",
      "picture": "https://idp.example/profile/123",
      // Ids of those RPs where this account can be used
      "approved_clients": ["123", "456", "789"],
      // This account has 'login_hints`. When an RP calls `navigator.credentials.get()`
      // with a `loginHint` value specified, for example, `exampleHint`, only those
      // accounts will be shown to the user whose 'login_hints' array contains the `exampleHint`.
      "login_hints": ["demo1", "exampleHint"],
      // This account is labelled. IdP can implement a specific config file for a
      // label, for example, `https://idp.example/developer-config.json`. Like that
      // RPs can filter out accounts by calling `navigator.credentials.get()` with
      // `https://idp.example/developer-config.json` config file.
      "labels": ["hr", "developer"]
    }, {
      "id": "5678",
      "given_name": "Johnny",
      "name": "Johnny",
      "email": "johnny@idp.example",
      "picture": "https://idp.example/profile/456",
      "approved_clients": ["abc", "def", "ghi"],
      "login_hints": ["demo2"],
      "domain_hints": ["@domain.example"]
    }]
  }

Se l'utente non ha eseguito l'accesso, rispondi con HTTP 401 (Non autorizzato).

L'elenco di account restituito viene utilizzato dal browser e non sarà disponibile per il RP.

Endpoint asserzione dell'identità

L'endpoint dell'affermazione dell'identità dell'IdP restituisce un'affermazione per l'utente che ha eseguito l'accesso. Quando l'utente accede a un sito web RP utilizzando la chiamata navigator.credentials.get(), il browser invia una richiesta POST con cookie con SameSite=None e un tipo di contenuto application/x-www-form-urlencoded a questo endpoint con le seguenti informazioni:

Proprietà Descrizione
client_id (campo obbligatorio) L'identificatore client dell'RP.
account_id (campo obbligatorio) L'ID univoco dell'utente che accede.
disclosure_text_shown Restituisce una stringa di "true" o "false" (anziché un valore booleano). Il risultato è "false" nei seguenti casi:
  • Se il testo dell'informativa non è stato mostrato perché l'ID cliente dell'RP è stato incluso nell'elenco delle proprietà approved_clients della risposta dell'endpoint account.
  • Se il testo dell'informativa non è stato mostrato perché il browser ha rilevato un momento di registrazione in passato in assenza di approved_clients.
  • Se il parametro fields non include uno o più dei tre campi ("name", "email" e "picture"), ad esempio fields=[ ] o fields=['name', 'picture']. Questo è necessario per la compatibilità con le implementazioni precedenti delle IdP che prevedono che una stringa di informativa includa sempre tutti e tre i campi.
is_auto_selected Se sull'RP viene eseguita la ri-autenticazione automatica, is_auto_selected indica "true". In caso contrario, "false". Questo è utile per supportare più funzionalità correlate alla sicurezza. Ad esempio, alcuni utenti potrebbero preferire un livello di sicurezza più elevato che richiede la mediazione esplicita dell'utente nell'autenticazione. Se un'IDP riceve una richiesta di token senza questa mediazione, potrebbe gestirla in modo diverso. Ad esempio, restituisci un codice di errore in modo che l'RP possa chiamare di nuovo l'API FedCM con mediation: required.
fields (facoltativo) Array di stringhe che specifica le informazioni dell'utente ("name", "email", "picture") che l'RP deve condividere con l'IdP.
Il browser invierà fields, disclosure_text_shown e disclosure_shown_for elencando i campi specificati nella richiesta POST, come nell'esempio seguente.

Nota: il parametro Fields è supportato da Chrome 132.
params (facoltativo) Qualsiasi oggetto JSON valido che consenta di specificare parametri chiave-valore personalizzati aggiuntivi, ad esempio:
  • scope: un valore di stringa contenente le autorizzazioni aggiuntive che l'RP deve richiedere, ad esempio "drive.readonly calendar.readonly"
  • nonce: una stringa casuale fornita dall'RP per garantire che la risposta venga emessa per questa richiesta specifica. Impedisce gli attacchi di replay.
  • Altri parametri coppia chiave-valore personalizzati.
Quando il browser invia una richiesta POST, il valore params viene serializzato in JSON e poi codificato in percentuale.

Nota: l'API Parameters è supportata da Chrome 132 e versioni successive.

Intestazione HTTP di esempio: 

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

  // disclosure_text_shown is set to 'false', as the 'name' field value is missing in 'fields' array
  // params value is serialized to JSON and then percent-encoded.
  account_id=123&client_id=client1234&disclosure_text_shown=false&is_auto_selected=true&params=%22%7B%5C%22nonce%5C%22%3A%5C%22nonce-value%5C%22%7D%22.%0D%0A4&disclosure_text_shown=true&fields=email,picture&disclosure_shown_for=email,picture

Al ricevimento della richiesta, il server deve:

  1. Rispondere alla richiesta con CORS (Cross-Origin Resource Sharing).
  2. Verifica che la richiesta contenga un'intestazione HTTP Sec-Fetch-Dest: webidentity.
  3. Abbina l'intestazione Origin all'origine RP determinata da client_id. Rifiuta se non corrispondono.
  4. Corrispondenza di account_id con l'ID dell'account con cui è già stato eseguito l'accesso. Rifiuta se non corrispondono.
  5. Rispondi con un token. Se la richiesta viene rifiutata, rispondi con una risposta di errore.

L'IdP può decidere come emettere il token. In genere, è firmato con informazioni come l'ID account, l'ID client, l'origine dell'emittente e il nonce, in modo che l'RP possa verificare l'autenticità del token.

Il browser si aspetta una risposta JSON che includa la seguente proprietà:

Proprietà Descrizione
token Un token è una stringa contenente rivendicazioni sull'autenticazione.
continue_on URL di reindirizzamento che abilita un flusso di accesso a più passaggi.

Il token restituito viene passato all'RP dal browser, in modo che l'RP possa convalidare l'autenticazione.

  {
    // IdP can respond with a token to authenticate the user
    "token": "***********"
  }
Continuare con la funzionalità

L'IdP può fornire un URL di reindirizzamento nella risposta dell'endpoint di affermazione dell'identità per attivare un flusso di accesso in più passaggi. Questa opzione è utile quando l'IDP deve richiedere informazioni o autorizzazioni aggiuntive, ad esempio:

  • Autorizzazione per accedere alle risorse lato server dell'utente.
  • Verifica che i dati di contatto siano aggiornati.
  • Controllo genitori.

L'endpoint di affermazione dell'identità può restituire una proprietà continue_on che include un percorso assoluto o relativo all'endpoint di affermazione dell'identità.

  {
    // In the id_assertion_endpoint, instead of returning a typical
    // "token" response, the IdP decides that it needs the user to
    // continue on a popup window:
    "continue_on": "https://idp.example/continue_on_url"
  }

Se la risposta contiene il parametro continue_on, viene aperta una nuova finestra popup che indirizza l'utente al percorso specificato. Dopo l'interazione dell'utente con la pagina continue_on, l'IDP deve chiamare IdentityProvider.resolve() con il token passato come argomento in modo che la promessa della chiamata navigator.credentials.get() originale possa essere risolta:

  document.getElementById('example-button').addEventListener('click', async () => {
    let accessToken = await fetch('/generate_access_token.cgi');
    // Closes the window and resolves the promise (that is still hanging
    // in the relying party's renderer) with the value that is passed.
    IdentityProvider.resolve(accessToken);
  });

Il browser chiuderà automaticamente il popup e restituirà il token all'autore della chiamata dell'API. Una chiamata IdentityProvider.resolve() una tantum è l'unico modo per consentire alla finestra principale (RP) e alla finestra popup (IdP) di comunicare.
Se l'utente rifiuta la richiesta, l'IdP può chiudere la finestra chiamando IdentityProvider.close().

  IdentityProvider.close();

L'API Continuation richiede un'interazione esplicita dell'utente (clic) per funzionare. Ecco come funziona l'API Continuation con diverse modalità di mediazione:

  • In modalità passiva:
    • mediation: 'optional' (valore predefinito): l'API Continuation funzionerà solo con un gesto dell'utente, ad esempio facendo clic su un pulsante nella pagina o nell'interfaccia utente di FedCM. Quando l'autenticazione automatica viene attivata senza un gesto dell'utente, non viene aperta alcuna finestra popup e la promessa viene rifiutata.
    • mediation: 'required': chiede sempre all'utente di interagire, quindi l'API Continuation funziona sempre.
  • In modalità attiva:
    • L'attivazione dell'utente è sempre obbligatoria. L'API Continuation è compatibile.

Se per qualche motivo l'utente ha modificato il proprio account nel popup (ad esempio, l'IDP offre una funzione "Usa un altro account" o in caso di delega), la chiamata resolve accetta un secondo argomento facoltativo che consente qualcosa di simile a:

  IdentityProvider.resolve(token, {accountId: '1234');
Restituire una risposta di errore

id_assertion_endpoint può anche restituire una risposta "error", che ha due campi facoltativi:

  • code: l'IdP può scegliere uno degli errori noti dall'elenco di errori specificati di OAuth 2.0 (invalid_request, unauthorized_client, access_denied, server_error e temporarily_unavailable) o utilizzare una stringa arbitraria. In questo caso, Chrome visualizza l'interfaccia utente di errore con un messaggio di errore generico e passa il codice all'RP.
  • url: identifica una pagina web leggibile da un utente con informazioni sull'errore per fornire agli utenti informazioni aggiuntive sull'errore. Questo campo è utile per gli utenti perché i browser non possono fornire messaggi di errore dettagliati in un'interfaccia utente integrata. Ad esempio, link per i passaggi successivi o informazioni di contatto dell'assistenza clienti. Se un utente vuole saperne di più sui dettagli dell'errore e su come correggerlo, può visitare la pagina fornita dall'interfaccia utente del browser per approfondire. L'URL deve essere dello stesso sito dell'IdP configURL.
  // id_assertion_endpoint response
  {
    "error" : {
      "code": "access_denied",
      "url" : "https://idp.example/error?type=access_denied"
    }
  }

Etichette account personalizzate

Con le Etichette account personalizzate, l'SP può annotare gli account utente con le etichette e l'RP può scegliere di recuperare solo gli account con etichette specifiche specificando il configURL per l'etichetta specifica. Ciò può essere utile quando un RP deve filtrare gli account in base a criteri specifici, ad esempio per visualizzare solo gli account specifici per ruolo come "developer" o "hr".

È possibile applicare un filtro simile utilizzando le funzionalità Suggerimento dominio e Suggerimento di accesso, specificandole nella chiamata navigator.credentials.get(). Tuttavia, le etichette account personalizzate possono filtrare gli utenti specificando il file di configurazione, il che è particolarmente utile quando vengono utilizzati più configURL. Le etichette degli account personalizzate sono diverse anche perché vengono fornite dal server dell'IDP, anziché dall'RP, come le indicazioni per l'accesso o il dominio.

Prendiamo in considerazione un'IDP che vuole distinguere gli account "developer" da quelli "hr". Per farlo, l'IdP deve supportare due configURL rispettivamente per "developer" e "hr":

  • Il file di configurazione dello sviluppatore https://idp.example/developer/fedcm.json ha un'etichetta "developer" e il file di configurazione aziendale https://idp.example/hr/fedcm.json ha un'etichetta "hr" come segue:
  // The developer config file at `https://idp.example/developer/fedcm.json`
  {
    "accounts_endpoint": "https://idp.example/accounts",
    "client_metadata_endpoint": "/client_metadata",
    "login_url": "https://idp.example/login",
    "id_assertion_endpoint": "/assertion",
    "accounts": {
      // Account label
      "include": "developer"
    }
  }

  // The hr config file at `https://idp.example/hr/fedcm.json`
  {
    "accounts_endpoint": "https://idp.example/accounts",
    "client_metadata_endpoint": "/client_metadata",
    "login_url": "https://idp.example/login",
    "id_assertion_endpoint": "/assertion",
    "accounts": {
      // Account label
      "include": "hr"
    }
  }
  • Con questa configurazione, il file well-known deve includere accounts_endpoint e login_url per consentire più configURL:
  {
    "provider_urls": [ "https://idp.example/fedcm.json" ],
    "accounts_endpoint": "https://idp.example/accounts",
    "login_url": "https://idp.example/login"
  }
  • L'endpoint account delle IdP comuni (in questo esempio https://idp.example/accounts) restituisce un elenco di account che include una proprietà labels con le etichette assegnate in un array per ogni account:
  {
  "accounts": [{
    "id": "123",
    "given_name": "John",
    "name": "John Doe",
    "email": "john_doe@idp.example",
    "picture": "https://idp.example/profile/123",
    "labels": ["developer"]
    }], [{
    "id": "4567",
    "given_name": "Jane",
    "name": "Jane Doe",
    "email": "jane_doe@idp.example",
    "picture": "https://idp.example/profile/4567",
    "labels": ["hr"]
    }]
  }

Quando un RP vuole consentire agli utenti di "hr" di accedere, può specificare il valore configURL https://idp.example/hr/fedcm.json nella chiamata navigator.credentials.get():

  let { token } = await navigator.credentials.get({
    identity: {
      providers: [{
        clientId: '1234',
        nonce: '234234',
        configURL: 'https://idp.example/hr/fedcm.json',
      },
    }
  });

Di conseguenza, l'utente può accedere solo con l'ID account 4567. L'ID account 123 viene nascosto silenziosamente dal browser in modo che all'utente non venga fornito un account non supportato dall'IDP su questo sito.

  • Le etichette sono stringhe. Se l'array labels o il campo include contiene un elemento diverso da una stringa, viene ignorato.
  • Se non vengono specificate etichette in configURL, tutti gli account verranno visualizzati nel selettore di account FedCM.
  • Se non vengono specificate etichette per un account, questo verrà visualizzato nel selettore di account solo se anche configURL non specifica un'etichetta.
  • Se nessun account corrisponde all'etichetta richiesta in modalità passiva (in modo simile alla funzionalità Suggerimento dominio), la finestra di dialogo FedCM mostra una richiesta di accesso che consente all'utente di accedere a un account IdP. Per la modalità attiva, la finestra popup di accesso si apre direttamente.

Disconnetti endpoint

Se viene invocato IdentityCredential.disconnect(), il browser invia una richiesta POST cross-origin con cookie con SameSite=None e un tipo di contenuto application/x-www-form-urlencoded a questo endpoint di disconnessione con le seguenti informazioni:

Proprietà Descrizione
account_hint Un suggerimento per l'account IdP.
client_id L'identificatore client dell'RP. 
  POST /disconnect.example HTTP/1.1
  Host: idp.example
  Origin: rp.example
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x123
  Sec-Fetch-Dest: webidentity

  account_hint=account456&client_id=rp123

Al ricevimento della richiesta, il server deve:

  1. Rispondere alla richiesta con CORS (Cross-Origin Resource Sharing).
  2. Verifica che la richiesta contenga un'intestazione HTTP Sec-Fetch-Dest: webidentity.
  3. Abbina l'intestazione Origin all'origine RP determinata da client_id. Rifiuta se non corrispondono.
  4. Abbina account_hint agli ID degli account che hanno già eseguito l'accesso.
  5. Scollega l'account utente dall'RP.
  6. Rispondere al browser con i dati dell'account utente identificato in formato JSON.

Un esempio di payload JSON di risposta è il seguente:

  {
    "account_id": "account456"
  }

Se invece l'IdP vuole che il browser scolleghi tutti gli account associati all'RP, deve passare una stringa che non corrisponda a nessun ID account, ad esempio "*".

Endpoint dei metadati client

L'endpoint dei metadati client dell'IdP restituisce i metadati della terza parte attendibile, ad esempio le norme sulla privacy, i Termini di servizio e le icone del logo della terza parte attendibile. Gli RP devono fornire in anticipo all'IdP i link alle proprie norme sulla privacy e ai propri Termini di servizio. Questi link vengono visualizzati nella finestra di dialogo di accesso quando l'utente non ha ancora eseguito la registrazione nell'RP con il provider di identità.

Il browser invia una richiesta GET utilizzando client_id navigator.credentials.get senza cookie. Ad esempio:

  GET /client_metadata.example?client_id=1234 HTTP/1.1
  Host: accounts.idp.example
  Origin: https://rp.example/
  Accept: application/json
  Sec-Fetch-Dest: webidentity

Al ricevimento della richiesta, il server deve:

  1. Determina l'RP per il client_id.
  2. Rispondi con i metadati del client.

Le proprietà per l'endpoint dei metadati client includono:

Proprietà Descrizione
privacy_policy_url (facoltativo) URL delle norme sulla privacy del RP.
terms_of_service_url (facoltativo) URL dei Termini di servizio del RP.
icons (facoltativo) Array di oggetti, ad esempio [{ "url": "https://rp.example/rp-icon.ico", "size": 40}]

Il browser si aspetta una risposta JSON dall'endpoint:

  {
    "privacy_policy_url": "https://rp.example/privacy_policy.html",
    "terms_of_service_url": "https://rp.example/terms_of_service.html",
    "icons": [{
          "url": "https://rp.example/rp-icon.ico",
          "size": 40
      }]
  }

I metadati del client restituiti vengono utilizzati dal browser e non saranno disponibili per l'RP.

URL di accesso

Questo endpoint viene utilizzato per consentire all'utente di accedere all'IdP.

Con l'API Login Status, l'IDP deve comunicare al browser lo stato di accesso dell'utente. Tuttavia, lo stato potrebbe non essere sincronizzato, ad esempio quando la sessione scade. In questo scenario, il browser può consentire all'utente di accedere in modo dinamico all'IdP tramite l'URL della pagina di accesso specificato con login_url del file di configurazione dell'IdP.

La finestra di dialogo FedCM mostra un messaggio che suggerisce di accedere, come mostrato nell'immagine seguente.

A
Una finestra di dialogo FedCM che suggerisce di accedere all'IdP.

Quando l'utente fa clic sul pulsante Continua, il browser apre una finestra popup per la pagina di accesso dell'IDP.

Un esempio di finestra di dialogo FedCM.
Un esempio di finestra di dialogo visualizzata dopo aver fatto clic sul pulsante Accedi all'IDP.

La finestra di dialogo è una normale finestra del browser con cookie proprietari. Tutto ciò che accade all'interno della finestra di dialogo dipende dall'IDP e non sono disponibili handle finestra per effettuare una richiesta di comunicazione cross-origin alla pagina RP. Dopo che l'utente ha eseguito l'accesso, l'IdP deve:

  • Invia l'intestazione Set-Login: logged-in o chiama l'API navigator.login.setStatus("logged-in") per informare il browser che l'utente ha eseguito l'accesso.
  • Chiama IdentityProvider.close() per chiudere la finestra di dialogo.
Un utente accede a un RP dopo aver eseguito l'accesso all'IdP utilizzando FedCM.

Informare il browser sullo stato di accesso dell'utente

L'API Login Status è un meccanismo in cui un sito web, in particolare un IdP, comunica al browser lo stato di accesso dell'utente sull'IdP. Con questa API, il browser può ridurre le richieste non necessarie all'IDP e attenuare potenziali attacchi di temporizzazione.

Gli IdP possono segnalare lo stato di accesso dell'utente al browser inviando un'intestazione HTTP o chiamando un'API JavaScript quando l'utente ha eseguito l'accesso all'IdP o quando ha eseguito la disconnessione da tutti i suoi account IdP. Per ogni IdP (identificato dall'URL di configurazione), il browser mantiene una variabile tri-stato che rappresenta lo stato di accesso con i seguenti possibili valori:

  • logged-in
  • logged-out
  • unknown (valore predefinito)
Stato di accesso Descrizione
logged-in Quando lo stato di accesso dell'utente è impostato su logged-in, l'RP che chiama FedCM invia richieste all'endpoint degli account dell'IDP e mostra all'utente gli account disponibili nella finestra di dialogo FedCM.
logged-out Quando lo stato di accesso dell'utente è logged-out, la chiamata a FedCM non va a buon fine e non viene effettuata alcuna richiesta all'endpoint degli account dell'IDP.
unknown (valore predefinito) Lo stato unknown viene impostato prima che l'IDP invii un segnale utilizzando l'API Login Status. Quando lo stato è unknown, il browser invia una richiesta all'endpoint degli account dell'IDP e aggiorna lo stato in base alla risposta dell'endpoint degli account.

Per indicare che l'utente ha eseguito l'accesso, invia un'intestazione HTTP Set-Login: logged-in in una navigazione di primo livello o una richiesta di risorsa secondaria nello stesso sito all'origine dell'IDP:

  Set-Login: logged-in

In alternativa, chiama il metodo JavaScript navigator.login.setStatus('logged-in') dall'origine dell'IDP in una navigazione di primo livello:

  navigator.login.setStatus('logged-in')

Lo stato di accesso dell'utente verrà impostato su logged-in.

Per segnalare che l'utente ha eseguito la disconnessione da tutti i suoi account, invia un'intestazione HTTP Set-Login: logged-out in una navigazione di primo livello o una richiesta di risorsa secondaria nello stesso sito all'origine dell'IDP:

  Set-Login: logged-out

In alternativa, chiama l'API JavaScript navigator.login.setStatus('logged-out') dall'origine dell'IDP in una navigazione di primo livello:

  navigator.login.setStatus('logged-out')

Lo stato di accesso dell'utente verrà impostato su logged-out.

Lo stato unknown viene impostato prima che l'IDP invii un segnale utilizzando l'API Login Status. Il browser invia una richiesta all'endpoint account dell'IdP e aggiorna lo stato in base alla risposta dell'endpoint account:

  • Se l'endpoint restituisce un elenco di account attivi, aggiorna lo stato su logged-in e apri la finestra di dialogo FedCM per visualizzare gli account.
  • Se l'endpoint non restituisce account, aggiorna lo stato su logged-out e interrompi la chiamata FedCM.

Consentire all'utente di accedere tramite un flusso di accesso dinamico

Anche se l'IdP continua a informare il browser dello stato di accesso dell'utente, potrebbe essere fuori sincronia, ad esempio quando la sessione scade. Il browser tenta di inviare una richiesta con credenziali all'endpoint degli account quando lo stato di accesso è logged-in, ma il server non restituisce account perché la sessione non è più disponibile. In questo caso, il browser può consentire all'utente di accedere dinamicamente all'IdP tramite una finestra popup.

Implementa FedCM come RP

Una volta che la configurazione e gli endpoint dell'IdP sono disponibili, gli RP possono chiamare navigator.credentials.get() per richiedere di consentire agli utenti di accedere all'RP con l'IdP.

Prima di chiamare l'API, devi verificare che FedCM sia disponibile nel browser dell'utente. Per verificare se FedCM è disponibile, inserisci questo codice nell'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 agli utenti di accedere all'IdP su un RP utilizzando FedCM, l'RP può chiamare navigator.credentials.get(), ad esempio:

  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;

Proprietà di contesto

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

  • signin (valore predefinito)
  • signup
  • use
Diagramma che spiega i componenti dell'interfaccia utente della finestra di dialogo FedCM: in alto a sinistra viene visualizzata un'icona. A destra dell'icona è presente un componente di contesto che mostra il messaggio "Accedi all'RP con l'IdP". In basso è presente un pulsante "Continua" con testo e colore di sfondo personalizzati.
Come viene applicato il branding alla finestra di dialogo FedCM

Ad esempio, l'impostazione di context su use comporterà il seguente messaggio:

Una finestra di dialogo FedCM che mostra un messaggio contestuale personalizzato: anziché "Accedi" con FedCM, il messaggio contestuale indica "Utilizza" FedCM.
Finestra di dialogo FedCM che mostra un messaggio contestuale personalizzato.

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 di account. Il browser non mostrerà il testo dell'informativa "Per continuare con ...." se l'utente ha già effettuato la registrazione al RP.
La proprietà providers accetta un array di oggetti IdentityProvider con le seguenti proprietà:

Proprietà Providers

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

Proprietà Descrizione
configURL (campo obbligatorio) Un percorso completo del file di configurazione dell'IdP.
clientId (campo obbligatorio) L'identificatore client dell'RP, emesso dall'IdP.
nonce (facoltativo) Una stringa casuale per garantire che la risposta venga emessa per questa richiesta specifica. Impedisce gli attacchi di replay.
loginHint (facoltativo) Se specifichi uno dei valori login_hints forniti dagli endpoint degli account, la finestra di dialogo FedCM mostra in modo selettivo l'account specificato.
domainHint (facoltativo) Se specifichi uno dei valori domain_hints forniti dagli endpoint degli account, la finestra di dialogo FedCM mostra in modo selettivo l'account specificato.
mode (facoltativo) Stringa che specifica la modalità dell'interfaccia utente di FedCM. Può essere uno dei seguenti valori:
  • "active": la richiesta di FedCM deve essere avviata dall'interazione dell'utente (ad esempio facendo clic su un pulsante).
  • "passive": il prompt di FedCM verrà avviato senza interazione diretta dell'utente.
Per scoprire di più sulla differenza tra le modalità attive e passive, consulta la pagina di panoramica.

Nota: il parametro mode è supportato da Chrome 132.
fields (facoltativo) Array di stringhe che specifica le informazioni dell'utente ("name", "email", "picture") che l'RP deve condividere con l'IdP.
Nota: l'API Field è supportata da Chrome 132 e versioni successive.
parameters (facoltativo) Oggetto personalizzato che consente di specificare parametri chiave-valore aggiuntivi:
  • scope: un valore di stringa contenente le autorizzazioni aggiuntive che l'RP deve richiedere, ad esempio "drive.readonly calendar.readonly"
  • nonce: una stringa casuale per garantire che la risposta venga emessa per questa richiesta specifica. Impedisce gli attacchi di replay.
  • Altri parametri coppia chiave-valore personalizzati.

Nota: parameters è supportato da Chrome 132.

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

Icona personalizzata in modalità attiva

La modalità attiva consente alle IdP di includere l'icona del logo ufficiale dell'RP direttamente nella risposta dell'endpoint dei metadati del client. L'RP deve fornire i dati di branding in anticipo.

Chiamare FedCM da un iframe cross-origin

FedCM può essere invocato da un iframe cross-origin utilizzando un criterio di autorizzazione identity-credentials-get, se il frame principale lo consente. Per farlo, accoda l'attributo allow="identity-credentials-get" al tag iframe come segue:

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

Puoi vederlo in azione in un esempio.

Se il frame principale vuole limitare le origini che possono chiamare FedCM, può inviare un'intestazione Permissions-Policy con un elenco di origini consentite.

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

Per scoprire di più sul funzionamento delle norme relative alle autorizzazioni, consulta Controllare le funzionalità del browser con le norme relative alle autorizzazioni.

API Login Hint

Utilizzando l'Indicativo di accesso, l'RP può consigliare con quale account un utente deve accedere. Questa opzione può essere utile per autenticare nuovamente gli utenti che non sanno con certezza quale account hanno utilizzato in precedenza.

Gli RP possono mostrare selettivamente un account specifico chiamando navigator.credentials.get() con la proprietà loginHint con uno dei valori login_hints recuperati dall'endpoint dell'elenco di 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 dall'RP. Quando l'utente tocca la richiesta, si apre una finestra popup con l'URL di accesso specificato nel file di configurazione. Al link vengono poi aggiunti i parametri di query dell'indicazione di accesso e dell'indicazione del dominio.

API Domain Hint

Gli RP possono mostrare in modo selettivo solo gli account associati a un determinato dominio. Questa funzionalità può essere utile per le RP limitate a un dominio aziendale.

Per visualizzare solo account di dominio specifici, l'RP deve chiamare navigator.credentials.get() con la proprietà domainHint con uno dei valori domain_hints recuperati dall'endpoint dell'elenco di 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 dall'RP. Quando l'utente tocca la richiesta, si apre una finestra popup con l'URL di accesso specificato nel file di configurazione. Al link vengono poi aggiunti i parametri di query dell'indizio di accesso e dell'indizio di dominio.

Un esempio di richiesta di accesso quando nessun account corrisponde a domainHint.
Un esempio di richiesta di accesso quando non sono presenti account corrispondenti a domainHint.

Parametri personalizzati

La funzionalità Parametri personalizzati consente all'RP di fornire parametri chiave-valore aggiuntivi all'endpoint di affermazione dell'ID. Con l'API Parameters, gli RP possono passare parametri aggiuntivi all'IDP per richiedere autorizzazioni per le risorse oltre all'accesso di base. La trasmissione di parametri aggiuntivi può essere utile in questi scenari:

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

Per utilizzare l'API, l'RP aggiunge i 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 tradurrà 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 l'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

L'RP può specificare le informazioni utente (qualsiasi combinazione di nome, indirizzo email e immagine del profilo) che l'IdP deve condividere con l'RP. Le informazioni richieste verranno incluse nell'interfaccia utente della nota informativa della finestra di dialogo FedCM. Se l'utente sceglie di accedere, visualizzerà un messaggio che lo informa che idp.example condividerà le informazioni richieste con rp.example.

Una finestra di dialogo della modalità attiva di FedCM che mostra un messaggio di informativa. Per continuare, l&#39;identity provider condividerà l&#39;indirizzo email e l&#39;immagine del profilo dell&#39;utente con il sito web.
Messaggio di informativa in modalità attiva: l'RP richiede all'IdP di condividere solo l'email e l'immagine del profilo dell'utente.

Per utilizzare la funzionalità Campi, l'RP deve aggiungere un array fields nella chiamata navigator.credentials.get(). I campi possono contenere qualsiasi permutazione di name, email e picture. In futuro, questo valore potrà essere esteso per includere altri valori. Una richiesta con fields avrà il seguente aspetto:

  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',

      },
    }
  });

Il browser lo tradurrà automaticamente in una richiesta HTTP all'endpoint di affermazione dell'ID che include il parametro fields specificato dall'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 il testo dell'informativa è stato mostrato e i campi richiesti includono tutti e tre i campi: 'name', 'email' e '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

Se fields è un array vuoto, lo user agent salta l'interfaccia utente dell'informativa.

Una finestra di dialogo in modalità passiva FedCM che non mostra un messaggio dell&#39;interfaccia utente relativo alle informative.
Il messaggio dell'informativa non viene visualizzato in modalità passiva. Nel flusso dei pulsanti, l'UI dell'informativa viene saltata completamente.

Questo accade anche se la risposta dell'endpoint accounts non contiene un ID cliente corrispondente all'RP in approved_clients.

In questo caso, disclosure_text_shown inviato all'endpoint di affermazione dell'ID è falso 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 l'IDP 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 l'IdP restituisce una risposta "error", l'RP può rilevarla e Chrome può avvisare l'utente mostrando l'interfaccia utente del browser con le informazioni di errore fornite dall'IDP.

A
Una finestra di dialogo FedCM che mostra il messaggio di errore dopo il fallimento del tentativo di accesso dell'utente. La stringa è associata al tipo di errore.
  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;
  }

Riautenticare automaticamente gli utenti dopo l'autenticazione iniziale

L'autenticazione automatica di FedCM (in breve "auto-autenticazione") consente agli utenti di autenticarsi automaticamente quando rientrano dopo l'autenticazione iniziale utilizzando FedCM. Per "autenticazione iniziale" si intende che l'utente crea un account o accede 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.

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 complicata dopo che l'utente l'ha completata una volta: dopo che l'utente ha concesso l'autorizzazione per consentire la comunicazione tra l'RP e l'IdP, non c'è alcun vantaggio in termini di privacy o sicurezza nell'applicazione di un'altra conferma esplicita dell'utente per qualcosa che ha già accettato in precedenza.

Con l'autenticazione automatica, il browser cambia il proprio comportamento in base all'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 è supportato parzialmente anche da PublicKeyCredential. La proprietà accetta i seguenti quattro valori:

  • 'optional'(valore predefinito): autenticazione automatica, se possibile, altrimenti richiede una mediazione. Ti consigliamo di scegliere questa opzione nella pagina di accesso.
  • 'required': per procedere è sempre necessaria una mediazione, ad esempio fare clic sul pulsante "Continua" nell'interfaccia utente. Scegli questa opzione se ti aspetti che gli utenti concedano l'autorizzazione esplicitamente ogni volta che devono essere autenticati.
  • 'silent': se possibile, esegui la riconferma automatica. In caso contrario, fallisci in silenzio senza richiedere 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 la pagina di un articolo su un sito web di notizie o la pagina di un articolo su un sito web di notizie.
  • 'conditional': utilizzato per WebAuthn e non disponibile per FedCM al momento.

Con questa chiamata, la reautorizzazione automatica avviene alle seguenti condizioni:

  • FedCM è disponibile per l'utilizzo. Ad esempio, l'utente non ha disattivato FedCM a livello globale o per l'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 quell'account.
  • La riconferma automatica non è avvenuta negli ultimi 10 minuti.
  • L'RP non ha chiamato navigator.credentials.preventSilentAccess() dopo l'accesso precedente.

Quando queste condizioni sono soddisfatte, viene avviato un tentativo di autenticazione automatica dell'utente non appena viene invocato il navigator.credentials.get() FedCM.

Quando mediation: optional, la disattivazione automatica dell'autenticazione potrebbe non essere disponibile per motivi noti solo al browser. L'RP può verificare se la disattivazione automatica dell'autenticazione viene eseguita esaminando la proprietà isAutoSelected.

Questo è utile per valutare il rendimento dell'API e migliorare di conseguenza l'esperienza utente. Inoltre, quando non è disponibile, all'utente potrebbe essere chiesto di accedere con la mediazione esplicita dell'utente, che è un flusso con mediation: required.

Un utente che esegue l'autenticazione automatica tramite FedCM.

Applicare la mediazione con preventSilentAccess()

La riconferma automatica degli utenti subito dopo la disconnessione non costituirebbe un'esperienza utente molto positiva. Ecco perché FedCM ha un periodo di attesa di 10 minuti dopo una riconferma automatica per impedire questo comportamento. Ciò significa che la riconferma dell'autenticazione avviene al massimo una volta ogni 10 minuti, a meno che l'utente non acceda nuovamente entro 10 minuti. L'RP deve chiamare navigator.credentials.preventSilentAccess() per richiedere esplicitamente al browser di disattivare la riconferma automatica quando un utente si disconnette esplicitamente dall'RP, ad esempio facendo clic su un pulsante di disconnessione.

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

Gli utenti possono disattivare la riconferma automatica nelle impostazioni

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

  • Su Chrome per computer, 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 l'opzione, l'utente può disattivare del tutto il comportamento di autorizzazione automatica. Questa impostazione viene archiviata e sincronizzata su più dispositivi se l'utente ha eseguito l'accesso a un Account Google nell'istanza di Chrome e la sincronizzazione è attivata.

Scollegare l'IdP dall'RP

Se un utente ha già eseguito l'accesso all'RP utilizzando l'IdP tramite FedCM, la relazione viene memorizzata localmente dal browser come elenco degli account collegati. L'RP può avviare una disconnessione chiamando la funzione IdentityCredential.disconnect(). Questa funzione può essere chiamata da un frame RP di primo livello. L'RP deve passare un configURL, il clientId che utilizza sotto l'IdP e un accountHint per scollegare l'IdP. Un indicazione dell'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 di 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 all'RP utilizzando l'IdP tramite FedCM.
  • L'API viene invocata da un iframe senza il criterio di autorizzazione FedCM.
  • L'URL di configurazione non è valido o manca l'endpoint di disconnessione.
  • Il controllo dei Criteri di sicurezza del contenuto (CSP) non va a buon fine.
  • È presente una richiesta di disconnessione in attesa.
  • L'utente ha disattivato FedCM nelle impostazioni del browser.

Quando l'endpoint di disconnessione dell'IdP restituisce una risposta, l'RP e l'IdP vengono disconnessi nel browser e la promessa viene risolta. L'ID degli account scollegati è specificato nella risposta dell'endpoint di disconnessione.