Implementa una soluzione di identità con FedCM lato provider di identità

L'implementazione di FedCM include diversi passaggi di base sia per il provider di identità (IdP) sia per la parte interessata (RP). Consulta la documentazione per scoprire come implementare FedCM lato RP.

Le IdPs devono completare i seguenti passaggi per implementare FedCM:

Creare un file well-known

Per impedire ai tracker di utilizzare in modo improprio l'API, è necessario pubblicare un file well-known 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 tra ambiente di test e 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 identity provider 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 file 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".

Nota: le Etichette account personalizzate sono supportate da Chrome 132.
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 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 per i quali l'utente ha eseguito l'accesso all'IdP. Se l'IDP supporta più account, questo endpoint restituirà tutti gli account con accesso.

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.

Nota: le Etichette account personalizzate sono supportate da Chrome 132.

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 navigator.credentials.get() chiamata, 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 dell'identità provider che prevedono che una stringa 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 gestire la richiesta 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. Cerca una corrispondenza tra account_id e l'ID dell'account con cui hai già 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 ID account, ID cliente, origine emittente e 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. Questo è 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 cambiato 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 per OAuth 2.0 (invalid_request, unauthorized_client, access_denied, server_error e temporarily_unavailable) o utilizzare una stringa arbitraria. In questo caso, Chrome esegue il rendering dell'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 dati 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 ulteriori dettagli. 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'IDP 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 quell'etichetta specifica. Ciò può essere utile quando un RP deve filtrare gli account in base a criteri specifici, ad esempio per visualizzare solo account specifici per ruolo come "developer" o "hr".

È possibile applicare un filtro simile utilizzando le funzionalità Suggerimento per il dominio e Suggerimento per l'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 account personalizzate sono diverse anche perché vengono fornite dal server dell'IDP, anziché dall'RP, come i suggerimenti per l'accesso o il dominio.

Considera un'IDP che vuole distinguere tra gli account "developer" e "hr". Per farlo, l'IdP deve supportare due configURL per "developer" e "hr" rispettivamente:

  • 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 "hr" di accedere, può specificare il valore https://idp.example/hr/fedcm.json configURL 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 (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 viene aperta 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, come 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 sul RP con l'IdP.

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 nella 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 tramite il quale un sito web, in particolare un provider di identità, 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 Set-Login: logged-out intestazione HTTP 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 degli account dell'IdP e aggiorna lo stato in base alla risposta dell'endpoint degli 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 non essere sincronizzato, 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.

Next steps

Implement FedCM for your RPs and distribute the JavaScript SDK. Keep RPs up-to-date by eliminating the need for self-implementation.
Learn how to setup your enviromnemt and debug your implementation.