keycloakについてまとめる : その他

 keycloakの用語ご要望に応じて、Keycloakの主要な用語とその説明を、ユーザーが理解しやすい順に並べ替えました。説明内容は変更しておりません。


用語
説明


レルム（Realm）
独立した認証・認可の領域であり、ユーザー、クライアント、ロールなどをグループ化して管理する単位です。各レルムは互いに分離され、独立して設定・管理が行われます

クライアント（Client）
Keycloakにユーザーの認証を要求するアプリケーションやサービスの単位です。

セッション（Session）
ユーザーのログイン状態を保持する情報です。セッション情報により、ユーザーは再度ログインすることなく、複数のクライアントやサービスにアクセスできます。

グループ（Group）
ユーザーをまとめるための概念であり、共通のロールや属性を一括で管理・付与する際に使用されます。

ロール（Role）
ユーザーやグループに付与される権限のことです。アプリケーション内でのユーザーの役割やアクセスレベルを定義します。

リソース（Resource）
アプリケーションや組織の資産の一部であり、保護される対象を指します。具体的には、Webページ、RESTfulエンドポイント、ファイルなどが含まれます。各リソースには一意の識別子があり、関連するスコープやパーミッションとともに管理されます。

スコープ（Scope）
OAuth 2.0で、トークンに含める権限の範囲を指定するための値です。クライアントがアクセスを要求するリソースや操作の範囲を定義します。

パーミッション（Permission）
特定のリソースやスコープへのアクセス権を定義するものです。Keycloakでは、リソースサーバーが保護するリソースやスコープに対して、どのユーザーやクライアントがどのような操作を許可されているかをパーミッションとして設定します。

ポリシー（Policy）
パーミッションの適用条件やルールを定義するものです。Keycloakでは、ロールベース、属性ベース、ユーザーベースなど、さまざまなタイプのポリシーを設定でき、これにより柔軟なアクセス制御を実現します。

サービスアカウント（Service Account）
各クライアントに関連付けられた特別なユーザーアカウントであり、クライアントが自身の名前でKeycloakに対して認証を行う際に使用されます。主に、バックエンドサービス間の通信や、ユーザーの介在しない自動化されたプロセスで利用されます。

アイデンティティプロバイダー（Identity Provider, IdP）
認証情報を提供する外部サービスのことです。Keycloakは、GoogleやGitHubなどの外部IdPと連携して、ユーザーの認証を委任できます。

サービスプロバイダー（Service Provider, SP）
IdPから認証情報を取得し、サービスを提供する側のことです。Keycloak自体がSPとして機能し、外部IdPと連携することも可能です。

UserInfo
OpenID Connectの標準エンドポイントで、認証済みユーザーの情報を取得するために使用されます。クライアントはアクセストークンを用いてこのエンドポイントにリクエストを送り、ユーザーのプロフィール情報などを取得できます。

ユーザー属性（User Attributes）
Keycloak内でユーザーごとに設定できるカスタム情報のフィールドです。メールアドレスや電話番号など、ユーザーに関連する静的な情報を保持するのに適しています。これらの属性は、必要に応じてトークンやUserInfoエンドポイントで公開することができます。

マッパー（Mapper）
IDトークンやアクセストークンにカスタム情報を追加するための仕組みです。ユーザー属性やロール情報をトークンに含める際に使用されます。

Authenticator
認証方法を定義する機能です。パスワード、ワンタイムパスワード（OTP）、多要素認証（MFA）など、さまざまな認証手段を設定できます。

クライアントスコープ（Client Scope）
クライアントが要求できる権限の集合を定義します。アクセストークンやIDトークンに含める情報をカスタマイズする際に利用されます。

Realm Management
レルムの設定や管理を行う機能です。レルム内のユーザー、クライアント、ロール、ポリシーなどの管理を担当します。

User Federation
外部のIDストア（例：LDAPやActive Directory）と連携し、ユーザー情報を管理する機能です。既存のユーザーディレクトリと統合する際に使用されます。

ログインテーマ
Keycloakのログイン画面のデザインや動作をカスタマイズするためのテンプレート。

