Guida per gli sviluppatori dell'API Federated Credential Management

Scopri come utilizzare FedCM per una federazione delle identità incentrata sulla tutela della privacy.

FedCM (Federated Credential Management) è un approccio ai servizi di identità federati (ad esempio "Accedi con...") incentrati sulla tutela della privacy, in cui gli utenti possono accedere ai siti senza condividere le loro informazioni personali con il servizio di identità o il sito.

Per saperne di più sui casi d'uso, sui flussi utente e sulla roadmap delle API di FedCM, consulta l'introduzione all'API FedCM.

Ambiente di sviluppo FedCM

Per utilizzare FedCM, è necessario un contesto sicuro (HTTPS o localhost) sia nell'IdP che nella RP in Chrome.

Codice di debug in Chrome su Android

Configura ed esegui in locale un server per eseguire il debug del codice FedCM. Puoi accedere a questo server in Chrome su un dispositivo Android collegato tramite cavo USB con port forwarding.

Puoi utilizzare DevTools su computer per eseguire il debug di Chrome su Android seguendo le istruzioni riportate in Eseguire il debug remoto dei dispositivi Android.

Bloccare i cookie di terze parti su Chrome

Simula la graduale eliminazione dei cookie di terze parti configurando Chrome in modo da bloccarli
Simula la graduale eliminazione dei cookie di terze parti configurando Chrome in modo da bloccarli

Puoi testare il funzionamento di FedCM senza cookie di terze parti su Chrome prima dell'applicazione effettiva.

Per bloccare i cookie di terze parti, utilizza la modalità di navigazione in incognito o scegli "Blocca cookie di terze parti" nelle impostazioni del desktop all'indirizzo chrome://settings/cookies o sul dispositivo mobile andando su Impostazioni > Impostazioni sito > Cookie.

Utilizzo dell'API FedCM

Per l'integrazione con FedCM, devi creare un file noto, un file di configurazione ed endpoint per l'elenco di account, l'emissione di un'assertion e, facoltativamente, i metadati client.

Da qui, FedCM espone le API JavaScript che le RP possono utilizzare per accedere con l'IdP.

Crea un file noto

Per evitare che i tracker utilizzino l'API in modo illecito, un file noto deve essere pubblicato da /.well-known/web-identity di eTLD+1 dell'IdP.

Ad esempio, se gli endpoint IdP vengono gestiti in https://accounts.idp.example/, devono pubblicare un file noto in https://idp.example/.well-known/web-identity e un file di configurazione IdP. Ecco un esempio di contenuto di file noto:

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

Il file JSON deve contenere la proprietà provider_urls con un array di URL dei file di configurazione IdP che possono essere specificati come parte del percorso di configURL in navigator.credentials.get dalle parti soggette a limitazioni. Il numero di stringhe URL nell'array è limitato a uno, ma questo potrebbe cambiare con il tuo feedback in futuro.

crea un file di configurazione e degli endpoint dell'IdP

Il file di configurazione dell'IdP fornisce un elenco degli endpoint richiesti per il browser. Gli IdP ospitano questo file di configurazione e gli endpoint e gli URL richiesti. Tutte le risposte JSON devono essere fornite con il tipo di contenuto application/json.

L'URL del file di configurazione è determinato dai valori forniti alla chiamata navigator.credentials.get eseguita su una parte soggetta a limitazioni.

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

Specifica come configURL l'URL completo del percorso del file di configurazione IdP. Quando navigator.credentials.get() viene chiamato nella parte soggetta a limitazioni, il browser recupera il file di configurazione con una richiesta GET senza l'intestazione Origin o Referer. La richiesta non contiene cookie e non segue i reindirizzamenti. In questo modo, si impedisce all'IdP di capire chi ha effettuato la richiesta e quale parte soggetta a limitazioni sta tentando di connettersi. Ad esempio:

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

Il browser si aspetta una risposta JSON dall'IdP che includa le seguenti proprietà:

