Consenti il riutilizzo delle passkey sui tuoi siti con richieste di origini correlate

Maud Nalpas
Maud Nalpas

Le passkey sono associate a un sito web specifico e possono essere utilizzate solo per accedere al sito web per cui sono state create.

Questo valore è specificato nell'ID della terza parte (ID RP), che per le passkey create per il dominio example.com potrebbe essere www.example.com o example.com.

Sebbene gli ID RP impediscano l'utilizzo delle passkey come singola credenziale per l'autenticazione ovunque, creano problemi per:

  • Siti con più domini: gli utenti non possono utilizzare la stessa passkey per accedere su diversi domini specifici per paese (ad esempio example.com e example.co.uk) gestiti dalla stessa azienda.
  • Domini con nome del brand: gli utenti non possono utilizzare la stessa credenziale su diversi domini utilizzati da un singolo brand (ad esempio acme.com e acmerewards.com).
  • App mobile: le app mobile spesso non hanno un dominio proprio, il che complica la gestione delle credenziali.

Esistono soluzioni alternative basate sulla federazione delle identità e altre basate sugli iframe, ma in alcuni casi sono scomodi. Le richieste di origine correlate offrono una soluzione.

Soluzione

Con le richieste di origine correlate, un sito web può specificare le origini autorizzate a utilizzare il proprio ID RP.

In questo modo, gli utenti possono riutilizzare la stessa passkey su più siti che gestisci.

Per utilizzare le richieste di origine correlate, devi pubblicare un file JSON speciale in un URL specifico https://{RP ID}/.well-known/webauthn. Se example.com vuole consentire alle origini aggiuntive di utilizzarlo come ID RP, deve pubblicare il seguente file in https://example.com/.well-known/webauthn:

{
    "origins": [
        "https://example.co.uk",
        "https://example.de",
        "https://example-rewards.com"
    ]
}

La volta successiva che uno di questi siti effettua una chiamata per la creazione di passkey (navigator.credentials.create) o l'autenticazione (navigator.credentials.get) che utilizza example.com come ID RP, il browser noterà un ID RP che non corrisponde all'origine richiedente. Se il browser supporta le richieste di origine correlata, cerca prima un file webauthn in https://{RP ID}/.well-known/webauthn. Se il file esiste, il browser controlla se l'origine che effettua la richiesta è inclusa nella lista consentita in quel file. In questo caso, si passa alla procedura di creazione o autenticazione della passkey. Se il browser non supporta le richieste di origine correlate, viene generato un errore SecurityError.

Supporto browser

  • Chrome: supportato a partire da Chrome 128.
  • Safari: supportato a partire dalla versione beta 3 di macOS 15 e su dispositivi mobili dalla versione beta 3 di iOS 18.
  • Firefox: In attesa di posizione.

La seguente demo utilizza l'esempio di due siti, https://ror-1.glitch.me e https://ror-2.glitch.me.
Per consentire agli utenti di accedere con la stessa passkey su entrambi i siti, utilizza Richieste di origini correlate per consentire a ror-2.glitch.me di usare ror-1.glitch.me come ID della parte soggetta a limitazioni.

Demo

https://ror-2.glitch.me implementa le richieste di origine correlate per utilizzare ror-1.glitch.me come ID RP, quindi sia ror-1 che ror-2 utilizzano ror-1.glitch.me come ID RP al momento della creazione di una passkey o dell'autenticazione con essa.
Abbiamo implementato anche un database di passkey condiviso su questi siti.

Osserva la seguente esperienza utente:

  • Puoi creare una passkey e autenticarti con essa su ror-2, anche se il suo ID RP è ror-1 (e non ror-2).
  • Una volta creata una passkey su ror-1 o ror-2, puoi autenticarti sia su ror-1 che su ror-2. Poiché ror-2 specifica ror-1 come ID RP, effettuare una richiesta di creazione o autenticazione della passkey da uno di questi siti equivale a effettuare la richiesta su ror-1. L'ID RP è l'unico elemento che lega una richiesta a un'origine.
  • Una volta creata una passkey su ror-1 o ror-2, può essere compilata automaticamente da Chrome sia su ror-1 sia su ror-2.
  • Una credenziale creata su uno di questi siti avrà un ID RP pari a ror-1.
