Pythonで学ぶKeycloakハンズオン

Pythonで学ぶ Keycloak ハンズオン 20250524 Shingen.py @山梨県甲府市 会場: SHIRO-no-IRO・株式会社シグナイト様 Keycloak × FastAPI 体験するハンズオンワークショップ Hiroki Abe

開催地・Shingen.pyのご案内 本日のハンズオンは山梨県甲府市 のSHIRO-no-IRO（株式会社シグナイト様）で 開催しています。 1 Shingen.py とは 2 活動 山梨県を中心に活動する 不定期にハンズオン形式の Pythonプログラミングコミュニ ワークショップを開催していま ティです。初心者から経験者ま す。2023年から山梨県主催の で歓迎しています。 AIハッカソンのサポートも行っ ています。 3 会場について 「SHIRO-no-IRO」は甲府市内のコワーキングスペースで、株式会社シグ ナイト様が運営されています。

本日の目的とゴール 参加者同士の交流、知識の共有 実践コミュニティの形成を促進 FastAPI でセキュアなAPI を実装 エンドポイント実装スキルの習得 OIDC / Keycloak の概要を理解 認証・認可の基礎知識の獲得 本日は、認証・認可の基礎知識～実践的な実装まで段階的に学び、実際に動作するシステムを構築し、Keycloakを活用できるようになるこ とを目指します。また参加者同士の交流を通じて知見を共有し、継続的な学びのコミュニティ形成が作れたらうれしいです。

タイムライン & ハンズオン構成 今日の学習とハンズオンの流れ 概念整理 OIDC、JWTの基礎を学び、 Keycloakの概要を掴みます Hands-on① Keycloakの環境構築と基本設定を行います 休憩 質問タイムと個別サポート Hands-on② FastAPIとの連携基盤を構築します Hands-on③ RBACの実装とJWT検証を学びます 発展課題と発表 選択課題に取り組み、成果を共有します

会場スポンサー様のご紹介 本日の会場 SHIRO-no-IROは、株式会社シグナイト様 が運営する創造的な ワークスペースです。 「集う・出会う・創造する」 何かが始まるサードプレイス

発表者について あべ ひろき 山形県出身、山梨県在住。現在はCソフトウェアエンジニアです。現在は東京の会社に勤務しています。 Python使用経験：画像処理、Webアプリ開発、製造データ分析 Ex. OpenCV, FastAPI, Pandas/Numpy …) 本日はKeycloakとPythonの連携についてご紹介します。皆さんもぜひ簡単に自己紹介をお願いします！ Shingen.pyはPython知識豊富なメンバーがおりますのでどんどん質問してください！

自己紹介 みなさんについて教えてください お名前、普段のお仕事や技術スタック、本日持ち帰りたい知識について簡潔 にご紹介をお願いします。（オンライン参加の方で発言が難しい場合は、 Discordへのメッセージでも構いません) Discordコミュニティへの参加 現地参加の方も、ぜひDiscordに一言メッセージをお寄せください。 Discordはハンズオン中の質問対応や情報共有に活用します。技術的な疑問点 やトラブルシューティング、発見した知見など、積極的に共有していただければと 思います。

Keycloakで実現できること 集中型認証・認可管理 ソーシャルログイン連携 複数アプリケーションの認証・認可を一元管理し、シングルサ Google、GitHub、Facebookなど様々なIDプロバイダとの インオン（SSO）を実現できます 連携が簡単に構築できます 多要素認証（MFA） APIとの連携 OTPやモバイル認証などの多要素認証を導入し、セキュリ REST APIを介して管理・運用が可能で、Pythonなどのプロ ティを強化できます グラミング言語から操作できます

認証と認可の違い Authentication（認証） Authorization（認可） ユーザーが「誰であるか」を確実に確認するプロセスです。 認証後に、そのユーザーが「何にアクセスできるか」「どのような操作が許可 確認方法: ID・パスワード、二要素認証（OTPなど）、生体認証（指紋・顔認 されるか」を定義するプロセスです。 証）、ソーシャルログイン（Google、Facebookなど） ロール（管理者/一般ユーザー）、属性（部署/役職）、スコープ/ポリシー（読 例: 会社の社員証や身分証明書を提示して、自分が本人であることを証明 取/編集権限）を用いて、適切なアクセス範囲を制御します。 する 例: 社内システムで、経理部は財務データへのアクセス権限を持つが、他 部署は閲覧できないという制御。 セキュリティシステムの設計時には、この2つの概念を明確に区別することが重要です。適切な認証で正確な本人確認を行い、認可では最小権限原則に従う ことでリスクを大幅に低減できます。仮に認証システムが突破されても、適切な認可制限により被害を最小化します。 Keycloakは両方の機能を提供し、柔軟な認証メカニズム（様々なログインフロー・MFA）と細かな認可制御（ロール、グループ、ポリシー）を簡単に実装できま す。今日のハンズオンでは、これら両方の実装方法を実践的に学び、システムへの適用方法を習得していきます。