Proprietà Descrizione
accounts_endpoint (campo obbligatorio) URL per l'endpoint degli account.
client_metadata_endpoint (facoltativo) URL per l'endpoint dei metadati del client.
id_assertion_endpoint (campo obbligatorio) URL per l'endpoint dell'asserzione ID.
disconnect (facoltativo) URL per l'endpoint di disconnessione.
login_url (campo obbligatorio) L'URL della pagina di accesso che l'utente può utilizzare per accedere all'IdP.
branding (facoltativo) Oggetto contenente 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) Opzione di branding che imposta l'oggetto icona, visualizzato nella finestra di dialogo di accesso. L'oggetto icona è un array con due parametri:
  • url (obbligatorio): URL dell'immagine dell'icona. Non sono supportate immagini SVG.
  • size (facoltativo): dimensioni dell'icona, che l'applicazione presume siano quadrate e a risoluzione singola. Questo numero deve essere maggiore o uguale a 25.

La parte soggetta a limitazioni potrebbe modificare la stringa nell'interfaccia utente della finestra di dialogo FedCM tramite il valore identity.context per navigator.credentials.get() per adeguarsi ai contesti di autenticazione predefiniti. La proprietà facoltativa può essere una tra "signin" (predefinita), "signup", "use" o "continue".

Come viene applicato il branding alla finestra di dialogo FedCM
Come viene applicato il branding alla finestra di dialogo FedCM

Ecco un esempio di corpo di risposta dall'IdP:

{
  "accounts_endpoint": "/accounts.php",
  "client_metadata_endpoint": "/client_metadata.php",
  "id_assertion_endpoint": "/assertion.php",
  "disconnect_endpoint": "/disconnect.php",
  "login_url": "/login",
  "branding": {
    "background_color": "green",
    "color": "#FFEEAA",
    "icons": [{
      "url": "https://idp.example/icon.ico",
      "size": 25
    }]
  }
}

Una volta che il browser recupera il file di configurazione, invia le richieste successive agli endpoint IdP:

Endpoint IdP
Endpoint IdP

Endpoint account

L'endpoint degli account dell'IdP restituisce un elenco di account a cui l'utente ha attualmente eseguito l'accesso sull'IdP. Se l'IdP supporta più account, questo endpoint restituirà tutti gli account a cui è stato eseguito l'accesso.

Il browser invia una richiesta GET con cookie con SameSite=None, ma senza parametro client_id, l'intestazione Origin o Referer. Ciò impedisce in modo efficace all'IdP di capire a quale RP l'utente sta tentando di accedere. Ad esempio:

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

Alla ricezione della richiesta, il server deve:

  1. Verifica che la richiesta contenga un'intestazione HTTP Sec-Fetch-Dest: webidentity.
  2. Abbina i cookie di sessione agli ID degli account a cui è già stato eseguito l'accesso.
  3. Rispondi fornendo l'elenco degli account.

Il browser prevede una risposta JSON che includa una proprietà accounts con un array di informazioni sull'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 client 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. La parte soggetta a limitazioni 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. La parte soggetta a limitazioni può chiamare navigator.credentials.get() con una proprietà domainHint per filtrare gli account.

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",
    "approved_clients": ["123", "456", "789"],
    "login_hints": ["demo1", "demo1@idp.example"]
  }, {
    "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", "demo2@idp.example"],
    "domain_hints": ["corp.example"]
  }]
}

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

L'elenco degli account restituito viene utilizzato dal browser e non sarà disponibile nella parte soggetta a limitazioni.

Endpoint dei metadati client

L'endpoint dei metadati client dell'IdP restituisce i metadati della parte richiedente, come le norme sulla privacy e i termini di servizio della parte soggetta a limitazioni. Le 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 nella parte soggetta a limitazioni con l'IdP.

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

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

Alla ricezione della richiesta, il server deve:

  1. Determina la parte soggetta a limitazioni per client_id.
  2. Rispondi con i metadati del client.

Le proprietà per l'endpoint di metadati del client includono:

Proprietà Descrizione
privacy_policy_url (facoltativo) URL delle norme sulla privacy della parte soggetta a limitazioni.
terms_of_service_url (facoltativo) URL dei Termini di servizio della parte soggetta a limitazioni.

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",
}

I metadati del client restituiti vengono utilizzati dal browser e non sono disponibili per la parte soggetta a limitazioni.

