Guida per gli sviluppatori dell'API Federated Credential Management

Scopri come utilizzare FedCM per una federazione delle identità che tutela la privacy.

FedCM (Federated Credential Management) è una piattaforma che tutela la privacy ai servizi di identità federati (ad esempio "Accedi con...") in cui gli utenti possono accedere ai siti senza condividere le loro informazioni personali con servizio di identità o il sito.

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

Ambiente di sviluppo FedCM

È necessario un contesto sicuro (HTTPS o localhost) sia nell'IdP sia nella parte soggetta a limitazioni in Chrome per utilizzare FedCM.

Eseguire il debug del codice in Chrome su Android

Configura ed esegui un server in locale per eseguire il debug del codice FedCM. Puoi accedi a questo server in Chrome su un dispositivo Android collegato tramite un cavo USB con porta l'inoltro.

Puoi utilizzare DevTools sul computer per eseguire il debug di Chrome su Android seguendo le istruzioni Istruzioni in Debug remoto di Android dispositivi mobili.

Bloccare i cookie di terze parti su Chrome

Simula il ritiro graduale dei cookie di terze parti configurando Chrome per bloccarli
Simula il ritiro graduale dei cookie di terze parti configurando Chrome per bloccarli

Puoi testare il funzionamento di FedCM senza cookie di terze parti su Chrome prima che effettivamente applicate.

Per bloccare i cookie di terze parti, usa la modalità In incognito modalità oppure seleziona "Blocca cookie di terze parti" nelle impostazioni del desktop in chrome://settings/cookies o il giorno dispositivo mobile andando su Impostazioni > Impostazioni sito > Cookie:

Utilizzo dell'API FedCM

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

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

Crea un file noto

Per impedire ai tracker di utilizzare in modo illecito API, un file noto deve essere pubblicato da /.well-known/web-identity di eTLD+1 del o provider di identità.

Ad esempio, se gli endpoint IdP vengono gestiti https://accounts.idp.example/, devono pubblicare un file noto all'indirizzo https://idp.example/.well-known/web-identity e una configurazione 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 IdP degli URL del file di configurazione che possono essere specificati come parte del percorso configURL in navigator.credentials.get per parte soggetta a limitazioni. Il numero di Le stringhe URL nell'array sono limitate a una, ma questo può cambiare con feedback in futuro.

crea un file di configurazione e degli endpoint IdP

Il file di configurazione dell'IdP fornisce un elenco degli endpoint richiesti per il browser. IdPs ospiterà questo file di configurazione e gli endpoint e gli URL richiesti. Tutto JSON le risposte devono essere fornite con il tipo di contenuti 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 un URL completo della posizione del file di configurazione dell'IdP come configURL. Quando La parte navigator.credentials.get() viene chiamata 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 sapere chi ha effettuato la richiesta e quali L'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 quanto segue 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 di asserzione ID.
disconnect (facoltativo) URL dell'endpoint di disconnessione.
login_url (campo obbligatorio) L'URL della pagina di accesso a cui l'utente deve accedere per 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 di "Continua come..." . Utilizza la sintassi CSS pertinente, ovvero hex-color, hsl(), rgb() oppure named-color.
branding.color (facoltativo) Opzione di branding che imposta il colore del testo di "Continua come..." . Utilizza la sintassi CSS pertinente, ovvero hex-color, hsl(), rgb() oppure 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 le immagini SVG.
  • size (facoltativo): dimensioni dell'icona che vengono presupposte dall'applicazione come risoluzione singola e quadrata. 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 consentire l'autenticazione predefinita i contesti. 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 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 richieste successive alla Endpoint IdP:

Endpoint IdP
Endpoint IdP

Endpoint degli account

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

Il browser invia una richiesta GET con cookie con SameSite=None, ma senza un parametro client_id, l'intestazione Origin o Referer. Questo impedisce all'IdP di apprendere la parte soggetta a limitazioni che l'utente sta tentando di firmare in. 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 è stato già eseguito l'accesso.
  3. Rispondi con l'elenco degli account.

