権限と同意

ユーザーがアカウントの同意ページで見る権限は、デベロッパポータルで設定した必須 / 任意の scope、必須権限の理由とプライバシーポリシー、および認可リクエストで実際に申請した scope によります（サーバーはポータル登録をマージします。後述の「古いクライアントの互換」を参照）。

2026-08-11 プラットフォーム更新：権限は編集可能、必須権限には理由とプライバシーポリシーが必要、サインインのたびに明示確認が必要です。同ディレクトリ「更新」の「2026-08-11 権限と同意のプラットフォーム更新」を参照してください。

互換の案内

• すでに本番の古いクライアントは、今回のプラットフォーム更新のためにコード変更や再リリースは不要です。 ポータルでの権限変更と、サインインのたびに認可確認ページへ入る処理は、アカウント側が行います。
• 新規連携や新規開発のクライアントは、この文書と同ディレクトリの最新ガイドに従ってください（ポータル登録どおりに scope を申請し、必須権限の理由とプライバシーポリシーのリンクを用意し、「毎回認可確認ページが出る」前提でサインイン UX を設計する。黙って認可ページをスキップすることに依存しない）。

開発の原則

単一の profile で個人情報をまとめて取ることはできません。基本プロフィールはフィールド単位の scope に分かれ、ユーザーは同意ページで任意項目を個別にチェックまたは拒否できます。

• 認可リクエストがまだ歴史的な scope=openid profile … なら、サーバーは同意ページを出す前に profile を次の細目へ展開します。
• トークンの scope は、ユーザーが最終的にチェックした細目（および openid / email など）を反映し、まとめた profile には依存しません。
• UserInfo のプロフィール系クレームは安定したフィールド集合です。認可済みは実値（未記入なら空文字など）。未認可は既定のプレースホルダで、実データは漏らしません。「トークンとユーザー情報」を参照。

対応する scope

歴史的な別名（「一括」権限として頼らないでください）：

デベロッパポータルの規則：

製品で本当に使う項目だけを選んでください。プロフィール権限を「全部必須」にしないでください。権限を強制するときは、理由で用途を正直に書いてください（例：認可先でユーザー名として保存する必要がある）。

デベロッパになるには：アカウントに通知用メールが紐づいている必要があります。そうでないとデベロッパポータルにサインインできず、クライアント登録 API も呼べません。

同意ページの動作

1. サインイン後、ユーザーは毎回同意 / 確認ページ（passport.swaymoon.com）へ入ります。「以前に同じ権限を認可済み」でも黙ってスキップしません。
2. アプリ名とアイコン（あれば）を表示します。プライバシーポリシーのリンクがあれば入口があります。ジャンプ前に「このドメインは Swaymoon の管理下にありません…」と出ます。必須権限を申請するときはプライバシーポリシーのリンクが必須です。
3. 権限が変わっていない（そのユーザーの既存同意と比べて）：「サインインを確認」と、すでに認可した項目の要約。ユーザーが確認して続行します。
4. 権限の増減がある：タイトルは「権限が変更されました」。区画は新しい必須 / 新しい任意（新しい必須の横にデベロッパが書いた理由）、もう申請しない、引き続き認可。ユーザーは新しい任意を選び、確認して続行します。確認後、「もう申請しない」権限は同意記録に残りません。
5. 初回認可：必須と任意の区画。必須の横に理由。
6. 必須権限：チェック済みで外せない。注記は「必須」。
7. 任意権限：既定でチェック。ユーザーは項目ごとに外せる。注記は「任意」。
8. 今回 email を付与するのに、アカウントにメールが未紐づけ：先にメールの紐づけと確認を終えないと、認可とコード発行を続けられません（必須 email はすぐ紐づけページへ。任意ならメールのチェックを外して続行も可）。
9. 今回の申請に email があり、アカウントに通知用メールが紐づいているときだけ、メール権限の横にドロップダウンが出ます（既定はプライバシーメール、実メールも選べます）。ファーストパーティアプリにはこの選択肢はありません。
10. 「続ける」では、最終的にチェックした任意 scope とすべての必須 scope だけを付与します（「もう申請しない」は含みません）。
11. 「キャンセル」では認可は完了しません。

認可リクエストの prompt=consent はまだ送れますが、確認ページを強制する必要条件ではなくなりました。本番で「毎回確認」のためにこのパラメータに頼る必要はありません。

古いクライアントの互換

アプリのサインイン時、アドレスに今回申請する権限が付きます（例：scope=openid email）。すでに公開済みのアプリでは、この文字列をすぐ変えられないことがあります。

あとからポータルで権限を必須にしたり、任意を足したりすると、アカウントはサーバー側で自動補完します。古いアプリはすぐコードを変えなくて構いません：