Endpoint dell'asserzione dell'ID

L'endpoint dell'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 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) Identificatore client della parte soggetta a limitazioni.
account_id (campo obbligatorio) L'ID univoco dell'utente che ha eseguito l'accesso.
nonce (facoltativo) Il nonce della richiesta, fornito dalla parte soggetta a limitazioni.
disclosure_text_shown Restituisce una stringa "true" o "false" (anziché un valore booleano). Se il testo dell'informativa non è stato mostrato, il risultato è "false". Questo accade quando l'ID client della parte soggetta a limitazioni è stato incluso nell'elenco delle proprietà approved_clients della risposta dall'endpoint degli account o se il browser ha osservato un momento di registrazione in passato in assenza di approved_clients.
is_auto_selected Se viene eseguita la riautenticazione automatica sulla parte soggetta a limitazioni, is_auto_selected indica "true". In caso contrario, "false". Questa funzionalità è utile per supportare un numero maggiore di funzionalità di sicurezza. Ad esempio, alcuni utenti potrebbero preferire un livello di sicurezza superiore che richiede la mediazione esplicita dell'utente nell'autenticazione. Se un IdP riceve una richiesta di token senza tale mediazione, potrebbe gestire la richiesta in modo diverso. Ad esempio, restituisci un codice di errore che consenta alla parte soggetta a limitazioni di chiamare di nuovo l'API FedCM con mediation: required.

Intestazione HTTP di esempio:

POST /assertion.php HTTP/1.1
Host: accounts.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=Ct60bD&disclosure_text_shown=true&is_auto_selected=true

Alla ricezione della richiesta, il server deve:

  1. Rispondi alla richiesta con CORS (condivisione delle risorse tra origini).
  2. Verifica che la richiesta contenga un'intestazione HTTP Sec-Fetch-Dest: webidentity.
  3. Abbina l'intestazione Origin all'origine della parte soggetta a limitazioni determinata dal valore client_id. Rifiuta se non corrispondono.
  4. Abbina account_id all'ID dell'account a 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.

La modalità di emissione del token spetta all'IdP, ma in generale è firmato con informazioni quali l'ID account, l'ID client, l'origine dell'emittente, nonce, in modo che la parte soggetta a limitazioni possa verificare che il token sia autentico.

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

Proprietà Descrizione
token (campo obbligatorio) Un token è una stringa che contiene attestazioni sull'autenticazione. 
{
  "token": "***********"
}

Il token restituito viene passato alla parte soggetta a limitazioni dal browser, in modo che quest'ultima possa convalidare l'autenticazione.

Restituire una risposta di errore

id_assertion_endpoint può anche restituire una risposta "errore", contenente due campi facoltativi:

  • code: l'IdP può scegliere uno degli errori noti dall'elenco degli errori specificati OAuth 2.0 (invalid_request, unauthorized_client, access_denied, server_error e temporarily_unavailable) o utilizzare qualsiasi stringa arbitraria. Nel secondo caso, Chrome visualizza l'interfaccia utente con un messaggio di errore generico e passa il codice alla parte soggetta a limitazioni.
  • url: identifica una pagina web leggibile con informazioni sull'errore per fornire agli utenti ulteriori informazioni sull'errore. Questo campo è utile per gli utenti perché i browser non possono fornire messaggi di errore avanzati in un'interfaccia utente nativa. ad esempio link per i passaggi successivi, dati di contatto dell'assistenza clienti e così via. 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 maggiori 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"
  }
}

Disconnetti endpoint

Richiamando IdentityCredential.disconnect(), il browser invia una richiesta POST multiorigine 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 Identificatore client della parte soggetta a limitazioni. 
POST /disconnect.php 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

Alla ricezione della richiesta, il server deve:

  1. Rispondi alla richiesta con CORS (condivisione delle risorse tra origini).
  2. Verifica che la richiesta contenga un'intestazione HTTP Sec-Fetch-Dest: webidentity.
  3. Abbina l'intestazione Origin all'origine della parte soggetta a limitazioni determinata dal valore client_id. Rifiuta se non corrispondono.
  4. Trova la corrispondenza di account_hint con gli ID degli account a cui è già stato eseguito l'accesso.
  5. Scollega l'account utente dalla parte soggetta a limitazioni.
  6. Rispondere al browser con i dati dell'account utente identificati in formato JSON.

