Guida per gli sviluppatori dell'API Federated Credential Management

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

FedCM (Federated Credential Management) è un approccio che tutela la privacy ai servizi di identità federati (come "Accedi con…") in cui gli utenti possono accedere ai siti senza condividere le proprie informazioni personali con il servizio di identità o con il sito.

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

Ambiente di sviluppo FedCM

Per utilizzare FedCM, è necessario un contesto sicuro (HTTPS o localhost) nell'IdP e nella parte soggetta a limitazioni in Chrome.

Eseguire il debug del codice su Chrome su Android

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

Puoi utilizzare DevTools sul 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 il ritiro graduale dei cookie di terze parti configurando Chrome per bloccarli
Simula il ritiro dei cookie di terze parti configurando Chrome in modo che li blocchi

Puoi testare il funzionamento di FedCM senza cookie di terze parti su Chrome prima che venga applicato.

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

Utilizzo dell'API FedCM

Puoi eseguire l'integrazione con FedCM creando un file noto, un file di configurazione e gli endpoint per l'elenco di account, l'emissione di asserzioni e, facoltativamente, i metadati del client.

Da qui, FedCM mostra le API JavaScript che le parti soggette a limitazioni possono utilizzare per accedere con l'IdP.

Crea un file noto

Per impedire ai tracker di eseguire un abuso dell'API, è necessario pubblicare un file noto da /.well-known/web-identity di eTLD+1 dell'IdP.

Ad esempio, se gli endpoint dell'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 dell'IdP. Ecco un esempio di contenuti di file molto noti:

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

Il file JSON deve contenere la proprietà provider_urls con un array di URL del 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 1, ma questo potrebbe cambiare con il tuo feedback in futuro.

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

Il file di configurazione dell'identità provider fornisce un elenco di endpoint richiesti per il browser. Gli IdP 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 a 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 un URL completo della posizione del file di configurazione dell'IdP come configURL. Quando viene chiamata la funzione navigator.credentials.get() nell'RP, il browser recupera 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

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

Proprietà Descrizione
accounts_endpoint (campo obbligatorio) URL dell'endpoint account.
client_metadata_endpoint (facoltativo) URL per l'endpoint dei metadati del 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) 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. 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.

L'RP potrebbe modificare la stringa nell'interfaccia utente della finestra di dialogo FedCM tramite il valore identity.context per navigator.credentials.get() per adattarsi ai contesti di autenticazione predefiniti. La proprietà facoltativa può essere "signin" (valore predefinito), "signup", "use" o "continue".

Come viene applicato il branding alla finestra di dialogo FedCM
In che modo il branding viene applicato alla finestra di dialogo FedCM

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

{
  "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 richieste successive agli endpoint IdP:

Endpoint IdP
Endpoint IdP

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 eseguito.

Il browser invia una richiesta GET con cookie con SameSite=None, ma senza un parametro client_id, l'intestazione Origin o Referer. In questo modo, l'IdP non può sapere 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 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 client RP con cui l'utente si è registrato.
login_hints (facoltativo) Un array di tutti i possibili tipi di filtro 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. L'RP può chiamare navigator.credentials.get() con una proprietà domainHint per filtrare gli account.

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",
    "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 (Autorizzazione non autorizzata).

L'elenco di account restituito viene utilizzato dal browser e non sarà disponibile per la parte soggetta a limitazioni.

Endpoint dei metadati client

L'endpoint dei metadati client dell'IdP restituisce i metadati della terza parte attendibile, ad esempio le norme sulla privacy e i Termini di servizio della terza parte attendibile. Le parti soggette a limitazioni devono fornire preventivamente all'IdP i link alle norme sulla privacy e ai termini di servizio. Questi link vengono visualizzati nella finestra di dialogo di accesso quando l'utente non ha ancora eseguito la registrazione nell'RP con il provider di identità.

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

GET /client_metadata.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 l'RP per il client_id.
  2. Rispondi con i metadati del client.

Le proprietà dell'endpoint dei metadati del 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 della parte soggetta a limitazioni.

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

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

Endpoint di asserzione 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 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 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 di "true" o "false" (anziché un valore booleano). Se il testo dell'informativa non viene mostrato, il risultato è "false". Ciò accade quando l'ID cliente dell'RP è stato incluso nell'elenco delle proprietà approved_clients della risposta dell'endpoint account o se il browser ha rilevato 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 opzione è utile per supportare altre funzionalità relative alla sicurezza. Ad esempio, alcuni utenti potrebbero preferire un livello di sicurezza più elevato che richiede la mediazione esplicita dell'utente durante l'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 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. 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 della parte soggetta a limitazioni determinata dal 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 dipende dall'IdP, ma in genere è firmato con informazioni quali ID account, ID cliente, origine emittente, nonce, in modo che il RP possa verificare l'autenticità del token.

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

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

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

Restituire una risposta di errore

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

  • code: l'IdP può scegliere uno degli errori noti dall'elenco di errori specificati di OAuth 2.0 (invalid_request, unauthorized_client, access_denied, server_error e temporarily_unavailable) o utilizzare una stringa arbitraria. Nel secondo caso, Chrome visualizza l'UI di errore 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 informazioni aggiuntive sull'errore. Questo campo è utile per gli utenti perché i browser non possono fornire messaggi di errore avanzati in una UI nativa. Ad esempio, link per i passaggi successivi, informazioni 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 approfondire. L'URL deve appartenere allo stesso sito dell'IdP configURL.
// id_assertion_endpoint response
{
  "error" : {
     "code": "access_denied",
     "url" : "https://idp.example/error?type=access_denied"
  }
}

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

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 della parte soggetta a limitazioni determinata dal client_id. Rifiuta se non corrispondono.
  4. Abbina account_hint agli 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 identificato in formato JSON.

Un esempio di payload JSON di risposta è simile al 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 "*".

URL di accesso

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.
Una finestra di dialogo di esempio mostrata dopo aver fatto clic sul pulsante Accedi all'IdP.

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

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

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

L'API Login Status è un meccanismo tramite il quale un sito web, in particolare un IdP, comunica al browser lo stato di accesso dell'utente sull'IdP. Con questa API, il browser può ridurre le richieste non necessarie all'IDP e mitigare i 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 in base al relativo URL di configurazione), il browser mantiene una variabile tri-stato che rappresenta lo stato dell'accesso con i possibili valori logged-in, logged-out e unknown. Lo stato predefinito è unknown.

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 l'API JavaScript navigator.login.setStatus("logged-in") dall'origine dell'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, l'RP che chiama FedCM invia richieste all'endpoint account dell'IdP e mostra all'utente gli account disponibili nella finestra di dialogo FedCM.

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