OpenID Connect（OIDC）と IdP OAuth 2.0 拡張 ID Token セキュアな認証委譲 シングルサインオン OAuth 2.0の「認可フレーム JWT形式でユーザー情報(こ 各サービス（RP）は認証情報 標準化されたプロトコルにより ワーク」に「認証レイヤー」を追 の人はだれか?をセキュアに を保持せず、IdP（Keycloak） SSOを実現し、ユーザビリティ 加した標準プロトコル 伝達し、認証の証明として機 が安全に一元管理します が向上します 能します OAuth 2.0は「アプリケーションに代わってAPIを呼び出すためのアクセス権限委譲フレームワーク」= 「自分のパスワードを教えず、アプリ に “許可したこと ˮだけ代行してもらう」 です。OIDCはこれを拡張し、ユーザー認証の標準メカニズムを提供します。これにより各サービスは独 自の認証システムを実装する必要がなく、Identity Provider（Keycloak）のエンドポイントを利用するだけで堅牢な認証フローを実現できま す。

ミニマムなシステム構成例 OIDCを実装するのに 最小限必要なシステ ム構成を示していま す。

OIDCフロー (Authorization Code Flow) ブラウザ → IdP (Keycloak) へリダイレクト WebアプリWebサイト)がユーザーアクセスをKeycloakへリダイレクトします Webアプリは認証後に認可コード(Authorization Code)を受領 認可コードは有効期限が短く、1度しか使えないIDトークン・アクセストークンの「引換券」 Webアプリは認可コードとIDトークン・アクセストークンを交換する WebアプリはバックエンドでCodeをアクセストークンと交換します アクセストークンを用いて、API 呼び出す 取得したトークンを使用して保護されたリソースにアクセスするための APIを呼び出します 右のフローはブラウザがアクセストークンを保持しますが、アクセス・認証コード交換まではフロントエンドで行 い、トークンはブラウザに渡さずWeb アプリが保持するBFF Back-End for Front-End) パターンもありま す。セキュリティの観点からこちらがおすすめですが、今回はブラウザがアクセストークンを保持するパターンで 進めます。

認可コードのセキュリティ (PKCE) Code Verifier 生成 クライアントSPAが暗号学的に安全なランダム文字列を コード受領 生成し、そのハッシュ値をCode Challengeとして作成しま 認証成功後、IdPから認可コードを安全に受け取ります す 1 2 3 4 Challenge 送信 Verifier 提示 認可リクエスト時にCode Challengeとハッシュメソッドを トークン交換時に元のCode Verifierを提示し、IdPがハッ IdPに送信します シュ照合で本人性を検証します PKCE（Proof Key for Code Exchange、ピクシーと発音）は、パブリッククライアント（クライアントシークレットを安全に保管できないSPAやモバイルアプリ）のための 必須セキュリティ拡張機能です。認可コードの横取り攻撃（中間者攻撃）を防止し、正規クライアントのみがトークン交換できることを保証します。「PKCE は例外なく 常に有効化する」がセキュリティのベストプラクティスです。 Keycloakでは、パブリッククライアントに対してPKCEを必須設定にすることができ、今日のハンズオンではこの重要なセキュリティ設定を実装していきます。