Il browser si aspetta una risposta JSON che includa una proprietà accounts con un array di 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 filtro supportati dall'IdP per specificare un account. La parte soggetta a limitazioni può richiamare navigator.credentials.get() con la proprietà loginHint per selettivamente l'account specificato.
domain_hints (facoltativo) Un array di tutti i domini a cui è associato l'account. La parte soggetta a limitazioni può chiama navigator.credentials.get() con un domainHint per filtrare la proprietà .

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 (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 del client dell'IdP restituisce i metadati della parte coinvolta, le norme sulla privacy e i termini di servizio della parte soggetta a limitazioni. Le parti soggette a limitazioni devono fornire link ai loro le norme sulla privacy e i Termini di servizio all'IdP. Questi link sono visualizzato nella finestra di dialogo di accesso quando l'utente non si è 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. Stabilisci la parte soggetta a limitazioni per client_id.
  2. Rispondere 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 della parte soggetta a limitazioni.
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 a disposizione della parte soggetta a limitazioni.

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 basato sulla parte soggetta a limitazioni utilizzando navigator.credentials.get() , il browser invia una richiesta POST con i cookie SameSite=None e un tipo di contenuti application/x-www-form-urlencoded per 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". 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 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 (risorsa interorigine) condivisione).
  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 un errore risposta.
di Gemini Advanced.

La modalità di emissione del token dipende dall'IdP, ma in generale viene firmato con informazioni quali l'ID account, l'ID cliente, l'origine dell'emittente, nonce, in modo che la parte soggetta a limitazioni può verificare che il token sia autentico.

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

Proprietà Descrizione
token (campo obbligatorio) Un token è una stringa che contiene dichiarazioni 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 un "errore" , che ha due campi facoltativi:

  • code: l'IdP può scegliere uno degli errori noti dell'interfaccia OAuth 2.0 errore specificato elenco (invalid_request, unauthorized_client, access_denied, server_error e temporarily_unavailable) oppure utilizzare una stringa arbitraria. Nel secondo caso, Chrome esegue il rendering dell'interfaccia utente di errore con un messaggio di errore generico e passa il codice alla parte soggetta a limitazioni.
  • url: identifica una pagina web leggibile da una persona con informazioni sul 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 una un'interfaccia utente nativa. Ad esempio, link per i passaggi successivi, contatto dell'assistenza clienti informazioni e così via. Se un utente vuole saperne di più sui dettagli dell'errore e su come risolverlo, potrebbe visitare la pagina fornita dall'interfaccia utente del browser per ulteriori dettagli. 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 richiama IdentityCredential.disconnect(), il browser invia una richiesta multiorigine Richiesta POST con cookie con SameSite=None e tipo di contenuti pari a 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

Alla ricezione della richiesta, il server deve:

  1. Rispondere alla richiesta con CORS (risorsa interorigine) condivisione).
  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. Rispondi al browser con i dati dell'account utente identificati in un file JSON formato.
di Gemini Advanced.

Un esempio di payload JSON di risposta è simile al seguente:

{
  "account_id": "account456"
}

Se invece vuole che il browser disconnetta tutti gli account associati l'RP, trasmetti una stringa che non corrisponde ad alcun ID account, ad esempio "*".

URL di accesso

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

Nella finestra di dialogo FedCM viene visualizzato un messaggio che suggerisce un accesso, come mostrato nella nell'immagine che segue.

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 Accedi all'IdP.
di Gemini Advanced.

Si tratta di una normale finestra del browser con cookie proprietari. Qualsiasi cosa avviene all'interno della finestra di dialogo dipende dall'IdP e non sono disponibili handle di finestre per effettuare una richiesta di comunicazione multiorigine alla pagina parte soggetta a limitazioni. Dopo che l'utente ha ha eseguito l'accesso, l'IdP deve:

  • Invia l'intestazione Set-Login: logged-in o chiama il API navigator.login.setStatus("logged-in") per informare il browser che È stato eseguito l'accesso all'utente.
  • Chiama IdentityProvider.close() per chiudere la finestra di dialogo.