• 必須：ポータルに登録した必須はすべて今回の認可に入ります（アプリのアドレスに書いてなくても）。
• 新しい任意：ユーザーがサインイン済みで、まだその項目を認可していないとき、確認ページに出してチェックできます。すでに認可済みのものは「新規」扱いしません。

例：ポータルが必須「ユーザー名」、任意「アバター」を追加。古いアプリはまだ openid email だけを要求 → ユーザーは「ユーザー名」（必須）と、未認可なら「アバター」（任意）を見ます。

より詳しい説明と対照表は、同ディレクトリ「更新」の「2026-08-11 権限と同意のプラットフォーム更新」です。

新規クライアントは、認可リクエストに必要な scope を明示し、ポータル登録と揃えることを推奨します。

データ削除コールバック

アプリの登録または編集時に データ削除コールバック URL を設定できます（規則と登録入口は同ディレクトリ「登録と設定」の「データ削除コールバック URL」）。ユーザーがプライバシーセンターで「取り消しとデータ削除のリクエスト」を選ぶと、アカウントは次を行います：

1. そのアプリへの認可を取り消す；
2. アプリ担当者のアカウント紐づけメールへ説明メールを送る（コールバックの成否も記載）；
3. コールバック URL が設定されていれば、アカウントのサーバーがそのアドレスへ JSON を POST します（type=swaymoon.passport.data_deletion_request）。ヘッダは X-Swaymoon-Signature: sha256=<hmac> と X-Swaymoon-Request-Id。署名は生のリクエスト本文バイトに対する HMAC-SHA256 です（先に JSON をパースして再シリアライズしてから検証しないでください）。

署名鍵（平文）

その平文を安全に保管してください。アカウント側は同じ平文を webhook 署名鍵として保存します。DB 内の OAuth クライアント認証用 client_secret は、あとから bcrypt など不可逆ハッシュになることがあります。ハッシュや {bcrypt} 付きの保存値で HMAC をしないでください。鍵をローテーションしたら、新しく渡された平文で検証してください。

コールバック URL は HTTPS のみで、ホストは 127.0.0.1 / localhost にできません。ログイン Redirect は loopback のまま使えます（ブラウザ遷移）。削除コールバックはサーバーからの送信なので、ローカル連携では HTTPS トンネルを使ってください。削除を押すときは受信端が稼働している必要があります。

subject（およびあなたが保存したユーザー識別）に従って、ローカルデータを速やかに削除してください。実行できる連携は「Python の最小実行例」の機密クライアント節「データ削除コールバックのデモ」です。

したがって、authorize に並べた任意 scope が、トークンの scope にすべて入るとは限りません。トークン交換後は応答の scope を読み、それに従って UserInfo を解釈してください（未認可フィールドは既定値であり、実データではありません）。

リクエストと設定の関係

• 認可リクエストの scope は、クライアントに登録済みの権限範囲の部分集合であるべきです（登録時に profile があれば、サーバーは対応細目が登録済みと見なします）。サーバーはさらに上記「古いクライアントの互換」どおり、ポータルの必須と新しい任意をマージします。
• 認可リクエストには openid が必須です。
• 細目を直接申請することを推奨します。例：scope=openid name picture。当分は profile を送り続けてもよく、サーバーが展開します。
• ユーザーが同意すると同意台帳に記録されます。アカウントの「プライバシー」ページで見られます。ユーザーガイド「認可済みアプリ」を参照。

製品側とメール

• メールが不要なら email を申請しないでください。
• 登録 / アカウント作成にメールが必要なら email を申請すれば足ります。未紐づけのユーザーは認可フローで紐づけを終え、成功後 UserInfo は使える email を返します。
• ユーザーはプライバシーメールを選ぶことがあります。あなたが受け取るのは送受信できるアドレス 1 件だけで、実メールは渡りません。通常メールとして扱ってください。
• アカウントの主キーは sub、メールは連絡先またはローカルアカウント名に使います。

権限を変える

scope を増減するには：

1. デベロッパポータルで識別子を開き、対象アプリを編集し、ウィザードの「機能」で任意 / 必須権限を調整して保存します（権限変更のためにクライアントを作り直す必要はありません。クライアント種類は依然として相互変更不可です）。
2. 権限を必須にするとき：その権限についてユーザーに見える理由を書き、プライバシーポリシーのリンクが設定済みであることを確認します。
3. ユーザーが同じアプリに次回サインインすると認可ページへ入ります。権限の増減があれば、新規 / もう申請しない / 引き続き の区画を見て、新しい任意を選びます。権限が変わっていなければ、サインインの確認だけで足ります。

すでに本番の古いクライアントは、この能力に合わせるためのコード変更は不要です。 ポータルで保存したあと、サーバーが scope をマージし、認可確認ページを必ず出します。新規クライアントは最新ドキュメントに従ってください。

識別子を削除したあと、またはユーザーが同意を取り消したあと、古いトークンでユーザーデータへアクセスし続けないでください。