アクセストークン・IDトークン 種別 目的 アクセストークン リソースアクセスの権限を表す (認可) IDトークン ユーザー認証の証明として機能(認証) JWT（JSON Web Token）の構造 JWTは3つの部分から構成されています： ヘッダー Header：トークンタイプと署名アルゴリズム（RS256など）を指 定 用途 APIリクエスト時に使用 ユーザー識別に使用 ペイロード Payload)：クレーム（ユーザーID、権限、発行者、有効期限な 送信 AuthorizationヘッダーにBearer形式で - (クライアントアプリケーションへ送付される) ど）を含む 方法 付与 内容 スコープに基づく権限情報 ユーザー情報（クレーム） 有効 短期間（数分～数時間） 通常アクセストークンと同等 Opaque文字列 もしくは JWT IdPによ JWT 署名 Signature)：ヘッダーとペイロードの整合性を保証 これらはBase64URLエンコードされ、ピリオドで区切られます： ヘッダー.ペイロード.署名 期限 形式 る) 仕様 OAuth 2.0 OpenID Connect JWT形式のトークンは署名され改ざんから保護されており、検証可能な形式で発行されます。 Idpの公開鍵で検証可能です。公開鍵はOAuth 2.0/OIDCで規定されるエンドポイントから取得でき ます。

トークンの例
アクセストークンと IDトークンの JWT形式のペイロード例：

アクセストークン（ペイロード部分）
{
"iss": "https://auth.example.com",
"sub": "1234567890",
"aud": ["https://api.example.com"],
"exp": 1673427600, // 無効になる時間
"iat": 1673424000, // 発行時間
"azp": "client_123",
"scope": "openid profile read:data write:data",
"roles": ["user", "admin"],

// 割り当てられたロール

"jti": "abcd1234-5678-efgh-9012"
}

IDトークン（ペイロード部分）
{
"iss": "https://auth.example.com",
"sub": "1234567890",
"aud": "client_123",
"exp": 1673427600,
"iat": 1673424000,
"auth_time": 1673423950,
"nonce": "n-0S6_WzA2M",
"name": "山田 太郎",
"preferred_username": "taro.yamada",
"email": "[email protected]",
"email_verified": true,
"picture": "https://example.com/photos/taro.jpg"
}

// 許可された操作範囲

Keycloak 構成モデル全体像 Keycloakは階層的な構成要素を持つフレームワークです。 Realm (テナント) Clients (アプリ) Users、(Group) 認証ドメインの最上位の論理単位 Keycloakと連携する個別アプリケーショ 認証される主体。Group や Roles に • 外部IdP連携可能 ン、サービス よって権限を割り当て （Google/GitHub/SAML/LDAP） • • アプリケーション種別 Realm Rolesによるクロスアプリケー • SPA、モバイル ションの権限管理 • サーバーサイドアプリ • API Only Client Rolesによるアプリケーション固 有権限管理 属性やRoleを持ち、Groupに所属さ せることができる • Groupsにより組織やプロジェクト階 層を再現し、ロールや属性をまとめ て継承できる

クライアント種別比較 クライアント種 使用例 認証方法 特徴 SPAアプリ、モバイル PKCE 秘密なし、クライアント側 別 Public アプリ Confidential サーバーサイドアプ で認証フロー client_secret リ、BFF Bearer-only APIサーバー 安全な環境でシークレット を保管可能 トークン検証の ログインフロー非対応、 み トークン検証のみ Service マシン間（M2M）連 client_credenti ユーザー不在でのアクセ Account 携 als ス、バッチ処理など アプリケーションの性質に応じて適切なクライアントタイプを選択することが重要です。今日のハンズ オンではFastAPIとの連携に「Public」クライアントを使用し、 PKCE拡張によりセキュリティを確保しま す。 実際の業務システムでは、フロントエンドとバックエンドの分離度合いやセキュリティ要件に応じて、 最適なクライアントタイプを選択してください。

実践に向けて① トークン管理 短命アクセストークン 必要最小限の リフレッシュトークンの リフレッシュトークン ローテーション 5分程度の短い有効期限を設定し、侵害時の影 アクセストークンの再取得に使用します。UXを リフレッシュトークンを一度使用すると無効化 響を最小化します。有効期限が切れると再認証 損なわない程度で必要最小限の30分〜数日の し、新しいリフレッシュトークンを発行する仕組み が必要になります。 有効期限を設定します。また、HttpOnlyクッ です。連続使用攻撃を防止します。 キーに保持します。

実践に向けて② 脅威 と 対策 XSS（クロスサイトスクリプティング） CSRF（クロスサイトリクエストフォー 過大な権限 ジェリ） 最小権限の原則を守り、必要な権限だけを CSPとTrusted Typesで悪意あるスクリプト SameSite=Laxの設定で他サイトからのリク 与えるようにします。 を防ぎます。トークンはHTTPOnlyクッキー エストを制限します。または、Double で保護し、JavaScriptからの読み取りを防 Submit Tokenで正しい送信元を確認しま 止します。 す。 XSSやCSRFに対しては、サーバーサイドにトークンをもつBFF方式が考えられます。認証・認可以外にも、画面とサーバー両方で安全対策を行いましょう！実際の 運用ではさらに広範な対策が必要です。