用語	説明
レルム（Realm）	独立した認証・認可の領域であり、ユーザー、クライアント、ロールなどをグループ化して管理する単位です。各レルムは互いに分離され、独立して設定・管理が行われます
クライアント（Client）	Keycloakにユーザーの認証を要求するアプリケーションやサービスの単位です。
セッション（Session）	ユーザーのログイン状態を保持する情報です。セッション情報により、ユーザーは再度ログインすることなく、複数のクライアントやサービスにアクセスできます。
グループ（Group）	ユーザーをまとめるための概念であり、共通のロールや属性を一括で管理・付与する際に使用されます。
ロール（Role）	ユーザーやグループに付与される権限のことです。アプリケーション内でのユーザーの役割やアクセスレベルを定義します。
リソース（Resource）	アプリケーションや組織の資産の一部であり、保護される対象を指します。具体的には、Webページ、RESTfulエンドポイント、ファイルなどが含まれます。各リソースには一意の識別子があり、関連するスコープやパーミッションとともに管理されます。
スコープ（Scope）	OAuth 2.0で、トークンに含める権限の範囲を指定するための値です。クライアントがアクセスを要求するリソースや操作の範囲を定義します。
パーミッション（Permission）	特定のリソースやスコープへのアクセス権を定義するものです。Keycloakでは、リソースサーバーが保護するリソースやスコープに対して、どのユーザーやクライアントがどのような操作を許可されているかをパーミッションとして設定します。
ポリシー（Policy）	パーミッションの適用条件やルールを定義するものです。Keycloakでは、ロールベース、属性ベース、ユーザーベースなど、さまざまなタイプのポリシーを設定でき、これにより柔軟なアクセス制御を実現します。
サービスアカウント（Service Account）	各クライアントに関連付けられた特別なユーザーアカウントであり、クライアントが自身の名前でKeycloakに対して認証を行う際に使用されます。主に、バックエンドサービス間の通信や、ユーザーの介在しない自動化されたプロセスで利用されます。
アイデンティティプロバイダー（Identity Provider, IdP）	認証情報を提供する外部サービスのことです。Keycloakは、GoogleやGitHubなどの外部IdPと連携して、ユーザーの認証を委任できます。
サービスプロバイダー（Service Provider, SP）	IdPから認証情報を取得し、サービスを提供する側のことです。Keycloak自体がSPとして機能し、外部IdPと連携することも可能です。
UserInfo	OpenID Connectの標準エンドポイントで、認証済みユーザーの情報を取得するために使用されます。クライアントはアクセストークンを用いてこのエンドポイントにリクエストを送り、ユーザーのプロフィール情報などを取得できます。
ユーザー属性（User Attributes）	Keycloak内でユーザーごとに設定できるカスタム情報のフィールドです。メールアドレスや電話番号など、ユーザーに関連する静的な情報を保持するのに適しています。これらの属性は、必要に応じてトークンやUserInfoエンドポイントで公開することができます。
マッパー（Mapper）	IDトークンやアクセストークンにカスタム情報を追加するための仕組みです。ユーザー属性やロール情報をトークンに含める際に使用されます。
Authenticator	認証方法を定義する機能です。パスワード、ワンタイムパスワード（OTP）、多要素認証（MFA）など、さまざまな認証手段を設定できます。
クライアントスコープ（Client Scope）	クライアントが要求できる権限の集合を定義します。アクセストークンやIDトークンに含める情報をカスタマイズする際に利用されます。
Realm Management	レルムの設定や管理を行う機能です。レルム内のユーザー、クライアント、ロール、ポリシーなどの管理を担当します。
User Federation	外部のIDストア（例：LDAPやActive Directory）と連携し、ユーザー情報を管理する機能です。既存のユーザーディレクトリと統合する際に使用されます。
ログインテーマ	Keycloakのログイン画面のデザインや動作をカスタマイズするためのテンプレート。

ebi_yu

 認可情報のやり取り方式
 トークンベース認証後にアクセストークン（JWTなど）を発行し、クライアントがリクエストのたびにトークンを送信。
トークンはAuthorization: Bearer <token>ヘッダーで送られる。
サーバー側はトークンを検証し、認可を実行。
トークンはステートレスで管理され、サーバー側に保持しない。

 メリット
ステートレス：サーバーがセッション管理をしないため、スケーラビリティが高い。

認証情報の共有が容易：複数のシステムで同じトークンを利用可能（SSOなど）。

柔軟な運用：アクセス権限をトークンに含められる（例：JWTのペイロード）。

 デメリット
トークン漏洩リスク：トークンが漏洩すると、期限が切れるまで不正利用される。

トークンの失効管理が難しい：サーバー側でブラックリストを管理しないと即時無効化できない。

セキュリティ設定が必要：HTTPS必須、トークン保存場所（ローカルストレージやCookie）の管理が重要。

 セッションベース認証後にサーバー側でセッションを生成し、セッションIDをクライアントに付与（Cookieに保存）。
