Aggiornamenti di FedCM: prove dell'origine per il bundle dell'API Continuation e concessione automatica dell'API Storage Access

Eiji Kitamura

A partire da Chrome 126, gli sviluppatori possono iniziare a eseguire una prova dell'origine per un bundle di funzionalità dell'API Federated Credential Management (FedCM) desktop che consentono alcuni casi d'uso di Authorization. Il bundle è composto dall'API Continuation e dall'API Parameters, che abilitano un'esperienza simile a un flusso di autorizzazione OAuth che coinvolge una finestra di dialogo delle autorizzazioni fornita da un provider di identità (IdP). Il bundle include anche altre modifiche, ad esempio l'API Fields, più configURL ed etichette dell'account personalizzate. A partire da Chrome 126, stiamo anche introducendo una prova dell'origine per l'API Storage Access (SAA) che concede automaticamente le richieste SAA se l'utente ha eseguito l'accesso correttamente utilizzando FedCM in passato.

Prova dell'origine: bundle dell'API FedCM Continuation

Il bundle dell'API FedCM Continuation è composto da più estensioni FedCM:

• API Continuation
• API Parameters
• API Field
• Più configURL
• Etichette dell'account personalizzate

API Continuation

Un utente sta accedendo alla parte soggetta a limitazioni e poi autorizza tramite la modalità a pulsante.

Puoi guardare una demo dell'API su Glitch.

L'API Continuetion consente all'endpoint di asserzione ID dell'IdP di restituire facoltativamente un URL che verrà visualizzato da FedCM per consentire all'utente di continuare un flusso di accesso in più passaggi. Ciò consente all'IdP di richiedere all'utente di concedere alla parte rimanente (RP) autorizzazioni aggiuntive rispetto a quanto possibile nell'interfaccia utente di FedCM esistente, ad esempio l'accesso alle risorse lato server dell'utente.

In genere, l'endpoint di asserzione dell'ID restituisce un token necessario per l'autenticazione.

{
  "token": "***********"
}

Tuttavia, con l'API Continuation, l'endpoint di asserzione ID può restituire una proprietà continue_on che include un percorso assoluto o un percorso relativo all'endpoint di asserzione ID.

{
  // In the id_assertion_endpoint, instead of returning a typical
  // "token" response, the IdP decides that it needs the user to
  // continue on a pop-up window:
  "continue_on": "/oauth/authorize?scope=..."
}

Non appena il browser riceve la risposta continue_on, si apre una nuova finestra popup che indirizza l'utente al percorso specificato.

Dopo che l'utente ha interagito con la pagina, ad esempio concedendo ulteriori autorizzazioni a condividere informazioni aggiuntive con la parte soggetta a limitazioni, la pagina dell'IdP può chiamare IdentityProvider.resolve() per risolvere la chiamata navigator.credentials.get() originale e restituire un token come argomento.

document.getElementById('allow_btn').addEventListener('click', async () => {
  let accessToken = await fetch('/generate_access_token.cgi');
  // Closes the window and resolves the promise (that is still hanging
  // in the relying party's renderer) with the value that is passed.
  IdentityProvider.resolve(accessToken);
});

Il browser chiuderà il popup da solo e restituirà il token al chiamante dell'API.

Se l'utente rifiuta la richiesta, puoi chiudere la finestra chiamando il numero IdentityProvider.close().

IdentityProvider.close();

Nota: il popup si comporta come se fosse stato specificato noopener, noreferrer (di conseguenza, window.opener è nullo) e non c'è modo che sia la finestra principale (RP) sia la finestra popup (IdP) interagiscano tra loro. L'unico modo per comunicare dovrebbe essere una chiamata IdentityProvider.resolve() una tantum, che chiude anche il popup.

Nota: l'API Continuation è consentita solo in caso di interazione dell'utente (clic espliciti). Pertanto, l'utente deve selezionare un account in modalità widget (con mediation: 'required') o in modalità con pulsante (che richiede sempre l'attivazione da parte dell'utente). Tuttavia, il popup non è consentito per mediation: silent. Per la modalità widget mediation: optional, l'API controlla l'attivazione temporanea dell'utente se viene attivata la riautenticazione automatica. In caso contrario, non si apre alcuna finestra popup e la promessa viene rifiutata.