Docker Compose で Keycloakを起動しましょう! コマンド実行 docker compose up アクセス http://localhost:8080 に接続 ログイン admin / admin で管理コンソールにログイン 今回使用するソースコードです https://github.com/shingen-py/doc_20250524 Docker Composeを使用することで、Keycloakとその依存関係を簡単に起動できます。ハンズオンでは、事前に設定済みの docker-compose.ymlファイルを使用します。起動後は管理コンソールにログインして、Keycloakを体験してみてください。 ※Docker Composeは v2を想定しています。

• https://github.com/shingen-py/doc_20250524

管理コンソール ホーム画面 ユーザー管理 クライアント登録 左側のサイドバーから各種設定にアクセスで ユーザーの作成、編集、検索が行える画面で アプリケーションの登録と設定を行う画面で きます。Manage relamsからRealm切り替 す。ロールの割り当てやグループへの参加な す。リダイレクトURI、アクセスタイプ、スコー えができ、管理者がマルチテナント環境を効 ども管理できます。 プなど、クライアントの詳細設定が可能です。 率的に管理できます。 ハンズオンではここでFastAPIアプリを登録し ます。 http://localhost:8080/realms/master/.well-known/openid-configurationを確認してください。このエンドポイントはOIDC関連の重要な URLを提供しており、クライアントアプリケーションの設定に必要な情報が含まれています。このURLは後ほどFastAPIとの連携で使用します。

• http://localhost/keycloak/realms/master/.well-known/openid-configuration

Hands-on ① 1 2 Realmの作成 Clientの設定 独立したテナント環境を構築 FastAPIアプリ用のOIDCクライアント登録 3 4 Roleの定義 エンドポイントの確認 権限作成とユーザーへの割り当て OIDC連携に必要な URLを確認 このハンズオンパートでは、 Keycloakの管理コンソールを使って、認証・認可システムの基本構成を 設定します。これらの設定は、あらゆるアプリケーションと Keycloakを連携させる際の基礎となるも の です。GUI操作に慣れることで、後ほど CLIやAPIを使った自動化も理解しやすくなります。 設定完了後は、 issuer、token_endpoint、jwks_uriなどの重要なエンドポイント URLを確認します。 これらは次のステップで FastAPIとKeycloakを連携させる際に必要になります。

Step: Realm 作成 Realmセクションへ移動 左側メニューからManage realms]をクリック Create Realmを選択 新規Realm作成画面に移行 Realm名を入力 名前を「demo-realm」と設定 作成したRealmを選択 Realm一覧から「demo-realm」を選択 Realmは、Keycloakのマルチテナント機能を実現する基本単位です。異なるアプリケーション群やプロジェクト ご とに分離されたRealmを作成することで、独立した認証・認可環境を実現できます。デフォルトの masterレルム はKeycloak自体の管理用であり、アプリケーション用のRealmは別途作成するのがベストプラクティスです。 実際のプロジェクトでは、企業ロゴやブランドカラーに合わせたカスタムテーマを作成することが可能です。

Step: Realm 設定変更 Realm settingsへアクセス 左側メニューから「Realm settings」を選択します。 Loginタブを開く 上部タブから「Login」を選択し、認証関連の設定画面に移動します。 Email as usernameを有効化 「Email as username」オプションを「ON」に切り替えます。 設定を保存 画面下部の「Save」ボタンをクリックして変更を適用します。 機能確認 これにより、ユーザーはユーザー名の代わりにメールアドレスでログイン可能になります。

Step: Client 作成 & PKCE クライアント登録画面に移動 左側メニューからClientsを選択し、Create clientボタンをクリックします 基本情報の設定 Client Type: Open ID Connect, Client ID: fastapi, Client authorization: on, Authorization: off, Authentication flow: Standard, Service accounts rolesとします。 リダイレクトURLの設定 Valid redirect URIs: http://localhost:8000/api/auth/callbackを入力し、認証後のリダイレクト先を指定しま す Credentialsの確認とコピー Client Secretをソースのbackend/.envのKEYCLOAK_CLIENT_SECRETにコピーしておきます Service accounts roles の追加 userの操作を行えるように、Assing roles ボタンをおしてmanage-users を追加します クライアント設定はアプリケーションとKeycloakの連携方法を定義します。今回はPythonとFastAPIで実装するWebアプリ ケーション用に「Confidential Client authentication = On)」タイプのクライアントを作成します。 python-keycloakは、Admin Client API のラッパーライブラリの仕様が Keycloakの標準と異 なりConfidential クライアントでも Service Account を有効化しないとユーザーの取得や追加 が動かないため、これらを On/有効化しています。