Un esempio di payload JSON di risposta ha il seguente aspetto:

{
  "account_id": "account456"
}

Se invece l'IdP vuole che il browser disconnetta tutti gli account associati alla parte soggetta a limitazioni, trasmetti una stringa che non corrisponde ad alcun ID account, ad esempio "*".

URL di accesso

Con l'API Login Status, l'IdP deve informare lo stato di accesso dell'utente al browser. Tuttavia, lo stato potrebbe non essere sincronizzato, ad esempio alla scadenza della sessione. In questo scenario, il browser può consentire dinamicamente all'utente di accedere all'IdP tramite l'URL della pagina di accesso specificato con il valore login_url del file di configurazione idp.

La finestra di dialogo FedCM mostra un messaggio che suggerisce un accesso, 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
Una finestra di dialogo di esempio mostrata dopo aver fatto clic sul pulsante di accesso al pulsante IdP.

La finestra di dialogo è una normale finestra del browser contenente cookie proprietari. Qualunque cosa avvenga all'interno della finestra di dialogo spetta all'IdP e non sono disponibili handle di finestra per effettuare una richiesta di comunicazione multiorigine 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.
A
Un utente accede a una parte soggetta a limitazioni dopo aver eseguito l'accesso all'IdP utilizzando FedCM.

Comunica al browser lo stato di accesso dell'utente al provider di identità

L'API Login Status è un meccanismo in cui un sito web, in particolare un IdP, informa il browser dello stato di accesso dell'utente all'IdP. Con questa API, il browser può ridurre le richieste non necessarie all'IdP e mitigare i potenziali attacchi di tempistica.

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 sull'IdP o quando è disconnesso da tutti i suoi account IdP. Per ogni IdP (identificato dal relativo URL di configurazione), il browser conserva una variabile a tre stati che rappresenta lo stato dell'accesso con i possibili valori logged-in, logged-out e unknown. Lo stato predefinito è unknown.

Per segnalare 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 sottorisorse dello stesso sito all'origine dell'IdP:

Set-Login: logged-in

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

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

Queste chiamate registrano lo stato di accesso dell'utente come logged-in. Quando lo stato di accesso dell'utente è impostato su logged-in, il FedCM che chiama la RP invia richieste all'endpoint degli account dell'IdP e mostra gli account disponibili all'utente nella finestra di dialogo FedCM.

Per segnalare che l'utente è disconnesso da tutti i suoi account, invia l'intestazione HTTP Set-Login: logged-out in una navigazione di primo livello o una richiesta di sottorisorse dello stesso sito all'origine dell'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")

Queste chiamate registrano lo stato di accesso dell'utente come logged-out. Se lo stato di accesso dell'utente è logged-out, la chiamata al FedCM ha esito negativo senza inviare una richiesta all'endpoint degli account dell'IdP.

Lo stato unknown viene impostato prima che l'IdP invii un indicatore utilizzando l'API Login Status. Unknown è stato introdotto per una transizione migliore, perché un utente potrebbe aver già eseguito l'accesso all'IdP quando è stata spedita questa API. L'IdP potrebbe non avere la possibilità di segnalarlo al browser prima della chiamata a FedCM per la prima volta. In questo caso, Chrome invia una richiesta all'endpoint degli account dell'IdP e aggiorna lo stato in base alla risposta dall'endpoint degli account:

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

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

Anche se l'IdP continua a informare lo stato dell'accesso dell'utente al browser, potrebbe non essere sincronizzato, ad esempio alla scadenza della sessione. 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 alcun 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.

Accedi alla parte attendibile con il provider di identità

Quando la configurazione e gli endpoint dell'IdP sono disponibili, le parti soggette a limitazioni possono chiamare navigator.credentials.get() per richiedere di consentire agli utenti di accedere alla parte soggetta a limitazioni con l'IdP.