Queste chiamate registrano lo stato di accesso dell'utente come logged-out. Quando lo stato di accesso dell'utente è logged-out, la chiamata a FedCM non riesce senza inviare una richiesta all'endpoint degli account dell'IdP.

Lo stato unknown viene impostato prima che l'IdP invii un segnale 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 rilasciata questa API. L'IDP potrebbe non avere la possibilità di segnalarlo al browser al momento della prima chiamata di FedCM. In questo caso, Chrome 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 in logged-out e non soddisfi la chiamata FedCM.

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

Anche se l'IdP continua a informare lo stato di 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 dell'accesso è logged-in, ma il server non restituisce account perché la sessione non è più disponibile. In questo scenario, il browser può consentire all'utente di accedere in modo dinamico all'IdP mediante una finestra popup.

Accedi alla parte che utilizza il provider di identità con il provider di identità

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

Prima di chiamare l'API, devi verificare che [FedCM sia disponibile sul browser dell'utente]. Per verificare se FedCM è disponibile, inserisci questo codice nell'implementazione di FedCM:

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

Per richiedere di consentire agli utenti di accedere all'IDP dall'RP, 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 oggetti IdentityProvider che hanno le seguenti proprietà:

Proprietà Descrizione
configURL (campo obbligatorio) Un percorso completo del file di configurazione dell'IdP.
clientId (campo obbligatorio) L'identificatore client della parte soggetta a limitazioni, emesso dall'IdP.
nonce (facoltativo) Una stringa casuale per garantire che la risposta venga emessa per questa richiesta specifica. Impedisce gli attacchi di replay.
loginHint (facoltativo) Se specifichi uno dei valori login_hints forniti dagli endpoint degli account, la finestra di dialogo FedCM mostra in modo selettivo l'account specificato.
domainHint (facoltativo) Se specifichi uno dei valori domain_hints forniti dagli endpoint degli account, la finestra di dialogo FedCM mostra in modo selettivo l'account specificato.

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

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

  • Se approved_clients include clientId dell'RP.
  • Se il browser ricorda che l'utente ha già eseguito la registrazione all'RP.
Un utente accede a una parte soggetta a limitazioni utilizzando FedCM.

Quando l'RP chiama navigator.credentials.get(), vengono svolte le seguenti attività:

  1. Il browser invia richieste e recupera diversi documenti:
    1. Il file well-known 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 dell'RP, recuperati dall'endpoint dei metadati del client.
  2. Il browser mostra l'elenco degli account che l'utente può utilizzare per accedere, nonché i Termini di servizio e le Norme sulla privacy, se disponibili.
  3. Dopo che l'utente ha scelto un account con cui accedere, all'IdP viene inviata una richiesta all'endpoint di asserzione 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

Gli RP dovrebbero supportare i browser che non supportano FedCM, pertanto gli utenti dovrebbero essere in grado di utilizzare una procedura di accesso esistente non FedCM. Fino a quando i cookie di terze parti non verranno eliminati completamente, questo problema dovrebbe rimanere irrisolto.