Step: Role & User 作成 ロールとユーザーの作成は、認可システムの中核となる部分です。「Roles」タグを選択し、「Create role」ボタンをクリックします。 fastapi_userとfastapi_adminという2つの基本ロールを作成しましょう。これらのロールは、後ほどFastAPIアプリケーションでの権限制御に 使用します。 次に「Users」メニューから「Add User」を選択し、テストユーザーを作成します。ユーザー名には「[email protected]」を使用し、 「Credentials」タブでパスワードを設定します。 その後、「Role Mapping」タブで先ほど作成したfastapi_userロールをこのユーザーに割り当てます。アプリケーションに対して、ユーザーの 権限に応じて適切なロールを割り当てることで、きめ細かいアクセス制御が可能になります。

OIDC エンドポイント確認 設定画面へのアクセス 左側メニューからRealm Settingsを選択します エンドポイントの表示 Endpointsまでスクロールし、「OpenID Endpoint Configuration」リンクをクリックします ※最初に紹介したwell-knownエンドポイントと同じページです 必要な情報の確認 表示されたJSON内から、issuer、authorization_endpoint、token_endpoint、jwks_uriの値を確認 します OIDCエンドポイントの確認は、クライアントアプリケーションとKeycloakを接続するた めに必要なステップです。これらのエンドポイントURIは、認証フローの各ステージで使 用されます。 これらのエンドポイントはOpenID Connectの仕様に基づいており、認証リクエスト、 トークン交換、ユーザー情報取得など、様々な目的で使用されます。

休憩 + 個別 Q&A お疲れ様でした！ここで休憩に入ります。ここまでのセッションで不明点があれ ば、この時間を利用して質問してください。 また、Discord チャンネルでも質問を受け付けています。お気軽にご質問くださ い。次のセクションでは、FastAPIとKeycloakを連携させる実装に入ります。 Python環境の基本的な知識を前提としていますが、必要に応じて補足説明も行 います。

Hands-on② 概要 FastAPIプロジェクト構成 • 効率的なディレクトリ構造と最適なモジュール分割 • 再利用可能なKeycloak連携用ヘルパー関数 /login エンドポイント実装 • 安全なOIDC認可リクエストの動的生成 /callback エンドポイント処理 • 認可コード検証とトークン交換プロセスの実装 /user CRUD操作設計 • JWT検証によるユーザー情報の安全な取得 • RBAC原則に基づく管理操作のアクセス制御 このハンズオンでは、 FastAPIフレームワークを活用して Keycloakと連携する実用的な Webアプリ ケーションを構築します。 python-keycloakライブラリを用いて完全な OIDC認証フローを実装し、安 全なトークン取得・検証・管理の仕組みを実際のコードで学びます。実装を通じて認証・認可の理論 が実務でどう活かされるかを体験しましょう。

python-keycloak によるKeycloakの操作 Pythonから簡単にKeycloakを操作するためのライブラリを活用します KeycloakOpenIDのインスタンス化 from keycloak import KeycloakOpenID サーバーURL、レルム名、クライアント IDを指定してKeycloak連携クライア ントを初期化します。これが Keycloak APIとの通信の起点となります。 # Keycloakクライアントの初期化 keycloak_openid = KeycloakOpenID( server_url="http://localhost:8080/", client_id="fastapi", 認証エンドポイントの取得と認可処理 realm_name="demo-realm" 認証URLを生成して、認可コードフローを開始します。取得した認可コード を使用してIDトークンとアクセストークンを交換します。 ) # Keycloakの認証エンドポイントの取得 トークンレスポンス解析 redirect_url = keycloak_openid.auth_url( 返却されるJSONには、access_token、refresh_token、expires_inなど redirect_uri=os.getenv("REDIRECT_URL"), の情報が含まれます。これらを適切に管理する必要があります。 scope="openid email profile", state=state, nonce=nonce )