Prima di chiamare l'API, devi confermare che [FedCM è disponibile sul browser dell'utente]. Per verificare se FedCM è disponibile, esegui il wrapping di questo codice intorno alla tua implementazione FedCM:

if ('IdentityCredential' in window) {
  // If the feature is available, take action
}

Per richiedere l'autorizzazione agli utenti di accedere all'IdP dalla parte soggetta a limitazioni, segui questi passaggi, ad esempio:

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

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

Proprietà Descrizione
configURL (campo obbligatorio) Un percorso completo del file di configurazione IdP.
clientId (campo obbligatorio) Identificatore client della parte soggetta a limitazioni, emesso dall'IdP.
nonce (facoltativo) Una stringa casuale per garantire che la risposta venga inviata per questa richiesta specifica. Impedisce la ripetizione degli attacchi.
loginHint (facoltativo) Specificando uno dei valori login_hints forniti dagli endpoint degli account, la finestra di dialogo FedCM mostra selettivamente l'account specificato.
domainHint (facoltativo) Specificando uno dei valori domain_hints forniti dagli endpoint degli account, la finestra di dialogo FedCM mostra selettivamente l'account specificato.

Il browser gestisce i casi d'uso di registrazione e accesso in modo diverso a seconda dell'esistenza di approved_clients nella risposta dall'endpoint dell'elenco di account. Il browser non mostrerà il testo dell'informativa "Per continuare con..." se l'utente si è già registrato alla parte soggetta a limitazioni.

Lo stato di registrazione viene determinato a seconda che siano soddisfatte o meno le seguenti condizioni:

  • Se approved_clients include clientId della parte soggetta a limitazioni.
  • Se il browser ricorda che l'utente si è già registrato alla parte soggetta a limitazioni.
Un utente accede a una parte soggetta a limitazioni utilizzando FedCM

Quando la parte soggetta a limitazioni chiama navigator.credentials.get(), vengono eseguite le seguenti attività:

  1. Il browser invia richieste e recupera diversi documenti:
    1. Il file noto e un file di configurazione IdP che dichiarano gli endpoint.
    2. Un elenco di account.
    3. (Facoltativo) URL delle norme sulla privacy e dei Termini di servizio della parte soggetta a limitazioni, recuperati dall'endpoint dei metadati del client.
  2. Il browser visualizza l'elenco degli account che l'utente può utilizzare per eseguire l'accesso, nonché i Termini di servizio e le norme sulla privacy, se disponibili.
  3. Dopo che l'utente sceglie un account con cui accedere, all'IdP viene inviata una richiesta all'endpoint di valutazione dell'ID per recuperare un token.
  4. La parte soggetta a limitazioni può convalidare il token per autenticare l'utente.
chiamata API di accesso
Chiamata API di accesso

Le RP dovrebbero supportare browser che non supportano FedCM, pertanto gli utenti devono essere in grado di utilizzare un processo di accesso esistente non FedCM. Fino a quando i cookie di terze parti non verranno eliminati completamente, questo comportamento non dovrebbe presentare problemi.

Dopo la convalida del token da parte del server RP, quest'ultima può registrare l'utente o consentirgli di accedere e avviare una nuova sessione.

API Login Hint

Dopo che l'utente ha eseguito l'accesso, a volte la parte richiedente (RP) chiede all'utente di eseguire nuovamente l'autenticazione. ma l'utente potrebbe non essere sicuro di quale account sta utilizzando. Se la parte soggetta a limitazioni può specificare con quale account eseguire l'accesso, sarebbe più facile per l'utente scegliere un account.

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

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      nonce: nonce,
      loginHint : "demo1@example.com"
    }]
  }
});

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

API Domain Hint

In alcuni casi la parte soggetta a limitazioni sa già che solo gli account associati a un determinato dominio sono autorizzati ad accedere al sito. Questo è particolarmente comune in scenari aziendali in cui il sito a cui si accede è limitato a un dominio aziendale. Per offrire una migliore esperienza utente, l'API FedCM consente alla parte soggetta a limitazioni di mostrare solo gli account che possono essere utilizzati per accedere alla parte soggetta a limitazioni. In questo modo, è possibile evitare gli scenari in cui un utente tenta di accedere alla parte soggetta a limitazioni utilizzando un account esterno al dominio aziendale, per poi ricevere un messaggio di errore in un secondo momento (o disattivare l'audio quando l'accesso non funzionava) perché non è stato utilizzato il tipo di account corretto.