di Gemini Advanced.
A
Un utente accede a una parte soggetta a limitazioni 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 Un sito web, in particolare un provider di identità, informa il browser sullo stato di accesso dell'utente sull'IdP. Con questa API, il browser può ridurre le richieste non necessarie ai all'IdP e mitigare i potenziali attacchi temporali.

Gli IdP possono segnalare al browser lo stato di accesso dell'utente inviando un'intestazione HTTP o chiamando un'API JavaScript quando l'utente ha eseguito l'accesso all'IdP o quando viene disconnesso da tutti i propri account IdP. Per ogni IdP (identificato tramite config) il browser mantiene una variabile tri-state 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 in una richiesta di sottorisorse nello stesso sito presso l'IdP origine:

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 l'accesso dell'utente lo stato è impostato su logged-in, l'RP che chiama FedCM invia richieste all'IdP l'endpoint degli account e mostra gli account disponibili all'utente nel file 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 risorsa secondaria 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. Quando l'utente lo stato di accesso è logged-out, la chiamata a FedCM non riesce senza effettuare un all'endpoint degli account dell'IdP.

Lo stato unknown viene impostato prima che l'IdP invii un segnale utilizzando lo stato di accesso tramite Google Cloud CLI o tramite l'API Compute Engine. Unknown è stato introdotto per migliorare la transizione perché un utente potrebbe aver ha già eseguito l'accesso all'IdP al momento della spedizione di questa API. L'IdP potrebbe non avere di segnalarlo al browser quando viene richiamato per la prima volta FedCM. In questo caso, Chrome invia una richiesta all'endpoint degli account dell'IdP e aggiorna basato sulla risposta dell'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 mostrare questi account.
  • Se l'endpoint non restituisce account, aggiorna lo stato in logged-out e non superi la chiamata FedCM.
di Gemini Advanced.

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, potrebbero non essere sincronizzati, ad esempio alla scadenza della sessione. Il browser prova a invia 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ù disponibili. 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 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, aggrega questo codice intorno al tuo Implementazione di FedCM:

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

Per richiedere di consentire 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 con 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 inviata per questa richiesta specifica. Impedisce la ripetizione degli attacchi.
loginHint (facoltativo) Specifica uno dei login_hints valori forniti da gli endpoint degli account, il file FedCM mostra selettivamente l'account specificato.
domainHint (facoltativo) Specifica uno dei domain_hints valori forniti da gli endpoint degli account, il file FedCM la finestra di dialogo mostra selettivamente l'account specificato.

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

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

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

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

  1. Il browser invia richieste e recupera diversi documenti:
    1. Il file noto e una configurazione IdP file 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 recuperato dall'endpoint dei metadati del client.
  2. Il browser visualizza l'elenco di account che l'utente può utilizzare per accedere, nonché ai Termini di servizio e alle Norme sulla privacy, se disponibili.
  3. Dopo che l'utente ha scelto un account con cui accedere, viene inviata una richiesta all'ID asserzione endpoint viene inviato all'IdP per recuperare un di accesso.
  4. La parte soggetta a limitazioni può convalidare il token per autenticare l'utente.
di Gemini Advanced.
chiamata API di accesso
chiamata API di accesso

Le parti soggette a limitazioni dovrebbero supportare browser che non supportano FedCM, quindi Gli utenti devono essere in grado di utilizzare una procedura di accesso esistente non FedCM. Fino al giorno i cookie di terze parti verranno eliminati completamente, per cui dovrebbero rimanere non problematico.

Dopo che il token è stato convalidato dal server RP, quest'ultima può registrare l'utente o consenti loro di accedere e avviare una nuova sessione.

API Login Hint