シーケンス: /login → /callback ユーザーがログイン要求 Keycloakで認証 バックエンドでトークン交換 ユーザーがアプリケーションの/loginエ ユーザーがKeycloakの認証画面で FastAPIバックエンドが認可コードを ンドポイントにアクセスして認証プロセス ユーザー名とパスワードを入力し、身元 使ってKeycloakからアクセストークンと を開始します 確認を完了します IDトークンを取得します 認証サーバーへリダイレクト アプリケーションへ戻る セッション確立 state、nonceなどの必要なパラメータ 認証成功後、認可コードを含むパラメー 取得したトークンをHTTP Onlyクッキー を含むKeycloak認証URLを生成し、ブ タとともにアプリケーションの/callback に安全に保存し、認証済みユーザーと ラウザをリダイレクトします エンドポイントへリダイレクトされます してSPAアプリケーションにリダイレクト します これはAuthorization Code Flowの実装であり、ブラウザベースアプリにおける安全な認証方法です。PKCEメカニズムを使用することで、パブリッククライアントでも 中間者攻撃からの保護と安全なトークン取得が可能になります。(前述の通りpython-keycloakがPKCE対応していないため今回はPKCEはスキップします)

Swagger UI Swagger UIはRESTful APIを視覚的に表現し、インタラクティブに操作できるツールです。APIのエンドポイント、メソッド、パラメータを簡単に 確認でき、実際にリクエストを送信してレスポンスを確認することができます。Keycloakとの連携では認証トークンを使用したAPIリクエストの テストや、保護されたリソースへのアクセス検証に役立ちます。 http://localhost:8000/docs からアクセスしてみてください。

• http://localhost:8000/docs

デモ アクセストークンの取得 ブラウザにログインのエンドポイント http://localhost:8000/api/auth/login?state=/ を入力してください。Keycloakの画面が現れますの で作成したユーザー([email protected], password)でログインします。ログイン後にKeycloakに設定したエンドポイントへのリダイレクト が発生します。本来はHttpOnly Cookieにアクセストークンを保存しますが、今回は画面にアクセストークンが出力されます。 トークン設定 Swagger UIに移ってください。FastAPIのSwagger UIには「Authorize」ボタンがあり、ここからBearerトークンを設定できます。これによ り、UIから保護されたAPIをテストすることが可能になります。 保護されたAPI呼び出し /userエンドポイントなどの保護されたAPIを呼び出すと、正しいトークンがあれば200 OKレスポンスとデータが返されます。トークンが無効な 場合は403エラーが返されます。

• http://localhost:8000/api/auth/login?state=/

Hands-on③ 概要 ユーザーへロール付与 Keycloakコンソールでユーザーに適切なロールを割り当てます JWTローカル検証 JWKSエンドポイントから公開鍵を取得し、トークンの署名を検証します RBAC実装 検証済トークンからロール情報を抽出しAPIアクセスを制御します このハンズオンでは、認証から一歩進んで認可（Authorization）の実装に焦点を当てます。JWTトークンをローカルで検証する方法を学び、トークンに含ま れるロール情報を使用してAPIエンドポイントへのアクセスを制御します。これにより、ユーザーの権限に応じて機能へのアクセスを制限する、ロールベース のアクセス制御（RBAC）を実装します。 FastAPIのDependsシステムを活用して、エンドポイントごとに必要なロールを指定する方法を実装します。

Role の 付与 ユーザーへのロールを付与するプロセスは、Keycloakの管理コンソールで簡単に行えます。まずメニューから「Users」を選択し、対象のユー ザー（[email protected]）を検索します。ユーザー名をクリックして詳細画面を開き、「Role Mapping」タブに移動します。 「Assign role」ボタンをクリックして、利用可能なロールの一覧を表示します。ここから「fastapi_admin」を選択し、「Assign」ボタンをクリックし てロールを割り当てます。これにより、ユーザーに特定の権限が付与され、アプリケーション側でこのロール情報を使ってアクセス制御を行う ことができるようになります。

.well-known/jwks.json 取得
公開鍵エンドポイント

キー取得方法

KeycloakはJWKS（JSON Web Key Set）形式で署名検証用の公

HTTP GETリクエストで簡単に取得できます。curlコマンドでは:

開鍵を提供します。このエンドポイントはOIDC設定から確認できま

curl

す。

https://kc.example/realms/demo/protocol/openid-connect/