Se per qualche motivo l'utente ha modificato il proprio account nel popup (ad esempio, l'IdP offre una funzione "cambia utente" o in casi di delega), la chiamata di risoluzione utilizza un secondo argomento facoltativo che consente un esempio di:

IdentityProvider.resolve(token, {accountId: '1234');

API Parameters

L'API Parameters consente alla parte soggetta a limitazioni di fornire parametri aggiuntivi all'endpoint di asserzione ID. Con l'API Parameters, le parti soggette a limitazioni possono passare parametri aggiuntivi all'IdP per richiedere autorizzazioni per le risorse oltre all'accesso di base. L'utente autorizzerebbe queste autorizzazioni tramite un flusso UX controllato dall'IdP che viene avviato tramite l'API Continuazione.

Per utilizzare l'API, aggiungi parametri alla proprietà params come oggetto nella chiamata navigator.credentials.get().

let {token} = await navigator.credentials.get({
  identity: {
    providers: [{
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      // Key/value pairs that need to be passed from the
      // RP to the IdP but that don't really play any role with
      // the browser.
      params: {
        IDP_SPECIFIC_PARAM: '1',
        foo: 'BAR',
        ETC: 'MOAR',
        scope: 'calendar.readonly photos.write',
      }
    },
  }
});

I nomi delle proprietà nell'oggetto params sono preceduti da param_. Nell'esempio precedente, la proprietà dei parametri contiene IDP_SPECIFIC_PARAM come '1', foo come 'BAR', ETC come 'MOAR' e scope come 'calendar.readonly photos.write'. Questo verrà tradotto come param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write nel corpo HTTP della richiesta:

POST /fedcm_assertion_endpoint HTTP/1.1
Host: 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=234234&disclosure_text_shown=false&param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write

Ottieni le autorizzazioni in modo dinamico

In generale, per gli utenti è più utile richiedere le autorizzazioni quando ne hanno bisogno, anziché quando lo sviluppatore ritiene che siano più facili da implementare. Ad esempio, per chiedere l'autorizzazione ad accedere a una fotocamera mentre l'utente sta per scattare una foto, è preferibile chiedere l'autorizzazione non appena l'utente arriva sul sito web. Lo stesso vale per le risorse server. Richiedi le autorizzazioni solo quando sono necessarie per l'utente. Questa si chiama "autorizzazione dinamica".

Per richiedere l'autorizzazione in modo dinamico con FedCM, l'IdP può:

1. Richiama navigator.credentials.get() con i parametri richiesti che l'IdP sia in grado di comprendere, ad esempio scope.
2. L'endpoint di asserzione ID conferma che l'utente ha già eseguito l'accesso e risponde con un URL continue_on.
3. Il browser apre una finestra popup con la pagina delle autorizzazioni dell'IdP che richiede un'autorizzazione aggiuntiva corrispondente agli ambiti richiesti.
4. Dopo l'autorizzazione tramite IdentityProvider.resolve() dall'IdP, la finestra viene chiusa e la chiamata navigator.credentials.get() originale della parte soggetta a limitazioni riceve un token pertinente o un codice di autorizzazione, in modo che l'RP possa scambiarlo con un token di accesso appropriato.

API Fields

L'API Field consente all'RP di dichiarare gli attributi dell'account da richiedere all'IdP in modo che il browser possa visualizzare un'interfaccia utente per l'informativa adeguata nella finestra di dialogo FedCM. È responsabilità dell'IdP includere i campi richiesti nel token restituito. Potresti richiedere un "profilo di base" in OpenID Connect anziché un "ambiti" in OAuth.

Messaggio di divulgazione in modalità widget.

Messaggio di divulgazione in modalità pulsante.

Per utilizzare l'API Fields, aggiungi parametri alla proprietà fields come array nella chiamata navigator.credentials.get(). Per il momento, i campi possono contenere 'name', 'email' e 'picture', ma possono essere espansi per includere altri valori in futuro.

Una richiesta con fields avrebbe il seguente aspetto:

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      fields: ['name', 'email', 'picture'],
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      params: {
        scope: 'drive.readonly calendar.readonly',
      }
    },
  }
  mediation: 'optional',
});

