>100 Views
November 17, 26
スライド概要
認証認可とマイクロサービスの設計を任された新任のテックリーダーに向けて、JWT に載せる独自クレームの設計を解説する資料です(149 枚、ノート欄に詳しい解説つき)。主題は標準クレームそのものではなく、組織のあらゆるサービスで共用する独自クレームを、どう設計し、どう流し、どう治めるかです。
・既存のクレームの地図:16 の用途ごとに、標準クレームが意味すること・しないことと、独自クレームが要る隙間
・4 つの IdP の実際:Microsoft Entra ID・Keycloak・Auth0/Okta・Amazon Cognito(2026 年 11 月時点の挙動と最近の変更)
・設計原則:載せるか問い合わせるか、名前空間、型、不変の ID、書き手、サイズ、前方互換
・流れ:発行時フック、入口での内部トークンへの交換、Transaction Tokens、ヘッダーへの転記、証跡
・データ層、有効期限とリフレッシュ、機微情報とログ、AI エージェントの委任、ガバナンス(台帳・契約テスト・変更の手順)
根拠は各スライドに、RFC・OpenID の仕様、NIST(IR 8587・SP 800-63C-4・SP 800-162)・OWASP・デジタル庁の指針、日本語の専門書(『OpenID Connect入門』『デジタルアイデンティティのすべて』『実践 Keycloak』『セキュアAPI』)の章とページで示しています。調査基準日 2026-11-17。
Web スライド・調査メモ: https://github.com/Takenori-Kusaka/jwt-claims-guide
本資料は生成AI(Claude)を使って作成し、筆者が確認して公開しています。
IoT・クラウド・生成AIエンジニア。製造業の現場からクラウド、生成AIまでを横断して15年。組込み開発、無線機器、クラウド基盤の標準化とガバナンス、生成AIの業務実装に携わってきました。現場の課題を選択肢・コスト・影響範囲として示し、意思決定を前進させる設計を専門としています。 スライドは Advanced RAG、AI協調型の開発プロセス(ピットイン方式)、製造業DXなど。 Zenn: https://zenn.dev/takenori_kusaka 発信は個人の見解であり、所属組織の公式見解ではありません。
JWT CLAIM DESIGN GUIDE JWT クレーム設計ガイド 組織のあらゆるサービスで共用する独自クレームを、どう設計し、どう流し、どう治めるか HEADER alg・kid・typ . PAYLOAD iss・sub・aud・exp … と独自クレーム . SIGNATURE 発行者の鍵による署名 対象:認証認可とマイクロサービスの設計を任された、新任のテックリーダー 根拠:IETF・OpenID の仕様/NIST・OWASP・デジタル庁などの指針/日本語の専門書 4 冊(調査基準日 2026-11-17)
この資料のゴールと読み方 「トークンに何を入れるか」を、事故・仕様・運用の根拠つきで説明し、組織の規則として決められる状態を目指す 理解のゴール リーダーとしてのゴール この資料の使い方 • 標準と各社 IdP のクレームの意味と範 囲を説明できる • クレームの台帳と変更の手順を作れる • 本文は要点、ノート欄は詳しい解説 • 発行・伝搬・検証の責任分担を決められる • 前半は地図、後半は設計と運用 • 独自クレームの名前・型・意味の決め方を 説明できる • 新しいクレームの提案を審査できる • 最後に審査の質問とチェックリスト • クレームが事故になる経路を説明できる 凡例 仕様 RFC・OpenID の仕様 伝搬 右上の表示:クレームの一生(定義・発行・伝搬・検証・認可・運用)の 指針 NIST・OWASP・デジタル庁など どこの話か リーダーの視点:判断・説明の観点 書籍 日本語の専門書(章・ページ) スライド下の行:そのスライドの根拠(3 種類) JWT クレーム設計ガイド|組織で共用する独自クレーム 2
定義 発行 伝搬 検証 認可 運用 この資料の主張:クレームは、サービス間の「契約」である 1 つのクレームを、発行者と多数の受け手が同じ意味で読む。決めずに足すと、読み違いが事故になる 誰が書くか • 発行者(iss)。書き込める主体を 1 つに決 める 意味 • 何を表し、何を表さないか 名前 • 衝突しない名前と名前空間 寿命 • いつまで正しいか。変わったらどうなるか 型 • 文字列か配列か。無いときの意味 持ち主と受け手 • 誰が変更を決め、誰が読んでよいか リーダーの視点 クレームの追加・変更は、API の変更と同じ重さで扱う。台帳に載っていないクレームは、どのサービスも頼らない 仕様 RFC 7519 §4(クレームの定義) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-162 §2.4.2(属性の名前・定義・値の正規 化)/IR 8587 §5.2.1.1(必須要素の文書化) 書籍 『デジタルアイデンティティのすべて』(考え方)2.1・15.1 節(ク レームは発行者の言明) 3
定義 発行 伝搬 検証 認可 運用 なぜ難しいか:1 つの発行者、多数の受け手、それぞれの解釈 発行者は 1 つでも、受け手は API・ゲートウェイ・DB・エージェントと増え、ライブラリも言語も違う API サーバー Java・Go・Node… ゲートウェイ クレーム→ヘッダー 発行者 IdP/内部のトークン発行サービ ス サービスメッシュ 照合式(CEL など) 受け手ごとに読み方がずれる • 配列か、空白区切りの文字列か • 数値の ID が、言語によって丸められる • クレームが無いのか、null なのか • ヘッダーに移すと、偽装の余地が生まれる データベース 行単位の制御 バッチ・キュー 利用者がいない時間 ポイント 読み方を受け手に任せない。名前・型・無いときの 意味を発行側で決め、共通の検証部品で読ませる AI エージェント ツール呼び出し 仕様 RFC 7519 §4(理解できないクレームは無視)/RFC 8725 §3(受け手の検証) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-162 §3.2.1.3(定義と意味の文書化)/ OWASP JWT Cheat Sheet 書籍 『セキュアAPI』8.3 節 pp.236–239 4
定義 発行 伝搬 検証 認可 運用 事故の例:署名は正しかった。受け入れてはいけなかった どの事故も、暗号が破られたのではない。どのクレームを、どこまで確かめるかの設計が欠けていた 事例 何が起きたか 欠けていた確認 クレーム設計の教訓 Storm-0558(2023) 個人向けの署名鍵で、企業向けのトークンを偽造。 22 組織と 503 アカウントのメールが読まれた 鍵と発行者の対応。ライブラリが確認して いると思い込んだ 「署名が正しい」と「受け入れてよい」は別。iss と鍵の組を確かめる CVE-2025-55241(2025) Actor token を包む署名なしの代理トークンを、 古い API がテナントを確かめずに受理 発行元のテナント(tid) テナントのクレームは、必ず照合する。代理の トークンにも署名と期限 nOAuth(2023) メールアドレスをキーにしたアプリで、他人のアカウ ントに入れた email が検証済みか。そもそも email は変更できる 変更できる属性をキーにしない。sub(と iss )をキーにする GitHub Actions の sub( 2026 改定) 名前だけの sub は、改名や再作成で別の持ち主に も作れた 名前ではなく不変の ID 名前と ID を対で出し、照合は ID で。区切り 文字も設計する 暗号ではなく「どのクレームを、何と照合するか」が破れた。照合の規則は、ライブラリではなく組織で決める 仕様 OIDC Core §5.7(sub と iss だけが安定) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 CSRB 報告書(2024-03、Storm-0558)/NIST IR 8587 §5.2.1.2(鍵のスコープ) 書籍 『実践 Keycloak』2.4 節 p.24(sub をキーにする) 5
全体の構成 既にあるクレームを知る → 独自クレームを設計する → 流す・読む → 期限と情報を守る → 治める PART 1 PART 2 PART 3 PART 4 基礎 既存の地図 IdP の実際 設計原則 JWT の構造と検証 用途別の標準クレーム Entra・Keycloak・Auth0/Okta・ Cognito 名前・型・識別子・書き手 PART 5 PART 6 PART 7 PART 8 権限の表現 流れ データ層 期限 利用者・サービス・システム、テナント どこで足し、どこで絞るか 行単位の制御と DB 認証 リフレッシュ・失効・非同期 PART 9 PART 10 PART 11 PART 12 機微情報 AI エージェント ガバナンス 実践 最小化・暗号化・ログ 委任・承認・ツール 台帳・契約テスト・変更手順 アンチパターンとチェックリスト 地図(1〜3) 設計と流れ(4〜7) 守りと統治(8〜12) JWT クレーム設計ガイド|組織で共用する独自クレーム 6
用語:この資料での呼び方 同じものを仕様ごとに違う名前で呼ぶ。この資料では次の呼び方に揃える この資料の呼び方 意味 ほかの呼び方 トークン 主に JWT 形式のアクセストークンと ID トークン アサーション(SAML、NIST) クレーム トークンの中の、名前と値の組 属性値、claim 属性 主体が持つ性質。クレームはそれを運ぶ形 attribute 発行者 トークンに署名して発行する主体 IdP、認可サーバー(AS)、STS、内部のトークン発行 サービス 受け手 トークンを検証し、判断に使う側 RP、リソースサーバー(RS)、API 主体 トークンが誰について述べているか。利用者・サービス・エージェント subject、principal PEP/PDP 要求を止める場所/許可するかを判断する場所 ポリシー実施点/判断点 仕様 RFC 7519 §2(用語)/OIDC Core §1.2 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-162 §3(PEP・PDP) 書籍 『デジタルアイデンティティのすべて』(考え方)2.1 節・12.3 節 (pp.194–195) 7
根拠の示し方:仕様・公的な指針・日本語の専門書 各スライドの下に 3 種類の根拠を示す。権威の高い指針を優先し、書籍は章とページで示す 仕様 • RFC 7519(JWT)・8725(安全な扱い) • RFC 9068(アクセストークン)・8693(委 任) 公的な指針 日本語の専門書 • NIST IR 8587・SP 800-63C-4・SP 800-162 • 『OpenID Connect入門』技術評論社 2026(OIDF-J 理事 監修) • OWASP ASVS 5.0・JWT Cheat Sheet • 『デジタルアイデンティティのすべて』オライリ ー 2024(OIDF-J 代表理事 監訳) • OpenID Connect Core 1.0 • デジタル庁 DS-212・DS-511 • Transaction Tokens(草案 11)・MCP 認可仕様 • OpenID Foundation(エージェントの ID 管理) • 『実践 Keycloak』オライリー 2022 • 『セキュアAPI』翔泳社 2026 仕様の状態は 2026-11-17 時点。草案(Transaction Tokens など)は名前や規則が変わりうる 指針 NIST IR 8587(2026-09、CISA 共著)/SP 800-63C-4(2025-07)/SP 800-162/OWASP ASVS 5.0/デジタル庁 DS-212・DS-511 JWT クレーム設計ガイド|組織で共用する独自クレーム 8
PART 1 基礎:JWT の構造と検証 このPartで答えられるようになる問い • JWT の 3 つの部分は、それぞれ何を保証するか • 受け手は、どの順序で何を確かめるか • ID トークンとアクセストークンは、どう違うか • ライブラリに任せて安全か 独自クレームを読む前に、そのトークンを受け入れてよいかを 確かめる。順序と既定値の落とし穴 9
定義
発行
伝搬
検証
認可
運用
JWT の構造:ヘッダー・ペイロード・署名
3 つの部分を Base64URL で符号化し、ピリオドでつなぐ。署名は改ざんを検出するだけで、中身を隠さない
{"alg":"RS256","kid":"2026-11-a","typ":"at+jwt"}
ヘッダー
ペイロード
どう署名したか。受け手は鵜呑みにしない
{"iss":"https://idp.example.com","sub":"u7f3a…","aud":"https://api.example.com","exp":1795…,"https://claims.example.
com/tenant":"t-042"}
クレームの集合。誰でも読める
RSASSA(鍵, ヘッダー.ペイロード)
署名
発行者の鍵で計算。改ざんを検出する
署名は改ざんを検出するが、中身を隠さない。トークンを持つ人は誰でもペイロードを読める
仕様 RFC 7515 §3.1(JWS の形式)/RFC 7516 §3.1(JWE 指針 OWASP JWT Cheat Sheet(署名つき JWT は秘密ではな
)/RFC 7519 §3
い)
JWT クレーム設計ガイド|組織で共用する独自クレーム
書籍 『OpenID Connect入門』4.2.2 節 pp.62–65
10
定義 発行 伝搬 検証 認可 運用 受け手の検証の順序:受け入れてから、クレームを読む どの独自クレームを読むより先に、形式・署名・発行者・宛先・期限・種類を確かめる 1. 形式 2. alg 3. 署名 4. iss ピリオドで 3 部分。JWE と区別 許可リストに入っているか 事前に設定した発行者の鍵で 想定の発行者と完全一致 5. aud 6. exp・nbf 7. typ 8. クレーム 自分が含まれるか 期限内か(ずれは数分まで) トークンの種類(at+jwt など) 必須か、型は正しいか 独自クレームは最後に読む。署名を確かめる前のクレームは、誰でも書ける文字列にすぎない 仕様 RFC 9068 §4(検証手順)/RFC 8725 §3.1・3.8・3.9 ・3.11 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-63C-4 §4.9/IR 8587 §5.2.1.2(使 う前に出どころと完全性を確認)/OWASP ASVS 9.1・9.2 書籍 『OpenID Connect入門』6.2.1・13.8.1 節 pp.86–87, 227/『実践 Keycloak』5.6 節 p.86 11
定義 発行 伝搬 検証 認可 運用 ヘッダーの危険なパラメータ:鍵とアルゴリズムは受け手が決める alg・kid・jku・jwk・x5u はトークンの作り手が書ける。鍵とアルゴリズムは受け手の設定で決める ヘッダー 本来の意味 攻撃 受け手の規則 alg 署名のアルゴリズム none にする。RS256 を HS256 に変える 許可リストで照合。鍵ごとにアルゴリズムを 1 つに 固定 kid 鍵を探すヒント パスや SQL に混ぜて注入する 事前に取得した鍵の一覧の中だけで探す jku・x5u 鍵の場所(URL) 攻撃者の鍵の場所を指す(SSRF にもなる) たどらない。たどるなら許可リスト jwk・x5c 鍵そのもの 自分の鍵を埋め込み、自分で署名する 埋め込まれた鍵を信頼しない typ トークンの種類 別の目的のトークンを持ち込む 期待する種類と照合する リーダーの視点 「none を禁止する」ではなく「許可したものだけ通す」。禁止リストは、大文字小文字の違いなどで回避される 仕様 RFC 8725 §2.1・3.1・3.10/8725bis(草案 10) §2.11・§3.1 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP JWT Cheat Sheet/ASVS 9.1.1〜9.1.3/ NIST SP 800-228 REC-API-11 書籍 『実践 Keycloak』14.5.2 節 p.295 12
定義 発行 伝搬 検証 認可 運用 ID トークンとアクセストークン:宛先が違う ID トークンはクライアントに「誰がログインしたか」を伝える。API に渡すのはアクセストークン ID トークン アクセストークン 仕様 OpenID Connect Core OAuth 2.0(JWT 形式なら RFC 9068) 宛先(aud) ログインを依頼したクライアント API(リソースサーバー) 伝えること 誰が、いつ、どうやってログインしたか このクライアントに、どの範囲を許した か typ 多くは JWT at+jwt 使う場所 クライアントでのログインの確認 API での認可 形式 必ず JWT JWT か、中身のない参照型 仕様 OIDC Core §2(ID トークン)/RFC 9068 §2.1・§5( typ で区別) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP ASVS 9.2.2・10.5.5/Identity Propagation Cheat Sheet よくある誤り • ID トークンを API に送る • API が aud を確かめない • 別のクライアント向けのトークンを受け入 れる リーダーの視点 独自クレームを「ID トークンに足すか 、アクセストークンに足すか」は、誰が 読むかで決める。API が読むならアク セストークン 書籍 『OpenID Connect入門』4.3 節 pp.67–69/『実践 Keycloak』4.5 節 p.54 13
定義 発行 伝搬 検証 認可 運用 自己完結型と参照型:クレームを運ぶか、問い合わせるか JWT は受け手が手元で検証できるが、発行後の変更が届かない。参照型は毎回問い合わせる 自己完結型(JWT) 参照型(イントロスペクション) • 利点:受け手が手元で検証。速く、発行者が止まっても動く • 利点:取り消しがすぐ反映される • 欠点:取り消し・属性の変更が、期限まで届かない • 欠点:毎回の問い合わせで遅く、発行者に依存する • 向く:短い寿命で、安定した属性だけを運ぶ • 向く:すぐ取り消す必要がある、重要な操作 リーダーの視点 自己完結型のトークンのクレームは「発行時点の写し」。変わりやすい属性を載せるかは、寿命と取り消しの要件で決める(Part 4・8) 仕様 RFC 7662(イントロスペクション)/RFC 9701(JWT 形式 の応答) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-63C-4 §4.11.1/IR 8587 §5.3.1.2( 失効の伝え方) 書籍 『OpenID Connect入門』4.2.3・6.2.2 節 pp.66–67, 87–88/『実践 Keycloak』5.6 節 p.84 14
定義 発行 伝搬 検証 認可 運用 ライブラリの既定値は、安全側とは限らない aud を既定で確かめないもの、exp が無くても通すもの。ライブラリごとに違う ライブラリ aud・iss exp 注意 jsonwebtoken(Node) 値を渡したときだけ検証 あれば検証。無くても通る algorithms を指定する jose(panva) 値を渡したときだけ検証 あれば検証。無くても通る none は常に拒否 golang-jwt v5 値を渡したときだけ検証 あれば検証。無くても通る WithExpirationRequired を使う Spring Security aud は既定で検証しない 既定で検証 audiences を設定する Microsoft.IdentityModel 既定で検証 既定で必須(ずれ 5 分) 署名鍵自体の確認は既定で無効 PyJWT aud があり audience 未指定ならエラ ー あれば検証。無くても通る algorithms の指定が必須 リーダーの視点 検証の設定を各サービスに任せない。許可するアルゴリズム・発行者・宛先・必須クレームを固定した、組織共通の検証部品を配る 仕様 RFC 8725 §3.1(ライブラリは許可アルゴリズムを指定させ る) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 CSRB 報告書 勧告 6(共通の認証ライブラリ)/NIST IR 8587 §5.2.1.2 書籍 『セキュアAPI』8 章(API 認証と認可の実装) 15
定義 発行 伝搬 検証 認可 運用 攻撃の型:どれも「確かめなかったクレーム」から入る JWT への攻撃の多くは、暗号ではなく、検証の抜けを突く。独自クレームも同じ経路で狙われる 攻撃 抜けていた確認 対策 alg を none にする、RS256 を HS256 に変える ヘッダーの alg アルゴリズムの許可リスト。鍵ごとに固定 別のサービス向けのトークンを差し替える aud aud に自分が含まれるかを必ず確かめる 別のテナントのトークンを持ち込む iss・テナントのクレーム テナントごとの発行者・鍵と照合する ID トークンや別目的のトークンを持ち込む typ 種類ごとに検証規則を分ける 古いトークンを使い続ける exp・nbf、時刻のずれ exp を必須にし、ずれは数分まで 同名のクレームを重ねる、JSON の解釈の差を突く クレームの一意性 重複を拒否するパーサを使う 独自クレームも同じ経路で狙われる。テナントや権限を表すクレームは、受け入れの確認を全部通った後にだけ読む 仕様 RFC 8725 §2(脅威)/RFC 7519 §4(重複クレームの 扱い) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP JWT Cheat Sheet・API Security Top 10 2023(API2) 書籍 『OpenID Connect入門』13.8・13.9.6 節 pp.225–229 /『セキュアAPI』4 章 16
PART 2 既存のクレームの地図:独 自クレームを作る前に このPartで答えられるようになる問い • どのクレームが既に標準で決まっているか • 既存のクレームは、何を意味し、何を意味しないか • 標準の登録簿にない用途はどれか • 独自クレームを作る前に、どこを探すか 同じ意味のクレームを作り直さない。既存の名前と衝突させ ない。既存のクレームが「意味しないこと」に隙間がある 17
定義 発行 伝搬 検証 認可 運用 登録クレーム:7 つの意味と、意味しないこと RFC 7519 が定める基本の 7 つ。どれも意味は狭く、受け手の確認の仕方まで決まっている クレーム 意味 型 意味しないこと・注意 iss トークンを発行した主体 文字列( StringOrURI) 完全一致で比べる。部分一致で受け入れない sub 発行者の中で一意な主体 文字列( StringOrURI) 発行者をまたいで一意ではない。iss と組で使う aud 受け手 文字列か配列 自分が含まれなければ拒否。両方の形を受け付ける exp この時刻以降は受け入れない 数値(秒) ずれの許容は数分まで nbf この時刻より前は受け入れない 数値(秒) 同上 iat 発行した時刻 数値(秒) 認証した時刻ではない(auth_time は別) jti トークンの一意な ID 文字列 発行者をまたいでも衝突させない。リプレイ検知に使える RFC 9068 のアクセストークンでは iss・exp・aud・sub・client_id・iat・jti が必須。これらと同じ意味の独自クレームを別名で作らない 仕様 RFC 7519 §4.1/RFC 9068 §2.2(必須クレーム) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP JWT Cheat Sheet/NIST SP 800-63C-4 §3.4 書籍 『セキュアAPI』7.2.2 節 pp.194–195 18
定義
発行
伝搬
検証
認可
運用
名前の 3 区分:登録名・公開名・私的名
新しい名前は IANA に登録するか、自分が管理する名前空間を含む「公開名」にする
登録名(Registered)
公開名(Public)
私的名(Private)
• IANA の登録簿に載った名前
• 衝突しない名前を含む
• 発行者と受け手の合意だけ
• 登録には仕様と専門家の審査が要る
• 自社ドメインの URI など
• 登録も衝突回避もしない
• 組織固有のクレームは通常対象外
• 組織で共用する独自クレームの基本形
• 閉じた範囲だけで、慎重に使う
{
"iss": "https://idp.example.com",
"sub": "u-7f3a…",
"roles": ["approver"],
// 登録名
"https://claims.example.com/tenant": "t-042", // 公開名
"dept": "sales"
// 私的名(避ける)
RFC 9068:登録名で意味が十分に表せる属性
は、その登録名を使う(SHOULD)。まず登録簿
を探し、無ければ公開名を作る
}
仕様 RFC 7519 §4.1–4.3・§10.1/RFC 9068 §2.2.2
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 NIST SP 800-162 §2.4.2(属性の名前を正規化し中央で
管理)
書籍 『デジタルアイデンティティのすべて』10.2.1 節 p.136(識別
子の名前空間の考え方)
19
定義 発行 伝搬 検証 認可 運用 用途別の地図:16 の用途と既存のクレーム 多くの用途には既に登録クレームがある。登録簿にないのは、テナント・同意と目的・端末と場所 1 利用者の識別 2 テナント・組織 3 役割・グループ・資格 4 権限 iss+sub、sub_id 登録なし(tid・org_id は各社) roles・groups・entitlements scope 5 細かい認可 6 認証の強さ 7 セッション 8 委任 authorization_details acr・amr・auth_time sid act・may_act 9 クライアント 10 鍵の保持 11 イベント・相関 12 同意・目的 client_id・azp cnf events・toe・txn 登録なし 13 ロケール・プロフィール 14 端末・IP・場所 15 本人確認済みの属性 16 失効状態 locale・name ほか 登録なし(ipaddr は各社) verified_claims status・status_list(草案) 標準の登録クレームがある 名前は登録済み。値の語彙・構造は組織で決める 仕様 IANA JSON Web Token Claims(2026-10-28 版)/ RFC 9068 §2.2 JWT クレーム設計ガイド|組織で共用する独自クレーム 汎用の登録クレームがない(独自クレームの候補) 指針 NIST SP 800-162 §3.2.1.3(属性の定義と意味の文書化 書籍 『OpenID Connect入門』4.2.2・4.3 節 pp.62, 67 ) 20
定義 発行 伝搬 検証 認可 運用 利用者の識別:安定したキーは iss と sub の組だけ email・preferred_username・name は変わり、再利用されうる。一意のキーにしない(MUST NOT) クレーム 意味 意味しないこと sub 発行者の中で一意。再割り当てし ない 発行者をまたいだ一意性。ペアワイズ ならアプリごとに違う 独自クレームの隙間 • 複数の IdP をまたぐ社内の安定キー • ペアワイズの sub をまたぐ突き合わせ email 連絡先のメールアドレス 一意のキー。別人に再利用されうる preferred_username・ name 表示用の名前 一意のキー。変わらないこと sub_id(RFC 9493) 形式つきの構造化された識別子 sub と別の主体。sub と組み合わせ て主体を決めること oid(Entra、各社独自) テナント内でアプリをまたいで同 じ 別のテナントでも同じ値 • 例:社員番号(変わらない ID) メールアドレスをキーにすると、再利 用や変更で別人と取り違える(冒頭の 事故例、スライド 5 の nOAuth) 名前と ID を分ける。キーは「iss+sub」か、組織が決めた変わらない ID だけ 仕様 OIDC Core §2・§5.7・§8/RFC 9493 §4.1 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-63C-4 §3.4・§4.9/OWASP ASVS 10.5.2 書籍 『実践 Keycloak』2.4 節 p.24/『デジタルアイデンティティ のすべて』(考え方)10.2.2 節 p.139 21
定義 発行 伝搬 検証 認可 運用 テナント・組織:登録クレームはなく、各社が独自 テナントを表す標準のクレームはない。先に aud と iss をテナントごとに分けられないかを考える IdP クレーム 入る条件と注意 Entra ID tid テナントの GUID。iss と突き合わせ、データのキ ーに含める Auth0 org_id(org_name) Organizations 経由のログイン時。org_id で検 証する organization organization スコープを要求したとき。別名を キーにしたオブジェクト 標準の代わりの手段 • aud を分ける:テナントを含む resource の URI(RFC 8707) • iss を分ける:テナントごとの発行者と鍵。鍵と 発行者を照合(RFC 8725 §3.8) • 独自クレーム:上の 2 つと組み合わせて使う Keycloak "tid": "9c1e…" // Entra "org_id": "org_9a…" // Auth0 "organization": { "acme": { "id": "…" } } // Keycloak テナントは独自クレームの正当な候補。ただしクレームだけで分離せず、aud・iss・鍵の分離と重ねる(Part 5) 仕様 RFC 8707 §3/RFC 8725 §3.8(鍵は発行者のもの) /IANA JWT Claims(tenant 相当なし) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.2.1.2(テナント単位の鍵)/CSRB 勧 告6 書籍 『実践 Keycloak』1.4.1.1・4.3 節 pp.11, 46(レルムと iss ) 22
定義 発行 伝搬 検証 認可 運用 役割・グループ・資格:名前は標準、語彙は組織で RFC 9068 は roles・groups・entitlements の名前を勧める。値の語彙と認可モデルは定めない groups roles entitlements 意味しないこと • 所属するグループ • 利用者が何者か • 利用者が持つ権利 • 同じ文字列が、どの受け手でも同じ意味 • 直接・入れ子・動的 • 例:Student • 語彙も構文もない • IdP の roles が同じ位置・意味 • 認可モデルは定めない • 語彙も構文もない • SAML は URI の先例あ り • グループが全件入っていること(Part 3) "roles": [ "https://claims.example.com/roles/billing-admin" ], "groups": ["g-1203", "g-2210"] 名前は roles・groups・entitlements を使い、値の語彙を組織の名前空間で定義する。これが独自に決める部分 仕様 RFC 9068 §2.2.3.1/RFC 7643 §4.1.2/ eduPerson 2020-01 §2.2.2 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP JWT Cheat Sheet(roles・groups は別発行者 の詐称に注意) 書籍 『実践 Keycloak』8.2・8.3.1 節 pp.146–152 23
定義 発行 伝搬 検証 認可 運用 権限:scope はクライアントに許した範囲 scope は利用者の全権限ではない。取引単位の細かい認可は authorization_details で表す authorization_details(RFC 9396) scope • 形:空白区切りの文字列(Okta は scp という配列) • 意味:クライアントに委ねた範囲 • 規則:各スコープは aud のリソースにとって意味を持つ "authorization_details": [{ "type": "https://claims.example.com/rar/payment", "actions": ["initiate"], "locations": ["https://api.example.com/payments"], "instructedAmount": { "currency": "JPY", "amount": "120000" } }] • 意味しない:利用者が持つ全権限 • type は必須。自分が管理する URI を勧める • 受け手向けに絞って入れる • 同じ API では scope か authorization_details の一方( RECOMMENDED) リーダーの視点 独自の「権限オブジェクト」を作る前に、authorization_details の type として定義できないかを検討する(Part 5) 仕様 RFC 9068 §2.2.3/RFC 8693 §4.2/RFC 9396 §2・§3.1・§9.1 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.2.1.1(scope と RAR) 書籍 『OpenID Connect入門』5.2.1 節 pp.74–75 24
定義 発行 伝搬 検証 認可 運用 認証の強さとセッション:acr・amr・auth_time・sid amr は使った方式、acr は保証の水準。値は認証時に固まり、リフレッシュでは変わらない 足りないときの応答(RFC 9470) クレーム 意味 意味しないこと acr 認証の保証クラス。値の意味は合意で決 める 合意のない値どうしの比較 amr 使った認証方式の配列(pwd・otp・ mfa…) 保証の水準(mfa ≠ 高い保証) auth_time 利用者が認証した時刻 発行時刻(iat)。再認証なしの再発 行がある sid IdP 側のセッションの ID アプリのセッションの ID ID トークンの exp トークンの有効期限 ログインセッションの寿命 HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer error="insufficient_user_ authentication", acr_values="…/loa/2", max_age=300 値は認証時に固まり、リフレッシュでも変わ らない(RFC 9068) 独自に決めるのは acr の値の語彙。どの値がどの水準かを台帳で定め、amr の mfa を水準の代わりにしない 仕様 OIDC Core §2/RFC 8176 §2/RFC 9068 §2.2.1 /RFC 9470 §3 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-63C-4 §2.5・§4.9(xAL と認証時刻) 書籍 『OpenID Connect入門』4.3 節 p.67 25
定義
発行
伝搬
検証
認可
運用
委任とクライアント:sub は代理される主体
act は今の行為者、may_act は代理してよい者。client_id はトークンを要求したクライアント
{
"sub": "u-7f3a…",
"client_id": "portal",
"act": {
"sub": "svc-orders",
"act": { "sub": "agent-17" }
}
// 代理される利用者
// 今の行為者
// 以前の行為者
クレーム
意味
注意
act
今の行為者(入れ子で履歴
)
認可は最上位と最も外側の act
だけ
may_act
代理してよい者の表明
交換時に認可サーバーが使う
client_id
要求したクライアント
RFC 9068 で必須
azp
ID トークンの発行先
Keycloak は AT にも入れる
}
独自クレームの隙間
sub だけを見ると、エージェントや別サービス経由の操作を本
人の操作と区別できない。act の中に権限を入れない(Part
5・10)
• 委任の理由・承認者(act の外に置く)
• 利用者のトークンかアプリのトークンかの明示
仕様 RFC 8693 §4.1–4.4/RFC 9068 §2.2/OIDC
Core §2(azp)
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 OIDF「Agentic AI のアイデンティティ管理」§2.11
書籍 『OpenID Connect入門』4.2.2 節 p.62(Keycloak は
azp)
26
定義 発行 伝搬 検証 認可 運用 鍵・イベント・本人確認:既存の構造を使う 端末への結び付けは cnf、相関の ID は txn、確認済みの属性は verified_claims が既にある cnf(鍵の保持) events・toe・txn • 提示者が特定の鍵を持つことの確認 • セキュリティイベント(RFC 8417) • DPoP は jkt、mTLS は x5t#S256 • txn は他の JWT でも使える相関 ID • 入れる鍵は 1 つだけ • イベントトークンには exp を入れない(推奨 ) • 独自の端末の結び付けを作らない verified_claims • OpenID Identity Assurance(2024 Final、2026-07 正誤表) • verification と確認済みの claims の組 • 未確認の given_name 等と混同させない email_verified が true でも、意味は「確認した時点でそのメールを管理していた」だけ。本人確認済みを意味しない 独自の名前で作り直す前に、既存の構造で表せないかを確かめる 仕様 RFC 7800 §3.1/RFC 8417 §2.2/OpenID IDA Schema 1.0 §5 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-63C-4 §3.14(bearer と鍵の保持) 書籍 『セキュアAPI』7.5 節 pp.212–216(cnf) 27
定義 発行 伝搬 検証 認可 運用 標準の登録簿にないもの:テナント・同意・端末 似た名前の登録クレームはあるが、意味が違う。ここが独自クレームの正当な隙間 用途 似た登録クレーム(別物) 各社の独自クレーム 独自に作る前に テナント・組織 なし tid・org_id・organization aud・iss の分離で足りるか 同意・目的 rdap_allowed_purposes(RDAP 専用) オープンバンキングの同意 ID など scope・authorization_details で表せるか 端末・IP・場所 location(証明を出す機器の位置)、cdniip( CDN 用) Entra の ipaddr など 変わる状態は PEP で都度評価できないか( Part 6) 同じ名前、違う意味 • purpose がトークンの種類を表す製品もある 仕様 IANA JWT Claims(2026-10-28 版)/RFC 9711 §4.2.10/RFC 9246 §2.1.10 JWT クレーム設計ガイド|組織で共用する独自クレーム 名前の表記揺れ • 仕様書の中で - と _ が揺れ、相互運用の不具合に 指針 NIST SP 800-162 §2.4.2(属性の名前と定義を管理) 書籍 『デジタルアイデンティティのすべて』(考え方)15.2 節 p.262 (スキーマの統一) 28
定義 発行 伝搬 検証 認可 運用 SAML の属性と JWT:対応表は規範ではない 概念の対応はあるが、規範として定めた対応表は見当たらない。ブローカーでの写し方を組織で決める 概念 SAML JWT 注意 発行者・宛先 Issuer・AudienceRestriction iss・aud 一般的な対応 主体 NameID sub メール形式の NameID を sub にしない 識別子の属性 subject-id・pairwise-id sub(public・pairwise) subject-id は大文字小文字を無視して比べる 認証の方式 AuthnContextClassRef acr か amr Entra は amr に対応づけ。名前は acr に近い テナント(Entra) …/identity/claims/tenantid tid 同じ属性が SAML では URI 名 外部の IdP IdP マッパー Keycloak のユーザー プロトコルマッパー トークン SAML の属性 属性・ロールに取り込む 属性・ロール 社内の名前のクレームに 組織の公開名 仕様 SAML 2.0 Profiles §8/SAML Subject ID Attributes §3.3–3.4 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-162 §3.2.3.2(組織間の属性の対応づけ) 書籍 『実践 Keycloak』10.3 節 pp.198–199、解答 p.318 29
定義 発行 伝搬 検証 認可 運用 独自クレームを作る前の確認:4 つの場所を探す 登録簿・仕様・IdP の文書・組織の台帳の順に探し、無いときだけ名前空間つきで作る 1. IANA の登録簿 2. 仕様の構造 3. IdP の文書 4. 組織の台帳 5. 作る 意味が合えば登録名を使 う type や format など、値 の中で拡張できないか 既存のクレーム、予約名、 衝突時の挙動 同じ意味のクレームが別名 で無いか https://claims.examp le.com/ の下に 作るときに書き残すこと この先の Part • 何を意味し、何を意味しないか • Part 3:各 IdP の予約名と衝突時の挙動 • 近い既存クレームとの違い • Part 4:名前・型・識別子の決め方 • 探した場所と、使わなかった理由 • Part 11:クレームの台帳と変更の手順 仕様 RFC 7519 §4.2・§10.1/RFC 9068 §2.2.2 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 デジタル庁 DS-212 §3.2.3(属性名・型・値を事前に標準化 ) 書籍 『デジタルアイデンティティのすべて』(考え方)21.2 節 pp.380–381 30
PART 3 4 つの IdP の実際 このPartで答えられるようになる問い • 利用者の安定したキーは、IdP ごとにどれか • アクセストークンの aud は、どう決まるか • 独自クレームは、どこで入れ、何が禁じられているか • 古い理解のままだと、どこで誤るか 同じ名前のクレームでも、IdP ごとに位置・形・意味が違う。 2026 年 11 月時点の挙動と、最近の変更 31
定義 発行 伝搬 検証 認可 運用 4 つの IdP の比較:同じ用途、違うクレーム 利用者のキー、aud、ロールの位置、独自クレームの入れ方は、IdP ごとにすべて違う 観点 Entra ID Keycloak Auth0/Okta Cognito 利用者のキー oid+tid(sub はアプリごと) sub Auth0:sub/Okta:AT は uid sub(username は一意でない) テナント tid organization(レルムは iss) Auth0:org_id なし(プールは iss) AT の aud API の App ID URI か client ID 自動では入らない Auth0:audience 指定時/Okta: Custom AS 既定は無し。resource 指定時のみ ロール・グループ roles・scp・groups・wids realm_access・ resource_access Auth0:permissions/Okta: groups・scp cognito:groups・scope 独自クレーム 任意クレーム・クレームの対応づけ プロトコルマッパー・クライアントスコー プ Auth0:Actions/Okta:Custom AS のみ 発行前フック V1〜V3・custom: 属 性 acr・amr acr は v1 のみ(0/1)・acrs acr(LoA マッパー) Okta:acr・amr・auth_time 固定 4 段階(順次提供) トークン交換 OBO(jwt-bearer) Standard V2(正式)・委任( preview) OBO(RFC 8693) RFC 8693(2026-11〜) 仕様 Entra/Keycloak/Auth0/Okta/Cognito の公式文 書(2026-11 時点) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-63C-4 §3.4(iss と sub の組) 書籍 『セキュアAPI』7.7 節 p.219(IdP ごとのロールの運び方) 32
定義
発行
伝搬
検証
認可
運用
Entra ID:キーは oid と tid、sub はアプリごと
sub はアプリごとに値が違う。サービス間で共有するキーは oid+tid。iss は tid で照合する
{
"aud": "<API の client ID>",
"tid": "9c1e…",
// テナント
"oid": "3f2b…",
// テナント内で共通
"sub": "Kx9…",
// アプリごとに違う
"scp": "Orders.Read",
// 空白区切り
"azp": "<クライアントのアプリ ID>",
"upn": "[email protected]" // 認可に使わない
識別子
• 共有のキーは oid+tid、tid をデータのキーに
• email・preferred_username・upn で認可しない
}
マルチテナント
• issuer のテンプレートを tid で置き換えて照合
• tid が保存データのテナントと一致するか確かめる
Microsoft Graph 向けなど、自分の API 宛てでないトークン
は検証も受け入れもしない(独自形式。confused deputy にな
る)
組織のキーは oid+tid に揃える(Part 5)
仕様 Entra:access-token-claims-reference/claimsvalidation/access-tokens
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 NIST SP 800-63C-4 §3.4・§4.9(IdP をまたいで一意
とみなさない)
書籍 『デジタルアイデンティティのすべて』(考え方)4.2.4 節
pp.33–35(指向性のある識別子)
33
定義 発行 伝搬 検証 認可 運用 Entra ID:scp と roles、グループの超過、拡張属性 groups は 200 件を超えると消えて別の形に置き換わる。「無い」は「所属なし」ではない クレーム・設定 挙動 グループの超過 scp クライアントが同意を得たスコープ(空白区切り)。利用者のトークンだけ • 印にある古い URL に頼らない roles アプリ専用のトークンでは、許可された権限はここに入る • idtyp を見て Microsoft Graph に問 い合わせる groups JWT で 200 件、SAML で 150 件を超えると出ず、_claim_names・ _claim_sources に置き換わる • アプリに割り当てたグループに絞る トークンの版 API 側の requestedAccessTokenVersion で決まる(null は v1)。acr は v1 だけ 拡張属性 extn.<属性名> で出る。名前の大文字小文字の揺れで黙って欠落する Agent ID xms_act_fct・xms_sub_fct・idtyp などでエージェントを表す(Part 10) リーダーの視点 groups が無いトークンを「所属なし 」と読まない。超過の経路を実装する か、件数を絞る アクセストークンは常にリソース側の設定で作られる 仕様 Entra:access-token-claims-reference/optionalclaims/schema-extensions JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP JWT Cheat Sheet(roles・groups の扱い) 書籍 『セキュアAPI』7.7 節 p.219(Entra は roles・groups) 34
定義
発行
伝搬
検証
認可
運用
Keycloak:マッパーがなければクレームは出ない
属性はプロトコルマッパーで初めてクレームになる。束ねて再利用するのがクライアントスコープ
ユーザー属性
プロトコルマッパー
利用者ごとの値
名前・JSON の型・載せるトークン
クライアントスコープ
Default は常に、Optional は要求
時
トークン
クレームとして出る
{
"iss": "https://kc.example.com/realms/corp",
"azp": "portal",
"aud": ["orders-api"],
"realm_access": { "roles": ["employee"] },
"resource_access": { "orders-api": { "roles": ["approver"] } },
"scope": "openid profile",
"https://claims.example.com/tenant": "t-042"
}
仕様 Keycloak Server Administration Guide(Mappers・
Client scopes)
JWT クレーム設計ガイド|組織で共用する独自クレーム
注意点
• 入るロールは「利用者」∩「クライアント」
• Full scope allowed は本番でオフに
• クレームの JSON の型をマッパーで固定
• グループはマッパーが要り、フルパスで出る
指針 NIST SP 800-63C-4 §3.10(必要最小限のデータ)
書籍 『実践 Keycloak』4.5.2・5.5.2 節 pp.56–58, 77–81(
UI は旧版)
35
定義 発行 伝搬 検証 認可 運用 Keycloak:aud・軽量トークン・組織・トークン交換 API を aud に入れるには設定が要る。トークン交換は V2 が正式、委任はまだ preview aud 軽量アクセストークン • 自動では API を含まない • クレームを絞ったアクセストークン • Audience マッパーをスコープに設定 • 全クレームが要るならトークン交換で変換 • 既定の account は API 固有の値ではない • マッパーごとに載せるかを選ぶ 組織(Organizations) トークン交換 • organization スコープで organization クレーム • Standard V2:正式・既定で有効(内部同士) • CVE-2025-1391:ドメイン一致だけで所属を付与 • 旧 V1:非推奨 • 所属は確かな情報源から付ける • 委任(act):26.8 で preview • CVE-2025-14559:無効な利用者にも発行 仕様 Keycloak:Server Admin Guide/Token exchange /26.8.0 告知 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NVD CVE-2025-1391・CVE-2025-14559 書籍 『OpenID Connect入門』9.4 節 p.130/『実践 Keycloak』5.5.1 節 pp.76–77 36
定義
発行
伝搬
検証
認可
運用
Auth0:名前空間の規則と、黙って消えるクレーム
名前空間なしも許されるようになったが制約が多い。予約名と衝突すると、エラーなしで外れる
規則
内容
名前
名前空間つき・なしの両方を許可。名前空間つきを推奨
予約名
acr・act・aud・client_id・cnf・groups・org_id・permissions・roles
・sid・sub ほか
使えない名前空間
auth0.com・webtask.io・webtask.run・urn:auth0
API 宛ての AT
Auth0 の API 宛てには、名前空間なしの私的クレームを入れられない
衝突したとき
トランザクションは失敗せず、クレームが黙って追加されない
上限
独自クレームの合計 100KB
{
"sub": "auth0|64f…",
"aud": ["https://api.example.com",
"https://<テナント>/userinfo"],
"org_id": "org_9a…",
"permissions": ["orders:read"],
"https://claims.example.com/tenant": "t-042"
}
// "roles" を素の名前で足しても黙って外れる
audience を付け忘れると、自分の API では
検証できない不透明な AT が返る
独自クレームは必ず組織の名前空間つきで足し、発行後のトークンに入っているか
をテストで確かめる
仕様 Auth0:create-custom-claims/get-access-tokens
指針 NVD CVE-2025-68129(ID トークンを AT として受理)
/access-token-profiles
JWT クレーム設計ガイド|組織で共用する独自クレーム
書籍 『セキュアAPI』7.7 節 p.219・付録 B pp.355–356
37
定義 発行 伝搬 検証 認可 運用 Okta:Custom AS を使い、AT では uid を見る Org AS の AT は自分の API で検証しない。AT の sub はログイン名なので、キーは uid Org 認可サーバー Custom 認可サーバー クレーム アクセストークン ID トークン 用途 Okta 自身の API 自分の API の保護 sub ログイン名(メール形式) ユーザー ID(00u…) AT を自分で検証 しない(予告なく変わる) する uid ユーザー ID — 独自クレーム groups クレームだけ 任意のクレーム・スコープ cid client ID —(aud が client ID) aud 変えられない 設定した audience scp スコープの配列 — groups は 100 件まで • 超えると要求そのものが失敗(Entra と逆) 仕様 Okta:auth-servers/reference/api/oidc/customize-tokens-groups-claim JWT クレーム設計ガイド|組織で共用する独自クレーム 値は式で書く(1024 文字まで) • プレビューの画面で発行前に確かめる 指針 NIST SP 800-63C-4 §3.4/OWASP ASVS 10.5.2(変わらない識別子) 38
定義
発行
伝搬
検証
認可
運用
Cognito:token_use を確かめ、aud の欠落に備える
ID トークンが API を通らないよう token_use を確かめる。AT の aud は resource 指定時だけ
{
"iss": "https://cognito-idp.<リージョン>.amazonaws.com/<プール ID>",
"token_use": "access",
"client_id": "6s1q…",
"sub": "c4f8…",
"username": "taro",
"cognito:groups": ["approvers"],
"scope": "orders/read"
}
確認
内容
token_use
access か id。API では access だけ
aud・client_id
ID トークンは aud、AT は client_id をアプリクライアント
の ID と照合
aud(AT)
既定では無い。2025-10 以降、resource 指定時に入る
sub
利用者のキー。UUID として厳密に検証しない
username
プール内で一意とは限らない
aud を必須とする検証の部品をそのまま使うと、失敗するか素通りする。署名と exp だけでは、サインアウトや失効は検出できない
acr・amr は固定の 4 段階。順次提供中で、発行前のフックでは変えられない
仕様 Cognito:verifying-a-jwt/using-the-access-token/What's new 2025-10
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 OWASP ASVS 9.2.2(トークンの種類の確認)
39
定義 発行 伝搬 検証 認可 運用 Cognito:発行前フックと custom: 属性の落とし穴 AT を変えるには V2 以上が要る。custom: 属性は利用者本人が書き換えられることがある 版 変えられるトークン プラン custom: 属性 V1_0 ID トークンだけ — • 最大 50 個、値は 2048 文字まで V2_0 +利用者のアクセストークン Essentials・Plus +M2M のアクセストークン Essentials・Plus(M2M は 別料金) • 追加後は削除・改名・型の変更ができない • 読み取り専用にしない限り本人が書き換えうる V3_0 フックで変えられないクレーム トークン交換(2026-11-12〜) • sub・username・cognito:username • client_id・aud・acr・amr • 単一の aud、リフレッシュトークンなし • その他の cognito: で始まるもの • actor token ありなら act。無しは本人と区別不能 • may_act は発行も評価もしない 仕様 Cognito:pre-token-generation/user-pool-settings-attributes/tokenexchange JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-162 §3.1.3.3(権威ある主体だけが属性を付与) 40
定義 発行 伝搬 検証 認可 運用 最近の変更:古い理解のままだと誤る点 2025〜2026 年に各社が大きく変えた。古い記事や書籍の手順は、現行の文書で確かめ直す 時期 IdP 古い理解 現在 2025-03-03 Cognito M2M の AT は変えられない 発行前フック V3 で変えられる 2025-10-27 Cognito AT に aud は入らない resource を指定すると aud が入る 2026-11-12 Cognito トークン交換はない RFC 8693 のトークン交換。act つき、RT なし 順次提供中 Cognito acr・amr は出ない 固定 4 段階の acr・amr 26.x Keycloak トークン交換は preview Standard V2 は正式。旧 V1 は非推奨 2026-10(26.8) Keycloak 委任は experimental 委任(act)は preview 現行 Auth0 独自クレームは名前空間が必須 名前空間なしも可。予約名と衝突すると黙って外れる 2026-04 更新 Entra ID エージェントも普通のアプリ Agent ID 用のクレーム(xms_act_fct など) 社内の手順書や書籍の記述は、現行の公式文書で確かめ直してから使う(『実践 Keycloak』は 18 前提) 仕様 Cognito What's new/Keycloak 26.8.0 告知/Auth0・Entra 公式文書 JWT クレーム設計ガイド|組織で共用する独自クレーム 書籍 『実践 Keycloak』は Keycloak 18 前提(訳者まえがき p.vii) 41
定義 発行 伝搬 検証 認可 運用 独自クレームの入れ方:失敗しても黙って出る 仕組みも上限も IdP ごとに違う。フックが失敗しても、クレームなしでトークンが出ることがある IdP 入れる仕組み 失敗・衝突のとき 上限 Entra ID custom claims provider(発行直前に REST ) 対応づけたものだけ入る。型は文字列と配列だけ 合計 3KB Keycloak プロトコルマッパー(SPI で自作も可) マッパーが無ければ出ない 軽量 AT で削る Auth0 post-login Action(RT 交換時も実行) 予約名と衝突すると黙って外れる 合計 100KB Okta 式・token inline hook 3 秒で打ち切り、リトライなし。クレームなしで出る 式 1024 文字・groups 100 件 Cognito 発行前フック(リフレッシュ時も) V1 では AT を変えられない クレームとスコープで 5,000 リーダーの視点 受け手は fail-closed にする。必要な独自クレームが無いトークンは拒否し、「無い」を「既定の権限あり」と読まない 仕様 Entra custom claims provider/Okta inline hooks /Auth0 login trigger/Cognito quotas JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP ASVS 8.1.1〜8.1.3(認可ルールと属性の文書化) 書籍 『実践 Keycloak』13.5 節 p.276・解答 pp.319–320( SPI による拡張) 42
定義 発行 伝搬 検証 認可 運用 取り違えやすい点:同じ名前でも形と意味が違う sub・scope・groups・aud・トークンの種類は、IdP ごとに形も意味も挙動も違う 論点 IdP ごとの違い 受け手の規則 sub Entra:アプリごと/Okta の AT:ログイン名/Auth0:IdP の種類|ID 共通のキーは入口で決める scope の形 Entra の scp・Cognito の scope:空白区切り/Okta の scp:配列 正規化した 1 つの形で渡す groups の超過 Entra:200 件超で超過の印に/Okta:100 件超で要求が失敗 「無い」を「所属なし」と読まない aud Cognito:既定で無い/Keycloak:設定が要る/Auth0:配列になる 文字列と配列の両方を受け、無ければ拒否 トークンの種類 Cognito:token_use/Entra:idtyp/RFC 9068:typ が at+jwt 種類の確認を IdP ごとに実装する 各サービスに IdP ごとの読み方を持たせると、IdP を足すたびに全サービスの修正が要る 仕様 Entra/Okta/Auth0/Cognito/Keycloak の公式文書(Part 3 各スライド) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP JWT Cheat Sheet(トークンの種類の取り違え) 43
定義
発行
伝搬
検証
認可
運用
IdP の差は入口で吸収する
IdP ごとの検証と対応づけは入口で 1 回だけ行い、内側のサービスには組織の形で渡す
Entra ID
oid+tid
{
"iss": "https://sts.internal.example.com",
"sub": "u-7f3a…",
"aud": "https://orders.internal.example.com",
"https://claims.example.com/tenant": "t-042",
"https://claims.example.com/roles":
["approver"]
入口(1 回だけ)
• IdP ごとに iss・aud・種類を検証
Keycloak
sub・organization
• IdP のキーを組織のキーへ
• scope・ロールを組織の語彙へ
}
• 無いクレームは拒否
Auth0/Okta
sub・org_id/uid
Cognito
sub(token_use を確認)
リーダーの視点
内側のサービスが読むのは組織の名前空間のクレームだけにする。方法は Part 6(入口での交換)、対応表と台帳は Part 11
仕様 RFC 8693(トークン交換)/RFC 9068 §2.2.2
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 CSRB 勧告 6(共通の認証ライブラリ)/NIST SP 800162 §3.2.3.2
書籍 『デジタルアイデンティティのすべて』(考え方)4.2.5・13.4.2
節 pp.35–36, 207–209
44
PART 4 独自クレームの設計原則 このPartで答えられるようになる問い • 何をトークンに載せ、何を都度問い合わせるか • 名前・名前空間・型を、どう決めるか • 識別子と、値を書ける主体を、どう分けるか • 上限・欠落・未知のクレームに、どう備えるか 何を載せ、どう名付け、どの型で、誰が書くか。受け手が読み 違えない契約にする 45
定義 発行 伝搬 検証 認可 運用 トークンは写し:発行後の変更は届かない 載せたクレームは発行時点の値のまま、期限まで使われる。権限を外しても、すぐには効かない 10:00 発行 10:05 権限を外す 10:05〜 まだ通る 10:15 期限切れ roles に editor を載せる DB では editor ではない トークンは editor のまま 次の発行で、やっと反映 製品・研究 公式に書かれていること 同じ構造:new enemy 問題 Firebase クレームの変更は、再ログインかトークンの更新まで反映されない • 共有から外した人に、新しい内容が見える Supabase app_metadata を更新しても、JWT の更新まで反映されない • 古い設定で新しい内容を評価すると起きる • 権限を固めたトークンでも同じ形で起きる OpenFGA 関係が変わっても、トークンの期限までアクセスが続く Verified Permissions 失効やリソースの削除は、トークンの有効性に影響しない リーダーの視点 変わりやすい権限・関係は、トークンではなく、都度問い合わせる側(PDP・DB)に置く 仕様 Firebase・Supabase・OpenFGA・AVP 公式文書/ Zanzibar(USENIX ATC 2019) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-162 §3.3.1(キャッシュと鮮度)/ASVS 8.3.2 書籍 『デジタルアイデンティティのすべて』12.6 節 pp.199–200( 考え方) 46
定義 発行 伝搬 検証 認可 運用 載せるか、問い合わせるか:4 つの問いで決める 認可に使い、寿命より変化が遅く、小さく、全受け手が要るものだけを載せる はい 1. 認可・ルーティングに 使うか はい 2. 寿命の間、変わらな いか いいえ いいえ はい 3. 小さく、上限に収まる か はい 4. 受け手の全員が要る か いいえ いいえ 載せない 都度問い合わせる 参照だけ載せる 宛先ごとに絞る UserInfo・DB で取る PDP・DB で判定 ID を載せ、中身は API 宛先別・交換時に付ける 載せる 名前・型・上限を台帳に登録 (Part 11) リーダーの視点 詰め込みの代償 揮発的な業務権限は API 側で管理し、ト ークンのクレームを鍵に引く(Curity) • 更新漏れが、そのまま権限の漏れになる • 内部の構成が、トークンを読む人に見える • ヘッダーの上限を超え、性能も落ちる 仕様 Curity クレームのベストプラクティス/Firebase カスタムク レーム JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-63C-4 §3.10(必要最小限のデータ)/ ASVS 8.3.2 書籍 『セキュアAPI』7.7 節 pp.220–221/『OpenID Connect入門』4.3 節 p.68 47
定義 発行 伝搬 検証 認可 運用 クレーム名:まず登録名、無ければ自社の名前空間 意味が足りる登録名は使う。独自の名前は自社が管理する URI を接頭辞にし、予約名を避ける 1. 登録名で足りるか 2. 自社の名前空間 3. 予約名と照合 roles・groups・act・authorization_details https://claims.example.com/… IdP・基盤の予約を避ける 基盤 予約・使えない名前 衝突したとき Auth0 urn:auth0、auth0.com、roles・groups・permissions など 失敗せず、黙って追加されない Firebase OIDC の登録名、firebase、user_id 使えない Cognito(AVP 連携) 接頭辞 cognito・dev・custom 追加しない(予約) Kubernetes extra の k8s.io・kubernetes.io、接頭辞 system: 予約。検証ルールで拒否する例 Auth0 では衝突しても失敗しない。名前は、発行の前に予約名の一覧と機械的に照合する 仕様 RFC 7519 §4.2・4.3/RFC 9068 §2.2.2(登録名を 優先) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-162 §2.4.2(名前と値を中央で正規化) 書籍 『実践 Keycloak』5.5.3 節 pp.81–82(名前に接頭辞) 48
定義
発行
伝搬
検証
認可
運用
名前空間:1 つにまとめ、受け手のツールで試す
まとめると衝突と散らばりを防げる。ただし「.」を含む名前は、ドット区切りのツールで読めない
まとめる(Kubernetes・AWS の形)
{
フラット(ネストできない IdP 向け)
{
"sub": "u-7f3a…",
"https://claims.example.com/": {
"tenant_id": "t-042",
"org_unit_ids": ["ou-12"]
}
"sub": "u-7f3a…",
"https://claims.example.com/tenant_id": "t-042",
"https://claims.example.com/org_unit_ids": ["ou-12"]
}
}
Envoy の claim_name
https://claims.example.com/tenant_id
「.」で分割
"https://claims" / "example" /
"com/tenant_id"
見つからない
claim_path(キーの完全一致)を使う
リーダーの視点
名前空間の形(ネストかフラットか)は、受け手の全ツール(ゲートウェイ、メッシュ、CEL、JSONPath)で読めると確かめてから決める
仕様 Envoy jwt_authn(claim_name・claim_path)/AWS セ
ッションタグ/K8s SA トークン
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 OWASP WIF CS(独自クレームを条件に使えるか確認)
書籍 『デジタルアイデンティティのすべて』10.2.1 節 p.136(識別
子の名前空間の考え方)
49
定義
発行
伝搬
検証
認可
運用
型:1 つに固定する。ID と金額は文字列で
同じ種類の値で型が揺れると、受け手ごとに比較が変わる。型は台帳で 1 つに決める
GitLab の公式例(抜粋):型が揺れる
値の種類
決める型
根拠・実例
ID
文字列
大きな数値はパーサによって化ける
金額・数量
文字列
RFC 9396・Txn-Token の例
時刻
数値(NumericDate)
RFC 7519 §2
真偽
JSON の true / false
文字列 "false" と混ぜない
複数値
常に配列(1 件でも)
Cognito の groups は 1 件でも配列
{
"project_id": "20",
"runner_id": 1,
"ref_protected": "false",
"groups_direct": ["mygroup/mysubgroup"],
"ci_config_ref_uri": null
}
大きな数値の ID は、パーサによって最大値や 0 に化ける(Bishop Fox の 49 パーサ調査)。ID は最初から文字列で運ぶ
仕様 RFC 7519 §2(NumericDate)/RFC 9396 §9.1 の例/GitLab・Hasura 公式文書
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 デジタル庁 DS-212 §3.2.3(属性名・データ型・値を標準化)
50
定義 発行 伝搬 検証 認可 運用 形:配列は配列で、JSON は JSON のまま 区切り文字の連結や JSON の文字列化は、受け手に分割と解析の規則を押しつける 形 実例 受け手に起きること 代わりに カンマ連結 GitHub の複数選択 "us-east-1,eu-west-1" 文字列の一致・contains で評価する 文字列の配列 空白区切り scope。Istio は他のクレームを分割しない "admin editor" が 1 つの値になる scope 以外は配列 JSON の文字列化 Hasura の stringified_json(Cognito 向け) もう一度 JSON として解析する オブジェクトのまま 文字列の真偽 GitLab の "ref_protected": "false" 真偽値として比べると誤る true / false # Kubernetes の設定例(公式、抜粋) groups: claims.roles.split(",") claims.?email_verified.orValue(true) == true 仕様 RFC 8693 §4.2(scope)/GitHub・Istio・Hasura・Kubernetes 公式文書 JWT クレーム設計ガイド|組織で共用する独自クレーム ポイント 真偽値は true と明示的に比べる(Kubernetes の推奨)。こ の例はクレームが無ければ通す。必須なら claims.email_verified == true 指針 デジタル庁 DS-212 §3.2.3/NIST SP 800-162 §3.2.1.3(定義を文書化) 51
定義 発行 伝搬 検証 認可 運用 無い・null・false・空配列:意味を決めておく 「無い」は偽か、不明か、上限超えか。決めずにいると、受け手ごとに解釈が分かれる 無い null false 空配列 [ ] キーそのものが無い • AWS の mfa_present は無 い=偽 値が null • GitLab の ci_config_ref_uri 明示的な偽 • 真偽値のクレームだけで使う 0 件と明示 • 複数値のクレームで使う • Firebase は null で全削除 • 文字列の "false" と混ぜな い • 「無い」と区別できる • GitLab の groups_direct は 200 超で無い クレームの種類 無いときの扱い(台帳に書く) 許可を与える(roles など) 何も許さない 制限をかける(区分・地域など) 拒否する(fail closed) 上限で欠落しうる(一覧など) 0 件とみなさない。認可に使わない 仕様 AWS 送信側 JWT(mfa_present)/GitLab id_tokens/Firebase・Istio 公式文書 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.2.1.1(必須要素を文書化) 52
定義 発行 伝搬 検証 認可 運用 大文字小文字と文字:比べ方を決める クレームは変換せずに比べるのが原則。基盤ごとの大小の扱いの差で、値が黙って消える どこで 大文字小文字の扱い 起きること RFC 7519(StringOrURI) 区別する。正規化しない "T-042" と "t-042" は別の値 Entra の拡張属性 設定時は区別せず、読むときは区別 大小が混在すると、クレームが黙って欠落 AWS のセッションタグ キーの大小を区別しない 同じキーの既存のタグを上書き Hasura x-hasura-* の名前は区別しない 受け手によって区別の有無が違う Entra 連携 ID 資格情報 区別して完全一致 大小が違えば信頼が成り立たない リーダーの視点 値は小文字の ASCII の識別子に限る(RFC 9396 は type の値を ASCII に限るよう勧める)。発行時に一度だけ正規化し、受け手は 変換せず完全一致で比べる 仕様 RFC 7519 §2・§7.3/RFC 9396 §2.1(ASCII に限る)/Entra・AWS 公式文書 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-162 §2.4.2(属性の名前と値を正規化) 53
定義
発行
伝搬
検証
認可
運用
識別子:名前ではなく、変わらない ID で一致させる
名前は改名や再利用で別の主体を指す。認可の条件は ID で書き、名前は表示と補助に使う
GitHub Actions の sub
# 従来:名前だけ(再利用されると別の持ち主と一致)
repo:octo-org/octo-repo:ref:refs/heads/main
実例
設計
GitHub
名前に現れない @ で ID を連結。値の「:」は %3A
GitLab
過去に使われたパスを含む sub は発行しない
Kubernetes
name と uid を対で出す
Entra ID
oid+tid で共有。email・upn で認可しない
# 2026-07-15 以降の作成・改名・移譲:名前@ID
repo:octo-org@123456/octo-repo@456789:ref:refs/heads/main
"https://claims.example.com/": {
"org_unit_id": "ou-12", "org_unit_name": "経理部" }
リーダーの視点
名前と ID を対で出し、受け手には ID での一致を求める。合成の sub を作るなら、区切り文字と退避の規則を発行者が決めて公開する
仕様 OIDC Core §5.7/GitHub 不変の sub(2026-04 告
知)/K8s SA トークン
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 OWASP WIF CS(変わらない ID を使う)/ASVS 10.3.3
書籍 『デジタルアイデンティティのすべて』(考え方)10.2 節
pp.135–136・p.139
54
定義
発行
伝搬
検証
認可
運用
書き手で分ける:確認済みの値と申告の値
発行者が確かめた値、呼び出しの申告、本人が編集できる値を、同じ場所に混ぜない
発行者が確かめた値
呼び出し側の申告
本人が編集できる値
• AWS の principal_tags
• AWS の request_tags
• Supabase の user_metadata
• Supabase の app_metadata
• API の引数で任意に指定
• プロフィールの項目
• Txn-Token の tctx
• 呼び出し側が指定した値
• 本人が更新できる属性
認可に使える
記録と参考。認可は慎重に
"https://claims.example.com/": {
"verified": { "tenant_id": "t-042" },
"requested": { "job_id": "job-9" } }
仕様 AWS 送信側 JWT(principal_tags・request_tags)/
Supabase RLS/Txn-Token 草案 11
JWT クレーム設計ガイド|組織で共用する独自クレーム
認可に使わない
Supabase:user_metadata に依存する行の
制御は危険。Txn-Token の rctx は TTS が
書く環境の値で、要求時点の値として扱う
指針 NIST SP 800-162 §3.1.3.3(権限ある機関だけが付与)
書籍 『デジタルアイデンティティのすべて』(考え方)7.2 節 pp.63–
64(出自)
55
定義 発行 伝搬 検証 認可 運用 サイズの予算:上限を超えると黙って消える 上限を超えたときの挙動は、エラー・失敗・置き換え・黙った欠落と、基盤ごとに違う 基盤 上限 超えたとき サイズの予算 Firebase 独自クレーム 1000 バイト エラー Okta groups 100 件 リクエストが失敗 Entra ID groups 200 件(JWT) 超過の印に置き換え • クレームごとに最大の長さ・件数 • 超えたら発行を失敗させる • 欠落しうる値で認可しない • 長い一覧は ID だけ載せる GitLab groups_direct 200 件 丸ごと省略(0 件と区別不能) Cloudflare Access custom 約 1KB 末尾から切り捨て AWS セッションタグ 50 件 容量を超えると失敗 Auth0 独自クレーム 100KB 重いペイロードを避けるよう注意 Cloudflare は、大きくなりうる custom クレームを認可の判断に使わないよう明記している 仕様 Firebase・Okta・Entra・GitLab・Cloudflare Access・AWS 公式文書 JWT クレーム設計ガイド|組織で共用する独自クレーム 書籍 『セキュアAPI』7.7 節 pp.220–221(肥大とヘッダーの上限) 56
定義 発行 伝搬 検証 認可 運用 前方互換:知らないものは無視、必須の欠落は拒否 未知のクレームは、アプリが求めない限り無視する(MUST)。制限は受け手側の「必須」で効かせる 未知のクレーム 新しい制限のクレーム 必須のクレームが無い 無視する 古い受け手は無視する 拒否する(fail closed) • RFC 7519 §4:別の要件が無ければ • 受け手の実装が先 • フックの失敗で欠けても通さない • 足しても古い受け手は壊れない • 対応するまで制限は効かない • 必須の一覧を台帳に書く 1. 受け手が先に対応 2. 発行を選択制に 3. 期日で既定に 4. 旧形式を廃止 GitHub:受け手の条件を先に作ってから、発行側を変える。逆だとトークンが受け入れられない(手順は Part 11) 仕様 RFC 7519 §4(求めない限り未知は無視)/RFC 8417 §4/RFC 9396 §5/Txn-Token 草案 11 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.2.1.1(必須要素の文書化) 書籍 『実践 Keycloak』5.6 節 p.86(必要なクレームを確認) 57
定義 発行 伝搬 検証 認可 運用 付与するのは単一の発行者:各サービスは足さない 属性の源は多くても、クレームを書くのは 1 か所。受け手は、許可した発行者のクレームだけを信じる 人事・ディレクトリ テナント・契約の管理 受け手:サービス A 組織の発行者 IdP、または入口のトークン交換 名前・型・上限を台帳どおりに 認証の結果(acr・amr) 受け手:サービス B 受け手:サービス C × 各サービスが独自に追記・再発行 受け手は、許可した発行者のクレームだけを信じる リーダーの視点 サービスの中で追加の文脈が要るなら、トークン交換や Transaction Tokens の発行サービスに書かせる(Part 6) 仕様 Curity API セキュリティのベストプラクティス JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP Identity Propagation CS/NIST SP 800162 §2.4.2・§3.3.2 書籍 『デジタルアイデンティティのすべて』15.1.2 節 pp.260– 261(考え方) 58
定義
発行
伝搬
検証
認可
運用
設計例:組織の名前空間オブジェクト
登録名・名前空間・版・型・識別子・書き手の原則を、1 つのペイロードにまとめた例
{
"iss": "https://idp.example.com", "sub": "u-7f3a…",
"aud": "https://api.example.com", "roles": ["approver"],
"https://claims.example.com/": {
"v": "1",
"tenant_id": "t-042",
"org_unit_ids": ["ou-12", "ou-31"],
"employment": "regular"
}
}
ネストできない IdP 向けに、同じ内容のフラットな名前(
https://claims.example.com/tenant_id)も台帳に定義しておく
仕様 RFC 7519 §4.2/RFC 9068 §2.2.3.1(roles)
JWT クレーム設計ガイド|組織で共用する独自クレーム
原則
この例での決め方
登録名を優先
roles は RFC 9068 の名前でトップに
名前空間
自社の URI を 1 つのオブジェクトに
版
v で構造の版を示す
型
ID は文字列、複数値は常に配列
識別子
テナント・部署は ID。名前は載せない
書き手
発行者が確かめた値だけ
載せないもの
文書ごとの権限、氏名・メール
指針 NIST IR 8112 §3.1(属性スキーマのメタデータ)/DS212 §3.2.3
書籍 『セキュアAPI』7.2.2 節 p.195(ロール・組織を独自クレーム
で)
59
定義 発行 伝搬 検証 認可 運用 設計のチェックリスト:12 の確認 新しい独自クレームを足す前に、設計の観点で確かめること。審査の質問は Part 11 で扱う 観点 確認すること 観点 確認すること 載せるか 認可に使い、寿命の間に変わらないか 欠落 無い・null・false・空配列の意味を決めたか 既存 登録名・IdP の既存クレームで足りないか 比較 大小の扱いを決め、完全一致で比べるか 名前 自社の名前空間か。予約名と照合したか 識別子 名前ではなく、変わらない ID か ツール 受け手の全ツールで参照できるか 書き手 誰が書けるか。申告の値と分けたか 型 型は 1 つか。ID は文字列か サイズ 上限と、超えたときの挙動を決めたか 形 複数値は配列か。連結・文字列化していないか 必須 欠けたら拒否するか。発行者は 1 つか リーダーの視点 1 つでも答えられない項目があれば、まだトークンに載せない。答えは台帳に残し、受け手と共有する 仕様 RFC 7519 §4/RFC 9068 §2.2.2 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-162 §2.4.2/IR 8587 §5.2.1.1/デ ジタル庁 DS-212 §3.2.3 書籍 『実践 Keycloak』8.2 節 p.146(最小限のロールだけ) 60
PART 5 権限の表現:利用者・サービ ス・システム このPartで答えられるようになる問い • 1 つのリクエストで、利用者とサービスをどう表すか • 粗い権限と細かい権限を、どこで分担するか • テナントをどう表し、どう検証するか • クレームだけで認可してはいけないのはどこか 誰の権限で、誰が実行し、どのテナントの、どのオブジェクトに 対してか。クレームで運ぶ範囲と、都度判定する範囲を分ける 61
定義 発行 伝搬 検証 認可 運用 3 種類の主体:利用者・ワークロード・システム 人だけが主体ではない。サービスと、基盤自身の操作も、別の種類の主体として表す 主体 例 代表的な表し方 利用者 社員、顧客、取引先の担当者 IdP のトークンの sub。Entra は oid+tid ワークロード マイクロサービス、ジョブ、エージェント SPIFFE ID、client credentials、マネージド ID システム・基盤 クラウドのサービス、運用者、バッチ AWS のサービスにリンクされたロール、FAS リーダーの視点 CloudEvents の authtype • app_user・user:利用者 RFC 9068 の sub は、利用者にもクライアントにもなる。 名前空間が重なるなら、AS は受け手が区別できる手段を用 意する(RFC 9700 §4.15.1 の MUST) • service_account・api_key:ワークロード • system:基盤が起こしたイベント 仕様 RFC 9068 §2.2・§5/RFC 9700 §4.15.1/SPIFFE 指針 NIST IR 8587 §5.3.1.6(ワークロードは短命・狭いスコー JWT-SVID/CloudEvents プ) JWT クレーム設計ガイド|組織で共用する独自クレーム 書籍 『デジタルアイデンティティのすべて』13.7.4.2 節 pp.226– 227(考え方) 62
定義 発行 伝搬 検証 認可 運用 1 リクエストで運ぶ:誰の権限・誰が実行・どこ経由 利用者の権限、実行しているワークロード、経由したサービスを、別々のクレームやチャネルで運ぶ 利用者 ゲートウェイ サービス A サービス B ブラウザ 検証し、内部トークンへ mTLS で自分を示す sub・act・req_wl を確認 問い クレーム・チャネル 実例 誰の権限で sub(トップレベル) RFC 8693、Txn-Token の sub 誰が実行しているか act・req_wl・mTLS の相手の ID RFC 8693 §4.1、Txn-Token、SPIFFE どこを経由したか 経由を示す別の属性 AWS FAS の aws:CalledVia 利用者の文脈ごと運ぶ 完全性を保護した内部の切符 Google BeyondProd、Netflix Passport リーダーの視点 認可は元の利用者の権限で判断し、仲介するサービスの権限で判断しない(ASVS 8.3.3) 仕様 RFC 8693 §4.1/Txn-Token 草案 11 §9.2/AWS FAS(aws:CalledVia) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-228 REC-API-12(各 ID を認可)/ASVS 8.3.3 63
定義 発行 伝搬 検証 認可 運用 権限のモデル:RBAC・ABAC・関係ベース RBAC は役割だけを属性にした ABAC の特別な形。関係ベースは、主体と対象の関係で判定する RBAC(役割) ABAC(属性) 関係ベース • 判定:役割で許可を決める • 判定:主体・対象・環境の属性 • 判定:所有者・共有先などの関係 • クレーム:roles・groups • クレーム:主体の安定した属性 • クレーム:sub だけ。関係は PDP • 向く:機能の粗い区別 • 向く:部署・地域・認証の強さ • 向く:文書・フォルダの共有 • 弱点:細かくするとロールが増える • 弱点:設計とテストが難しい • 例:Zanzibar、OpenFGA リーダーの視点 どのモデルでも、トークンが運ぶのは判定の入力の一部。関係とオブジェクト単位の判定は、PDP とデータの側に置く 仕様 RFC 9068 §2.2.3.1(roles・groups・entitlements) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-162(ABAC)/IR 8587 §4.1.4 書籍 『デジタルアイデンティティのすべて』(考え方)12.2.5 節 p.194/『実践 Keycloak』8 章 pp.143–156 64
定義 発行 伝搬 検証 認可 運用 PEP と PDP:クレームは判断の入力の 1 つ サービス(PEP)がトークンを検証し、判断は方針(PDP)に任せる。足りない属性は PIP から補う PIP 属性の源(DB・ディレクトリ) 要求 PEP ゲートウェイ・サービス。トークンを検 証 PDP 方針に従って判断 PAP 方針の管理・レビュー 判断の入力 出どころ 例 主体の安定した属性 トークンのクレーム sub、tenant_id、roles 関係・オブジェクトの属性 PIP(DB・関係の保存先) 所有者、共有先、文書の区分 環境・文脈 PEP が要求の時点で取得 IP アドレス、時刻、端末の状態 トークンが有効かどうかだけで認可しない。提示された文脈も考える(IR 8587 §4.1.4) 指針 NIST SP 800-162 §3(PEP・PDP)/IR 8587 §4.1.4/SP 800-207 §2.1 原則 4 JWT クレーム設計ガイド|組織で共用する独自クレーム 書籍 『デジタルアイデンティティのすべて』(考え方)12.3 節 pp.194–195/『実践 Keycloak』8.6 節 pp.154–155 65
定義 発行 伝搬 検証 認可 運用 粗い権限と細かい権限:3 層で分担する scope と roles は粗く、取引の中身は authorization_details、オブジェクトは都度判定 層 クレーム 表すこと 置き場所 粗い scope・roles・groups 機能の範囲、役割 トークン(長く安定) 取引単位 authorization_details この支払い・この金額 トークン(宛先ごとに絞る) オブジェクト単位 載せない この文書を読めるか PDP・DB で都度判定 // RFC 9396 §9.1 の例(抜粋) "authorization_details": [{ "type": "https://scheme.example.com/payment_initiation", "actions": ["initiate", "status", "cancel"], "instructedAmount": { "currency": "EUR", "amount": "123.50" }, "creditorName": "Merchant A" }] 仕様 RFC 9396 §5・§9.1/RFC 9068 §2.2.3・2.2.3.1 JWT クレーム設計ガイド|組織で共用する独自クレーム authorization_details は宛先に合わせて絞って 入れる(§9.1)。知らない type やフィールドは、発行 者が拒否する(§5) 指針 NIST IR 8587 §5.2.1.1(scope と RAR)/ASVS 10.3.2 書籍 『セキュアAPI』7.7 節 pp.219–223 66
定義 発行 伝搬 検証 認可 運用 scope と role:守る相手が違う scope はクライアントに委ねた範囲、role は利用者が持つ役割。トークンに入るのは両者の重なり 利用者が持つロール ∩ クライアントが使えるロール トークンに入るロール 本番は Full Scope Allowed を切る IdP クライアントへの委任 利用者・アプリの役割 Entra ID scp(利用者のトークンだけ。空白区切り) roles・groups・wids Keycloak scope realm_access(全体)・resource_access(クライアント固有) Auth0 scope permissions(RBAC を有効にしたとき) Cognito scope(空白区切り) cognito:groups(1 件でも配列) リーダーの視点 scope は「クライアントに何を許したか」で、利用者の全権限ではない。両方を確かめる(各 IdP の詳細は Part 3) 仕様 Entra アクセストークンのクレーム/Keycloak サーバー管理 ガイド JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 ASVS 10.4.11(必要な scope だけを割り当てる) 書籍 『実践 Keycloak』5.5.2 節 pp.77–81・8.4 節 pp.152– 153 67
定義
発行
伝搬
検証
認可
運用
ロール爆発:細かい権限をロールで表さない
役割 × テナント × 対象でロールを作ると、数が掛け算で増え、トークンも膨らむ
悪い例:組み合わせをロール名に焼く
分ける:役割・テナント・対象
"roles": [
"t-042-invoice-approver",
"t-042-invoice-viewer",
"t-043-invoice-approver",
"t-042-ou-12-expense-approver",
… ]
"roles": ["approver"],
"https://claims.example.com/": {
"tenant_id": "t-042" }
// どの請求書を承認できるかは PDP・DB で判定
細かい権限はロールにしない
まとめるならグループ
膨らむと上限に当たる
• ロールは役割の名前
• 複数のロールはグループに
• Entra は groups 200 件で置換
• 対象ごとの許可は PDP
• 複合ロールは性能と管理に注意
• 長い一覧は集約の兆候
仕様 Entra グループの超過(groups overage)
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 ASVS 8.1.1(認可ルールを文書化)
書籍 『実践 Keycloak』8.2 節 pp.145–146/『セキュアAPI』
7.7 節 pp.220–221
68
定義 発行 伝搬 検証 認可 運用 システムの権限:バッチ・運用者・緊急時を分ける 利用者の権限を借りず、主体の種類が分かる形で発行する。運用者は実行者として名を残す 場面 主体とトークン クレームで示すこと 確かめること 夜間バッチ ワークロード自身(client credentials ) sub はクライアント 利用者のトークンと区別できるか 運用者の操作 交換で得た委任のトークン sub に利用者、act に運用者 監査で両方を記録 緊急時の特権(breakglass) 運用者のトークン+承認 may_act・act、承認の ID 承認(RAR・CIBA)と短い期限 基盤の操作 サービスにリンクされたロール サービス自身の ID 管理者も権限を編集できない 運用者が利用者として振る舞うと、sub だけでは区別できない。act で実行者を残し、承認と期限を確かめる 仕様 RFC 8693 §4.1・§4.4(may_act)/RFC 9068 §2.2 ・§5/RFC 9700 §4.15.1 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.3.1.6(非人間は短命・狭いスコープ) 書籍 『OpenID Connect入門』12.5 節 pp.208–209(client credentials) 69
定義 発行 伝搬 検証 認可 運用 マルチテナント:iss と tid の両方で確かめる テナントの表し方は 3 通り。どれでも、発行者・テナント・保存データのテナントを照合する 表し方 例 受け手の確認 テナントごとの発行者 Keycloak のレルム(iss がレルムごと) iss を許可リストと完全一致 テナントのクレーム Entra の tid、Auth0 の org_id、ID-JAG の tenant iss の {tenantid} を tid で置換して一致 テナントごとの宛先 テナントを含む resource の URI aud に自分のテナントが含まれるか 署名の鍵 iss tid 保存データ テナント単位の鍵か 許可したテナントの発行者か iss の中のテナントと一致 行のテナント=tid リーダーの視点 署名鍵はテナント単位にスコープする(IR 8587 §5.2.1.2)。共有の発行者は、他のテナントのトークンも通しうる 仕様 Entra アクセストークンの検証/RFC 8707 §3/RFC 8725 §3.8・§3.9 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.2.1.2(テナント単位の鍵)/ASVS 8.4.1 書籍 『実践 Keycloak』1.4.1.1 節 p.11・4.3 節 p.46(レルム) 70
定義
発行
伝搬
検証
認可
運用
テナントをまたぐ:利用者・運用者・取引先
またぐ場面ごとに、識別子と権限の出し方を変える。テナントをまたいだ暗黙の名寄せはしない
複数テナントの利用者
テナント横断の運用者
取引先(B2B)
• Entra の oid はテナントごとに別
• 交換で得た委任のトークン
• トークン交換で相手の発行者へ
• tid+oid を複合キーに
• 承認と期限を確かめる
• 相手が自分の語彙に変換
• idp で名寄せしない
• sub と act を両方記録
• 外にはペアワイズの識別子
// 運用者がテナント t-042 の利用者のために操作する
{ "sub": "u-7f3a…",
"act": { "sub": "op-118" },
"https://claims.example.com/": { "tenant_id": "t-042" } }
仕様 Entra ID トークンのクレーム/RFC 8693 §4.1/
identity-chaining 草案
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 ASVS 8.4.1(テナント横断の制御)/OWASP WIF CS
取引先の API は自分宛ての aud だけを受け
入れ、クレームを自分の語彙に変換し直す(流れ
の例は Part 6)
書籍 『デジタルアイデンティティのすべて』4.2.4 節 pp.33–35(考
え方)
71
定義 発行 伝搬 検証 認可 運用 BOLA:クレームはオブジェクトの確認を代わらない roles に approver があっても、この請求書を承認できるかは分からない。データ側の照合が要る 3. このオブジェクトか 1. トークンを検証 2. 機能を使えるか 署名・iss・aud・exp・typ roles・scope(BFLA を防ぐ) -- 悪い例:ID だけで取り出す SELECT * FROM invoices WHERE id = :id; -- 良い例:トークンのテナントと主体で絞る SELECT * FROM invoices WHERE id = :id AND tenant_id = :tid AND owner_id = :sub; 所有者・テナントをデータ側で照合(BOLA を防ぐ ) 照合で決めること • 隠すなら 404、示してよいなら 403 • ゲートウェイ・WAF は BOLA を防げない • 利用者 A・B の自動テストで回帰を防ぐ リーダーの視点 クレームは「誰か」「どのテナントか」を運ぶだけ。オブジェクトとの関係は、毎回データの側で確かめる(データ層は Part 7) 指針 OWASP API Security Top 10 2023 API1・API5/ASVS 8.2.2 JWT クレーム設計ガイド|組織で共用する独自クレーム 書籍 『セキュアAPI』4.3 節 pp.101–103・4.7–4.8 節 pp.120–124・2.3.4 節 p.058 72
定義 発行 伝搬 検証 認可 運用 代理の混乱:連鎖を見せ、自分宛てだけを受ける 仲介するサービスが、他人の権限と自分の権限を取り違える。経路をクレームで示し、宛先を確かめる 利用者 サービス A(仲介) サービス B sub = u-7f3a… 自分の広い権限で B を呼ぶと… 誰の権限か分からない 対策 中身 出典 経路を見せる act のネストで委任の連鎖を記録する RFC 8693 §4.1 判断は今の実行者まで ネストした過去の act は情報としてだけ使う RFC 8693 §4.1 自分のための代理か aws:SourceArn・SourceAccount を確かめる AWS の confused deputy トークンをそのまま渡さない 自分宛て以外は受け入れない(MUST NOT) MCP の仕様 経由を別の属性に CalledVia。IP などの文脈はホップで消える AWS FAS ホップごとの交換と絞り方は Part 6、AI エージェントの委任は Part 10 で扱う 仕様 RFC 8693 §4.1/MCP Security Best Practices/AWS confused deputy・FAS JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-228 §2.7.6(confused deputy)/ASVS 8.3.3 73
PART 6 流れ:どこで足し、どこで絞 るか このPartで答えられるようになる問い • クレームは、どの段階で誰が足すのか • 下流へ渡すとき、何をどこまで絞るのか • IP や端末の情報を、トークンに入れてよいか • 誰が・どの経路で・何の承認で動いたかを、どう残す か クレームは発行時だけでなく、入口・サービス間・追加認証・承 認でも生まれる。段階ごとに書き手と寿命を決め、下流ほど 絞る 74
定義 発行 伝搬 検証 認可 運用 段階の地図:クレームは 6 か所で生まれる 段階ごとに、足してよいものと足してはいけないものが違う。寿命と書き手が違うから 段階 代表的な仕組み 足してよいもの 足してはいけないもの ① 認証時(IdP) acr・amr・auth_time 認証の事実(方式・時刻・強さ) 業務の権限の詳細 ② 発行時フック Entra・Auth0・Okta・Cognito・ Keycloak テナント ID・プラン・粗いロール 秒単位で変わる状態、生の個人情報 ③ 入口 phantom token・Passport・ext_authz 内部用トークン、正規化した主体 ID クライアントが送った同名ヘッダーの値 ④ サービス間 Transaction Tokens・mTLS(SPIFFE) 呼び出し全体で不変の文脈、取引 ID 外部のアクセストークンそのもの ⑤ 追加認証 RFC 9470(step-up) より強い・より新しい認証の事実 — ⑥ 承認・同意 RAR・CIBA 承認された取引の内容(金額・相手先) 承認していない操作 クレームの台帳に「どの段階で、誰が書くか」の列を持つ。段階ごとに書き手を 1 つに決める(Part 4) 仕様 RFC 9470/RFC 9396 §9/Transaction Tokens 草案 11 §9.2・§13.4 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-228 §2.7(資格情報の正規化) 書籍 『セキュアAPI』9.1 節 pp.260–268(ゲートウェイの役割) 75
定義 発行 伝搬 検証 認可 運用 発行時フック:失敗しても、トークンは出る 外部 API を呼んで足すクレームは、遅延・上限・失敗で欠けうる。受け手は欠けたら拒否する IdP の仕組み いつ呼ばれるか 制約と挙動 Okta token inline hook カスタム AS の発行時 既定 3 秒で打ち切り、リトライなし。失敗す るとクレームなしで発行 Entra custom claims provider 発行の直前 対応付けたものだけ。文字列と文字列配列、 合計 3KB Auth0 post-login Action ログイン後と、リフレッシュ 時 同期実行。終わるまで後続が待つ Cognito pre token generation 発行時。リフレッシュ時も スコープの追加・抑止は V2_0 以上 Keycloak protocol mapper トークンの生成時 属性はマッパーを置いて初めてクレームにな る 仕様 Okta Inline Hooks/Entra custom claims provider /Auth0 Login Trigger JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-63C-4 §3.12.2(派生属性値)/IR 8587 §5.2.1.1 受け手の規則 • クレームが無ければ拒否する • 無い=権限なし。既定の権限にしない • 大きな権限表は載せず PDP へ • 安定した属性だけを載せる 注意 Entra のサンプルは生年月日を返す。 生の個人情報はフックで足さない( Part 9) 書籍 『実践 Keycloak』4.5.2 節 pp.56–58(マッパーでクレーム にする) 76
定義 発行 伝搬 検証 認可 運用 入口での交換:外の形式を、内側に持ち込まない 外部のトークンは入口で検証して終わらせ、内部専用のトークンに作り替える(腐敗防止層) ブラウザの Cookie 入口(ゲートウェイ) 参照型のアクセストークン 検証して終わらせ、正規化する 内部トークン 正規化した主体 ID・認証レベル・内部の aud サービス群 内部の形だけを読む 取引先・IdP ごとの JWT 方式 入口でしていること クレームの扱い Phantom token(Curity) クライアントには参照型。入口でイントロスペクションし JWT に差し替 え クライアントにはクレームが見えない Split token(Curity) JWT の署名部分だけを渡し、入口で本体と連結 イントロスペクションの往復が要らない Netflix Passport Cookie・端末のトークン・取引先のトークンを入口で終わらせる 内部は HMAC で守った短命の構造。専用ライブラリで読む Cloudflare Access IdP の認証を終え、オリジン向けに自前の JWT を発行 IdP の独自属性は best-effort。約 1KB 超で切り捨て 仕様 Curity Phantom・Split Token/Cloudflare Access app token JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-228 §2.7/OWASP Identity Propagation CS(内部アサーション) 書籍 『セキュアAPI』9.1 節 pp.260–268 77
定義
発行
伝搬
検証
認可
運用
Transaction Tokens:呼び出し全体の文脈を運ぶ
入口で発行し、サービス間は Txn-Token ヘッダーで改変せずに渡す。寿命は分以下
例:入口が取得した Txn-Token(ヘッダー typ は txntoken+jwt)
{
"aud": "trust-domain.example.com",
"txn": "97053963-771d-…",
"sub": "u-7f3a…",
"scope": "orders.create",
"req_wl": "gateway.example.com",
"tctx": { "tenant": "t-042", "action": "CREATE" },
"rctx": { "req_ip": "203.0.113.7" },
"iat": 1795…, "exp": 1795…
}
作り直すとき、権限を減らす・値を足すのは可。scope の拡大と
txn・sub・aud の変更は不可
仕様 Transaction Tokens 草案 11 §6・§9.2・§12・§13.4・§13.15・§15.2
JWT クレーム設計ガイド|組織で共用する独自クレーム
クレーム
要否
意味
txn
必須
取引の一意の ID(監査・リプレイ検知)
sub
必須
取引の主体。信頼ドメイン内で一意
scope
必須
最も狭い目的。TTS が決める
req_wl
必須
Txn-Token を求めたワークロード
aud
必須
信頼ドメイン。その外では受け入れない
tctx
推奨
呼び出し全体で変わらない文脈
rctx
推奨
要求元の IP などの環境
Authorization ヘッダーで送らない。アクセストークンにしない
。全体をログに出さない。旧名 purp・azd は使わない
指針 NIST IR 8587 §5.3.1.6(ワークロードは短命・狭い範囲)
78
定義 発行 伝搬 検証 認可 運用 追加認証と承認:その場で求め、結果を足す 認証の強さは発行時点の事実。高リスクの操作では受け手が判断し、追加認証や承認を求める 追加認証(RFC 9470 step-up) API が拒否 insufficient_user_authenticat ion と acr_values・max_age クライアント IdP API 値を使って認可要求を組み立て直す 追加の認証をして新しいトークン acr・auth_time を確かめて実行 承認の内容:RAR(authorization_details) 別端末での承認:CIBA • 承認された金額・相手先などを運ぶ • 結果は poll・ping・push で受け取る • JWT に入れるときは宛先ごとに絞る • 要求に binding_message を入れられる 追加認証を起動するのは受け手の判断。Entra は acrs と xms_cc で同じことをする。エージェントの承認は Part 10 仕様 RFC 9470/RFC 9396 §9.1・§9.2/CIBA Core §5 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-63C-4 §4.7(認証の新しさ)/OWASP ASVS 10.3.4 79
定義 発行 伝搬 検証 認可 運用 下流ほど絞る:仕様は強制しない。組織で決める RFC 8693 はトークン交換で範囲を狭めることを求めない。aud・scope・寿命の規則は自分で書く 例:ホップごとに絞る 縮小を求める規範 入口 注文サービスへ 在庫サービスへ • Txn-Token:scope は同じかそれ以下 aud api.example.com orders inventory scope orders.read orders.write inventory.reserve orders.write inventory.reserve inventory.reser ve 寿命 1 時間以内 分単位 分単位 • OAuth 2.1:RT は同意した範囲に束縛 • RFC 9700:aud は特定の RS に(SHOULD) • IR 8587:scope は最小限(MUST) 仕様が求めないもの 独自クレーム tenant・plan・roles tenant・roles tenant だけ • RFC 8693 の交換での縮小 • 寿命(Txn-Token は元より長くてよい) リーダーの視点 • act のネストによる縮小の保証 「下流は aud・scope・寿命のどれでも上流を超えない」を規則に書き、トークン 交換のサービスで検証する 仕様 RFC 8693 §5/RFC 9700 §2.3/Txn Tokens 草案 11 §13.6・§13.14 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.3.1.3/OWASP Identity Propagation CS(aud を広げない) 書籍 『実践 Keycloak』6.5 節 p.105(そのまま伝搬する例) 80
定義 発行 伝搬 検証 認可 運用 検証の分担:入口で検証しても、各サービスでも検証する 入口は壊れうるし、入口を通らない経路もある。内部の API にも受け手としての検証を置く 確かめること 入口(ゲートウェイ) 各サービス 署名・iss・exp まとめて確かめる 共通の検証部品で再確認 aud 入口宛てか 自分宛てか(内部トークン・Txn-Token ) 相手のサービス — mTLS の相手と req_wl 独自クレーム 形と有無 意味と、その操作への当てはめ オブジェクト単位 できない データを取るときに照合する 書籍の指摘(p.250) • ゲートウェイも壊れうる • 独自クレームは入口で検証しきれないことがある • すべての API が入口を通るとは限らない リーダーの視点 呼び出し元のサービスと利用者を、それぞれ 認可する(SP 800-228 REC-API-12) 内部の呼び出しでも、元の利用者の権限で判断する。仲介サービスの権限で判断しな い(ASVS 8.3.3) 仕様 RFC 9068 §4(受け手の検証) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-228 REC-API-12/SP 800-207 §2.1 原則 3/OWASP ASVS 8.3.3 書籍 『セキュアAPI』8.5 節 NOTE p.250・3.4 節 pp.082– 084 81
定義 発行 伝搬 検証 認可 運用 アクセス元の文脈:トークンに入れると古くなる IP・ネットワーク・端末は、認証した瞬間の値。認可には PEP がその要求から得た値を使う トークンに入れた文脈 PEP で要求ごとに評価する • Entra の ipaddr は認証した時点の IP • ゲートウェイ・サイドカーが接続から取る • 寿命は既定 60〜90 分、CAE では 20〜28 時間 • サービス間には Txn-Token の rctx で • AWS FAS では VPC 系の条件が消える • PE が判断し、PEP が実施(SP 800-207) • X-Forwarded-For は偽装できる • トークンには「認証時の値」と分かる名前で // トークン:認証時の値と分かる名前で "https://claims.example.com/authn_ip": "198.51.100.20" // Txn-Token:TTS が書く要求時点の値 "rctx": { "req_ip": "203.0.113.7" } 仕様 Entra のクレーム(ipaddr)/Txn Tokens 草案 11 §9.2 (rctx) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-207 §3(PE・PEP)・§2.1 原則 4/IR 8587 §4.1.4 リーダーの視点 「今どこから来たか」の判断を、トークンのクレーム に頼らない 書籍 『デジタルアイデンティティのすべて』(考え方)12.3 節 pp.194–195 82
定義 発行 伝搬 検証 認可 運用 ヘッダーへの転記:利用者が送った同名ヘッダーを消す 検証済みのクレームをヘッダーに写すと、ヘッダーが信頼の対象になる。偽装の入口を塞ぐ クライアント 入口 サービス X-User-Role: admin を付 けて送る ① 同名ヘッダーを除去 ② 検 証 ③ 書き込み 入口が書いたヘッダーだけを 読む ゲートウェイの挙動 • Istio:同名ヘッダーを上書き(試験的機能) • Envoy:全経路で除去してから書く • Envoy:配列等は JSON→base64 事例 何が起きたか 教訓 CVE-2023-27487(Envoy) クライアントが送った内部ヘッダーを除去せず、 JWT の確認を回避 内部ヘッダーも除去する CVE-2025-64484( OAuth2-Proxy) アンダースコアの変種を除去せず、アプリが「-」に 読み替えて信頼 大小文字と _・- を無視し て除去 CVE-2026-26308(Envoy RBAC) 同名ヘッダーの複数の値を連結して照合し、拒否 の規則を回避 重複したヘッダーを拒否 仕様 Istio RequestAuthentication/Envoy jwt_authn( claim_to_headers) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NVD(3 件の CVE)/OWASP Authorization Patterns CS(コピーを除去) • extract_only_without_validation は認可に使 わない ヘッダーだけを見て JWT と署名を確かめな いと、なりすましを許す(Cloudflare Access の注意) 書籍 『セキュアAPI』1.4 節 pp.033–034(利用者が付けるヘッダ ー) 83
定義
発行
伝搬
検証
認可
運用
証跡:誰が・どの経路で・何の承認で動いたか
主体・実行者・経路・承認・取引を別のクレームで残す。ネストした act は監査用で、認可に使わない
{
問い
クレーム・情報
注意
誰の権限で
sub(最上位)
ログではハッシュなどで隠す
誰が実行したか
act(現在の実行者)・req_wl・mTLS の相
手
認可に使うのは最上位と現在の実行者
だけ
どこを経由したか
ネストした act(過去の実行者)
情報提供のみ。認可に使わない
何の承認で
authorization_details・同意 ID(
intent_id など)
承認の記録を指す ID を残す
どの取引か
txn
TTS と各サービスが記録。リプレイ検
知にも
"sub": "u-7f3a…",
"act": {
"sub": "spiffe://example.com/orders",
"act": {
"sub": "spiffe://example.com/gateway"
}
},
"txn": "97053963-…"
}
トークン内の ID(txn)
ヘッダーの ID(traceparent)
署名で改ざんできない → 監査向き
改ざんできる → 観測向き。tracestate に個人情報を入れない
仕様 RFC 8693 §4.1/Txn Tokens 草案 11 §13.2・
§15.2/W3C Trace Context
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 NIST IR 8587 §5.3.1.4・§5.3.1.7 表 6/OWASP
Logging CS
書籍 『デジタルアイデンティティのすべて』(考え方)11.6.7 節
pp.182–183
84
定義 発行 伝搬 検証 認可 運用 結果を返す:JWT にするのは、自己完結した主張だけ 否認防止が要る判断は署名つきで返す。業務データの本文は HTTP メッセージ署名で守る 方式 用途 要点 RFC 9701 署名つきイントロスペクシ ョン応答 AS の判断を否認できない形 で受け取る アクセストークンとして使わない JWT が向く • 自己完結した主張を第三者に示す • 受け手が複数、オフラインで検証 JARM 認可応答の完全性 iss・aud・exp 必須。最大 10 分 を推奨 RFC 9421 HTTP Message Signatures Webhook・サービス間の応 答 @method・@path・ContentDigest、created・keyid を要求 できる(必須はプロファイルで) 承認つきトークン(RAR) 人の承認の証跡 authorization_details を宛先 ごとに SET(RFC 8417)・CAEP 状態の変化の通知 Part 8 で扱う • 期限と宛先に意味がある JWT が向かない • 大きな本文・ストリーム → RFC 9421 • すぐ取り消したい → 参照型 • 中継者に見せたくない機密 typ で種類を分け、種類ごとに検証規則を分ける。結果の JWT をアクセストークンと取り 違えさせない 仕様 RFC 9701/RFC 9421/JARM/RFC 8725 §3.11・ §3.12 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP Authentication Patterns CS(HTTP Message Signatures) 書籍 『セキュアAPI』10.6 節 pp.301–304(FAPI 2.0 メッセー ジ署名) 85
定義 発行 伝搬 検証 認可 運用 流れの例 1:ブラウザから DB まで ブラウザにトークンを置かず、入口で内部の形に替え、DB には利用者のトークンを渡さない ブラウザ BFF ゲートウェイ • セッションの Cookie だ け • IdP から AT・RT・ID ト ークン • トークンを置かない • + acr・amr(認証時) • + tenant・plan(フック ) サービス A・B DB • ✓ aud・exp・scope • mTLS + Txn-Token • − 利用者が送った XUser-* • ✓ 相手の ID と req_wl • サービスの資格情報で接 続 • + 正規化した sub • ✓ scope が操作に合う か • TTS から Txn-Token • 改変せずに転送 • ID トークンは API に送 らない • 利用者の AT は渡さない • 行の絞り込みに tctx.tenant • 詳細は Part 7 凡例 + 追加 − 除去 ✓ 検証 高リスクの操作:サービスが insufficient_user_authentication を返し、BFF が追加認証して新しい AT を取る 仕様 RFC 8707(resource)/RFC 9470/Txn Tokens 草 案 11 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP ASVS 10.1.1(トークンは必要な所だけ)/NIST SP 800-228 §2.7 書籍 『OpenID Connect入門』10 章 pp.143–167(BFF) 86
定義 発行 伝搬 検証 認可 運用 流れの例 2:マルチテナント SaaS テナントは入口で 1 回確かめて Txn-Token の tctx に固定し、以降は誰も書き換えない ホップ 持つトークン クレームの操作 ログイン テナント固有の発行者、または tenant 付きの AT + tenant、テナント内のロール(発行時フック) 入口 同上 ✓ iss とテナントの対応・aud。✓ URL やヘッダーのテナント ID と一致するか。 不一致なら拒否 入口 → TTS Txn-Token + tctx.tenant(以降は変わらない) サービス間 Txn-Token 作り直しても sub・aud・txn は変えられない。tctx は TTS が決める 運用者の横断作業 トークン交換で得た委任の AT(may_act) + act.sub=運用者。✓ 緊急時の承認と期限。監査に顧客と運用者の両方 外部への識別子 Entra なら oid+tid と sub 社内の照合は不変の ID、外部にはアプリごとの値 テナントを書ける者を、発行時フックと TTS の 2 つに限る。以降のホップは読むだけ 仕様 Txn Tokens 草案 11 §9.2・§13.15/RFC 8693 §4.1・§4.4 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.2.1.2(テナント単位の鍵)/OWASP ASVS 8.4.1 書籍 『実践 Keycloak』4.3 節 p.46(iss はレルムごと) 87
定義 発行 伝搬 検証 認可 運用 流れの例 3・4:取引先との API と、イベント駆動 ドメインをまたぐときは相手の AS で作り直す。キューにはトークンでなく主体の参照を入れる 取引先との API(ドメインをまたぐ) イベント駆動(Pub/Sub・Kafka・ワークフロー) ホップ クレームの操作 ホップ クレームの操作 自社の AS トークン交換。主体 ID の写像・最小化・絞り込み。aud は相 手の AS 1 つ トピックへ発行 発行者のワークロード ID。メタデータに利用者の間接参照と txn。AT は入れない 相手の AS ✓ aud=自分(RFC 7523 のグラント)。相手の形に作り直 し、短命の AT 配送(push) サービスアカウントの OIDC トークン。✓ aud・期待するア カウントか 相手の API mTLS か DPoP で送信者に束縛。✓ cnf コンシューマー 自分の ID で Txn-Token を取得。TTS が利用者と承認の 有効性を判断 応答・Webhook RFC 9421 で署名(Content-Digest・created・keyid ) 失効 SSF・CAEP の SET。txn で同じ原因のものを相関 夜間バッチ・長時間ジョブは Part 8、AI エージェントの流れは Part 10 で扱う 仕様 Identity Chaining 草案 17 §2.3・§2.5/RFC 7523/RFC 9421/CloudEvents Auth Context JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 FAPI 2.0 §5.3.2.1(送信者制約)/SSF 1.0 §4.1.9 88
定義 発行 伝搬 検証 認可 運用 流れの規則:レビューで確かめる 10 項目 足す・絞る・渡す・残すの規則。どれも仕様だけでは担保されず、組織で決めて検証する 1 段階ごとに書き手を決め、フックには安定した属性だけを入れ る 6 Txn-Token は専用ヘッダーで送り、アクセストークンにしない 2 フックの失敗でクレームが欠けたら、受け手は拒否する 7 入口でも、各サービスでも検証する 3 外部のトークンは入口で終わらせ、内部専用の形に替える 8 利用者が送った ID 系のヘッダーは、除去してから書き込む 4 受け取ったトークンを、別の宛先へそのまま渡さない 9 アクセス元の文脈は、PEP が要求ごとに評価する 5 下流は aud・scope・寿命で上流を超えない(組織の規則) 10 sub・act・txn・承認 ID を分けて残す。トークン全文は残さな い 仕様 RFC 8693 §4.1・§5/Txn Tokens 草案 11 §12・ §13 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.3.1.3・§5.3.1.7/OWASP Identity Propagation CS 書籍 『セキュアAPI』8.5 節 NOTE p.250 89
PART 7 データ層:データアクセスと データベース認証 このPartで答えられるようになる問い • クレームは、どの経路で DB に届くか • 誰が DB の文脈を設定してよいか • 接続プールで、なぜ他人の文脈が漏れるのか • DB の監査ログに、利用者を残すべきか クレームは DB の手前で消えない。行の絞り込み・DB への ログイン・マスキングで、誰がどの値を信じるかを決める 90
定義 発行 伝搬 検証 認可 運用 DB への 3 つの経路:誰がクレームを解釈するか 注入する/DB が検証する/STS が一時認証情報に替える。経路ごとに信頼境界が違う A 注入する B DB が検証する C STS が変換する ゲートウェイ・アプリが DB の文脈を設定 DB がトークンを受け、自分の主体に対応付け クレームを一時認証情報の属性に • 例:PostgREST・Supabase・Hasura・ Data API builder・アプリの set_config • 例:Azure SQL・PostgreSQL の Entra 認証、Snowflake External OAuth、 Kafka • 例:AWS のセッションタグ、GCP Workload Identity Federation • DB が信じる:注入した者 • 危険:任意の SQL での上書き、接続プールで の漏れ • DB が信じる:発行者と対応付けの規則 • 危険:トークンの寿命と接続の寿命のずれ • DB が信じる:信頼ポリシーと属性の対応 • 危険:利用者が編集できる属性からタグを作 る 経路を選ぶ前に「DB の文脈を設定するのは誰か」を図に書く。その主体以外が書ける経路を残さない 仕様 PostgREST Transactions/Azure SQL Entra 認証/ AWS STS セッションタグ JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-162 §3.1.3.3(権威ある者だけが属性を付 与) 書籍 『デジタルアイデンティティのすべて』(考え方)12.3 節 pp.194–195 91
定義 発行 伝搬 検証 認可 運用 行単位の制御:クレームで行を絞る製品の違い 同じ「クレームで行を絞る」でも、どのクレームを誰が評価するかが製品ごとに違う 製品 クレームの届き方 評価する者 注意 PostgreSQL RLS+ PostgREST request.jwt.claims(取引単位)。role で SET LOCAL ROLE DB のポリシー role は DB ロールそのもの。汎用名は衝突する Supabase auth.uid()・auth.jwt() DB のポリシー user_metadata は本人が書ける。 app_metadata を使う Hasura x-hasura-* のセッション変数 Hasura エンジン x-hasura-role で許されたロールから選べる SQL Server・Azure SQL SESSION_CONTEXT(アプリ・DAB が設定) DB のセキュリティポリシー DAB は全クレームを送る。@read_only を確認 Snowflake scp の session:role:* → CURRENT_ROLE() row access policy IdP の scope が見える行を決める BigQuery IAM の主体(WIF で対応付け) row access policy セッション変数ではなく主体で評価 RLS をすり抜ける主体を通常の経路から外す:superuser・BYPASSRLS・テーブル所有者・SUPERUSER が作ったビュー・Supabase の secret key 仕様 PostgreSQL RLS/PostgREST Auth/Supabase RLS/Hasura JWT JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP ASVS 8.2.2(データ単位の認可)・8.4.1 書籍 『セキュアAPI』4.3 節 pp.101–103(取得時に所有者を照合 ) 92
定義 発行 伝搬 検証 認可 運用 信頼境界:DB の文脈を設定してよいのは誰か 注入型の分離は、注入者以外が同じ接続で SQL を流せた時点で崩れる。AWS と Microsoft が明記 AWS の注意 • クエリできる者は誰でもセッション変数を変えられる。分離は弱い DB の権限を選ぶクレーム 何を選ぶか PostgREST の role DB のロール(SET LOCAL ROLE) Hasura の x-hasura-allowedroles 選べるロールの範囲 Snowflake の session:role:* セッションのロール Supabase の app_metadata 認可データ(user_metadata は不 可) • → 全 SQL に WHERE を付ける規約とレビューを併用 Microsoft の注意 • どのユーザーも自分のセッションの SESSION_CONTEXT を設定でき る • → @read_only = 1 と、接続主体の確認 SET LOCAL ROLE も、同じ取引で任意の SQL を流せれば RESET ROLE で戻せる。クライアントに任意の SQL を流させない DB の権限を選ぶクレームは最高権限のクレーム。発行元を限定し、名前空間を付けて製品の設定(jwt-role-claim-key など)で対応付ける 仕様 sp_set_session_context/PostgreSQL SET ROLE/Snowflake External OAuth JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-162 §3.1.3.3(本人が変えられない属性) 93
定義 発行 伝搬 検証 認可 運用 接続プール:前の利用者の文脈が残る セッション単位の設定は、プールで次の要求に引き継がれる。文脈は取引ごとに設定する 危ない:セッション単位の設定 -- 接続を取り出すたびに SET app.current_tenant = 't-042'; SELECT * FROM orders; -- 戻さずに返却 → 次の要求に残る 安全:取引単位の設定 BEGIN; SELECT set_config('app.current_tenant', $1, true); SELECT * FROM orders; -- RLS が行を絞る COMMIT; -- ここで設定が消える 環境 規則 PostgreSQL SET LOCAL か set_config(…, true) PgBouncer(transaction pooling) SET・RESET は使えない PostgREST 取引単位。コミット後は空文字になる SQL Server @read_only = 1。述語で接続主体も確認 ロールの切り替え サーバー側で SET LOCAL ROLE AWS も「サーバー側のプールとは互換性がない場合がある。状態を共有するか試験せよ」と注意している。値は文字列の連結でなくパラメータで渡 す 仕様 PostgreSQL set_config/PgBouncer features/SQL Server RLS(@read_only)/ PostgREST JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP ASVS 8.4.1(テナント横断の制御) 94
定義 発行 伝搬 検証 認可 運用 DB 認証:パスワードの代わりにトークンで入る DB がトークンを検証し、自分の主体に対応付ける。照合のキーは名前ではなく不変の ID 製品 対応付けのキー 要点・注意 Azure SQL(Entra) オブジェクト ID(SID) Entra のトークンだけ。グループ 2048 超はログイン不可。DB 内に主体を作る Azure PostgreSQL(Entra) 一意なユーザー ID 利用者は最大 1 時間、システム MI は最大 24 時間。同名で作り直すと別人 RDS・Aurora(IAM) IAM ポリシーの rds-db:connect トークンは 15 分。CloudTrail に IAM 認証は残らない Cloud SQL(IAM) IAM の主体(メールアドレス) トークンは 1 時間。コネクタが更新。グループ認証で個人の操作が監査に残る Snowflake External OAuth sub・upn を login_name に scp の session:role:* がロール。ACCOUNTADMIN などは既定でブロック Kafka OAUTHBEARER sub(名前は設定で変更可) 既定の unsecured 実装は本番不可。issuer・audience・JWKS を設定 組織の独自クレームを使うなら、製品ごとの「クレームの位置」の設定で対応付ける(Kafka の sub.claim.name、Snowflake の scope 属性など) 仕様 Azure SQL・PostgreSQL Entra 認証/RDS IAM/Cloud SQL IAM/Snowflake External OAuth JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.3.1.6(ワークロードは短命のトークン) 95
定義 発行 伝搬 検証 認可 運用 寿命のずれ:トークンが切れても、接続は生きている 多くの DB でトークンは「接続を開く鍵」。失効やロールの剥奪は、開いた接続に届かない ロールを剥奪 トークン(例:RDS は 15 分) この後も同じ接続で読める 接続(プールで使い回される) 時間 → 接続の最大寿命を 利用者のクレームは すぐ止めるなら トークン寿命以下に 取引ごとに注入 DB 側の主体を削除 製品 開いた接続への影響 RDS・Aurora IAM 影響しない(認証時だけ使う) Cloud SQL IAM 影響しない(期限後に失敗するのは新しい 接続だけ) Azure PostgreSQL 削除した利用者も最大 60 分は入れる。 DB 側で削除すれば即時 Kafka connections.max.reauth.ms で再 認証を強制。しなければ切断 1 時間のトークンで開いた接続を、ロールの剥奪後もプールで使い続けない。Kafka の再認証の既定値は 0(無効) 仕様 RDS IAM DB 認証/Cloud SQL IAM/Azure PG Entra/Kafka broker configs JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §4.1.4(有効性を権限付与と揃える)/OWASP ASVS 8.3.2 96
定義 発行 伝搬 検証 認可 運用 誰として接続するか:利用者の ID か、サービスの ID か 利用者単位の監査が要るなら ID を DB まで伝える。代わりに接続数とプールの効率を払う 観点 ID を伝える(OBO・DB のトークン認証) サービス ID+文脈の注入 サービス ID+アプリで認可 DB が知る主体 利用者(oid・sub) サービス+注入した属性 サービスだけ DB の監査ログ 利用者 サービス(注入値を別に記録しない限り) サービスだけ プールの効率 低い(利用者ごとのプール) 高い(取引単位の注入が前提) 高い 主な危険 寿命のずれ、接続数の増加 文脈の漏れ・偽装 アプリの不具合がそのまま越境 Entra OBO → Azure SQL 利用者の主体だけ。DAB は利用者ごとのプール でキャッシュ無効 仕様 Entra OBO/Data API builder OBO/AWS SaaS RLS・TVM の解説 JWT クレーム設計ガイド|組織で共用する独自クレーム AWS の SaaS 分離 RLS と app.current_tenant。全 SQL に WHERE も 指針 OWASP ASVS 8.3.3(元の主体の権限で判断)/NIST IR 8587 §5.3.1.4 Token Vending Machine JWT からテナント ID → ポリシーかタグ → AssumeRole 書籍 『セキュアAPI』4.6.2 節 pp.117–120(所属を DB で照合) 97
定義 発行 伝搬 検証 認可 運用 マスキング:ロールを決めるクレームが最も機微 マスキングはロールで選ばれる。ロールを決めるクレームの発行が、事実上の平文の閲覧権になる IdP トークン scope を発行 scp に session:role:analyst Snowflake CURRENT_ROLE() = ANALYST マスキング このロールなら平文を返す 製品 何で選ぶか 注意 Azure SQL・SQL Server DDM UNMASK 権限(Entra のグループにも付与可) 推論・総当たりは防がない。CONTROL を持つ管理者は常に平文 Snowflake CURRENT_ROLE()・IS_ROLE_IN_SESSION ロールの階層が要るなら IS_ROLE_IN_SESSION BigQuery Masked Reader・Fine-Grained Reader ポリシータグの階層で最初に見つかったロールが使われる DDM と RLS だけで機微データを守らない。エラー・統計・クエリ時間からも推測される。最小権限と監査を併用する(Part 9) 仕様 SQL Server DDM/Snowflake masking policies/BigQuery data masking JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-162 §3.2.1.6(許可・拒否から属性が推測される) 98
定義
発行
伝搬
検証
認可
運用
クラウドの属性:クレームがそのまま効くとは限らない
STS はクレームを一時認証情報の属性に替える。Azure Storage はクレームでなく属性を見る
AWS STS セッションタグ
GCP Workload Identity
Federation
Azure Storage ABAC
• タグは 50 個まで。多値は不可
• 属性の対応付けを CEL で書く
• 全ロールの信頼ポリシーに
sts:TagSession
• attribute condition で受け入れを絞る
• 主体の属性は Entra のカスタムセキュリテ
ィ属性
• principalSet で属性ごとに付与
• アプリの独自 JWT クレームでは効かない
• aws:RequestTag で渡せる値を制限
"https://aws.amazon.com/tags": {
"principal_tags": { "TenantID": ["t-042"] },
"transitive_tag_keys": ["TenantID"]
}
仕様 AWS STS セッションタグ/GCP Workload Identity Federation/Azure ABAC 条件の
形式
JWT クレーム設計ガイド|組織で共用する独自クレーム
• 同じ値を属性として二重に持つ
リーダーの視点
タグや属性の元を、利用者が編集できる属性にしない。トー
クンにあっても、ポリシーで使えるとは限らない
指針 OWASP Workload Identity Federation CS(ポリシーで使えるか確認)
99
定義 発行 伝搬 検証 認可 運用 データ層の規則:レビューで確かめる 10 項目 誰が文脈を設定するか、どの単位で設定するか、接続がいつまで生きるかを確かめる 1 DB の文脈は、検証済みトークンを受けた注入者だけが設定す る 6 RLS をすり抜ける主体を、通常の経路から外す 2 PostgreSQL は SET LOCAL か set_config(…, true) 7 DB ユーザーの対応付けは、名前でなく不変の ID で 3 SQL Server は @read_only = 1 と接続主体の確認 8 トークンと接続の寿命を分け、プール接続の寿命を決める 4 認可には、本人が書き換えられない属性だけを使う 9 利用者単位の監査が要るなら、ID を DB まで伝える 5 DB ロールを選ぶクレームは高権限。発行元を限定する 10 クレームが欠けたら拒否。DDM・RLS だけに頼らない 仕様 PostgreSQL・PostgREST・SQL Server・Supabase の 公式文書 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP ASVS 8.2.2・8.4.1/NIST SP 800-162 §3.1.3.3 書籍 『セキュアAPI』4.3 節 pp.101–103 100
PART 8 有効期限・リフレッシュ・失 効 このPartで答えられるようになる問い • トークンの寿命は、何を根拠に決めるか • リフレッシュのとき、クレームは計算し直されるか • ローテーションは常に正しいか • 利用者が去った後のジョブは、誰の権限で動くか トークンのクレームは発行時点の写し。いつまで信じてよいか を決め、変わったときに止める仕組みを用意する 101
定義 発行 伝搬 検証 認可 運用 トークンの種類と寿命:種類ごとに別々に決める アクセストークン・ID トークン・リフレッシュトークン・セッションは、役割も寿命の根拠も違う 種類 役割 寿命の手がかり(仕様・指針) 既定の例 アクセストークン API での認可 短命。1 時間以内とすべき(IR 8587) Entra 60〜90 分、Keycloak 5 分 ID トークン ログインの確認 短命。セッションの長さと混同しない Keycloak は AT と同じ 5 分 リフレッシュトークン AT の取り直し 対話用は再認証の期間を超えない Entra 90 日(SPA は 24 時間) セッション 再認証までの期間 AAL2 は 24 時間・無操作 1 時間 Keycloak SSO 最大 10 時間 認可コード 1 回限りの引換券 5 分以内(63C-4)、FAPI は 60 秒 — Txn-Token 内部の呼び出し連鎖 分以下(草案。Part 6) — リーダーの視点 「トークンの寿命」を 1 つの数字で語らない。種類ごとに上限を決め、組織の規則として文書化する 仕様 RFC 9700 §2.2.2/FAPI 2.0 §5.3.2.1/Entra・ Keycloak 各文書 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.3.1.1/SP 800-63B-4 §2.2.3/ 63C-4 §4.7・§4.11.1 書籍 『実践 Keycloak』12.3 節 pp.242–250/『デジタルアイデ ンティティのすべて』(考え方)13.7.4.3 節 p.227 102
定義 発行 伝搬 検証 認可 運用 寿命の決め方:RFC に数値はなく、指針は IR 8587 RFC は「短く」とだけ言う。最も明確な数値は NIST IR 8587 の「1 時間以内とすべき」 ≤ 1 時間 24h/12h ≤5分 アクセストークン・ID トークン(IR 8587 §5.3.1.1、SHOULD) 再認証の上限 AAL2/AAL3(63B-4)。対話用 RT はこれを超えない アサーション参照(認可コードなど)(63C-4 §4.11.1) 短くする理由 短すぎる代償 組織で決めること • 漏えい時に悪用できる期間が縮む • リフレッシュが増え、性能が落ちる • 種類ごとの上限を文書にする • 剥奪や属性の変更が早く届く • IdP が止まったときの影響が大きい • 例外を認める手順を決める • 即時の失効の仕組みを軽くできる • 認可サーバーへの依存が増す • AT の期限を当てにした実装をしない 書籍の「まず 30 分」は著者自身が根拠なしと断る目安。規範として引かない 仕様 RFC 7009 §3/FAPI 2.0 §6.1/OAuth 2.1 草案 17 §1.4(数値の規範なし) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.3.1.1/SP 800-63B-4 §2.2.3・ §2.3.3/63C-4 §4.11.1 書籍 『OpenID Connect入門』4.4・13.9.7 節 pp.68–69, 229/『実践 Keycloak』12.3.1 節 pp.243–245 103
定義
発行
伝搬
検証
認可
運用
寿命の間のクレーム:剥奪しても exp までは古い値
自己完結型のトークンは発行時点の写し。権限を外しても、期限が切れるまでは古い値で通る
10:00 発行
10:20 剥奪
10:20〜11:00
11:00 exp
roles に approver を載せる
IdP では承認者から外れる
トークンは approver のまま通る
次の発行で反映(IdP 次第)
{
"iss": "https://idp.example.com",
"sub": "u-7f3a…",
"iat": 1795…000,
"exp": 1795…600,
"https://claims.example.com/tenant": "t-042",
"https://claims.example.com/roles": ["approver"]
}
// 10:20 に外しても、exp までは approver のまま
仕様 RFC 7009 §3/CAEP 1.0 §3.2.1(token-claimschange)/Entra CAE 文書
JWT クレーム設計ガイド|組織で共用する独自クレーム
古さを縮める 3 つの手段
• 短命化:AT を短くする
• 都度判定:重要な判断は PDP に問い合わせる
• イベント:CAEP の token-claims-change を受ける
• 実例:Entra CAE はグループ変更の反映に最大 1 日
指針 NIST IR 8587 §4.1.4(有効性を権限の付与・解除と整合)
書籍 『OpenID Connect入門』4.2.3 節 pp.66–67
104
定義 発行 伝搬 検証 認可 運用 リフレッシュ時の再評価:IdP ごとに違う リフレッシュでクレームが計算し直されるかは製品次第。確かめずに前提にしない IdP リフレッシュ時の動き 設計への含意 Auth0 ログイン後の Action が RT の交換時にも動く。独自クレームは計算し直される Action の中で最新の値を引く Cognito 発行前フックが TokenGeneration_RefreshTokens で呼ばれる。 Lambda で計算し直せる フックで再計算を実装する Entra ID RT は利用者とクライアントに束縛。使うたびに新しい RT が出るが、古い RT は自動では失効しない(文書はアプリに古い RT の削除を求める。再利用検知の 記述なし) RT の漏えいを前提に AT を短く。CAE を使う Keycloak トークン交換で出した RT は、セッションが続く限り元の期限を越えて使えると 公式に警告 新しい subject token で交換し直す リーダーの視点 再計算されない、または確かめられない IdP では、AT を短くし、重要な判断は PDP に問い合わせる 仕様 Auth0 Actions/Cognito 発行前フック/Entra refresh tokens/Keycloak token exchange JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.3.1.1・§4.1.4 書籍 『実践 Keycloak』12.3.2 節 pp.245–247 105
定義 発行 伝搬 検証 認可 運用 ローテーション:RFC 9700 と FAPI 2.0 は前提が違う 対象が違う。公開クライアントは送信者制約かローテーション、FAPI 機密クライアントは送信者制約 RFC 9700:公開クライアント FAPI 2.0:機密クライアント • RT は送信者制約か、ローテーションが必須 • AS はローテーションを使わない(例外を除く) • 使うたびに新しい RT、古い RT は無効 • 送信者制約の下では利点がないため • 無効な RT が来たら、有効な RT も失効 • AT は送信者制約付きだけを発行 • 長く使われない RT は失効させる(SHOULD) • クライアントはローテーションに対応する クライアントの種類で分ける。公開クライアントはローテーション+再利用検知(MCP 仕様は AS に MUST)、FAPI 対象の機密クライアントは 送信者制約でローテーションなし。送信者制約なら両方を満たせる Auth0:再利用を検知すると RT の系列全体を無効化(ログに ferrt) 仕様 RFC 9700 §2.2.2・§4.14.2/FAPI 2.0 §5.3.2.1 NOTE 1・§5.3.3.1/MCP 認可仕様 JWT クレーム設計ガイド|組織で共用する独自クレーム Keycloak:Revoke Refresh Token は既定で無効。有効にすると 1 回 限り 指針 NIST IR 8587 §5.3.1.2(侵害の疑いのある RT は再認証 書籍 『セキュアAPI』7.4.5・10.4 節 pp.209–210, 293/『実践 なしに受けない) Keycloak』12.3.3 節 pp.247–248 106
定義 発行 伝搬 検証 認可 運用 失効の伝播:問い合わせ・状態リスト・イベント 失効を受け手に届ける手段は 3 つ。届いた受け手は拒否し、セッションを終える SET を送る 発行者・IdP 剥奪・停止・侵害を検知 受け手 session-revoked、token-claimschange トークンを拒否し、セッションを終える 手段 仕組み 状態 注意 イントロスペクション 受け手が毎回 AS に問い合わせる RFC 7662 キャッシュは応答の exp を超えない Token Status List status がビット列の位置を指す 草案(RFC Editor 待ち) RFC 番号は未割当 SSF/CAEP 発行者がイベントを SET で送る Final(2025-09) txn で同じ原因のイベントを相関 Entra CAE CAEP をもとに重大イベントで失効 製品機能 伝搬に最大 15 分。AT は最長 28 時間 失効を受け取った受け手は、トークンを拒否し、セッションを終えなければならない(IR 8587 §5.3.1.2、MUST) 仕様 RFC 7662 §4/Token Status List 草案 21/SSF 1.0・CAEP 1.0(Final) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.3.1.2/DS-511 表3-14(共有シグナ ルの合意) 書籍 『実践 Keycloak』12.3.4 節 pp.248–250 107
定義
発行
伝搬
検証
認可
運用
非同期処理:キューに利用者のトークンを入れない
メッセージには主体の参照と txn だけ。受け手が自分のワークロード ID で作り直す
1. ジョブ登録
2. キュー
3. ワーカー
4. トークン交換
5. 下流
AT を検証。sub・tenant・
承認 ID を保存
トークンは入れない。authid
はハッシュ
自分のワークロード ID で認
証
sub=利用者、act=ワーカ
ー。分単位
act を確かめ、誰の権限で誰
がを記録
// キューに入れるイベントの例(CloudEvents)
{
"type": "com.example.invoice.approved",
"authtype": "app_user",
"authid": "sha256:9c1e…",
"data": {
"tenant": "t-042",
"approval_id": "ap-311",
"txn": "6f0b…" }
}
CloudEvents の規則
• authclaims に資格情報を入れない(MUST NOT)
• authid に個人情報を入れない
Pub/Sub の push
• 配信にサービスアカウントの OIDC トークン
• 受け手は aud・email・email_verified を確かめる
仕様 CloudEvents Auth Context 拡張/Pub/Sub push 認証/Txn-Token 草案 11 §6
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 NIST IR 8587 §5.3.1.6(非人間 ID は狭く短命なトークン)
108
定義
発行
伝搬
検証
認可
運用
期限切れの後の下流呼び出し:作り直しを AS が判断
利用者のトークンを延命しない。ワークロード ID で交換し、可否はその都度 AS が決める
方式
何が起きるか
評価
利用者の RT を保持して更新(
offline_access)
長命の資格情報がジョブ側に残る。剥奪
が届きにくい
避ける
サービス自身の権限だけで呼ぶ
誰の権限で動いたかが消える。sub の
捏造は禁止
利用者の文脈が要
らない処理だけ
ワークロード ID で交換し、短命
トークンを作り直す
AS が承認記録と利用者の状態を見て、
毎回可否を決める
推奨(本資料)
// 作り直したトークンの例
{
"sub": "u-7f3a…",
"act": {
"sub": "spiffe://example.com/
billing-worker" },
"aud": "https://api.example.com/
invoices",
"exp": 1795…300,
"https://claims.example.com/
approval_id": "ap-311"
}
補足(本資料の推奨)
③は複数の仕様(RFC 8693、Txn-Token 草案)と製品の部品を組み合わせた本資料の推奨。単一の仕様の手順ではない
仕様 RFC 8693 §4.1(act)/OIDC Core §11(
offline_access)/ID-JAG 草案 06 §4.4.4
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 NIST SP 800-63B-4 §5.1.2(AT は利用者がいる証拠
ではない)
書籍 『デジタルアイデンティティのすべて』(考え方)13.7.4.2 節
pp.226–227
109
定義 発行 伝搬 検証 認可 運用 判断表:寿命・リフレッシュ・失効を状況で選ぶ クライアントの種類と、剥奪をどれだけ早く効かせたいかで組み合わせを決める 状況 寿命 リフレッシュ 失効 一般の Web・SPA(公開クライアント) AT は 1 時間以内 ローテーション+再利用検知、または送信 者制約 SSF・CAEP、ログアウトで RT を失 効 FAPI 対象の機密クライアント AT は短命・送信者制約 ローテーションしない RS が失効状態を確かめる 剥奪をすぐ効かせたい操作 短命+都度判定 再計算されるかを確かめる イントロスペクション・PDP サービス間のワークロード できるだけ短く RT は持たないか、できるだけ短く ID・鍵の廃止で止める 長時間ジョブ・非同期処理 分単位で都度取り直す 利用者の RT を持たない 取り直しの時点で AS が拒否 リーダーの視点 「何分にするか」より先に「剥奪をどれだけ早く効かせたいか」を決める。数字はそこから導く 仕様 RFC 9700 §2.2.2・§4.14.2/FAPI 2.0 §5.3.2.1/ RFC 7662 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.3.1.1・§5.3.1.2・§5.3.1.6/SP 800-63B-4 §2.2.3 書籍 『実践 Keycloak』12.3 節 pp.242–250 110
PART 9 機微情報・最小化・ログ このPartで答えられるようになる問い • トークンに載せてはいけない情報は何か • 生の値の代わりに何を渡せばよいか • ペアワイズの識別子と暗号化は、いつ使うか • ログとトレースに何を残し、何を残さないか 署名つきのトークンは誰でも読める。載せる情報を最小にし、 ログ・URL・ブラウザから漏らさない 111
定義
発行
伝搬
検証
認可
運用
JWS は誰でも読める:載せる前に漏れる先を考える
Base64URL は暗号ではない。トークンを手にした人は誰でもペイロードを読める
// 誰でもデコードして読める
{
"sub": "u-7f3a…",
"email": "[email protected]",
"birthdate": "1990-04-01",
"ipaddr": "203.0.113.24",
"https://claims.example.com/permissions":
["invoice:read", "invoice:approve", …]
}
RFC 7519 §12 の 3 点
• 機微情報を含むなら漏えい対策が必須
• 暗号化+受け手の認証、または TLS のみ
• 最も簡単なのは、含めないこと
見える場所
• ブラウザ・ゲートウェイ・ログ・トレース
• クライアントも中身を見られる
トークンに載せた値は、トークンが通るすべての場所に配られる。載せる前に「誰が読めるか」を問う
仕様 RFC 7519 §12/RFC 9068 §6(中身は利用者・クライ
アントに見える)
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 OWASP JWT Cheat Sheet/ASVS 14.1.1(ペイロードを
書籍 『セキュアAPI』7.2.2 節 pp.195–197
機微データとして分類)
112
定義 発行 伝搬 検証 認可 運用 載せない情報:秘密・機微な属性・変わる識別子 認証の秘密は禁止。機微な属性は API で、識別子は不透明な ID で、権限の一覧は PDP で 種類 例 理由 代わり 認証の秘密 パスワード、API キー アサーションに含めてはならない 入れない 機微な属性 氏名・住所・生年月日 全リクエストに載り、盗まれうる identity API・UserInfo で取得 平文の個人情報を含む ID メールや社員番号を sub に FAL2 以上では禁止 不透明な ID、ペアワイズの sub 変わりうる識別子 email、upn 再利用・変更で別人になる oid+tid、iss+sub(Part 4) 細かい権限の一覧 エンドポイントごとの許可 内部の構成が見え、肥大する PDP に問い合わせる(Part 5) 接続元の詳細 IP、端末の識別子 個人データになりうる。古くなる PEP で都度取得(Part 6) リーダーの視点 迷ったら載せない。必要な受け手だけが、必要なときに API で取りに行く形にする 仕様 RFC 7519 §12/Entra optional claims(email・upn を認可に使わない) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-63C-4 §2.3・§3.12・§4.9/SP 800228 REC-API-11 書籍 『セキュアAPI』7.2.2・7.7 節 pp.195–196, 220–221 113
定義
発行
伝搬
検証
認可
運用
最小化と派生値:生年月日ではなく「18 歳以上か」
受け手が要るのは値か判定か。判定で足りるなら、元の値を明かさない派生値を渡す
値を渡す
判定を渡す(派生値)
{
{
"sub": "u-7f3a…",
"birthdate": "1990-04-01"
"sub": "u-7f3a…",
"https://claims.example.com/age_over_18": true
}
// 生年月日がすべての受け手に渡る
最小限だけ
}
// 判定だけ。元の値は明かさない
派生値
機微な属性は API で
• 機能に必要なデータだけ(63C-4 §3.10)
• 元の値を明かさない(§3.12.2)
• アサーションに入れない(§3.12.3)
• 必要以上を取得しない(DS-511)
• 判定は発行者が責任を持つ
• 送信者制約・期間を限る
クレームを足す前に「受け手は値が要るのか、判定で足りるのか」を問う
仕様 OIDC Core §5.1(標準クレーム birthdate)
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 NIST SP 800-63C-4 §3.10・§3.12.2・§3.12.3/
DS-511 表3-14 No.1
書籍 『デジタルアイデンティティのすべて』(考え方)4.2.2 節 p.31
/『実践 Keycloak』14.4 節 p.293
114
定義 発行 伝搬 検証 認可 運用 ペアワイズの識別子:受け手ごとに違う sub 同じ利用者でも受け手ごとに sub を変えれば、受け手どうしで突き合わせて追跡できない 受け手 A(経費) 種類 同じ利用者の sub 用途 public 全受け手で同じ 社内の共通 ID pairwise セクターごとに違う 外部の受け手、追跡を防 ぐ Entra の sub アプリごと(ペアワイズ) アプリの中の識別 Entra の oid+tid アプリをまたいで共通 サービス間のデータ共有 sub: 8d2c… 利用者 受け手 B(人事) 1人 sub: 41fa… 外部の受け手 C sub: e07b… リーダーの視点 社内で突き合わせる ID と、外部に出す ID を分ける。突き合わせが要るなら同じセクターにするか、別の ID を設計する 仕様 OIDC Core §8・§8.1/RFC 9068 §6/Entra ID ト ークンのクレーム JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-63C-4 §3.4.1.2(PPI)・§3.10 書籍 『デジタルアイデンティティのすべて』(考え方)4.2.4 節 pp.33–35 115
定義 発行 伝搬 検証 認可 運用 JWE と SD-JWT:暗号は最後の手段として使う まず載せない、次に派生値。それでも要るときに、暗号化か選択的開示を選ぶ 手段 できること 注意 使う場面 載せない(参照型・API) 漏れるものがない 問い合わせが増える まず検討する 派生値 判定だけを渡す 判定の責任は発行者 年齢や資格の確認 JWE(ネスト) 受け手以外から中身を隠す 外側と内側の両方を検証する 中継を通り、機微な値が要る SD-JWT(RFC 9901) 保持者が開示するクレームを選ぶ iss・aud・exp・cnf は選択開示にしない。鍵 束縛を使う 受け手ごとに開示の範囲が違う 載せない 派生値 仕様 RFC 8725 §2.3・§3.3/RFC 9901 §9.7・§9.9/ RFC 9068 §6 JWT クレーム設計ガイド|組織で共用する独自クレーム 暗号化・選択的開示 優先する順。暗号は最後の手段 指針 NIST SP 800-63C-4 §3.12.2(選択的開示)・§3.12.3 書籍 『セキュアAPI』7.2.2 節 pp.197–199 116
定義
発行
伝搬
検証
認可
運用
ログとトレース:トークン全文を残さない
ログに残すのは種別・発行者・宛先・scope・ハッシュ化した主体・イベントまで
残さない
Authorization: Bearer eyJhbGciOiJSUzI1NiIs…
// トークン全文がログ基盤に残り、再利用できる
IR 8587 表6 の要素
残し方
トークンの種別
typ(at+jwt など)
発行者
iss
scope
そのまま
クライアント・利用者
ハッシュなどで難読化
宛先
aud
イベント
発行・検証の失敗・失効
残す
{"event":"token.rejected",
"reason":"aud_mismatch",
"token_type":"at+jwt",
"iss":"https://idp.example.com",
"aud":"https://api.example.com",
"sub_hash":"sha256:3be0…","jti":"a91f…",
"scope":"invoice:read","txn":"6f0b…"}
『セキュアAPI』のログの例は Authorization を含む全ヘッダーを記録する。真似せず、記録するヘッダーを許可リストで決める
仕様 RFC 9700 §4.9.3/Txn-Token 草案 11 §15.2/
OpenTelemetry HTTP 規約
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 NIST IR 8587 §5.3.1.5・§5.3.1.7 表6/OWASP
Logging CS/ASVS 16.2.5
書籍 『セキュアAPI』11.4–11.6 節 pp.316–327/『デジタルアイ
デンティティのすべて』(考え方)11.6.7 節 pp.182–183
117
定義 発行 伝搬 検証 認可 運用 URL とブラウザ:トークンを履歴に残さない URL に載ったトークンは、履歴・アクセスログ・Referer・HAR ファイルから漏れる クエリパラメータ • AT を URI のクエリで渡さな い(MUST NOT) Referer • URL が別のサイトに送られる • 認可応答に注意(§4.2) • 履歴・アクセスログに残る 共有したファイル ブラウザの保存領域 • HAR ファイルにトークンが残 る • Browser-Based Apps は RFC 10017 • 障害調査の共有で漏れる • BFF で RT を置かない選択肢 GET /export?access_token=eyJhbGciOi… // 悪い例 GET /export Authorization: Bearer … // ヘッダーで送る 認可要求は PAR で、認可応答は form_post で URL から外す。AT は Authorization ヘッダーで送る 仕様 RFC 9700 §4.2・§4.3.1・§4.3.2/RFC 10017( BCP 212) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.3.1.5(トークンをログ・成果物に出さな い) 書籍 『セキュアAPI』4.4・7.4・10.4 節 pp.106, 202, 291– 292 118
定義 発行 伝搬 検証 認可 運用 チェックリスト:機微情報・最小化・ログ 新しいクレームを足すとき、トークンを流すとき、ログを設計するときに確かめる 段階 確かめること 根拠 定義 認証の秘密・平文の個人情報を載せていないか 63C-4 §2.3・§4.9 定義 値ではなく判定(派生値)で足りないか 63C-4 §3.12.2 定義 外部の受け手にペアワイズの sub を使うか OIDC Core §8 発行 受け手ごとに必要なクレームだけを出すか 63C-4 §3.10 発行 暗号化するなら、ネストの両方の層を検証するか RFC 8725 §3.3 伝搬 URL・クエリにトークンを載せていないか RFC 9700 §4.3.2 運用 ログ・トレースにトークン全文を出していないか IR 8587 §5.3.1.7 運用 記録するヘッダーを許可リストにしているか OpenTelemetry HTTP 規約 運用 監査ログ自体を機微な情報として守るか ASVS 16.4.2 仕様 RFC 7519 §12/RFC 8725 §3.3/RFC 9700 §4.3.2/OIDC Core §8 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST SP 800-63C-4 §3.10/IR 8587 §5.3.1.7/ ASVS 16.2.5・16.4.2 書籍 『デジタルアイデンティティのすべて』(考え方)11.6.7 節 pp.182–183 119
PART 10 AI エージェントのアクセス ポリシー このPartで答えられるようになる問い • エージェントの ID と、利用者の委任をどう分けるか • 誰が・どのエージェントが・何を承認し・どこに対して 、をどのクレームで表すか • MCP では、受け取ったトークンをどう扱うか • 委任の連鎖の深さを、誰が制限するか エージェントは独立した主体。利用者の委任と分けて表し、ツ ールごとに狭く、タスクごとに短く渡す 120
定義
発行
伝搬
検証
認可
運用
エージェントの ID:利用者のトークンを借りない
エージェントは独立した主体として登録する。代理で動くときは、利用者と別のクレームで表す
自律(エージェント自身の権限)
sub=エージェント。client credentials など
委任(利用者の代理)
sub=利用者、act・client_id=エージェント
// 委任:利用者 u-7f3a の代わりに経費アシスタントが動く
{
"iss": "https://idp.example.com",
"sub": "u-7f3a…",
"client_id": "agent-console",
"act": { "sub": "agent:expense-assistant" },
"aud": "https://mcp.example.com/expenses",
"scope": "expenses:read",
"https://claims.example.com/tenant": "t-042"
}
なりすまし(避ける)
利用者のトークンをそのまま使う。区別できない
リーダーの視点
エージェントを独立した ID として登録し、自身の権限と代理の権限を分ける。委任の連鎖は資格情報とログの両方で見せる(CoSAI は
MUST。業界の枠組みで標準ではない)
仕様 RFC 8693(なりすましと委任)§4.1(act)
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 CoSAI Agentic IAM v1.0 §1.2/OIDF「Agentic AI
のためのアイデンティティ管理」§3.2
書籍 『デジタルアイデンティティのすべて』(考え方)18.6.1 節
p.326
121
定義 発行 伝搬 検証 認可 運用 4 つの問いとクレーム:誰が・何が・何を・どこに 利用者・エージェント・承認の内容・宛先を、それぞれ既存のクレームで答える 問い 主なクレーム 注意 誰が利用者か iss+sub(Entra は tid+oid) sub は発行者と組で扱う どのエージェント・クライアントか client_id、azp、act.sub、req_wl 現在のアクターは最も外側の act 何が承認されたか scope、authorization_details、acr・amr・auth_time 承認内容は宛先ごとに絞って入れる どのリソース向けか aud(MCP は正規の URI)、resource aud は 1 つに絞る(本資料の推奨。63C-4 は FAL2 以上で必須) 誰が持つべきか cnf(DPoP・mTLS の鍵) 盗まれたトークンの再利用を防ぐ ネストした act は過去の経路の情報。アクセス制御の判断に使わない(RFC 8693 §4.1) 仕様 RFC 8693 §4.1・§4.4/RFC 9068 §2.2/RFC 9396/RFC 8707/ID-JAG 草案 06 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OIDF Agentic AI §2.11(主体と act を記録)/CoSAI §3.4 122
定義 発行 伝搬 検証 認可 運用 ツールごとのスコープ:狭く始め、タスクごとに短く 最小のスコープで始め、必要なときだけ引き上げる。トークンはタスク単位で作り直す 最小で始める 基本のツールだけのスコープ 不足を返す WWW-Authenticate で必要な scope を示す 段階的に引き上げ ホップごとに交換 昇格は相関 ID つきで記録 aud は 1 つ、分単位、RT なし 300 秒 分以下 RT なし ID-JAG 草案の例示。RT を返すべきでない Txn-Token の寿命。RT は返さない Cognito のトークン交換(2026-11) リーダーの視点 非人間の ID は狭いスコープの短命トークンを使う(IR 8587 §5.3.1.6、MUST)。ワイルドカードのスコープは禁止する エージェントにも IR 8587 を適用すべき(§1.1.1)。OWASP ASI03 はタスクごとの短命・狭いトークンを緩和策に挙げる 仕様 MCP Security Best Practices(スコープの最小化)/ID-JAG 草案 06 §4.3.4・§4.4.4 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §1.1.1・§5.3.1.6/OWASP Agentic Top 10 2026 ASI03 123
定義
発行
伝搬
検証
認可
運用
人の承認の証拠:エージェントに判断させない
承認したかどうかは、認可サーバーが本人に確かめる。承認の内容をトークンに載せて照合する
エージェントが要求
CIBA。内容を
authorization_details に
利用者が承認
別の端末で。AS が本人を確かめる
"authorization_details": [{
"type": "https://claims.example.com/payment",
"actions": ["initiate"],
"amount": { "currency": "JPY", "value": "120000" },
"creditor": "B-019"
}],
"https://claims.example.com/approval_id": "ap-311"
トークン発行
承認内容を宛先ごとに絞って載せ
る
受け手が照合
要求と承認の内容が一致するか
承認の扱いの規則
• 承認の有無をエージェントに任せない
• 承認内容は宛先ごとに絞る
• 受け手が要求と承認を照合する
• 承認 ID を監査ログと相関させる
承認は「エージェントが言った」ではなく「認可サーバーが本人に確かめた」ものだけを信じる
仕様 OpenID CIBA Core/RFC 9396 §9.1(宛先ごとに絞る)
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 OIDF Agentic AI §2.6(最小権限)/CoSAI §1.2
124
定義 発行 伝搬 検証 認可 運用 MCP の認可:受け取ったトークンを渡さない MCP サーバーは自分宛てのトークンだけを受け入れ、上流には別のトークンを使う 規則 内容 強さ 宛先を指定する 認可要求とトークン要求の両方に resource(MCP サーバーの正規 URI) MUST 宛先を検証する 自分宛てに発行されたトークンだけを受け入れる MUST パススルーの禁止 受け取ったトークンを上流 API に渡さない。上流には別のトークン MUST NOT 代理の混乱を防ぐ 固定のクライアント ID のプロキシは、クライアントごとに同意を取る MUST 発行者を確かめる 認可応答の iss を検証する(RFC 9207) MUST(あれば) PKCE S256 を使う MUST Enterprise-Managed Authorization 拡張(2026-06-18 Stable):IdP の ID-JAG を MCP サーバーの AS でトークンに交換し、利用 者ごとの同意画面なしに組織が許可を管理する 仕様 MCP Authorization 2026-07-28(Security Considerations)/RFC 8707/RFC 9207 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 OWASP Agentic Top 10 2026 ASI03(ID と権限の悪用) 125
定義
発行
伝搬
検証
認可
運用
委任の連鎖と深さ:上限は組織の規則で決める
act の入れ子は記録にすぎず、縮小も深さの上限も標準は保証しない
利用者
{
"sub": "u-7f3a…",
"act": {
"sub": "tool:invoice-mcp",
"act": { "sub": "agent:expense-assistant" }
}
}
// 外側の act(ツール)が現在のアクター
// 内側は記録用。判断に使わない
エージェント
ツール(MCP)
バックエンド
仕組み
深さの扱い
RFC 8693
上限なし。入れ子は情報のみ
Auth0 On-Behalf-Of
上限 4 を超えるとエラー(例)
Auth0 Agent as Principal(EA
)
最大 5 ホップ、入れ子 4 段
2026 年の縮小・深さの提案
個人草案のみ。標準ではない
CVE-2025-55241:署名のない内部の代理トークンが、テナント未検証・24 時間失効不能・ログなしだった。委任トークンはこの逆に作る
仕様 RFC 8693 §4.1(入れ子の act は情報のみ)/Auth0
On-Behalf-Of・Agent as Principal
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 CoSAI §3.4(深さ・TTL・宛先で制御)/OIDF Agentic
AI §3.2
書籍 『デジタルアイデンティティのすべて』(考え方)18.6.1 節
p.326
126
定義 発行 伝搬 検証 認可 運用 各社の機能:2026 年 11 月時点の姿 各社がエージェント用の ID と委任の仕組みを出している。名前と載るクレームは製品ごとに違う 製品 機能 トークンでの表れ Entra Agent ID blueprint とエージェント ID。OBO で利用者との束縛を検証 xms_act_fct・xms_sub_fct・xms_par_app_azp Auth0 On-Behalf-Of トークン交換、Agent as Principal(早期アクセス) act(外側が現在のアクター)、sub_profile Okta Cross App Access(ID-JAG)。MCP の EMA に最初に対応 ID-JAG から範囲を絞った AT Cognito トークン交換(2026-11-12)。RT なし、may_act は扱わない actor token があれば act Keycloak 26.8 で AI エージェント向けの委任(同意・監査) may_act と act(プレビュー機能) AgentCore Identity エージェントをワークロード ID として管理、Token Vault 受信時に client_id・scope・独自クレームを照合 製品の独自クレームを組織の契約にしない。入口で act・client_id など標準のクレームにそろえる(Part 11) 仕様 Entra Agent ID/Auth0 for AI Agents/Okta XAA/Cognito token exchange/Keycloak 26.8 JWT クレーム設計ガイド|組織で共用する独自クレーム 127
定義 発行 伝搬 検証 認可 運用 指針と標準化:公的な根拠として引けるものは少ない 根拠は IR 8587・MCP・RFC。白書や草案は設計の参考に留める 文書 状態 要点 IETF 草案 状態(2026-11-17) NIST IR 8587 Final(2026-09) エージェントにも適用(§1.1.1) ID-JAG 第 6 版、WG 文書 NIST NCCoE 概念文書 ドラフト 委任とログを検討。要求事項はま だない Transaction Tokens 第 11 版、WG の合意済み OWASP Agentic Top 10 2026 公開 ASI03 ID と権限の悪用 identity-chaining RFC Editor の処理待ち OWASP NHI Top 10 2025 インキュベーター NHI5 過剰な権限 AI エージェントの OBO 個人草案、期限切れ OIDF 白書(OIDF-J 訳) ホワイトペーパー sub と act の 2 つの ID 縮小・深さの提案 個人草案のみ CoSAI Agentic IAM v1.0 自身と代理の権限を分ける( MUST) 規則の根拠には IR 8587・MCP 仕様・RFC を使う。白書と草案は「方向性」として示し、必須とは書かない 仕様 IETF datatracker(2026-11-17 確認)/MCP Authorization 2026-07-28 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §1.1.1/NCCoE 概念文書/OWASP/OIDF・OIDF-J/CoSAI v1.0 128
定義 発行 伝搬 検証 認可 運用 設計チェックリスト:エージェントのアクセス エージェントを組織のサービスにつなぐ前に、9 つを確かめる 観点 確かめること 根拠 主体 エージェントを独立した ID として登録したか CoSAI §1.2 委任 sub=利用者、act・client_id=エージェントで分けたか RFC 8693 §4.1 宛先 resource で要求し、aud を 1 つに絞ったか RFC 8707、MCP 転送 受け取ったトークンを渡さず、ホップごとに交換するか MCP 仕様 範囲 ツールごとの最小スコープで、昇格を記録するか MCP ベストプラクティス 寿命 タスク単位の短命トークンで、RT を出さないか IR 8587 §5.3.1.6/ID-JAG §4.4.4 承認 機微な操作は CIBA・RAR の承認を照合するか RFC 9396 連鎖 深さの上限と、根元からの一括失効を決めたか 組織の規則 監査 sub・全アクター・txn・承認 ID を相関できるか CoSAI §4.4 仕様 RFC 8693/8707/9396/MCP 認可/ID-JAG 06 §4.4.4/Txn-Token 11 §11.4 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 CoSAI §1.2・§4.4/NIST IR 8587 §5.3.1.6(短命・ 狭い範囲) 書籍 『デジタルアイデンティティのすべて』(考え方)18.6.1 節 p.326 129
PART 11 ガバナンス:クレームは API の契約 このPartで答えられるようになる問い • なぜクレームを API の契約として治めるのか • 台帳には何を書き、誰が持ち、誰が承認するのか • 形式を変えるとき、どの順で進めるか • 新しい共有クレームを足す前に、何を問うか 発行者は 1 つ、受け手は多数。名前・型・意味・持ち主を台帳 で決め、変更は受け手から先に進める 130
定義 発行 伝搬 検証 認可 運用 なぜ治めるか:発行者は 1 つ、受け手は多数 発行者の小さな変更が、多くの受け手で黙って壊れる。トークンの中身の変更は破壊的変更 ゲートウェイ 文書化された例 黙って起きること Auth0:予約名と衝突するクレーム エラーにならず、トークンから外れる Entra ID:groups が 200 件超 groups が消え、別の参照先に置き換わる GitLab:groups_direct が 200 件超 省かれ、所属 0 件と区別できない GitHub:sub テンプレートを先に変更 クラウド側がトークンを受理しない 注文サービス 発行者 夜間バッチ IdP・入口の交換 DB の行単位の制御 リーダーの視点 外部の SaaS 仕様 Auth0 Custom Claims/Entra AT claims(groups 超 過)/GitHub OIDC reference JWT クレーム設計ガイド|組織で共用する独自クレーム Curity:トークンの中身の変更は、破壊的変更として扱う。クレームの集合 は、API の応答と同じ「契約」 指針 NIST SP 800-162 §3.2.3.2(事前に合意した属性を使う ) 書籍 『デジタルアイデンティティのすべて』(考え方)15.2 節 p.262 131
定義 発行 伝搬 検証 認可 運用 台帳:クレームごとに決める 12 の項目 名前と型だけでは足りない。意味しないこと、書ける者、受け手、持ち主、状態まで決める 項目 決めること 項目 決めること 名前 名前空間つきの完全な名前(Part 4) 上限 最大の長さ・件数。超えたときの挙動 型 JSON の型を 1 つ。形式・許容値 個人情報の区分 ログ・転送してよいか(Part 9) 意味 何を表すか。何を意味しないか 持ち主 意味と値に責任を持つ部門 発行者 どの発行者だけが付与するか 鮮度 値の出どころと、反映までの遅れ 書ける者 管理者か、本人か、呼び出し側か 状態 提案・有効・廃止予定・廃止 許可された受け手 どのサービスが読んでよいか 変更履歴 いつ、誰が、何を変えたか(来歴) SP 800-162 §2.4.2:属性の名前・定義・許容値・スキーマは、中央の権限主体が管理する。DS-212 §3.2.3:名前・型・値を事前に標準化 する 指針 SP 800-162 §2.4.2・3.1.3.2・3.2.1.3/IR 8112 §3.1・3.2.1/DS-212 §3.2.3 JWT クレーム設計ガイド|組織で共用する独自クレーム 書籍 『デジタルアイデンティティのすべて』(考え方)21.2 節 pp.380–381 132
定義
発行
伝搬
検証
認可
運用
台帳の例:テナントのクレーム 1 件
1 件を YAML で書き、リポジトリで管理する。レビューと変更履歴がそのまま残る
claim: https://claims.example.com/tenant
type: string
# 常に文字列。配列にしない
pattern: "^t-[0-9]{3,}$"
# 例: t-042
meaning: 主体が今回の操作で属するテナントの ID
not_meaning: 閲覧できるテナントの一覧ではない
issuer: https://idp.example.com
writers: [identity-platform] # 本人・各サービスは書けない
consumers: [gateway, orders-api, billing-batch]
max_length: 32
pii: none
owner: identity-platform
freshness: 発行時点の写し。変更は次の発行で反映
status: active # proposed / active / deprecated / removed
not_meaning
• 拡大解釈を先に封じる
writers・consumers
• 書ける者と読む者を限定
status
• 廃止までの段階を追う
仕様 RFC 7519 §4.2(衝突しない公開名)
JWT クレーム設計ガイド|組織で共用する独自クレーム
指針 SP 800-162 §3.2.1.3(定義と意味)・§3.2.2.10(来歴)
/IR 8112 §3.2.1.3
書籍 『デジタルアイデンティティのすべて』(考え方)21.4 節 p.382
133
筆者の推奨
定義
発行
伝搬
検証
認可
運用
スキーマと契約テスト:台帳を機械で確かめる
台帳から JSON Schema を作り、発行側は出す前に、受け手は CI で、同じ契約を確かめる
{
"$id": "https://claims.example.com/schema/at/v3",
"type": "object",
"required": ["iss", "sub", "aud", "exp",
"https://claims.example.com/tenant"],
"properties": { "https://claims.example.com/tenant":
{ "type": "string", "pattern": "^t-[0-9]{3,}$",
"maxLength": 32 } },
"additionalProperties": true
発行側:出す前に確かめる
• 台帳から Schema を生成
• 発行の設定変更を CI で検証
• 実トークンをプレビューで確認
}
受け手:契約テスト
• 読むクレームと型を宣言
additionalProperties は true。知らないクレームで受け手を壊さな
い(前方互換、Part 4)。必須クレームの欠落は拒否する
仕様 RFC 9396 §5(AS の厳格な検証)/RFC 7519 §4(知
らないクレームは無視)
JWT クレーム設計ガイド|組織で共用する独自クレーム
• 新しい Schema の版で CI を回す
• 廃止予定を読んだら警告
指針 SP 800-162 §3.1.3.2(スキーマと許容値を公開)
書籍 『セキュアAPI』2.4–2.6 節 pp.58–63(軽量な標準と自動化
)
134
定義 発行 伝搬 検証 認可 運用 変更の手順:受け手が先、発行者が後 新旧を両方受け入れる受け手をそろえてから、選択制 → 期日で既定 → 旧形式の廃止へ進む 1. 受け手が先 2. 選択制 3. 期日で既定 4. 旧形式を廃止 新旧の両方を受け入れる 希望する受け手から新形式 日付を事前に告知 台帳の状態を removed に 実例:GitHub Actions の OIDC 発行者が用意するもの • クラウド側の条件を先、テンプレートは後 • 全受け手への事前通知 • 不変の sub:既存リポジトリは選択制 • 新形式のプレビュー手段 • 2026-07-15 以降の作成・改名・移譲は既定 • 互換期間の並行発行 • プレビューで新形式を事前に確認 • 受け手の移行状況の一覧(台帳) 互換期間は短く見積もらない。Netflix は新旧両対応への改修を「遅く、痛みを伴った」と振り返っている 仕様 GitHub OIDC reference(sub の変更順)/GitHub changelog 2026-04-23(不変の sub) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 SP 800-162 §3.3.3(変更は全依拠当事者に事前通知) 書籍 『デジタルアイデンティティのすべて』(考え方)21.4–21.5 節 pp.382–384 135
定義 発行 伝搬 検証 認可 運用 予約名と名前空間:持ち主を決め、発行時に弾く プラットフォームは予約名を明文化して強制する。組織の名前空間も持ち主と割り当て規則を決める プラットフォーム 予約・禁止されている名前 破るとどうなるか Kubernetes extra の k8s.io・kubernetes.io。system: で始まる利用者名・グループ 検証規則で拒否する(公式の設定例) Auth0 auth0.com・webtask.io・urn:auth0 などの名前空間。素の roles・ groups 黙ってトークンから外れる Firebase iss・sub などの登録名。firebase・user_id 使えない(予約名) Cognito(AVP 連携) cognito・dev・custom という名前のクレーム 追加しない(予約接頭辞) 名前空間の持ち主 claims.example.com は ID 基盤チーム 仕様 K8s Authentication(extra の予約・system: 接頭辞)/ Auth0 Create Custom Claims JWT クレーム設計ガイド|組織で共用する独自クレーム 下位の名前の割り当て 台帳への登録で決まる 指針 SP 800-162 §2.4.2(名前と値を正規化し中央で管理) 発行時の検査(推奨) 予約名・未登録の名前を拒否 書籍 『実践 Keycloak』5.5.3 節 pp.81–82(スコープ名に接頭辞 ) 136
定義 発行 伝搬 検証 認可 運用 変換層:IdP の差は入口と共通部品で吸収する 利用者キー・ロールの位置・宛先は IdP ごとに違う。受け手に IdP ごとの読み方をさせない Entra ID Keycloak Auth0・Okta Cognito 利用者のキー oid+tid(sub はアプリごと) sub Auth0:sub/Okta の AT:uid sub(username は不可) ロール・グループ roles・groups realm_access・ resource_access Auth0:permissions/Okta: groups cognito:groups AT の aud API のアプリ マッパーで付与 audience の指定が必要 resource 指定時のみ 入口での交換 共通の検証・公式パーサ 宣言的な写像 • 外部のトークンを内部トークンに • 各サービスに生で解析させない • GCP の属性マッピング • Netflix Passport(Part 6) • Passport Introspector・CSRB 勧告 6 • K8s claimMappings・Hasura claims_map 仕様 Entra・Keycloak・Okta・Cognito のトークン文書(Part 3 ) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 SP 800-228 §2.7(資格情報の正規化)/CSRB 勧告 6( 共通の認証ライブラリ) 書籍 『デジタルアイデンティティのすべて』(考え方)13.4.2 節 p.208 137
定義 発行 伝搬 検証 認可 運用 体制:台帳の持ち主・承認・ADR 台帳は中央の 1 チームが持ち、追加・変更・廃止はレビューで決めて ADR に残す 役割 担うこと 根拠 ADR に残すこと 名前空間・台帳・Schema を持ち、登録を承 認 SP 800-162 §2.4.2 意味・値・鮮度に責任を持つ §3.2.2.6(権威ある情報源) 発行者の運用者 発行の設定を変える唯一の者 §3.1.3.3(権限ある機関だけが付 与) 受け手のチーム 読むクレームを登録し、契約テストを持つ §3.2.1.3(定義に沿って使う) レビューの場 追加・変更・廃止を決め、ADR に残す 書籍 21.4 節 p.382 監査 台帳と実際の発行を定期的に照合 §3.4.1(定期的な監査) 台帳の管理者 クレームの持ち主 • 決定・理由・却下した案 • ポリシーは「何を」 • ADR は「どのように」 • 名前・識別子の形式は後戻りしにくい リーダーの視点 名前をそろえるのは技術ではなく政治の問題(書籍 15.2 節 p.262)。関係者を先に特定し、決め方を決めておく 指針 SP 800-162 §2.4.2・3.1.3.3・3.4.1/DS-212 §3.2.2(関係者の特定と調整) JWT クレーム設計ガイド|組織で共用する独自クレーム 書籍 『デジタルアイデンティティのすべて』(考え方)21.4–21.7 節 pp.382–389 138
定義 発行 伝搬 検証 認可 運用 追加前の質問(1/2):目的・名前・型 共有クレームを足す前に 25 の質問に答える。前半は、必要性と、名前・型の決め方 A. 目的と必要性 • 1. 受け手はこれで何を決めるか • 2. 寿命中に値が変わっても困らないか • 3. 既存の標準クレームで表せないか B. 名前と構造 C. 型と値 • 4. 自組織の名前空間か。予約名と衝突しな いか • 7. 型は 1 つか。区切り文字列を避けたか • 5. 「.」「/」入りの名前を全ツールで参照でき るか • 9. 無い・null・false・空配列の意味は • 6. トップレベルか、組織のオブジェクトの下 か • 8. ID・金額は文字列で運ぶか • 10. 大文字小文字・空白・比較方法は • 11. 誰が値を書けるか。自己申告と分けた か • 12. 名前と不変の ID を出し、ID で照合さ せるか 答えられない質問が残るなら、まだ共有クレームにしない。サービス内のローカルな属性にとどめる 仕様 RFC 7519 §4.2・4.3/RFC 9068 §2.2.3.1(groups ・roles・entitlements) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 SP 800-162 §2.4.2/DS-212 §3.2.3(名前・型・値を 事前に標準化) 書籍 『実践 Keycloak』5.5.3 節 pp.81–82 139
定義 発行 伝搬 検証 認可 運用 追加前の質問(2/2):境界・監査・変更 後半は、サイズと発行の境界、ログと委任、台帳と変更の手順 D. サイズ・発行・境界 E. 監査・プライバシー・変更 • 13. 上限は。超えたら失敗か、欠落か • 20. ログに残すか。値かハッシュか。個人情報か • 14. 全リクエストに載せる価値があるか • 21. 委任なら act・承認 ID との関係は • 15. 付与するのは単一の発行者だけか • 22. 台帳に登録し、受け手を把握したか • 16. 検証を共通ライブラリで提供するか • 23. 形式を変えるときの移行計画はあるか • 17. ヘッダーに移すとき偽装を除去するか • 24. 改名・廃止の互換期間と並行発行は • 18. 未検証の値を流すモードは無いか • 25. 発行前の確認手段と、受け手の条件のテストは • 19. 知らない受け手が無視しても安全か 25 問は、クレーム追加の申請テンプレートにそのまま使える。回答は ADR と台帳の 1 件に残す 仕様 RFC 8693 §4.1(act)/Okta OIDC reference( groups 100 件) JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 IR 8587 §5.3.1.7(トークンと PII をログに残さない)/ CSRB 勧告 6 書籍 『デジタルアイデンティティのすべて』(考え方)21.8–21.10 節 pp.389–391 140
筆者の提案 定義 発行 伝搬 検証 認可 運用 監査と指標:台帳と実際の発行のずれを測る 台帳は書いた時点から古くなる。実際のトークンと受け手の利用を、定期的に照合する 指標(提案) 何がわかるか 測り方 台帳に無いクレームの発行数 登録されていない追加 発行ログのクレーム名と台帳を照合 廃止予定のクレームを読む受け手 旧形式を廃止できる時期 契約テストの宣言を集計 共通の検証ライブラリの採用率・版 既定値の差が残る範囲 依存関係の一覧を走査 上限に近いサイズのトークンの割合 黙った欠落の予兆 発行時にサイズを記録 ログに出た個人情報の区分のクレーム 漏えいの経路 ログの定期的な走査 aud・型の検証失敗の件数 契約の破れ 受け手の拒否ログを集約 リーダーの視点 IR 8587 §5.3.1.4:トークンの使用パターンを監視する(MUST)。指標は台帳の持ち主が、決まった周期で確認する 指針 IR 8587 §5.3.1.4(使用の監視)・§5.3.1.7(ログ)/SP 800-162 §3.4.1(定期的な監査 ) JWT クレーム設計ガイド|組織で共用する独自クレーム 書籍 『デジタルアイデンティティのすべて』(考え方)21.8–21.10 節 pp.389–391/『セキュアAPI』 2.4–2.6 節 141
PART 12 テックリーダーの実践 このPartで答えられるようになる問い • 避けるべきアンチパターンは何か • レビューで何を確かめればよいか • 何に重点を置き、何を見送るかをどう決めるか • この資料の主張は、何に基づくか アンチパターンを避け、審査の観点を揃え、何に重点を置き何 を見送るかを、根拠つきで決める 142
定義 発行 伝搬 検証 認可 運用 アンチパターン(1/2):検証と識別子 多くは暗号ではなく、確かめなかったこと・決めなかったことから起きる アンチパターン 結果 対策 事例 トークンの alg に従って検証する none・HS256 の混同で偽造 許可リスト、鍵ごとに 1 つ CVE-2015-9235 署名を確かめずに中身で認可する 誰でもクレームを書ける 必ず検証してから読む — aud を確かめない 別サービス宛てのトークンの流用 aud を必須にし、自分を確認 CVE-2020-26160 マルチテナントで iss・tid を見ない 別テナントのトークンを受理 発行者とテナントの許可リスト CVE-2025-55241 署名が通れば発行者も正しいと仮定 別系統の鍵の署名を受理 鍵と発行者の対応を確かめる Storm-0558 email・upn を利用者のキーにする アカウントの乗っ取り iss+sub(Entra は tid+oid) nOAuth(2023) 本人が書ける属性から権限を作る 権限の昇格 権限は管理側だけが書く Cognito の custom 属 性 exp を必須にしない・ずれを大きく許す 期限のないトークン exp 必須、ずれは数分まで golang-jwt v5 の既定 仕様 RFC 8725 §3.1・3.9・3.10/OIDC Core §5.7 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 CSRB 報告書(2024-03)/NIST IR 8587 §5.2.1.2 書籍 『実践 Keycloak』14.5.2 節 p.295 143
定義 発行 伝搬 検証 認可 運用 アンチパターン(2/2):設計・流れ・運用 独自クレームの事故は、詰め込み・型の揺れ・ヘッダーへの転記・転送から起きる アンチパターン 結果 対策 グループ・ロールを全部トークンに詰める ヘッダーの上限、黙った欠落 粗いロールだけ。細かい権限は PDP(Part 5) 変わりやすい権限をトークンに焼き込む 取り消しが期限まで届かない 短命化、都度判定、失効の伝播(Part 8) 型を決めない・配列を区切り文字列にする 受け手ごとに解釈が分かれる 台帳で型を 1 つに固定(Part 4・11) 名前空間なしの独自クレーム 予約名と衝突し、黙って消える 組織の URI の名前空間(Part 4) クレームをヘッダーに移し、同名ヘッダーを消さない なりすまし 入口で除去してから書き込む(Part 6) 受け取ったトークンを上流へそのまま渡す 代理の混乱、監査の崩壊 宛先ごとに交換(Part 6・10) エージェントが利用者のトークンを借りる 誰が実行したか分からない act で委任を表す(Part 10) トークン全文をログに出す ログ経由の窃取・個人情報の流出 種別・発行者・ハッシュだけ(Part 9) 仕様 MCP Authorization 2026-07-28/RFC 8693 §4.1/Transaction Tokens 草案 11 JWT クレーム設計ガイド|組織で共用する独自クレーム 指針 NIST IR 8587 §5.3.1.5・5.3.1.7/OWASP Authorization CS 書籍 『セキュアAPI』7.7 節 pp.220–221 144
定義 発行 伝搬 検証 認可 運用 レビューの観点:クレームの一生に沿って 6 つ 定義・発行・伝搬・検証・認可・運用の各段で、誰が何を確かめるかを決める 定義 発行 伝搬 • 既存クレームで表せないか • 書けるのは 1 つの発行者だけか • 下流ほど aud・scope・寿命を絞るか • 名前空間・型・無いときの意味 • フックの失敗で欠けたら拒否できるか • 受け取ったトークンを渡していないか • 台帳に登録したか • サイズの上限 • ヘッダーの除去 検証 認可 運用 • 共通の検証部品を使うか • オブジェクト単位は DB で確認 • 変更の手順と互換期間 • alg・iss・aud・exp・typ • テナントを保存データと照合 • トークン全文をログに残さない • 必須クレームの欠落は拒否 • 書き手で値を区別 • 失効の伝え方 指針 NIST IR 8587 §5.2.1.1・5.3.1.3・5.3.1.7/SP 800-162 §2.4.2/OWASP ASVS 9 書籍 『デジタルアイデンティティのすべて』21 章 pp.379–392(考え方) ・10 JWT クレーム設計ガイド|組織で共用する独自クレーム 145
定義 発行 伝搬 検証 認可 運用 重点と見送り:共通の基準の上に、組織ごとの判断を置く 銀の弾丸はない。外せない共通の基準を決め、その上で何に重点を置き、何を見送るかを選ぶ マルチテナント SaaS 社内業務システム AI エージェントの委任 • 重点:テナント分離(tid の照合・テナント単位 の鍵・行単位の制御) • 重点:aud の絞り込み、ID トークンの流用防 止、属性の鮮度 • 重点:act の連鎖、タスク単位の短命トークン 、承認の証拠、転送の禁止 • 見送り候補:細かい権限のトークン化(都度判 定へ) • 見送り候補:暗号化(JWE)・送信者制約 • 見送り候補:標準による深さの強制(標準が ない。当面は組織の規則と入口の検査で上限 を設ける) 共通の基準(どの組織でも必須) 受け入れの検証(alg・iss・aud・exp・typ)/組織の名前空間/型の固定/不変の ID/必須の欠落は拒否/トークン全文と個人情報のクレームをログに残さ ない 見送るときは「何が起きたら見直すか」を書く。重点と見送りの効果と費用は、ケーススタディで測る 指針 NIST IR 8587 §5.2.1.1・5.3.1.1・5.3.1.3・5.3.1.7/OWASP ASVS 5.0 JWT クレーム設計ガイド|組織で共用する独自クレーム 146
定義 発行 伝搬 検証 認可 運用 主張と根拠:この資料は何に基づくか 主な主張ごとに、仕様・公的な指針・日本語の書籍の対応を示す 主張 仕様 公的な指針 書籍 受け入れの確認を全部通してから、クレームを読む RFC 9068 §4/RFC 8725 §3 IR 8587 §5.2.1.2/63C-4 §4.9 OIDC入門 13.8.1・13.9.6/ Keycloak 5.6 利用者のキーは iss+sub。名前を条件にしない OIDC Core §5.7 63C-4 §3.4/ASVS 10.5.2 Keycloak 2.4 p.24/DI 10.2 宛先を必ず入れ、受け手は自分宛てか確かめる RFC 7519 §4.1.3/RFC 8725 §3.9 IR 8587 §5.3.1.3(MUST) OIDC入門 13.9.6/Keycloak 5.5 トークンは写し。変わりやすい権限は都度判定 RFC 7662 SP 800-162 §3.3.1/IR 8587 §4.1.4 DI 12.6/Keycloak 8.5 名前・型・値を事前に標準化し、台帳で治める RFC 7519 §4.2 SP 800-162 §2.4.2/DS-212 §3.2.3 DI 15.2 p.262・21 章 最小化し、生の値でなく判定を渡す RFC 9068 §6 63C-4 §3.10・§3.12.2/DS-511 DI 4.2.2/Keycloak 14.4 寿命は短く、失効を伝える RFC 9700 IR 8587 §5.3.1.1・§5.3.1.2 OIDC入門 13.9.7/Keycloak 12 章 トークンと個人情報をログに残さない Txn-Token 草案 §15 IR 8587 §5.3.1.7(MUST NOT) DI 11.6.7 エージェントは独立した主体。委任は act で表す RFC 8693 §4.1/MCP 認可仕様 IR 8587 §1.1.1/CoSAI DI 18.6.1(考え方) DI=『デジタルアイデンティティのすべて』、Keycloak=『実践 Keycloak』、OIDC入門=『OpenID Connect入門』 JWT クレーム設計ガイド|組織で共用する独自クレーム 147
定義 発行 伝搬 検証 認可 運用 参考文献:日本語の書籍と、主な公的文書 書籍は章・印刷ページで引用した。仕様の状態は 2026-11-17 時点 日本語の書籍 出版社・年 著者・監修 主に使った箇所 OpenID Connect入門 技術評論社 2026 土岐孝平 著/倉林雅 監修(OIDF-J 理事) トークンの形式、検証、脅威(13 章) デジタルアイデンティティのすべて オライリー・ジャパン 2024 P. J. Windley 著/富士榮尚寛 監訳(OIDF-J 代表理 事) クレームと信頼、アクセス制御、最小化、ガバ ナンス 実践 Keycloak オライリー・ジャパン 2022 S. Thorgersen ほか著/和田広之ほか訳 マッパー、aud の制限、認可戦略、寿命 セキュアAPI 翔泳社 2026 J. H. Peralta 著/元内柊也ほか訳 API の認可、ゲートウェイ、ログ 公的文書 発行 主に使った箇所 NIST IR 8587(トークンとアサーションの保護) NIST・CISA 2026-09 必須要素、寿命 1 時間以内、宛先、ログ、エージェント NIST SP 800-63C-4(フェデレーションとアサーション) NIST 2025-07 識別子、最小化、派生値、検証 NIST SP 800-162(属性ベースのアクセス制御) NIST 属性の命名・正規化・来歴・鮮度 OWASP ASVS 5.0/JWT Cheat Sheet OWASP 検証の要件、トークンの種類の取り違え デジタル庁 DS-212・DS-511 デジタル庁 属性の事前の標準化、必要以上の属性を取らない CSRB 報告書(Storm-0558) 米国 DHS 2024-03 鍵と発行者の対応、共通の認証ライブラリ JWT クレーム設計ガイド|組織で共用する独自クレーム 148
定義 発行 伝搬 検証 認可 運用 まとめ:クレームは契約。決めてから足し、確かめてから読む 新任のテックリーダーが、明日から組織の規則として決めること 作る前に探す 標準・IdP・組織の台帳で、既存のクレームで表せないか 契約として決める 名前空間・型・意味・書き手・寿命・持ち主を台帳に 確かめてから読む 署名・iss・aud・exp・typ を共通の検証部品で トークンは写し 変わりやすい権限・関係は載せず、都度判定する 下流ほど絞る aud・scope・寿命を絞り、そのまま渡さない。エージェントは act で 重点と見送りを選ぶ 共通の基準の上で、見直しの条件つきで選ぶ 指針 NIST IR 8587/SP 800-63C-4/SP 800-162/OWASP ASVS 5.0/デジタル庁 DS-212・DS-511 JWT クレーム設計ガイド|組織で共用する独自クレーム 書籍 4 冊(前のスライド) 149