certs
JWTのローカル検証には、Keycloakが提供する公開鍵が必要です。これにより、トークンがKeycloakによって署名され、改ざんされてい
ないことを確認できます。Python実装では以下のようなコードでJWKSを取得します：
import requests
from jose import jwk, jwt
from jose.utils import base64url_decode

# JWKSエンドポイントからキー取得
jwks_uri = "http://localhost:8080/realms/demo-realm/protocol/openid-connect/certs"
jwks = requests.get(jwks_uri).json()

# トークン検証時に使用
def verify_token(token):
header = jwt.get_unverified_header(token)
rsa_key = {}
for key in jwks["keys"]:
if key["kid"] == header["kid"]:
rsa_key = key
break
# 以下、RSA鍵を使った署名検証処理

• https://kc.example/realms/demo/protocol/openid-connect/

FastAPI Depends で RBAC 依存関数の定義 エンドポイントへの適用 階層的なアクセス制御 特定のロールを要求する依存関数を FastAPIのDependsを使用して、エ ロール階層を設計し、上位ロールは 作成します。この関数は、JWTから ンドポイントごとに必要なロールを指 下位ロールの権限を継承するように ロール情報を抽出し、要求された 定します。これにより、コードの可読 します。例えば、adminロールは自 ロールが含まれているかを確認しま 性を維持しながらきめ細かいアクセ 動的にuserロールの権限も持つよう す。権限が不足している場合は403 ス制御が可能になります。 にします。 エラーを返します。 FastAPIでのRBAC実装のコード例： → user.pyを参照

イントロスペクション API 概要 イントロスペクションの目的 使用方法 トークンの有効性をリアルタイムに確認するために使用します。JWTの POSTリクエストでトークンを送信し、その有効性と詳細情報を取得しま ローカル検証と異なり、Keycloakサーバーに問い合わせることで、失効 す。クライアント認証が必要なため、Confidentialクライアントでの使用 したトークンも検出できます。 が一般的です。python-keycloakにもAPIが用意されています。 • リアルタイムの失効確認 • Opaqueトークンの検証 • 追加的なトークン情報の取得 POST /protocol/openid-connect/token/introspect Content-Type: application/x-www-form-urlencoded token=eyJhbGci...&token_type_hint=access_token イントロスペクションAPIは、セキュリティ要件が高いシステムや、トークンの即時失効が必要なケースで特に有用です。ただし、毎回サーバーに問い合 わせるため、パフォーマンスへの影響を考慮する必要があります。JWTのローカル検証と組み合わせて使用することで、バランスの取れたセキュリ ティとパフォーマンスを実現できます。

自由課題 これまでに学んだ知識を活かして、自分だけのプロジェクトにチャレンジしてみましょ う！具体的な実装でも、コンセプト設計だけでも構いません。以下にいくつかの提案 をご紹介します。実際に取り組むことに加えて、今後の展望についても共有していた だければ幸いです。 ① API の拡張開発 ② インタラクティブUIの構築 • • ユーザー情報管理や高度な設定変更機能 を追加実装 • Frontend(React.js/Vite)を改造して直感 的なユーザーインターフェースを開発 ログアウトAPIの実装 ③ テーマ設定 ④ PKCEに対応する (上級編) • Keycloakのログイン画面を組織やサービス • 自前でURLを組み立てて対応する に合わせてカスタマイズ • python-keycloakをforkして機能追加する • UIデザイン案とHTMLテンプレートを作成

発表タイム ・取り組んだテーマ (表示するものがあれば表示ください) ・今後の展望、やってみたいことなど

今日のまとめ & 次の一歩 基礎理解 OIDC/JWTの概念とKeycloakの構成要素を理解しました 連携実装 FastAPIとKeycloakの連携フローを実装しました RBAC構築 JWT検証とロールベースのアクセス制御を実現しました 自由課題 学んだ内容を元に自由課題に取り組みました 次のステップとしては、 Keycloakのテーマカスタマイズ、外部 IdPとの連携、多要素認証の 導入など、さらに発展的なトピックにも挑戦ください。 Discordでいつでもご質問ください。一 緒に学びましょう。

本日はご参加いただき、ありがとうございました。Shingen.pyは今後も不定期でイベントを開催予定です。 継続的な学びのためDiscordコミュニティにも引き続きご参加ください！さまざまな疑問や実装のヒントを共 有できる場として活用していただければ幸いです。