Passkeys über mehrere Domains und Apps hinweg mit RP ID verwalten

Eiji Kitamura

Bei WebAuthn und Passkeys wird der Umfang von Anmeldedaten durch den Domainnamen angegeben, der als Relying Party-ID (RP-ID) bezeichnet wird. Wenn Sie einen Passkey erstellen, verknüpft der Browser ihn mit einer bestimmten RP‑ID. Der Browser verhindert dann die Verwendung dieses Passkeys auf einer Domain, die nicht mit dieser ID übereinstimmt oder nicht in den Geltungsbereich dieser ID fällt. Wenn Sie Ihre RPID richtig definieren, wird ein nahtloses Passkey-Erlebnis über Subdomains, ursprungsübergreifende Websites und eigene mobile Apps hinweg ermöglicht.

Grundlagen der RP-ID

Die Relying Party-ID (RP-ID) ist ein eindeutiger String, der Ihren Dienst oder Ihre Website identifiziert. Eine RP-ID muss ein Domainstring sein. Das kann der aktuelle Hostname oder eine übergeordnete Domain sein, sofern es sich um eine eTLD+1 oder höher handelt. IP-Adressen und öffentliche Suffixe (eTLDs) können nicht als RP-ID verwendet werden.

Wenn Sie Ihren Server beispielsweise unter https://www.example.com hosten, können Sie je nach Bedarf example.com oder www.example.com als RP-ID verwenden. Die folgende Tabelle enthält Beispiele für zulässige RP‑IDs in Abhängigkeit von Ihrem Ursprungshost:

Ursprungshost Zulässige ID der eingeschränkten Partei (eTLD+1)
https://login.example.com example.com oder login.example.com
https://example.com:8080 example.com (Portnummern sind ausgeschlossen)
https://mobile.example.co.jp example.co.jp oder mobile.example.co.jp
https://sub.project.org.uk project.org.uk oder sub.project.org.uk
https://user.github.io user.github.io (github.io ist eine eTLD)
https://myapp.pages.dev myapp.pages.dev (pages.dev ist eine eTLD)
http://localhost localhost (Ausnahme von der HTTPS-Anforderung)

Der Browser verknüpft Passkeys beim Erstellen kryptografisch mit der RP-ID. Damit Anmeldedaten verwendet werden können, muss der Ursprung der Authentifizierungsanfrage mit der RP‑ID übereinstimmen.

Wenn Sie eine eTLD+1 als RP‑ID verwenden, funktioniert der Passkey für zugehörige Subdomains. Beispiel: Eine RP-ID von example.com funktioniert für https://login.example.com und https://shop.example.com. Eine spezifischere RPID wie login.example.com funktioniert für den genauen Ursprung, aber nicht für https://shop.example.com.

ID der eingeschränkten Partei in standortübergreifenden Kontexten

Wenn Ihr Dienst mehrere eTLD+1s umfasst (z. B. example.com und example.co.jp), handelt es sich um eine websiteübergreifende Konfiguration. Standard-RP-IDs unterstützen keine standortübergreifenden Setups.

Wenn Sie Passkeys zwischen verschiedenen Websites teilen möchten, verwenden Sie Related Origin Requests (ROR). Mit ROR können Sie Passkeys zwischen verschiedenen Websites teilen, da der Client (Browser) verschiedene Ursprünge als Teil desselben logischen Dienstes erkennt.

Anforderungen für ROR:

  • Eine RP-ID auswählen:Sie müssen eine RP-ID auswählen und auf allen Websites verwenden.
  • Konfigurationsdatei hosten:Die primäre RP‑ID-Domain muss eine Konfigurationsdatei unter /.well-known/webauthn hosten, in der autorisierte Ursprünge aufgeführt sind.
  • Konsistenz beibehalten:Auch wenn der Nutzer https://www.example.co.jp verwendet, muss der rpId im WebAuthn-Aufruf sowohl bei der Erstellung als auch bei der Authentifizierung der primäre sein (z. B. example.com).

Beispiel für ROR für RP-ID example.com: https://example.com/.well-known/webauthn

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

Weitere Informationen zu den Implementierungsdetails für verknüpfte Ursprungsanfragen finden Sie unter Passkeys auf Ihren Websites mit verknüpften Ursprungsanfragen wiederverwenden.

ID der eingeschränkten Partei in mobilen Apps

Mobile Anwendungen können Passkeys verwenden, indem sie mit einer Webdomain verknüpft werden. Sie müssen eine Bestätigungsdatei auf Ihrem Server hosten, um diese Beziehung herzustellen.

Der Android Credential Manager erfordert eine Digital Asset Link-Datei (DAL) in der RP-ID-Domain, die mit der App verknüpft werden soll.

  • Hosting:Hosten Sie die Datei unter https://<RP ID>/.well-known/assetlinks.json.
  • Bestätigung:Bestätigen Sie die origin in clientDataJSON. Unter Android ist dies ein String wie android:apk-key-hash:<hash>.

Beispiel für DAL für RP-ID example.com (gehostet unter 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"
      ]
    }
  }
]

Weitere Informationen finden Sie unter Digital Asset Links zwischen Ihrer App und Ihrer Website konfigurieren.

iOS: Zugehörige Domains

Für Apple-Plattformen ist eine apple-app-site-association-Datei (AASA) in der RP-ID-Domain erforderlich, um sie mit der App zu verknüpfen.

  • AASA-Datei:Host https://<RP_ID>/.well-known/apple-app-site-association.
  • Berechtigungen:Fügen Sie den App-Berechtigungen webcredentials:<app info> hinzu.

Beispiel für eine AASA für die RP-ID example.com: https://example.com/.well-known/apple-app-site-association:

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

Weitere Informationen finden Sie in der Apple-Entwicklerdokumentation unter Connecting to a service with passkeys.

Zusammenfassung

Die RP‑ID bestimmt, wo Ihre Nutzer auf ihre Passkeys zugreifen. Beachten Sie bei der Implementierung die folgenden Punkte:

  • Hierarchie und Subdomains: Die RP-ID muss ein Domainstring sein (eTLD+1 oder höher). Wenn Sie eine umfassendere Domain wie example.com verwenden, funktionieren Passkeys für alle Subdomains (z. B. login.example.com und shop.example.com).
  • Websiteübergreifende Lösungen: Verwenden Sie ROR-Anfragen (Related Origin Requests) für Dienste, die sich über mehrere eTLDs+1 erstrecken. Dazu sind eine RP-ID und eine Konfigurationsdatei unter /.well-known/webauthn erforderlich.
  • Mobile Integration: Stellen Sie eine bestätigte Beziehung zwischen Ihrer Website und Ihren mobilen Apps her. Verwenden Sie dazu eine Digital Asset Links-Datei (DAL) unter /.well-known/assetlinks.json für Android und eine Apple-App-Site-Association-Datei (AASA) unter /.well-known/apple-app-site-association für iOS.

Weitere Informationen