La richiesta HTTP all'endpoint di asserzione ID include il parametro fields specificato nell'RP, con il parametro disclosure_text_shown impostato su true se non si tratta di un utente di ritorno, e i campi che il browser ha divulgato all'utente in un parametro disclosure_shown_for:

POST /id_assertion_endpoint HTTP/1.1
Host: 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=234234&disclosure_text_shown=true&fields=email,name,picture&disclosure_shown_for=email,name,picture

Nota: al momento, Chrome genera un'eccezione, a meno che la parte soggetta a limitazioni non richieda fields: ['name', 'email', 'picture'] o nulla con fields: []. In futuro, Chrome renderà la UI più in grado di richiedere combinazioni diverse e inizierà ad accettare sottoinsiemi di questi valori.

Se la parte soggetta a limitazioni ha bisogno di accedere a dati aggiuntivi dell'IdP, ad esempio l'accesso a un calendario, questo deve essere gestito con un parametro personalizzato come indicato sopra. L'IdP restituisce un URL continue_on per richiedere l'autorizzazione.

Se fields è un array vuoto, la richiesta sarà simile a questa:

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      fields: [],
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      params: {
        scope: 'drive.readonly calendar.readonly',
      }
    },
  }
  mediation: 'optional',
});

Se fields è un array vuoto, lo user agent ignorerà l'UI per l'informativa.

Il messaggio di divulgazione non viene visualizzato in modalità widget. Nel flusso dei pulsanti, l'UI per l'informativa viene saltata completamente.

Questo è il caso anche se la risposta dall'endpoint dell'account non contiene un ID client che corrisponde alla parte soggetta a limitazioni in approved_clients.

In questo caso, il valore disclosure_text_shown inviato all'endpoint di asserzione ID è falso nel corpo HTTP:

POST /id_assertion_endpoint HTTP/1.1
Host: 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=234234&disclosure_text_shown=false

Più configURL

Più configURL consentono agli IdP di ospitare più file di configurazione per un IdP, specificando accounts_endpoint e login_url nel file noto come i file di configurazione.

Se accounts_endpoint e login_url vengono aggiunti al file noto, i provider_urls vengono ignorati in modo che l'IdP possa supportare più file di configurazione. In caso contrario, provider_urls continuerà a essere applicato per essere compatibile con le versioni precedenti.

Il noto file che supporta più configURL ha il seguente aspetto:

{
  "provider_urls": [ "https://idp.example/fedcm.json" ],
  "accounts_endpoint": "https://idp.example/accounts",
  "login_url": "https://idp.example/login"
}

Questo ci consente di:

1. mantenere la compatibilità con i file già noti esistenti e con le versioni precedenti dei browser di cui è già stato eseguito il deployment al pubblico.
2. Avere un numero arbitrario di file di configurazione, purché puntino tutti agli stessi accounts_endpoint e login_url.
3. Non avere la possibilità di aggiungere entropia alla richiesta di recupero delle credenziali effettuata all'accounts_endpoint, poiché deve essere specificata a livello "well-known".

Il supporto di più configURL è facoltativo e le implementazioni esistenti di FedCM possono rimanere invariate.

Etichette account personalizzate

Le etichette account personalizzate consentono agli IdP FedCM di annotare gli account in modo che le parti soggette a limitazioni possano filtrarli specificando l'etichetta in un file di configurazione. È stato possibile applicare filtri simili utilizzando l'API Domain Hint e l'API Login Hint specificandoli nella chiamata navigator.credentials.get(), ma le etichette account personalizzate possono filtrare gli utenti specificando il file di configurazione, il che è particolarmente utile quando vengono utilizzati più configURL. Le etichette account personalizzate sono diverse anche in quanto vengono fornite dal server IdP, anziché dall'RP, come gli suggerimenti di accesso o di dominio.

Esempio

Un IdP supporta due configURL rispettivamente per consumer e enterprise. Il file di configurazione consumer ha un'etichetta 'consumer' e il file di configurazione aziendale ha un'etichetta 'enterprise'.

Con questa configurazione, il file noto include accounts_endpoint e login_url per consentire più configURL.