Dopo che l'utente ha eseguito l'accesso, a volte la parte coinvolta (RP) chiede all'utente di eseguire nuovamente l'autenticazione. Tuttavia, l'utente potrebbe non sapere con certezza quale account è in uso. Se la parte soggetta a limitazioni può specificare con quale account accedere, sarebbe più facile per all'utente di 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 seguenti login_hints valori recuperati dall'elenco account endpoint, 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, nella finestra di dialogo FedCM viene visualizzata una richiesta di accesso, che consente all'utente di accedere a un account IdP corrispondente al suggerimento richiesto la parte soggetta a limitazioni. Quando l'utente tocca il prompt, si apre una finestra popup con il URL di accesso specificato nel file di configurazione. Il link viene quindi aggiunto con il suggerimento per l'accesso e i parametri di query con il suggerimento del dominio.

API Domain Hint

A volte la parte soggetta a limitazioni sa già che solo gli account associati a un determinati domini possono accedere al sito. Ciò è particolarmente comune scenari aziendali in cui il sito è accessibile solo a un'azienda dominio. Per offrire una migliore esperienza utente, l'API FedCM consente alla parte soggetta a limitazioni solo di mostrano gli account che possono essere utilizzati per accedere alla parte soggetta a limitazioni. In questo modo previene gli scenari in cui un utente tenta di accedere alla parte soggetta a limitazioni utilizzando un account esterno all'azienda dominio, da mostrare solo con un messaggio di errore in un secondo momento (o silenziare i punti in cui l'accesso non ha funzionato) 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 seguenti domain_hints valori recuperati dall'elenco account endpoint, 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, nella finestra di dialogo FedCM viene visualizzata una richiesta di accesso, che consente all'utente di accedere a un account IdP corrispondente al suggerimento richiesto la parte soggetta a limitazioni. Quando l'utente tocca il prompt, si apre una finestra popup con il URL di accesso specificato nel file di configurazione. Il link viene quindi aggiunto con il suggerimento per l'accesso e i parametri di query con il suggerimento del dominio.

Un esempio di richiesta di accesso quando nessun account corrisponde a domainHint.
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, come ad esempio quando il client non è autorizzato, il server è temporaneamente non disponibile. Se l'IdP restituisce un errore risposta, il parte soggetta a limitazioni può individuarla, così come Chrome avvisa l'utente mostrando una UI del browser con le informazioni sull'errore fornite l'IdP.

A
Una finestra di dialogo FedCM che mostra il messaggio di errore dopo che il tentativo di accesso dell'utente non va a buon fine. 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;
}

Nuova autenticazione degli utenti dopo l'autenticazione iniziale

Riautenticazione automatica FedCM ("auto-reauthn" in breve) può consentire agli utenti di eseguire nuovamente l'autenticazione quando dopo l'autenticazione iniziale tramite FedCM. "La prima autenticazione" significa che l'utente crea un account o accede sito web toccando 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 il account federato per impedire il monitoraggio (che è uno dei principali obiettivi di FedCM), risulta inutilmente ingombrante dopo che l'utente lo ha già attraversato una volta: dopo l'utente concede l'autorizzazione per consentire la comunicazione tra la parte soggetta a limitazioni e l'IdP, l'applicazione forzata di un altro utente esplicito non comporta alcun vantaggio in termini di privacy o sicurezza conferma di qualcosa già confermato in precedenza.

Con la riautenticazione automatica, il browser cambia il proprio comportamento in base all'opzione specificare 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à nella sezione API, si comporta allo stesso modo come per gli altri PasswordCredential e FederatedCredential ed è parzialmente supportato PublicKeyCredential . La proprietà accetta i quattro valori seguenti:

  • 'optional'(valore predefinito): se possibile, nuova autenticazione automatica richiede una mediazione in caso contrario. Me ti consigliamo di scegliere questa opzione nella pagina di accesso.
  • 'required': richiede sempre una mediazione per procedere, ad esempio facendo clic su "Continua" sulla UI. Scegli questa opzione se è previsto che i tuoi utenti concedino esplicitamente l'autorizzazione ogni volta che devono essere autenticati.
  • 'silent': se possibile, la nuova autenticazione automatica ha esito negativo automaticamente senza richiedere la mediazione, in caso contrario. Ti consigliamo di scegliere questa opzione nelle pagine diverse da la pagina di accesso dedicata, ma in cui vuoi mantenere gli utenti connessi, ad esempio, la pagina di un articolo su un sito web che si occupa di spedizioni o la pagina di un articolo sito web.
  • 'conditional': utilizzata per WebAuthn e al momento non disponibile per FedCM.

