トークンとユーザー情報 デベロッパ
最終更新：2026年8月15日
トークンとユーザー情報
トークン交換が成功したあと、ID Token の検証、Access Token の使い方、UserInfo が返すクレームの読み方を説明します。
トークンの種類
| トークン | 形態（ポータルアプリ） | 用途 |
|---|---|---|
id_token | JWT、ES256 署名 | ユーザーが認証済みであることをクライアントに証明。pairwise sub などを含む |
access_token | JWT、ES256 署名 | UserInfo など保護リソースの呼び出し。JWKS で検証できる |
refresh_token | 不透明トークン（機密クライアントのみ） | Access Token の更新 |
ディスカバリ文書の id_token_signing_alg_values_supported には ES256 が含まれているはずです。検証用の公開鍵は次から取得します：
GET {ISSUER}/oauth2/jwks
JWKS をキャッシュし、kid で鍵を選んでください。鍵がローテーションしたら JWKS を取り直してください。
ID Token の検証（必須）
少なくとも次を確認します：
- 署名：ES256 + JWKS。
iss：あなたの Issuer と一致（例：https://api-passport.swaymoon.com）。aud：あなたのclient_idを含む。exp/iat：期限切れでないこと。時計のずれに合理的な余裕を見る。nonce（認可リクエストで送った場合）：セッションに保存した値と一致。
ID Token の sub は、あなたのアプリ（チーム）向けの安定したユーザー識別です。ローカルユーザーを紐づける主キーに使ってください。
現在の実装では、email と大半のプロフィール系クレームは UserInfo が正です。ID Token に必ず email や picture があると思わないでください。例外：locale が付与されているとき、ID Token に locale が含まれます（BCP 47、例：zh-CN / zh-TW / en / ja）。認可コールバックで優先言語を読めます。ID Token の sub を検証したあと、Access Token で UserInfo を呼び、残りのクレームを読んでください。
Pairwise sub
デベロッパチームに紐づいたクライアントでは、アカウントは pairwise の主体識別子を使います：
- 同一の自然人ユーザーがあなたのチーム下のアプリに繰り返しサインインすると、
subは同じです。 - 同一ユーザーが別チームのアプリを認可すると、
subは異なります。 - したがって、
subで別アプリや別チームのユーザーを紐づけられると仮定しないでください。メールをsubの代わりに唯一の主キーにしないでください。ユーザーは紐づけメールを変えられます。
UserInfo
GET /userinfo
Host: api-passport.swaymoon.com
Authorization: Bearer ACCESS_TOKEN
このエンドポイントは JSON のクレームを返します。sub は ID Token と同じです（pairwise）。
常に含まれる
| クレーム | 意味 |
|---|---|
sub | pairwise ユーザー識別（openid がある限り） |
プロフィールクレーム：項目ごとの認可 + 既定値
次のクレームは UserInfo 応答に常に現れます（フィールド形状は安定）。実データかどうかは、トークンの scope に対応細目があるかによります（「権限と同意」を参照）。
| クレーム | 必要な scope | 認可済みのとき | 未認可のとき（既定値） |
|---|---|---|---|
name | name | 表示名 | Swaymoon ユーザー |
nickname | nickname | ニックネーム。未設定なら Swaymoon ユーザー | Swaymoon ユーザー |
picture | picture | アバターの HTTPS URL。未設定なら空文字 | "" |
biography | biography | 自己紹介。未設定なら空文字 | "" |
gender | gender | male / female / other。未設定なら空文字 | "" |
birthdate | birthdate | YYYY-MM-DD。未設定なら空文字 | "" |
region | region | 地域コード。未設定なら空文字 | "" |
preferred_username | preferred_username | ユーザー名。未設定なら空文字 | "" |
locale | locale | BCP 47 タグ（zh-CN / zh-TW / en / ja） | "" |
updated_at | いずれかのプロフィール細目 | プロフィール更新時刻（Unix 秒） | 0 |
既定値をユーザーの実プロフィールと見なさないでください。トークンの scope でどのフィールドが認可されたかを判断し、scope にない項目はプレースホルダです。
古いトークンがまとめて profile を含む場合、サーバーは上記のプロフィール細目がすべて認可済みと見なします。
picture（アバター）
picture が付与され、ユーザーがアバターを設定しているとき、UserInfo は絶対 HTTPS URL を返します（Issuer ドメイン。例：https://api-passport.swaymoon.com/media/avatars/…）。ブラウザやサーバーから追加認証なしで取得できます。未設定なら空文字です。
保存するときは次のどちらか（製品に応じて組み合わせも可）：
- URL だけ保存：
pictureURL をローカルのユーザー資料に書き、表示時はアカウントが提供するアドレスをそのまま使います。自前のオブジェクトストレージは不要で、実装は単純です。ユーザーが後からアバターを変えると、古い URL は使えなくなることがあります（ファイル名にランダム部分があります）。サインイン / プロフィール更新時に保存リンクを更新するか、表示前に UserInfo を再読してください。 - ファイルを保存：自前サーバー（または安全なクライアント）でその HTTPS URL を GET し、画像を自前ストレージに書き、ローカルには自前のリソース URL だけ残します。長期的に自社 CDN でホストしたい、オフライン / 切り抜き処理が必要な場合に向きます。合理的なキャッシュとサイズ制限を守り、高頻度で何度も取らないでください。
どちらも本番 Issuer が HTTPS であることが前提です。ローカル連携で Issuer が http://… なら、返る URL も HTTP のことがあります。公開前に本番設定で確認してください。
email
トークンに email があるときだけ返ります：
| クレーム | 意味 |
|---|---|
email | そのユーザーへ連絡できるメール（確認済み） |
email_verified | true（メールを返すとき） |
email が付与されていないとき、上記のメールクレームは応答に含まれません（プロフィール既定値の方針とは異なります）。
同意ページでユーザーは、メール権限を通常メールまたはプライバシーメールとして渡せます：
| ユーザーの選択 | 受け取る email | 実メール |
|---|---|---|
| 通常メール | アカウントに紐づいたメール | そのアドレス |
| プライバシーメール | あなたのアプリ専用の中継アドレス（…@privaterelay.swaymoon.com） | UserInfo や他の OAuth 経路では渡されません。中継宛のメールはアカウントが実メールへ転送します |
どちらの場合も email は普通に受信できるアドレスです。通常メールとして扱ってください（登録、送信、表示）。ユーザーはプライバシーメールを選ぶ可能性があるので、日常の私用メールだと仮定せず、実アドレスを求めたり推測したりしないでください。アカウントの主キーは引き続き sub です。
認可完了にメールが必要な場合： 認可リクエストに email があり、ユーザーがチェック / 必須で付与するとき、アカウントにメールが未紐づけなら、先に紐づけと確認へ案内し、成功してから同意とコード発行を続けます。したがってトークンに email scope があるとき、UserInfo は 常に email と email_verified を含むはずです。任意の email は外して続けることもできます（あなたが必須にしていなければ）。
取り消しとイントロスペクション
- 取り消し：
POST {ISSUER}/oauth2/revoke（RFC 7009 とサーバー実装に従ってトークンを渡します）。 - イントロスペクション：
POST {ISSUER}/oauth2/introspect（機密クライアントはトークン状態を照会できます）。
具体的なパラメータはディスカバリ文書とサーバー応答に従ってください。
アカウント作成の指針
- 検証済みの
subでローカルユーザーを検索または作成します。 - トークンの
scopeでプロフィールフィールドを解釈します。未認可フィールドの既定値は「利用不可」とし、業務プロフィールに書かないでください。 - アバター：先に「HTTPS URL だけ保存」か「ダウンロードして自前保存」かを決めてください。上記
pictureを参照。 - 機密クライアントは
client_secretを安全に保管します。非機密クライアントにシークレットはありません。ユーザーのアカウントパスワードを集めたり保存したりしないでください。 - Access Token の有効期間は短いので、必要に応じて更新してください。ユーザーがサインアウトするとき、製品の必要に応じて Refresh Token を取り消せます。
次のステップ：「権限と同意」を読んでください。連携中に問題があれば「例とトラブルシューティング」を参照してください。