Le parti soggette a limitazioni possono mostrare selettivamente solo gli account corrispondenti richiamando navigator.credentials.get() con la proprietà domainHint con uno dei valori domain_hints recuperati dall'endpoint dell'elenco degli account, come mostrato nel seguente esempio di codice:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "abc",
      nonce: nonce,
      domainHint : "corp.example"
    }]
  }
});

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

Un esempio di prompt di accesso quando nessun account corrisponde al dominio DomainHint.
Un esempio di richiesta di accesso quando nessun account corrisponde a domainHint.

Mostra 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 e il server è temporaneamente non disponibile. Se l'IdP restituisce una risposta di errore, la parte soggetta a limitazioni può rilevarla e Chrome avvisa l'utente mostrando una UI del browser con le informazioni sull'errore fornite dall'IdP.

A
Una finestra di dialogo FedCM che mostra il messaggio di errore dopo che un tentativo di accesso da parte dell'utente ha esito negativo. 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;
}

Riautentica automaticamente gli utenti dopo il consenso iniziale

La riautenticazione automatica FedCM ("riautenticazione automatica" in breve) consente agli utenti di riautenticarsi automaticamente quando tornano dopo l'autenticazione iniziale mediante FedCM. Per "autenticazione iniziale" si intende che l'utente crea un account o accede al sito web della parte soggetta a limitazioni toccando per la prima volta il pulsante "Continua come..." nella finestra di dialogo di accesso di FedCM sulla stessa istanza del browser.

Sebbene l'esplicita esperienza utente abbia senso prima che l'utente crei l'account federato per impedire il monitoraggio (che è uno degli obiettivi principali di FedCM), diventa inutilmente ingombrante una volta che l'utente l'ha elaborata una volta: dopo che l'utente ha concesso l'autorizzazione per consentire la comunicazione tra la parte soggetta a limitazioni e l'IdP, non esiste alcun vantaggio in termini di privacy o sicurezza per l'applicazione di un'altra conferma esplicita dell'utente per qualcosa che ha già confermato in precedenza.

Con la riautenticazione automatica, il browser cambia il suo comportamento a seconda dell'opzione che hai specificato per mediation durante la chiamata a navigator.credentials.get().

const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/fedcm.json",
      clientId: "1234",
    }],
  },
  mediation: 'optional', // this is the default
});

// `isAutoSelected` is `true` if auto-reauthn was performed.
const isAutoSelected = cred.isAutoSelected;

mediation è una proprietà nell'API Credential Management, si comporta allo stesso modo di PasswordCredential e FederatedCredential ed è parzialmente supportato anche da PublicKeyCredential. La proprietà accetta i seguenti quattro valori:

  • 'optional'(valore predefinito): viene effettuata una nuova autorizzazione automatica se possibile; in caso contrario è necessaria una mediazione. Ti consigliamo di scegliere questa opzione nella pagina di accesso.
  • 'required': richiede sempre una mediazione per procedere, ad esempio facendo clic sul pulsante "Continua" nell'interfaccia utente. Scegli questa opzione se gli utenti devono concedere esplicitamente l'autorizzazione ogni volta che devono essere autenticati.
  • 'silent': viene effettuata una nuova autorizzazione automatica se possibile. In caso contrario, viene annullata automaticamente l'autenticazione senza richiedere una mediazione. Ti consigliamo di scegliere questa opzione su pagine diverse dalla pagina di accesso dedicata, ma in cui vuoi mantenere l'accesso agli utenti, ad esempio una pagina di articolo su un sito web di spedizione o una pagina di articoli su un sito web di notizie.
  • 'conditional': utilizzato per WebAuthn e al momento non disponibile per FedCM.

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

  • FedCM è disponibile. Ad esempio, l'utente non ha disattivato FedCM né a livello globale né per la parte soggetta a limitazioni nelle impostazioni.
  • L'utente ha utilizzato un solo account con l'API FedCM per accedere al sito web su questo browser.
  • L'utente abbia eseguito l'accesso all'IdP con quell'account.
  • La nuova autorizzazione non è avvenuta negli ultimi 10 minuti.
  • La parte soggetta a limitazioni non ha chiamato navigator.credentials.preventSilentAccess() dopo l'accesso precedente.

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

