釣りキチ翔平の備忘録 
目次
はじめに
以下大きく２点について、
Keycloakを業務で実際に利用している自分の観点で
押さえておくべきポイントに絞ってまとめました。
- Keycloakを利用する際に押さえておくべき基本的な概念と用語
- セッション、アクセストークン、IDトークン、リフレッシュトークンの有効期限の関係
Keycloakを利用する上で抑えておくべき基本的な概念と用語
抑えるべきはざっくり以下4つです。
- Keycloakの設定周り一式を分割できるレルム
- Keycloakと連携するために必要なクライアント
- ユーザとユーザに付与できる情報(属性情報、ロール、グループ)
- トークンにユーザ関連の情報をマッピングする仕組み(プロトコルマッパー、クライアントスコープ)
Keycloakの設定周り一式を分割できるレルム
例えば、A社とB社にシステムを導入していて、認証方式や管理ユーザなどなど個別に異なる場合、
その各種設定範囲を分割するためにレルムがあります。
僕が現場で担当しているプロダクトもマルチテナントで動くように諸々設定をしているのですが、
導入先毎にレルムを分けて管理しています。
具体的なレルムの作成方法などは、
すでに結構丁寧に解説されているサイトなどもあるのでここでは省略します。
Keycloakと連携するために必要なクライアント
例えばOIDCのRPがKeycloak(OP)と連携するためのクライアントを作成する必要があったり、
リソースサーバがトークン検証の際、
Keycloakと連携するためのクライアントを作成する必要があったりします。
具体的なクライアントの作成方法は
すでに結構丁寧に解説されているサイトなどもあるのでここでは省略します。
ユーザとユーザに付与できる情報(属性情報、ロール、グループ)
Keycoakではユーザを管理でき、Keycloakがデフォルトで用意している属性(メールアドレス、ユーザ名など)
の他にユーザの属性情報(ユーザの職業情報とか)を追加で管理することができます。
また、グループ(ユーザが所属している組織のイメージ)、やロール(管理者権限、一般権限とか)も管理でき、
ユーザがどのグループでどのロールを持っているのかということが管理できます。
それによって、Aグループに所属しているユーザだけに参照できるようにする。
管理者権限を持つユーザのみ更新権限を与える。
などの制御が行えます。
トークンにユーザ関連の情報をマッピングする仕組み(プロトコルマッパー、クライアントスコープ)
これは見るのが早いので・・・
IDトークンにロール、グループ、属性追加をしてレルムにマッピングした例を見てください。
(IDトークンをデコードjwt.ioでデコード済み)
このようにユーザに追加した諸々の情報をIDトークンやアクセストークンのレルムとして追加したり、
OIDCのUserInfoエンドポイントで返却できるようにしたりする設定が、
プロトコルマッパー(クライアント単位で設定)やクライアントスコープ(クライアント横断で設定)です。
ちなみに今回はfrontendというクライアントを作って、そこにマッパーの設定をこんな感じで入れました。
セッションとアクセストークン、IDトークン、リフレッシュトークンの有効期限の関係と設定
有効期限の関係性を意識しないものとして全部で4つあります。
| 名前 | 推奨有効期限 | keycloakパラメータ名 |
| セッション | ー (ログイン頻度の要件次第) | SSO Session Max |
| 認可コード | 10分以内 | Client login timeout |
| ID(アクセス)トークン | 1時間以内 | Access Token Life Span |
| リフレッシュトークン | ー (ログイン頻度の要件次第) | SSO Session Idle |
セッションやリフレッシュトークンの有効期限を短くするとログイン(再度認証や認可のやり直し)
を頻繁に行うことになるので、ユーザビリティとのトレードオフで決めることになります。
一方、
認可コードやIDトークンなどは短く設定しておくことで、
漏洩のリスクや被害影響を最低限に抑えることができます。
具体的なKeycloakの設定画面はこんな感じです。
また、
これらの有効期限の関係を認可コードフローの時間軸と照らし合わせるとこんな感じです。
認可コードフローについて絵を使ってまとめた記事があるので、
必要であればこちらもご覧ください
認可コードフローを図解｜OAuth2.0(OIDC)の仕組みをSPAのSSO機能を例に解説
まとめ
今回はKeycloakを利用する上での基本的な概念と、
セッションとアクセストークン、IDトークン、リフレッシュトークンの有効期限の関係
についてまとめました。
Keycloakを利用する上で抑えておくべき概念は以下の４つです。
- Keycloakの設定周り一式を分割できるレルム
- Keycloakと連携するために必要なクライアント
- ユーザとユーザに付与できる情報(属性情報、ロール、グループ)
- トークンにユーザ関連の情報をマッピングする仕組み(プロトコルマッパー、クライアントスコープ)
逆にこの辺りが抑えられれば認証サーバや認可サーバとしてのKeycloakを設定は
ある程度正しく行えるようになると思います。
僕はこの辺り抑えてないまま設定していたので、、、
ちょこちょこ良くない設定をしていました。。。
おまけ
KeycloakでSpring Bootで作成したRestAPIを保護したり、
SPA(Single Page Application)にKeycloakのSSO機能でログイン機能を追加したり、
OIDCやOAuth2.0の違い解説などなどのまとめ記事を作りました。
興味のある方は是非ご覧ください！！
keycloakでAPI保護・SPAログイン機能設定例、OIDC・OAuth・PKCE・認可コードフロー図解などまとめ