{
  "provider_urls": [ "https://idp.example/fedcm.json" ],
  "accounts_endpoint": "https://idp.example/accounts",
  "login_url": "https://idp.example/login"
}

Quando accounts_endpoint viene fornito nel file noto, i provider_urls vengono ignorati. La parte soggetta a limitazioni può puntare direttamente ai rispettivi file di configurazione nella chiamata navigator.credentials.get().

Il file di configurazione consumer si trova in https://idp.example/fedcm.json, che include la proprietà accounts che specifica 'consumer' utilizzando include.

{
  "accounts_endpoint": "https://idp.example/accounts",
  "client_metadata_endpoint": "/client_metadata",
  "login_url": "https://idp.example/login",
  "id_assertion_endpoint": "/assertion",
  "accounts": {
    "include": "consumer"
  }
}

Il file di configurazione aziendale si trova in https://idp.example/enterprise/fedcm.json, che include la proprietà accounts che specifica 'enterprise' utilizzando include.

{
  "accounts_endpoint": "https://idp.example/accounts",
  "client_metadata_endpoint": "/enterprise/client_metadata",
  "login_url": "https://idp.example/login",
  "id_assertion_endpoint": "/assertion",
  "accounts": {
    "include": "enterprise"
  }
}

L'endpoint degli account IdP comune (in questo esempio https://idp.example/accounts) restituisce un elenco di account che include una proprietà etichetta con labels assegnato in un array per ogni account. Di seguito è riportato un esempio di risposta per un utente che dispone di due account. una per i consumatori e l'altra per le aziende:

{
 "accounts": [{
   "id": "123",
   "given_name": "John",
   "name": "John Doe",
   "email": "[e-mail]",
   "picture": "https://idp.example/profile/123",
   "labels": ["consumer"]
  }], [{
   "id": "4567",
   "given_name": "Jane",
   "name": "Jane Doe",
   "email": "[e-mail]",
   "picture": "https://idp.example/profile/4567",
   "labels": ["enterprise"]
  }]
}

Quando una parte soggetta a limitazioni vuole consentire l'accesso a 'enterprise' utenti, può specificare 'enterprise'configURL'https://idp.example/enterprise/fedcm.json' nella chiamata navigator.credentials.get():

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      clientId: '1234',
      nonce: '234234',
      configURL: 'https://idp.example/enterprise/fedcm.json',
    },
  }
});

Di conseguenza, solo l'ID account '4567' è disponibile per l'accesso dell'utente. L'ID account '123' viene nascosto automaticamente dal browser in modo che all'utente non venga fornito un account non supportato dall'IdP su questo sito.

Nota:

• Le etichette sono stringhe. Se l'array labels o il campo include contiene qualcosa che non è una stringa, viene ignorato.
• Se non vengono specificate etichette in configURL, tutti gli account verranno visualizzati nel selettore account FedCM.
• Se per un account non vengono specificate etichette, questa verrà visualizzata nel Selettore account solo se anche il valore di configURL non specifica un'etichetta.
• Se nessun account corrisponde all'etichetta richiesta nel flusso del widget (simile all'API Domain Hint), la finestra di dialogo FedCM mostra una richiesta di accesso, che consente all'utente di accedere a un account IdP. Per il flusso dei pulsanti, la finestra popup di accesso viene aperta direttamente.

Prova dell'origine: FedCM come indicatore di attendibilità per l'API Storage Access

Chrome 126 sta avviando una prova dell'origine di FedCM come indicatore di attendibilità per l'API Storage Access. Con questa modifica, la concessione di un'autorizzazione precedente tramite FedCM diventa un motivo valido per approvare automaticamente una richiesta di accesso allo spazio di archiviazione da parte delle API Storage Access.

Ciò è utile quando un iframe incorporato desidera accedere a risorse personalizzate, ad esempio se idp.example è incorporato in rp.example e deve mostrare una risorsa personalizzata. Se il browser limita l'accesso ai cookie di terze parti, anche se l'utente ha eseguito l'accesso a rp.example utilizzando idp.example con FedCM, l'iframe idp.example incorporato non potrà richiedere risorse personalizzate perché le richieste non includono cookie di terze parti.

