実装

RP ID とオリジンの決め方:サブドメインと複数ドメインでパスキーを使う

10 分で読めます

この記事の要点

  • RP ID はオリジンの effective domain と同じか、その登録可能なドメインの接尾辞でなければならず、パスキーは RP ID ごとに作られる。
  • サブドメインが複数あるなら、共通の親ドメイン (例 example.jp) を RP ID にすると、配下のどのサブドメインでも同じパスキーを使える。
  • 別のドメインどうしで共有するには related origin requests (/.well-known/webauthn) があるが、ブラウザの対応とラベル数の上限を確かめて使う。

パスキーの RP ID は、ログインする画面のホスト名と同じか、その親ドメインにします。サブドメインが複数あるサービスでは、共通の親ドメイン (例: login.example.jp と shop.example.jp なら example.jp) を RP ID にすると、どのサブドメインでも同じパスキーが使えます。パスキーは RP ID に結び付いて作られ、あとから RP ID を変えると登録済みのパスキーは使えなくなるため、最初に決め切ることが大切です。別のドメインどうしで共有したい場合は related origin requests という仕組みがありますが、使う前にブラウザの対応を確かめてください。

RP ID とオリジンの関係

WebAuthn では、パスキー (公開鍵の資格情報) は登録したときの RP ID (Relying Party Identifier) に結び付きます。W3C の WebAuthn Level 3 は、RP ID について次のように定めています。

  • RP ID はドメイン名にもとづく値で、スキーム (https://) やポート番号は含まない
  • RP ID は、呼び出し元のオリジンの effective domain と同じか、その「登録可能なドメインの接尾辞」でなければならない
  • オリジンのスキームは https であること。例外は http://localhost
  • 指定しなければ、RP ID はオリジンの effective domain になる

仕様の例では、オリジンが https://login.example.com:1337 のとき、有効な RP ID は login.example.com (既定) と example.com です。m.login.example.com (子のドメイン) や com (公開接尾辞) は使えません。

オリジンは「スキーム + ホスト + ポート」の組で、ブラウザが認証のたびに clientDataJSON に書き込みます。サーバーは、届いたオリジンが自分の許可したものかを確かめます。RP ID は「どの鍵を使えるか」の範囲、オリジンは「どの画面から呼ばれたか」の確認、と分けて考えると整理しやすくなります。

決める前に洗い出すこと

RP ID を決める前に、パスキーでログインさせたい画面をすべて並べます。

確認すること 例
ログインの画面があるホスト名 www.example.jp、app.example.jp
今後ログインを置く予定のホスト名 shop.example.jp (来年追加予定)
別ドメインのサービス example-shop.com
スマホのアプリ iOS / Android のネイティブアプリ
開発・検証の環境 localhost、staging.example.jp

ここで漏れたものは、あとから同じパスキーを使えなくなる可能性があります。

パターン 1: ホスト名が 1 つ

ログインの画面が www.example.jp だけなら、RP ID は www.example.jp でも example.jp でも動きます。迷ったら親ドメインの example.jp を選ぶと、将来 app.example.jp にログインを移したり増やしたりしても、同じパスキーを使い続けられます。

www.example.jp を RP ID にした場合、app.example.jp は www.example.jp の接尾辞ではないので、その鍵を使えません。

パターン 2: 同じ親ドメインのサブドメインが複数

login.example.jp・app.example.jp・shop.example.jp のように、同じ登録可能なドメインの下にある場合は、example.jp を RP ID にします。どのサブドメインから呼んでも、RP ID は自分の effective domain の接尾辞なので、同じパスキーで登録とログインができます。

このときサーバー側では、許可するオリジンを明示的に列挙します。「example.jp で終わるものを全部許可する」のような緩い判定にすると、利用者が投稿できるサブドメインや、使わなくなって放置したサブドメインからの要求まで通してしまいます。

パターン 3: 別のドメインが複数

example.jp と example-shop.com のように登録可能なドメインが違う場合、通常のルールでは同じ RP ID を使えません。取りうる方法は 3 つです。

  1. ログインを 1 つのドメインに集める。 login.example.jp でログインし、ほかのドメインには OpenID Connect などの連携でログイン状態を渡す。Chrome のブログも、多くのサイトにはこの「集約したログインと連携」を勧めています。
  2. related origin requests を使う。 後述します。
  3. ドメインごとに別の RP ID にする。 利用者は各ドメインで別々にパスキーを作ることになります。

related origin requests

WebAuthn Level 3 には、関係するオリジンの間で同じ RP ID を使う仕組み (related origin requests) があります。RP ID のドメインの https://<RP ID>/.well-known/webauthn に、次の形の JSON を application/json で置きます。

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

ブラウザは RP ID が自分のオリジンの接尾辞でないとき、このファイルを取りに行き、自分のオリジンが origins に入っていれば先に進みます。注意点は次のとおりです。

  • 仕様は、対応するブラウザに少なくとも 5 個の「登録可能なオリジンのラベル」を扱うことを求め、上限はブラウザの方針に任せています。ラベルは example.co.uk と example.de ならどちらも example です。web.dev の解説では、Chrome の上限は 5 ラベルです
  • Chrome は 2024 年に、Safari は 18.0 で対応しました。対応していないブラウザでは、このドメインからのパスキーの利用は失敗します
  • 対応しているかは PublicKeyCredential.getClientCapabilities() の relatedOrigins で確かめられます (仕様は対応するブラウザに含めることを推奨しています)

対応していないブラウザの利用者を締め出さないよう、パスワードなど別のログイン手段を残したうえで使います。

スマホのアプリ

ネイティブアプリからウェブと同じパスキーを使うには、ドメインとアプリを結び付ける設定が別に要ります。iOS は Associated Domains (webcredentials)、Android は Digital Asset Links です。どちらも RP ID のドメインにファイルを置くため、アプリを出す予定があるなら、そのファイルを置けるドメインを RP ID にします。

開発環境と検証環境

http://localhost は https でなくても WebAuthn を使える例外です。ただし RP ID が localhost のパスキーは本番の example.jp では使えません。逆も同じです。

検証環境を staging.example.jp に置き、RP ID を本番と同じ example.jp にすると、検証環境で作ったパスキーが本番でも「使える候補」として出てしまいます。検証用のデータベースと本番のデータベースは別なので、選んでもログインは失敗します。検証環境は本番と別の登録可能なドメイン (例: example-staging.jp) にするか、RP ID を staging.example.jp にして分けるのが無難です。

RP ID を変えたくなったら

RP ID を変えると、登録済みのパスキーはすべて使えなくなります。どうしても変える場合は、新しい RP ID で全員にパスキーを作り直してもらう期間が要り、その間はパスワードなど別のログインを残す必要があります。だからこそ、最初の設計で将来のホスト名まで含めて決めておく価値があります。

SealGate で実装する場合

SealGate では、プロジェクトの環境 (本番・テスト) ごとに rp_id と許可するオリジンを設定します。オリジンは https (localhost だけ http) で、rp_id の配下でなければなりません。rp_id は管理画面の環境の設定で変えられますが、変えると登録済みのパスキーは使えなくなります (API キーや MCP からは変えられません)。新しいプロジェクトのテスト環境は rp_id が localhost、オリジンが http://localhost:3000 で始まります。許可していないオリジンからの応答は検証で断り、origin_not_allowed (403) を返します。設定の項目は ドキュメント を参照してください。環境の分け方は テスト環境と本番環境の分け方 で扱います。

よくある質問

RP ID に www を付けるべきですか?

付けなくても動きます。www.example.jp でログインするなら example.jp を RP ID にしておくと、将来ほかのサブドメインにログインを置いても同じパスキーを使えます。

ポート番号が違うと別のパスキーになりますか?

RP ID はポートを含まないので、同じホスト名ならポートが違っても同じ RP ID を使えます。ただしオリジンはポートを含むため、サーバーで許可するオリジンには両方を入れる必要があります。

related origin requests を使えば、どのドメインでも共有できますか?

できません。ブラウザが扱うラベルの数には上限があり、対応していないブラウザもあります。多くの場合は、ログインを 1 つのドメインに集めて連携で渡す方が確実です。

出典

関連する記事

ブログの一覧へ