Gestire le passkey su più domini e app con l'ID RP

Eiji Kitamura

In WebAuthn e nelle passkey, l'ID relying party (RP ID) specifica l'ambito di una credenziale in base al nome di dominio. Quando crei una passkey, il browser la associa a un ID RP specifico. Il browser impedisce quindi l'utilizzo della passkey su un dominio che non corrisponde o non rientra nell'ambito di questo ID. La definizione corretta dell'ID RP garantisce un'esperienza con le passkey senza interruzioni su sottodomini, origini cross-site e app mobile proprietarie.

Nozioni di base sull'ID RP

L'ID Relying Party (RP ID) è una stringa univoca che identifica il tuo servizio o il tuo sito web. Un ID della parte soggetta a limitazioni deve essere una stringa di dominio. Può essere l'hostname corrente esatto o un dominio principale più ampio, purché sia un eTLD+1 o superiore. Non puoi utilizzare indirizzi IP e suffissi pubblici (eTLD) come ID RP.

Ad esempio, se ospiti il server su https://www.example.com, puoi utilizzare example.com o www.example.com come ID RP, a seconda delle esigenze specifiche. La seguente tabella mostra esempi di ID RP consentiti a seconda dell'host di origine:

Host di origine ID parte soggetta a limitazioni consentito (eTLD+1)
https://login.example.com example.com o login.example.com
https://example.com:8080 example.com (i numeri di porta sono esclusi)
https://mobile.example.co.jp example.co.jp o mobile.example.co.jp
https://sub.project.org.uk project.org.uk o sub.project.org.uk
https://user.github.io user.github.io (github.io è un eTLD)
https://myapp.pages.dev myapp.pages.dev (pages.dev è un eTLD)
http://localhost localhost (un'eccezione al requisito HTTPS)

Il browser lega crittograficamente le passkey all'ID RP quando le crei. Per utilizzare una credenziale, l'origine della richiesta di autenticazione deve corrispondere all'ID RP.

Quando utilizzi un eTLD+1 come RP ID, la passkey funziona su tutti i sottodomini correlati. Ad esempio, un ID RP di example.com funziona per https://login.example.com e https://shop.example.com. Un ID RP più specifico come login.example.com funziona sulla sua origine esatta, ma non su https://shop.example.com.

ID RP nei contesti cross-site

Se il tuo servizio si estende su più eTLD+1 (ad esempio example.com e example.co.jp), si tratta di una configurazione cross-site. Gli ID RP standard non supportano le configurazioni cross-site.

Per condividere le passkey tra siti distinti, utilizza le richieste di origine correlate (ROR). ROR ti consente di condividere le passkey tra siti distinti perché il client (browser) riconosce origini diverse come parte dello stesso servizio logico.

Requisiti per ROR:

  • Scegli un ID RP:devi scegliere un ID RP e utilizzarlo in tutti i siti.
  • Ospita un file di configurazione:il dominio ID RP principale deve ospitare un file di configurazione all'indirizzo /.well-known/webauthn che elenca le origini autorizzate.
  • Mantieni la coerenza:anche se l'utente si trova su https://www.example.co.jp, il rpId nella chiamata WebAuthn deve essere quello principale (ad esempio, example.com) sia durante la creazione sia l'autenticazione.

Esempio di ROR per l'ID parte soggetta a limitazioni example.com: https://example.com/.well-known/webauthn

{
  "origins": [
    "https://www.example.co.jp",
    "https://shop.example"
  ]
}

Per ulteriori informazioni sui dettagli di implementazione delle richieste di origine correlata, consulta Consentire il riutilizzo delle passkey nei tuoi siti con le richieste di origine correlata

ID parte soggetta a limitazioni nelle app mobile

Le applicazioni mobile possono utilizzare le passkey associandosi a un dominio web. Per stabilire questa relazione, devi ospitare un file di verifica sul tuo server.

Android Credential Manager richiede un file Digital Asset Link (DAL) sul dominio dell'ID RP da associare all'app.

  • Hosting:ospita il file all'indirizzo https://<RP ID>/.well-known/assetlinks.json.
  • Verifica:verifica origin in clientDataJSON. Per Android, si tratta di una stringa come android:apk-key-hash:<hash>.

Esempio di DAL per l'RPID example.com (ospitato su https://example.com/.well-known/assetlinks.json)

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.google.credentialmanager.sample",
      "sha256_cert_fingerprints": [
        "4F:20:47:1F:D9:9A:BA:96:47:8D:59:27:C2:C8:A6:EA:8E:D2:8D:14:C0:B6:A2:39:99:9F:A3:4D:47:3D:FA:11"
      ]
    }
  }
]

Per maggiori informazioni, vedi Configurare Digital Asset Links tra la tua app e il tuo sito web.

iOS: Associated Domains

Le piattaforme Apple richiedono un file apple-app-site-association (AASA) sul dominio RP ID da associare all'app.

  • File AASA: host https://<RP_ID>/.well-known/apple-app-site-association.
  • Diritti:aggiungi webcredentials:<app info> ai diritti dell'app.

Esempio di AASA per l'ID parte soggetta a limitazioni example.com: https://example.com/.well-known/apple-app-site-association:

{
  "webcredentials":
    {
      "apps": ["EXAMPLE123.com.example.passkey"]
    }
}

Per saperne di più, consulta Connessione a un servizio con passkey nella documentazione per sviluppatori Apple.

Riepilogo

L'ID RP determina dove gli utenti accedono alle proprie passkey. Tieni presente questi punti durante l'implementazione:

  • Gerarchia e sottodomini: l'ID RP deve essere una stringa di dominio (eTLD+1 o superiore). L'utilizzo di un dominio più ampio come example.com consente alle passkey di funzionare in tutti i sottodomini (ad esempio, login.example.com e shop.example.com).
  • Soluzioni cross-site: utilizza le richieste di origine correlata (ROR) per i servizi che si estendono su più eTLD+1. Per questa operazione sono necessari un ID RP e un file di configurazione in /.well-known/webauthn.
  • Integrazione mobile: stabilisci una relazione verificata tra il tuo sito web e le tue app mobile utilizzando un file Digital Asset Links (DAL) in /.well-known/assetlinks.json per Android e un file apple-app-site-association (AASA) in /.well-known/apple-app-site-association per iOS.

Scopri di più