クライアントはリクエスト時にセッションIDを送信。
サーバーはセッションストア（例：Redis、データベース）を参照し、ユーザー情報を確認。
セッションが有効であれば、リクエストを認可。

 メリット
セッション管理がしやすい：サーバー側でセッションを失効させられるため、不正アクセスのリスクを軽減。

XSS対策が容易：トークンをクライアント側に保存しないため、JavaScriptからアクセスできない。

 デメリット
ステートフル：サーバーがセッションを管理するため、スケーラビリティが低い。

負荷分散が必要：複数のサーバーでセッションを共有する必要がある（例：Sticky Session、分散セッションストア）。

マルチドメインに向かない：サブドメイン間のセッション共有には追加の設定が必要。

 トークン+セッションベース認証後にサーバー側でセッションを作成し、アクセストークンをセッションと紐付ける。
クライアントはCookieにセッションIDを保存し、リクエスト時に送信。
サーバーはセッションストアからトークンを取得し、検証後に認可を実行。
トークンは短期間有効で、リフレッシュトークンを利用することで長期的なセッションを維持可能。

 選択のポイント


特性
トークンベース
セッションベース
トークン+セッション


スケーラビリティ
高い（ステートレス）
低い（セッション管理が必要）
中程度（セッションストア次第）

セキュリティ
トークン漏洩リスクあり
セッション管理で安全
トークンをサーバー管理で安全

失効管理
難しい（ブラックリストが必要）
容易（セッション削除）
容易（セッション削除）

適用対象
API、SPA、マイクロサービス
従来のWebアプリ
API＋Webアプリのハイブリッド


 結論**内部的なAPI同士のやり取りはトークンベース、webアプリとAPIのやり取りはトークン+セッションベースで行うのがよさそう

特性	トークンベース	セッションベース	トークン+セッション
スケーラビリティ	高い（ステートレス）	低い（セッション管理が必要）	中程度（セッションストア次第）
セキュリティ	トークン漏洩リスクあり	セッション管理で安全	トークンをサーバー管理で安全
失効管理	難しい（ブラックリストが必要）	容易（セッション削除）	容易（セッション削除）
適用対象	API、SPA、マイクロサービス	従来のWebアプリ	API＋Webアプリのハイブリッド

ebi_yu

 Keycloak セッション関連の設定値

設定項目名
説明


SSO Session Idle
OIDCクライアント専用の設定。ユーザーが指定時間非アクティブであればセッションが無効になる。クライアントが認証を要求するか、リフレッシュトークンを送信するとタイムアウトがリセットされる。

SSO Session Max
SSOユーザーセッションの最大有効時間。(リフレッシュトークンの有効期限)この時間を超えるとセッションは失効する。

SSO Session Idle Remember Me
「Remember Me」機能を有効にした場合のSSOセッションのアイドルタイムアウト。標準のSSOセッションよりも長く設定可能。

SSO Session Max Remember Me
「Remember Me」機能を有効にした場合のSSOセッションの最大有効時間。標準のSSO Session Maxよりも長く設定可能。

Client Session Idle
クライアント単位のセッションのアイドルタイムアウト。非アクティブ状態が一定時間続くと無効化され、リフレッシュトークンの利用が制限される。

Client Session Max
クライアント単位のセッションの最大有効時間。リフレッシュトークンの有効期限にも影響する。

Offline Session Idle
オフライントークンが無効になるまでのアイドルタイムアウト。一定時間利用されないとKeycloakがトークンを失効させる。

Offline Session Max Limited
オフラインセッションの最大時間を制限するオプション。有効にすると、一定時間が経過したオフラインセッションは無条件に失効する。

Offline Session Max
オフライントークンが最大どのくらいの時間有効であるかを決める。ユーザーの活動に関係なく、この時間を超えるとトークンは失効する。

Login Timeout
ログイン処理全体にかかる最大時間。この時間を超えると、ログインプロセスはリセットされる。

Login Action Timeout
認証プロセスにおいて、ユーザーが特定の認証アクション（例：OTP入力）を完了するまでの最大時間。

Default Signature Algorithm
レルムのトークン署名に使用するデフォルトのアルゴリズム。

Revoke Refresh Token
有効にすると、リフレッシュトークンを一度使用すると失効し、新しいトークンが発行される。

Access Token Lifespan
OIDCアクセストークンの有効期限。

Access Token Lifespan For Implicit Flow
インプリシットフローで発行されるアクセストークンの有効期限。リフレッシュトークンがないため、短めに設定するのが一般的。

Client Login Timeout
クライアントがOIDCの認可コードフローを完了するまでの最大時間。

