L'implementazione di FedCM include diversi passaggi di base sia per il provider di identità (IdP) sia per la parte autorizzata (RP). Consulta la documentazione per scoprire come implementare FedCM sul lato del RP.
I IdPs devono completare i seguenti passaggi per implementare FedCM:
- Crea un file well-known.
- Crea un file di configurazione.
- Crea i seguenti endpoint:
- Endpoint dell'account
- Endpoint di asserzione dell'ID
- [facoltativo] Disconnetti endpoint
- [facoltativo] Endpoint dei metadati client
- Endpoint di accesso
- Informa il browser sullo stato di accesso dell'utente.
Crea un file well-known
Per impedire ai tracker di utilizzare l'API in modo improprio,
un file well-known deve essere pubblicato 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 IdP. 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 lo stesso 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 in cui l'utente deve accedere all'IdP. Ciò consente il supporto di più configurazioni, a condizione che ogni file di configurazione utilizzi lo stesso login_url e accounts_endpoint .Nota: il parametro è supportato a partire da Chrome 132 e versioni successive. |
Ad esempio, se gli endpoint IdP vengono pubblicati in https://accounts.idp.example/
, devono pubblicare un file .well-known in https://idp.example/.well-known/web-identity
e un file di configurazione IdP. Ecco un esempio di contenuti di un file noto:
{
"provider_urls": ["https://accounts.idp.example/config.json"]
}
Gli IdP possono ospitare 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 IdP deve supportare più configurazioni di test e produzione diverse.
- Un IdP deve supportare configurazioni diverse per regione (ad esempio,
eu-idp.example
eus-idp.example
).
Per supportare più configurazioni (ad esempio, per distinguere tra ambiente di test e 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 IdP e gli endpoint
Il file di configurazione IdP fornisce un elenco di endpoint richiesti per il browser. I provider di identità
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 contenuti application/json
.
L'URL del file di configurazione è determinato dai valori forniti alla chiamata
navigator.credentials.get()
eseguita su un RP.
Il RP trasmetterà l'URL del file di configurazione per ogni provider di identità:
// Executed on RP's side:
try {
const credential = await navigator.credentials.get({
identity: {
providers: [
{
// To allow users to sign in with the IdP1 using FedCM, RP specifies the IdP's config file URL:
configUrl: 'https://idp1.example/foo.json', // first IdP
clientId: '123',
},
// To allow users to sign in with the IdP2 using FedCM, RP specifies the IdP's config file URL.
// Note that multiple IdPs in a single get() are supported from Chrome 136.
{
configUrl: 'https://idp2.example/bar.json', // second IdP
clientId: '456',
},
],
},
});
const token = credential.token;
// Get the current IdP's configURL to identify which provider the user is signed in with
const currentIdpConfigUrl = credential.configURL;
if (currentIdpConfigUrl === 'https://idp1.example/foo.json') {
// handle the case where the user signed in with idp1
} else if (currentIdpConfigUrl === 'https://idp2.example/bar.json') {
// handle the case where the user signed in with idp2
}
} catch (error) {
// handle error
}
Il browser recupererà il file di configurazione con una richiesta GET
senza l'intestazione Origin
o l'intestazione Referer
. La richiesta non ha 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 risponde con un JSON. Il JSON include le seguenti proprietà:
Proprietà | Descrizione |
---|---|
accounts_endpoint (obbligatorio) |
URL dell'endpoint accounts. |
account_label (facoltativo)
|
Stringa dell'etichetta dell'account personalizzata, che determina quali account devono essere restituiti quando viene utilizzato questo file di configurazione, ad esempio: "account_label": "developer" .
Un IdP può implementare l'etichettatura personalizzata degli account nel seguente modo:
Ad esempio, un IdP implementa il "https://idp.example/developer-config.json" file di configurazione con "account_label": "developer" specificato. L'IdP contrassegna anche alcuni account con l'etichetta "developer" utilizzando il parametro label_hints nell'endpoint accounts. 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 personalizzate degli account sono supportate a partire da Chrome 132. |
supports_use_other_account (facoltativo) |
Valore booleano che specifica se l'utente può accedere con un account diverso da quello con cui ha eseguito l'accesso (se il provider di identità supporta più account). Questo vale solo per la modalità attiva. |
client_metadata_endpoint (facoltativo) |
URL dell'endpoint dei metadati client. |
id_assertion_endpoint (obbligatorio) |
URL dell'endpoint di asserzione dell'ID. |
disconnect (facoltativo) |
URL dell'endpoint di disconnessione. |
login_url (obbligatorio) |
L'URL della pagina di accesso in cui l'utente deve 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 icona ha due parametri:
|
Ecco un esempio di corpo della risposta del fornitore di identità:
{
"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.
"account_label": "developer",
"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 IdP:

Utilizza un altro account
Gli utenti possono passare a un account diverso da quello con cui hanno eseguito l'accesso, se il provider di identità supporta più account o la sostituzione dell'account esistente.
Per consentire all'utente di scegliere altri account, l'IdP deve specificare questa funzionalità nel file di configurazione:
{
"accounts_endpoint" : "/accounts.example",
"supports_use_other_account": true
}
Endpoint Accounts
L'endpoint degli account dell'IdP restituisce un elenco di account a cui l'utente ha eseguito l'accesso sull'IdP. Se il provider di identità supporta più account, questo endpoint restituirà tutti gli account con cui è stato eseguito l'accesso.
Il browser invia una richiesta GET
con i 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
Una volta ricevuta la richiesta, il server deve:
- Verifica che la richiesta contenga un'intestazione HTTP
Sec-Fetch-Dest: webidentity
. - Abbina i cookie di sessione agli ID degli account a cui è già stato eseguito l'accesso.
- Rispondi con l'elenco degli account.
Il browser si aspetta una risposta JSON che includa una proprietà accounts
con un
array di informazioni sull'account con le seguenti proprietà:
Proprietà | Descrizione |
---|---|
id (obbligatorio) |
ID univoco dell'utente. |
name |
Nome completo dell'utente in base alle impostazioni internazionali e alle preferenze. Nota: a partire da Chrome 141, è necessario almeno uno dei parametri name , email , username o tel . Nelle versioni precedenti di Chrome, sono necessari sia name che email .
|
username |
Un nome utente scelto dall'utente. Nota: a partire da Chrome 141, è necessario almeno uno dei parametri name , email , username o tel .
|
email |
Indirizzo email dell'utente. Nota: a partire da Chrome 141, è necessario almeno uno dei parametri name , email , username o tel . Nelle versioni precedenti di Chrome, sono necessari sia name che email .
|
tel |
Numero di telefono dell'utente. Nota: a partire da Chrome 141, è necessario almeno uno dei parametri name , email , username o tel .
|
picture (facoltativo) |
L'URL dell'immagine dell'avatar dell'utente. |
given_name (facoltativo) |
Nome dell'utente. |
approved_clients (facoltativo) |
Un array di ID client RP con cui l'utente si è registrato. |
login_hints (facoltativo) |
Un array di tutti i tipi di filtri possibili supportati dal provider di identità per specificare
un account. La 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. Il RP può
chiamare navigator.credentials.get() con una
proprietà domainHint per filtrare gli
account. |
label_hints (facoltativo)
|
Array di etichette account personalizzate stringa a cui è associato un account. Un IdP può implementare l'etichettatura personalizzata degli account nel seguente modo:
Ad esempio, un IdP implementa il https://idp.example/developer-config.json file di configurazione con "account_label": "developer" specificato. L'IdP contrassegna anche alcuni account con l'etichetta "developer" utilizzando il parametro label_hints nell' endpoint degli account. Quando un RP chiama navigator.credentials.get() con un 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 dal suggerimento di accesso e dal suggerimento di dominio in quanto sono gestite completamente dal server IdP e la RP specifica solo il file di configurazione da utilizzare. Nota: le etichette personalizzate degli account sono supportate a partire da Chrome 132. |
Esempio di corpo 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.
"label_hints": ["enterprise", "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 degli account restituiti viene utilizzato dal browser e non sarà disponibile per la RP.
Endpoint di asserzione dell'ID
L'endpoint di asserzione dell'ID dell'IdP restituisce un'asserzione 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 i cookie con SameSite=None
e un tipo di contenuti application/x-www-form-urlencoded
a questo endpoint con le seguenti informazioni:
Proprietà | Descrizione |
---|---|
client_id (obbligatorio) |
L'identificatore client del RP. |
account_id (obbligatorio) |
L'ID univoco dell'utente che ha eseguito l'accesso. |
disclosure_text_shown |
Restituisce una stringa di "true" o "false" (anziché un valore booleano). Il risultato è "false" nei seguenti casi:
|
disclosure_shown_for |
Elenca i campi che il browser ha mostrato all'utente nel testo dell'informativa per comunicare all'utente quali dati il RP sta richiedendo all'IdP. |
is_auto_selected |
Se viene eseguita la riautenticazione automatica sul RP, is_auto_selected indica "true" . Altrimenti "false" . Ciò è 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 la RP possa chiamare di nuovo l'API FedCM con mediation: required . |
fields (facoltativo)
|
Array di stringhe che specifica i dati dell'utente che il RP ha richiesto all'IdP di condividere. I seguenti campi possono essere specificati facoltativamente:
fields , disclosure_text_shown e disclosure_shown_for elencando i campi specificati nella richiesta POST, come nell'esempio seguente.Nota: l'API Fields è supportata da Chrome 132 e versioni successive. I campi"username" e"tel" sono supportati a partire da Chrome 141. |
params (facoltativo)
|
Qualsiasi oggetto JSON valido che consenta di specificare parametri chiave-valore personalizzati aggiuntivi, ad esempio:
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¶ms=%22%7B%5C%22nonce%5C%22%3A%5C%22nonce-value%5C%22%7D%22.%0D%0A4&fields=email,picture&disclosure_shown_for=email,picture
Una volta ricevuta la richiesta, il server deve:
- Rispondi alla richiesta con CORS (Cross-Origin Resource Sharing).
- Verifica che la richiesta contenga un'intestazione HTTP
Sec-Fetch-Dest: webidentity
. - Confronta l'intestazione
Origin
con l'origine RP determinata daclient_id
. Rifiuta se non corrispondono. - Confronta
account_id
con l'ID dell'account già effettuato l'accesso. Rifiuta se non corrispondono. - Rispondi con un token. Se la richiesta viene rifiutata, rispondi con una risposta di errore.
Il provider di identità può decidere come emettere il token. In generale, è firmato con informazioni come ID account, ID client, origine dell'emittente e nonce, in modo che il RP possa verificare che il token sia autentico.
Il browser prevede una risposta JSON che includa la seguente proprietà:
Proprietà | Descrizione |
---|---|
token |
Un token è una stringa che contiene attestazioni sull'autenticazione. |
continue_on |
URL di reindirizzamento che consente un flusso di accesso in più passaggi. |
Il token restituito viene passato alla parte autorizzata dal browser, in modo che possa convalidare l'autenticazione.
{
// IdP can respond with a token to authenticate the user
"token": "***********"
}
Continua sulla funzionalità
L'IdP può fornire un URL di reindirizzamento nella risposta dell'endpoint di asserzione ID per attivare un flusso di accesso in più passaggi. Ciò è utile quando il provider di identità deve richiedere ulteriori informazioni o autorizzazioni, ad esempio:
- Autorizzazione per accedere alle risorse lato server dell'utente.
- Verifica che i dati di contatto siano aggiornati.
- Controllo genitori.
L'endpoint di asserzione dell'ID può restituire una proprietà continue_on
che include un
percorso assoluto o relativo all'endpoint di asserzione dell'ID.
{
// 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 e l'utente viene indirizzato al percorso specificato. Dopo l'interazione dell'utente
con la pagina continue_on
, il provider di identità 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 al
chiamante API. Una chiamata IdentityProvider.resolve()
una tantum è l'unico modo per la finestra principale (RP) e la finestra popup (IdP) di comunicare.
Se l'utente rifiuta la richiesta, il provider di identità 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 le diverse modalità di mediazione:
- In modalità
passive
:mediation: 'optional'
(impostazione predefinita): l'API Continuation funzionerà solo con un gesto dell'utente, ad esempio un clic su un pulsante della pagina o sull'interfaccia utente FedCM. Quando viene attivata la riautenticazione automatica 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 è sempre compatibile.
Se per qualche motivo l'utente ha modificato il proprio account nel popup (ad esempio, il provider di identità offre una funzione "Usa un altro account" o nei casi di delega), la chiamata resolve accetta un secondo argomento facoltativo che consente di eseguire operazioni come:
IdentityProvider.resolve(token, {accountId: '1234');
Restituire una risposta di errore
id_assertion_endpoint
può anche restituire una risposta "error" (errore), che ha due campi facoltativi:
code
: l'IdP può scegliere uno degli errori noti dall'elenco degli errori specificati di OAuth 2.0 (invalid_request
,unauthorized_client
,access_denied
,server_error
etemporarily_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 al RP.url
: identifica una pagina web leggibile da una persona con informazioni sull'errore per fornire agli utenti ulteriori dettagli. Questo campo è utile agli utenti perché i browser non possono fornire messaggi di errore avanzati in un'interfaccia utente integrata. Ad esempio, link ai passaggi successivi o informazioni di contatto del servizio clienti. Se un utente vuole saperne di più sui dettagli dell'errore e su come risolverlo, può visitare la pagina fornita dall'interfaccia utente del browser per ulteriori dettagli. L'URL deve essere dello stesso sito dell'IdPconfigURL
.
// id_assertion_endpoint response
{
"error" : {
"code": "access_denied",
"url" : "https://idp.example/error?type=access_denied"
}
}
Etichette account personalizzate
Con le etichette account personalizzate, il
provider di identità può annotare gli account utente con etichette e il relying party può scegliere di recuperare solo
gli account con etichette specifiche specificando 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 gli account specifici del ruolo come "developer"
o "hr"
.
È possibile un filtraggio simile utilizzando i suggerimenti per il dominio e per l'accesso, specificandoli 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. Anche le etichette account personalizzate sono diverse
in quanto vengono fornite dal server IdP, anziché dal RP, come
suggerimenti per l'accesso o il dominio.
Prendi in considerazione un IdP che vuole distinguere tra gli account "developer"
e "hr"
. A questo scopo, 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"
, mentre il file di configurazione aziendalehttps://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",
"account_label": "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",
"account_label": "hr"
}
- Con questa configurazione, il file well-known deve includere
accounts_endpoint
elogin_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 accounts IdP comune (in questo esempio
https://idp.example/accounts
) restituisce un elenco di account che include una proprietàlabel_hints
con 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",
"label_hints": ["developer"]
}], [{
"id": "4567",
"given_name": "Jane",
"name": "Jane Doe",
"email": "jane_doe@idp.example",
"picture": "https://idp.example/profile/4567",
"label_hints": ["hr"]
}]
}
Quando un RP vuole consentire l'accesso agli utenti "hr"
, può specificare
l'URL di configurazione 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 di 123
viene nascosto automaticamente dal browser in modo che all'utente
non venga fornito un account non supportato dall'IdP su questo sito.
Considerazioni aggiuntive:
- Le etichette sono stringhe. Se l'array
label_hints
o il campoaccount_label
utilizza un valore che non è una stringa, il valore 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 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 richiami IdentityCredential.disconnect()
, il browser invia una richiesta multiorigine
POST
con i 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 del 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
Una volta ricevuta la richiesta, il server deve:
- Rispondi alla richiesta con CORS (Cross-Origin Resource Sharing).
- Verifica che la richiesta contenga un'intestazione HTTP
Sec-Fetch-Dest: webidentity
. - Confronta l'intestazione
Origin
con l'origine RP determinata daclient_id
. Rifiuta se non corrispondono. - Abbina
account_hint
agli ID degli account a cui è già stato eseguito l'accesso. - Scollega l'account utente dalla RP.
- Rispondi al browser con le informazioni dell'account utente identificate in formato JSON.
Un esempio di payload JSON di risposta è il seguente:
{
"account_id": "account456"
}
Se invece il provider di identità vuole che il browser disconnetta tutti gli account associati
al RP, passa una stringa che non corrisponde a nessun ID account, ad esempio
"*"
.
Endpoint dei metadati client
L'endpoint dei metadati client del fornitore di identità restituisce i metadati della relying party, ad esempio le norme sulla privacy, i termini di servizio e le icone del logo della RP. I 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 si è ancora registrato sul 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
Una volta ricevuta la richiesta, il server deve:
- Determina il RP per
client_id
. - Rispondi con i metadati del client.
Le proprietà dell'endpoint dei metadati client includono:
Proprietà | Descrizione |
---|---|
privacy_policy_url (facoltativo) |
URL delle norme sulla privacy di 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 prevede 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 il 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 lo stato di accesso dell'utente al browser. Tuttavia, lo stato potrebbe non essere sincronizzato, ad esempio
quando la sessione scade. In questo scenario, il browser può consentire dinamicamente all'utente di accedere al provider di identità tramite l'URL della pagina di accesso specificato con login_url
del file di configurazione del provider di identità.
La finestra di dialogo FedCM mostra un messaggio che suggerisce l'accesso, come mostrato nell'immagine seguente.

Quando l'utente fa clic sul pulsante Continua, il browser apre una finestra popup per la pagina di accesso del provider di identità.

La finestra di dialogo è una normale finestra del browser che contiene cookie originali. Qualsiasi operazione all'interno della finestra di dialogo dipende dal fornitore di identità e non sono disponibili handle di finestra per effettuare una richiesta di comunicazione multiorigine alla pagina RP. Dopo l'accesso dell'utente, il provider di identità deve:
- Invia l'intestazione
Set-Login: logged-in
o chiama l'APInavigator.login.setStatus("logged-in")
per comunicare al browser che l'utente ha eseguito l'accesso. - Chiama
IdentityProvider.close()
per chiudere la finestra di dialogo.
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 al provider di identità e mitigare potenziali attacchi di temporizzazione.
I provider di identità 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 al provider di identità o quando ha eseguito la disconnessione da tutti i suoi account del provider di identità. Per ogni IdP (identificato dal relativo URL di configurazione), il browser mantiene una variabile a tre stati che rappresenta lo stato di accesso con i seguenti valori possibili:
logged-in
logged-out
unknown
(valore predefinito)
Stato di accesso | Descrizione |
---|---|
logged-in |
Quando lo stato di accesso dell'utente è impostato su logged-in , la RP che chiama FedCM effettua 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 senza effettuare una richiesta all'endpoint degli account del fornitore di identità. |
unknown (valore predefinito) |
Lo stato unknown viene impostato prima che l'IdP invii un indicatore utilizzando l'API Login Status. Quando lo stato è unknown , il browser invia una richiesta all'endpoint degli account del fornitore di identità e aggiorna lo stato in base alla risposta dell'endpoint degli account. |
Per segnalare che l'utente ha eseguito l'accesso, invia un'intestazione HTTP Set-Login: logged-in
in una navigazione di primo livello o in una richiesta di risorsa secondaria dello stesso sito all'origine IdP:
Set-Login: logged-in
In alternativa, chiama il metodo JavaScript
navigator.login.setStatus('logged-in')
dall'origine 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 in una richiesta di
risorsa secondaria dello stesso sito all'origine IdP:
Set-Login: logged-out
In alternativa, chiama l'API JavaScript navigator.login.setStatus('logged-out')
dall'origine 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 il fornitore di identità invii un segnale utilizzando l'API Login Status. Il browser effettua una richiesta all'endpoint degli account del provider di identità e aggiorna lo stato in base alla risposta dell'endpoint degli account:
- Se l'endpoint restituisce un elenco di account attivi, aggiorna lo stato a
logged-in
e apri la finestra di dialogo FedCM per mostrare questi account. - Se l'endpoint non restituisce account, aggiorna lo stato a
logged-out
e non riuscire a chiamare FedCM.
Consentire all'utente di accedere tramite un flusso di accesso dinamico
Anche se l'IdP continua a comunicare lo stato di accesso dell'utente al browser, 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 scenario, il browser può consentire dinamicamente all'utente di accedere
all'IdP tramite una finestra popup.