In questa chiamata, la nuova autenticazione automatica viene eseguita 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 del browser.
  • L'utente ha eseguito l'accesso all'IdP con quell'account.
  • La nuova autenticazione automatica non è avvenuta negli ultimi 10 minuti.
  • La parte soggetta a limitazioni non ha navigator.credentials.preventSilentAccess() in seguito l'accesso precedente.

Quando queste condizioni sono soddisfatte, un tentativo di riautenticare automaticamente l'utente viene avviato non appena viene richiamato il metodo navigator.credentials.get() di FedCM.

Quando mediation: optional, la riautenticazione automatica potrebbe essere non disponibile per motivi che solo il browser lo sa; la parte soggetta a limitazioni può controllare se la riautenticazione automatica viene eseguita esaminando la proprietà isAutoSelected.

Ciò è utile per valutare le prestazioni delle API e migliorare la UX di conseguenza. Inoltre, quando non è disponibile, all'utente potrebbe essere chiesto di accedere in modo esplicito mediazione degli utenti, un flusso con mediation: required.

Riautenticazione automatica dell'utente tramite FedCM.

Applicare la mediazione con preventSilentAccess()

La riautenticazione automatica degli utenti subito dopo l'uscita non costituisce un vantaggio un'esperienza utente molto buona. Ecco perché FedCM ha un periodo di silenzio di 10 minuti dopo una nuova autenticazione automatica per evitare questo comportamento. Ciò significa che la riautenticazione automatica al massimo una volta ogni 10 minuti, a meno che l'utente non esegua nuovamente l'accesso entro 10 minuti. La parte soggetta a limitazioni deve chiamare navigator.credentials.preventSilentAccess() a richiedere esplicitamente al browser di disattivare la nuova autenticazione automatica quando un utente esce la parte soggetta a limitazioni in modo esplicito, ad esempio, facendo clic su un pulsante di disconnessione.

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

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

Disattivando l'opzione, l'utente può disattivare tutti i comportamenti di autenticazione automatica in sinergia. Questa impostazione viene memorizzata e sincronizzata su tutti i dispositivi, se l'utente: eseguito l'accesso a un Account Google sull'istanza di Chrome e la sincronizzazione in un bucket con il controllo delle versioni attivo.

Scollega 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, viene memorizzata dal browser localmente come elenco . La parte soggetta a limitazioni può avviare una disconnessione richiamando il metodo Funzione IdentityCredential.disconnect(). Questa funzione può essere chiamata da un frame RP di primo livello. La parte soggetta a limitazioni deve superare un configURL, il valore clientId che usa nell'IdP e un accountHint per la disconnessione dell'IdP. Un account il hint 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 corrisponda 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ò generare 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.
  • configURL non è valido o manca l'endpoint di disconnessione.
  • Controllo del Criterio di sicurezza del contenuto (CSP) non riuscito.
  • Esiste una richiesta di disconnessione in attesa.
  • L'utente ha disattivato FedCM nelle impostazioni del browser.

Quando l'endpoint di disconnessione dell'IdP restituisce un personalizzata, la parte soggetta a limitazioni e l'IdP sono disconnessi del browser e la promessa viene risolta. L'ID degli account scollegati è specificato nella risposta alla disconnessione endpoint.

Chiamare FedCM da un iframe multiorigine

FedCM può essere richiamato dall'interno di un iframe multiorigine utilizzando un Criterio di autorizzazione di identity-credentials-get, se il frame principale lo consente. A 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 di origini consentite.

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

Per ulteriori informazioni sul funzionamento dei criteri relativi alle autorizzazioni, consulta la pagina Controllo funzionalità del browser con autorizzazioni Norme.