A questo scopo, idp.example deve ottenere un'autorizzazione di accesso allo spazio di archiviazione tramite l'iframe incorporato nel sito web. Questa autorizzazione può essere ottenuta solo tramite un prompt di autorizzazione.

Con FedCM come indicatore di attendibilità per l'API Storage Access, i controlli delle autorizzazioni dell'API Storage Access non solo accettano la concessione dell'autorizzazione fornita da una richiesta di accesso allo spazio di archiviazione, ma anche la concessione dell'autorizzazione da parte di un prompt FedCM.

// In top-level rp.example:

// Ensure FedCM permission has been granted.
const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://idp.example/fedcm.json',
      clientId: '123',
    }],
  },
  mediation: 'optional',
});

// In an embedded IdP iframe:

// No user gesture is needed to call this, and the call will be auto-granted.
await document.requestStorageAccess();

// This returns `true`.
const hasAccess = await document.hasStorageAccess();

Dopo che l'utente ha eseguito l'accesso con FedCM, l'autorizzazione viene concessa automaticamente purché l'autenticazione FedCM sia attiva. Ciò significa che quando l'utente viene disconnesso, la richiesta di autorizzazione mostrerà un prompt.

Nota :per consentire a un iframe IdP incorporato di ottenere la concessione automatica di Storage Access nonostante lo stesso FedCM non sia richiamato all'interno dell'iframe, la parte soggetta a limitazioni deve aggiungere esplicitamente il criterio di autorizzazione identity-credentials-get FedCM.

Partecipare alla prova dell'origine

Puoi provare localmente il bundle dell'API FedCM Continuation attivando un flag di Chrome chrome://flags#fedcm-authz su Chrome 126 o versioni successive. Puoi anche provare FedCM come indicatore di attendibilità per l'API Storage Access localmente attivando #fedcm-with-storage-access-api su Chrome 126 o versioni successive.

Queste funzionalità sono disponibili anche come prove dell'origine. Le prove dell'origine consentono di provare nuove funzionalità e fornire feedback sulla loro usabilità, pratica ed efficacia. Per ulteriori informazioni, consulta la guida introduttiva alle prove dell'origine.

Per provare la prova dell'origine del bundle API FedCM Continuation, crea due token di prova dell'origine:

• Registrati per la prova. Incorpora il token nell'origine dell'IdP.
• Registrati alla prova dell'origine con una casella di controllo corrispondente di terze parti selezionata. Segui le istruzioni in Registrare una prova dell'origine di terze parti per la parte soggetta a limitazioni per incorporare il token per la parte soggetta a limitazioni.

Se vuoi abilitare l'API Continuation insieme al flusso dei pulsanti, abilita anche la prova dell'origine dell'API Button Mode:

• Registrati alla prova dell'origine come terza parte. Segui le istruzioni riportate in Registrare una prova dell'origine di terze parti per la parte soggetta a limitazioni per incorporare il token per la parte soggetta a limitazioni.

Per provare FedCM come indicatore di attendibilità per la prova dell'origine dell'API Storage Access:

• Registrati per la prova dell'origine. Incorpora il token nell'origine dell'IdP.

La prova dell'origine del bundle API Continuation e FedCM come indicatore di attendibilità per la prova dell'origine dell'API Storage Access sono disponibili da Chrome 126.

Registrare una prova dell'origine di terze parti per la parte soggetta a limitazioni

1. Vai alla pagina di registrazione della prova dell'origine.
2. Fai clic sul pulsante Registrati e compila il modulo per richiedere un token.
3. Inserisci l'origine dell'IdP come Origine web.
4. Controlla la corrispondenza di terze parti per inserire il token con JavaScript su altre origini.
5. Fai clic su Invia.
6. Incorpora il token emesso in un sito web di terze parti.

Per incorporare il token in un sito web di terze parti, aggiungi il codice seguente alla libreria JavaScript o all'SDK dell'IdP pubblicato dall'origine dell'IdP.

const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = 'TOKEN_GOES_HERE';
document.head.appendChild(tokenElement);

Sostituisci TOKEN_GOES_HERE con il tuo token.

Nota: se l'API FedCM viene richiamata dalla parte soggetta a limitazioni, non tramite script caricato dall'IdP, quest'ultima deve registrare la propria origine ed eseguire la prova dell'origine proprietaria.