Quando mediation: optional, la riautenticazione automatica potrebbe essere non disponibile per motivi noti solo al browser; la parte soggetta a limitazioni può verificare se la nuova autorizzazione automatica viene eseguita esaminando la proprietà isAutoSelected.

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

Un utente che esegue nuovamente l'autenticazione automatica tramite FedCM.

Applica la mediazione con preventSilentAccess()

La riautenticazione automatica degli utenti subito dopo l'uscita non offre un'esperienza utente molto positiva. Ecco perché FedCM prevede un periodo senza notifiche di 10 minuti dopo una nuova autorizzazione automatica, in modo da evitare questo problema. Ciò significa che la nuova autorizzazione automatica avviene al massimo una volta ogni 10 minuti, a meno che l'utente non acceda di nuovo entro 10 minuti. La parte soggetta a limitazioni deve chiamare navigator.credentials.preventSilentAccess() per richiedere esplicitamente al browser di disattivare la riautenticazione automatica quando un utente esce dalla parte soggetta a limitazioni in modo esplicito, ad esempio facendo clic su un pulsante di uscita.

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

Gli utenti possono disattivare la riautenticazione automatica nelle impostazioni

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

  • Su Chrome per computer, vai a chrome://password-manager/settings > Accedi automaticamente.
  • Su Android Chrome, aprite Impostazioni > Gestore delle password > toccate l'icona a forma di ingranaggio nell'angolo in alto a destra > Accesso automatico.

Disattivando l'opzione, l'utente può disattivare del tutto il comportamento di riautenticazione automatica. Questa impostazione viene archiviata e sincronizzata su più dispositivi, se l'utente ha eseguito l'accesso a un Account Google sull'istanza di Chrome e la sincronizzazione è abilitata.

Disconnetti l'IdP dalla parte soggetta a limitazioni

Se un utente ha già eseguito l'accesso alla parte soggetta a limitazioni utilizzando l'IdP tramite FedCM, la relazione viene memorizzata dal browser localmente come elenco degli account connessi. La parte soggetta a limitazioni potrebbe avviare una disconnessione richiamando la funzione IdentityCredential.disconnect(). Questa funzione può essere chiamata da un frame RP di primo livello. La parte soggetta a limitazioni deve passare un configURL, il clientId che utilizza sotto l'IdP e un accountHint affinché l'IdP venga disconnesso. Un suggerimento per l'account può essere una stringa arbitraria, purché l'endpoint di disconnessione sia in grado di 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 può rappresentare un'eccezione per i seguenti motivi:

  • L'utente non ha eseguito l'accesso alla parte soggetta a limitazioni utilizzando l'IdP tramite FedCM.
  • L'API viene richiamata dall'interno di un iframe senza norme relative alle autorizzazioni FedCM.
  • Il parametro configURL non è valido o manca l'endpoint di disconnessione.
  • Il controllo dei criteri di sicurezza del contenuto (CSP) non va a buon fine.
  • Esiste 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, la parte soggetta a limitazioni e l'IdP vengono disconnesse sul browser e la promessa viene risolta. L'ID degli account disconnessi viene specificato nella risposta dall'endpoint di disconnessione.

Chiama FedCM da un iframe multiorigine

FedCM può essere richiamato dall'interno di un iframe multiorigine utilizzando un criterio di autorizzazione identity-credentials-get, se il frame principale lo consente. A tale scopo, aggiungi 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 vederla in azione in un esempio.

Facoltativamente, se il frame principale vuole limitare le origini alla chiamata FedCM, invia un'intestazione Permissions-Policy con un elenco delle origini consentite.

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

Per saperne di più su come funziona il criterio relativo alle autorizzazioni, vedi Controllo delle funzionalità del browser con i criteri delle autorizzazioni.