User-Initiated Action Lifespan
ユーザーが自身で発行したアクション（例：パスワードリセット）の有効期限。通常短めに設定される。

Default Admin-Initiated Action Lifespan
管理者がユーザーに送信したアクションの有効期限（例：アカウント復旧リンク）。通常長めに設定される。

Email Verification Lifespan
電子メールの認証コードが有効な時間。

IdP Account Email Verification Lifespan
IdPアカウントのメール認証コードの有効期限。

Forgot Password Lifespan
パスワードリセット時のリンクが有効な時間。

Execute Actions Lifespan
特定のアクション（例：アカウント更新）を実行できる時間。

https://keycloak-documentation.openstandia.jp/22.0/ja_JP/server_admin/index.html#_timeouts

設定項目名	説明
SSO Session Idle	OIDCクライアント専用の設定。ユーザーが指定時間非アクティブであればセッションが無効になる。クライアントが認証を要求するか、リフレッシュトークンを送信するとタイムアウトがリセットされる。
SSO Session Max	SSOユーザーセッションの最大有効時間。(リフレッシュトークンの有効期限)この時間を超えるとセッションは失効する。
SSO Session Idle Remember Me	「Remember Me」機能を有効にした場合のSSOセッションのアイドルタイムアウト。標準のSSOセッションよりも長く設定可能。
SSO Session Max Remember Me	「Remember Me」機能を有効にした場合のSSOセッションの最大有効時間。標準のSSO Session Maxよりも長く設定可能。
Client Session Idle	クライアント単位のセッションのアイドルタイムアウト。非アクティブ状態が一定時間続くと無効化され、リフレッシュトークンの利用が制限される。
Client Session Max	クライアント単位のセッションの最大有効時間。リフレッシュトークンの有効期限にも影響する。
Offline Session Idle	オフライントークンが無効になるまでのアイドルタイムアウト。一定時間利用されないとKeycloakがトークンを失効させる。
Offline Session Max Limited	オフラインセッションの最大時間を制限するオプション。有効にすると、一定時間が経過したオフラインセッションは無条件に失効する。
Offline Session Max	オフライントークンが最大どのくらいの時間有効であるかを決める。ユーザーの活動に関係なく、この時間を超えるとトークンは失効する。
Login Timeout	ログイン処理全体にかかる最大時間。この時間を超えると、ログインプロセスはリセットされる。
Login Action Timeout	認証プロセスにおいて、ユーザーが特定の認証アクション（例：OTP入力）を完了するまでの最大時間。
Default Signature Algorithm	レルムのトークン署名に使用するデフォルトのアルゴリズム。
Revoke Refresh Token	有効にすると、リフレッシュトークンを一度使用すると失効し、新しいトークンが発行される。
Access Token Lifespan	OIDCアクセストークンの有効期限。
Access Token Lifespan For Implicit Flow	インプリシットフローで発行されるアクセストークンの有効期限。リフレッシュトークンがないため、短めに設定するのが一般的。
Client Login Timeout	クライアントがOIDCの認可コードフローを完了するまでの最大時間。
User-Initiated Action Lifespan	ユーザーが自身で発行したアクション（例：パスワードリセット）の有効期限。通常短めに設定される。
Default Admin-Initiated Action Lifespan	管理者がユーザーに送信したアクションの有効期限（例：アカウント復旧リンク）。通常長めに設定される。
Email Verification Lifespan	電子メールの認証コードが有効な時間。
IdP Account Email Verification Lifespan	IdPアカウントのメール認証コードの有効期限。
Forgot Password Lifespan	パスワードリセット時のリンクが有効な時間。
Execute Actions Lifespan	特定のアクション（例：アカウント更新）を実行できる時間。

ebi_yu

 keycloakのユーザ情報の持ち方
 1. アクセストークンに持つ認可系で情報量が少ないなものを持つ
ヘッダーで送るので、肥大化すると413 Paylood Too Largeが起きる

 2. idトークンに待つユーザの識別情報のみを持たせるべき
こちらも肥大化すると、ログアウトのid_token_hintなどにひっかかる

 3. userinfoに持つでかいユーザ情報はuseinfoに持つ
userinfoエンドポイントで取得
セッションごとに動的に変わらないなら、userAttributeでよい

 4. userAttributeで持つメールアドレスなどの動的に変わらない情報の場合

 5. そもそも持たない外部サービスでユーザ情報が管理されているかつ、フェデレーションしないなら

こっちのほうがシンプル
https://github.com/keycloak/keycloak/discussions/14032

ebi_yu

外部にロール情報を持つときの認可の検討

このスクラップは2025/01/31にクローズされました