Una volta convalidato il token dal server RP, la parte soggetta a limitazioni 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 terza parte attendibile (RP) gli chiede di eseguire nuovamente l'autenticazione. Tuttavia, l'utente potrebbe non essere sicuro di quale account abbia utilizzato. Se la parte soggetta a limitazioni può specificare con quale account accedere, sarebbe più semplice 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 login_hints valori recuperati dall'endpoint dell'elenco 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"
    }]
  }
});

Quando nessun account corrisponde a loginHint, la finestra di dialogo FedCM mostra una richiesta di accesso, che consente all'utente di accedere a un account IdP corrispondente al suggerimento richiesto dalla 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 quindi aggiunto con il suggerimento di accesso e i parametri di query del suggerimento del dominio.

API Domain Hint

In alcuni casi la parte soggetta a limitazioni sa già che solo gli account associati a un determinato dominio possono accedere al sito. Questo è particolarmente comune negli 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 i casi in cui un utente tenta di accedere alla parte soggetta a limitazioni utilizzando un account esterno al dominio aziendale e verrà visualizzato in un secondo momento un messaggio di errore (o verrà visualizzato un messaggio di errore quando l'accesso non funzionava) perché non è stato utilizzato il tipo di account corretto.

Gli RP possono mostrare in modo selettivo solo gli account corrispondenti chiamando navigator.credentials.get() con la proprietà domainHint con uno dei valori domain_hints recuperati dall'endpoint dell'elenco di account, come mostrato nel seguente esempio di codice:

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

Quando nessun account corrisponde a domainHint, la finestra di dialogo FedCM mostra una richiesta di accesso, che consente all'utente di accedere a un account IdP corrispondente al suggerimento richiesto dall'RP. Quando l'utente tocca la richiesta, si apre una finestra popup con l'URL di accesso specificato nel file di configurazione. Al link vengono poi aggiunti i parametri di query dell'indizio di accesso e dell'indizio di dominio.

Un esempio di richiesta di accesso quando nessun account corrisponde a domainHint.
Un esempio di richiesta di accesso quando 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 se il client non è autorizzato o il server non è temporaneamente disponibile. Se l'IdP restituisce una risposta di tipo "errore", l'RP può rilevarla e Chrome invia una notifica all'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 il fallimento del tentativo di accesso dell'utente. La stringa è associata al tipo di errore.
try {
  const cred = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: "https://idp.example/manifest.json",
          clientId: "1234",
        },
      ],
    }
  });
} catch (e) {
  const code = e.code;
  const url = e.url;
}

Riautenticare automaticamente gli utenti dopo l'autenticazione iniziale

L'autenticazione automatica di FedCM (in breve "auto-autenticazione") consente agli utenti di autenticarsi automaticamente quando rientrano dopo l'autenticazione iniziale utilizzando FedCM. "L'autenticazione iniziale" in questo caso significa 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 per la prima volta sulla stessa istanza del browser.

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

Con la riautenticazione automatica, il browser cambia il proprio comportamento a seconda dell'opzione specificata per mediation durante la chiamata di navigator.credentials.get().

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

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

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

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

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

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

Quando queste condizioni sono soddisfatte, viene avviato un tentativo di autenticazione automatica dell'utente non appena viene invocato il navigator.credentials.get() 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 riautenticazione automatica viene eseguita esaminando la proprietà isAutoSelected.

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

Riautenticazione automatica dell'utente tramite FedCM.

Applicare la mediazione con preventSilentAccess()

L'autenticazione automatica degli utenti subito dopo l'uscita non offre un'esperienza utente molto positiva. Ecco perché FedCM ha un periodo senza notifiche di 10 minuti dopo una riautenticazione automatica per evitare questo comportamento. Ciò significa che la nuova autenticazione automatica viene eseguita 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 disabilitare la riautenticazione automatica quando un utente esce esplicitamente dalla parte soggetta a limitazioni, ad esempio facendo clic su un pulsante di disconnessione.

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

Gli utenti possono disattivare la riconferma automatica nelle impostazioni

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

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

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

Scollegare l'IdP dall'RP

Se un utente ha già eseguito l'accesso all'RP utilizzando l'IdP tramite FedCM, la relazione viene memorizzata localmente dal browser come elenco degli account collegati. 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. L'RP deve passare un configURL, il clientId che utilizza sotto l'IdP e un accountHint per scollegare l'IdP. Un indicazione per l'account può essere una stringa arbitraria, purché l'endpoint di disconnessione possa identificare l'account, ad esempio un indirizzo email o un ID utente che non corrisponde necessariamente all'ID account fornito dall'endpoint dell'elenco 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 invocata da un iframe senza il criterio di autorizzazione FedCM.
  • L'URL di configurazione non è valido o manca l'endpoint di disconnessione.
  • Il controllo dei Criteri di sicurezza del contenuto (CSP) non va a buon fine.
  • È presente una richiesta di disconnessione in attesa.
  • L'utente ha disattivato FedCM nelle impostazioni del browser.

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

Chiamare FedCM da un iframe cross-origin

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

<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 di origini consentite.

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

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