Chrome compila automaticamente su entrambi i siti.
Grazie alle richieste di origine correlate, gli utenti possono utilizzare la stessa credenziale passkey in ror-1 e ror-2. Inoltre, Chrome compilerà automaticamente le credenziali.

Visualizza codice:

Passaggio 1: implementa un database dell'account condiviso

Se vuoi che i tuoi utenti possano accedere con la stessa passkey su site-1 e site-2, implementa un database dell'account condiviso tra questi due siti.

Passaggio 2: configura il file JSON .well-known/webauthn nel sito 1

Innanzitutto, configura site-1.com in modo che consenta a site-2.com di utilizzarlo come ID parte soggetta a limitazioni. Per farlo, crea il file JSON webauthn:

{
    "origins": [
        "https://site-2.com"
    ]
}

L'oggetto JSON deve contenere origini con nome chiave il cui valore sia un array di una o più stringhe contenenti origini web.

Limitazione importante: massimo 5 etichette

Ogni elemento di questo elenco verrà elaborato per estrarre l'etichetta del dominio di primo livello più un sottodominio (eTLD+1). Ad esempio, le etichette eTLD+1 di example.co.uk e example.de sono entrambeexample. Tuttavia, l'etichetta eTLD+1 di example-rewards.com è example-rewards. In Chrome, il numero massimo di etichette è 5.

Passaggio 3: pubblica il file JSON .well-known/webauthn in site-1

Poi, pubblica il file JSON in site-1.com/.well-known/webauthn.

Ad esempio, in Express:

app.get("/.well-known/webauthn", (req, res) => {
  const origins = {
    origins: ["https://site-2.com"],
  };
  return res.json(origins);
});

Qui utilizziamo Express res.json, che imposta già il valore corretto di content-type ('application/json').

Passaggio 4: specifica l'ID parte soggetta a limitazioni desiderato nel sito-2

Nel tuo codebase site-2, imposta site-1.com come ID parte soggetta a limitazioni ovunque necessario:

  • Al momento della creazione delle credenziali:
    • Imposta site-1.com come ID RP nella creazione delle credenziali options che vengono passate alla chiamata navigator.credentials.create frontend e in genere generate lato server.
    • Imposta site-1.com come ID RP previsto, mentre esegui le verifiche delle credenziali prima di salvarlo nel database.
  • Al termine dell'autenticazione:
    • Imposta site-1.com come ID RP nell'autenticazione options che vengono passati alla chiamata frontend navigator.credentials.get e tipicamente generati lato server.
    • Imposta site-1.com come ID RP previsto da verificare sul server, mentre esegui le verifiche delle credenziali prima di autenticare l'utente.

Risoluzione dei problemi

Popup del messaggio di errore in Chrome.
Messaggio di errore in Chrome durante la creazione delle credenziali. Questo errore viene generato se il file ".well-known/webauthn" non è disponibile all'indirizzo "https://{RP ID}/.well-known/webauthn".
Messaggio di errore popup in Chrome.
Messaggio di errore in Chrome al momento della creazione delle credenziali. Questo errore viene visualizzato se è possibile trovare il file ".well-known/webauthn", ma non viene indicata l'origine da cui stai tentando di creare la credenziale.

Altre considerazioni

Condividere le passkey su siti e app mobile

Le richieste di origine correlate consentono agli utenti di riutilizzare una passkey su più siti. Per consentire agli utenti di riutilizzare una passkey su un sito web e un'app mobile, utilizza le seguenti tecniche:

Condividere le password tra i siti

Le richieste di origini correlate consentono agli utenti di riutilizzare una passkey tra i siti. Le soluzioni per condividere le password tra i siti variano in base al gestore delle password. Per Gestore delle password di Google, utilizza Link asset digitali. Safari ha un altro sistema.

Ruolo di gestori delle credenziali e user agent

Questo va oltre il tuo ambito di sviluppatore di siti, ma tieni presente che, a lungo termine, l'ID parte soggetta a limitazioni non deve essere un concetto visibile all'utente nello user agent o nel gestore delle credenziali utilizzato dagli utenti. Gli agenti utente e i gestori delle credenziali devono invece mostrare agli utenti dove sono state utilizzate le loro credenziali. L'implementazione di questa modifica richiederà del tempo. Una soluzione temporanea potrebbe essere la visualizzazione sia del sito web attuale sia del sito di registrazione originale.