Keycloak 拡張入門
OSSセキュリティ技術の会 第五回勉強会
KeycloakとWebAuthnのツインシュートの巻
2019年06月07日
株式会社野村総合研究所
和田 広之
本資料に掲載されている会社名、製品名、サービス名は各社の登録 商標、又は商標です。

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 1
自己紹介
 和田 広之 @wadahiro
 野村総合研究所
 主にOSS系担当 (OpenStandia)
 最近のコミュニティ活動
▪ Keycloak FAPI対応のお手伝い
▪ Keycloak の OAuth 2.0 Device Authorization Grant 対応の提案
▪ WebAuthn4j JUnit5 Migration対応
▪ Keycloak ガイドの日本語翻訳
▪最新の6.0.1も翻訳済み！

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 2
今日話すこと
 Keycloakの拡張機能
 拡張事例の紹介

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 3
Keycloakの拡張機能

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 4
Keycloakの開発ポリシー
 フィーチャー・クリープを避ける
 OpenID Connect / SAML のみにフォーカス
 利用者が必要に応じて、機能拡張・カスタマイズ
ができるようにしておく
50を超える拡張ポイントを用意

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 5
Keycloakの拡張機能
 拡張ポイント
1. ログイン画面などのUI (テーマ)
2. スクリプトによる拡張
3. SPI (サービス・プロバイダー・インターフェイス)
実装による機能拡張
4. カスタムSPI の追加

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 6
1. テーマ
 種類
 Account: アカウント管理
 Admin: 管理コンソール
 Email: 送信メール
 Login: ログイン画面
 Welcome: ウェルカムページ

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 7
テーマ例
(出所) https://developers.redhat.com
https://velocityfrequentflyer.com/
https://login.dbschenker.com

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 8
テーマの開発
 $KEYCLOAK_HOME/themes/<テーマ名>/<テー
マ種類> ディレクトリを作成
 上記ディレクトリ内に各種リソースを格納する
 管理コンソールより、適用したいレルムのテーマ設
定で切り替える

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 9
テーマの開発
 開発時はテーマキャッシュを無効にするとよい
 テーマ修正 → ブラウザリロードで即反映されるようになる
 $KEYCLOAK_HOME/standalone/configuration/standalone.x
ml のtheme設定を変更する

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 10
テーマのデプロイ方式
 2方式
 展開方式
 アーカイブ方式
 展開方式
 $KEYCLOAK_HOME/themes ディレクトリ以下にリソースを配置
 アーカイブ方式
 リソースをJARファイルにまとめて
$KEYCLOAK_HOME/standalone/deployments/ 以下にデプロイ
 META-INF/keycloak-themes.json の作成が別途必要

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 11
2. スクリプトによる拡張
 管理コンソールからJavaScriptコードを設定
 以下の3つが利用可能
 ScriptBasedAuthenticator
▪認証処理のカスタマイズ
 ScriptBasedMapper
▪SAML利用時のマッパー処理のカスタマイズ
▪SAMLResponseに含めるAttributeをコードで処理できる
 ScriptBasedOIDCProtocolMapper
▪OIDC利用時のマッパー処理のカスタマイズ
▪ID TokenのClaim設定をコードで処理できる

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 12
JavaScriptコードの設定
 管理コンソールにて簡易エディタでコードを記述
 Nashornで動作するため、 Java.type("・・・") で
Javaのクラスにアクセス可能

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 13
3. SPI (サービス・プロバイダー・インターフェイス)
 Java 6 から導入された ServiceLoader を活用し
たプラグイン機構
 JARファイル/META-INF/services/<インターフェイス名> のファイ
ルに読み込む実装クラス名を書いておく
▪複数のJARに同名ファイルを配置できる
▪同ファイル内に複数の実装クラスをかける
 java.util.ServiceLoader.load(<インターフェイス名>.class) をコー
ルすると、対応するファイル内に記述した実装クラス群のインスタ
ンスをIterableで返す

各種SPIのインターフェ
イス定義、メタデータ定
義
(Internalかどうかなど)
SPI拡張する人は
ここだけを作って
いけばOK

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 15
基本的な作り方
1. SPI単位に提供される、拡張用インターフェイスを実装する
 ProviderFactoryのサブ・インターフェイス
▪ ユニークなID (Provider ID) を定義して返す
▪ 初期化・終了処理や対応するProviderのインスタンスを返す責務を
持つ
 Providerのサブ・インターフェイス
▪ これがSPIのメイン機能実装
 SPIによっては、上記を1つにまとめたサブ・インターフェイスや抽象
クラスを提供している場合もあり
(AbstractClientAuthenticator、 ProtocolMapperなど)
2. Service configuration file を作成する
 ＝ ServiceLoaderの設定ファイル
3. デプロイ

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 16
提供されるSPIの例
 Authenticator
 RequiredActionProvider
 ClientAuthenticator
 FormAction
 RealmResourceProvider
 SocialIdentityProviderFactory
 JpaEntityProvider
 EventListenerProvider
 UserStorageProvider
 ProtocolMapper
 LoginFormsProvider
 LoginProtocol
 ・・・

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 17
例: 認証ロジック追加のSPIの場合
1. ProviderFactory / Provider のサブ・インターフェイスを実装
 AuthenticatorFactory インターフェイス
▪ ユニークなProvider IDを定義して返す
▪ Authenticator実装クラスのインスタンスを生成して返す
▪ 管理コンソールから設定する項目のメタデータ定義
 Authenticator インターフェイス
▪ 認証処理時・ログイン等のアクション実行にコールバックされるメソッドが定義されている
のでこれらを実装する
2. Service configuration file を作成
 META-INF/services/org.keycloak.authentication.AuthenticatorFactory を作成し、 Authen
ticatorFactoryの実装クラスを書く
my.CustomLoginIdPasswordFormFactory

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 18
SPI実装のデプロイ
 ～ Keycloak 1.9系
 File-system方式
▪$KEYCLOAK_HOME/providers ディレクトリにJARを配置
▪現在でも実は使えるが、Third-partyライブラリを含めるのが難し
い＆ホットデプロイが効かないのでおすすめしない
 Module方式 (当時は推奨)
▪$KEYCLOAK_HOME/modules 以下にディレクトリを作成して
JARを配置
▪module.xml を作成し依存モジュールを定義
▪$KEYCLOAK_HOME/standalone/configuration/standalone.
xml にモジュールをロードするための設定を追記
▪ホットデプロイ未対応

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 19
SPI実装のデプロイ
 Keycloak 2系 ～
 Keycloak Deployer 方式 (推奨)
▪JARやEARの META-INF/jboss-deployment-structure.xml を
作成して依存モジュールを定義
▪JAR/EAR を $KEYCLOAK_HOME/standalone/deployments/
に配置する
▪Third-party ライブラリを使いたい場合は、EAR/lib に含めれば
良い
▪ホットデプロイが効きます！！
▪基本、この方式を使えばOK
 Module 方式
▪カスタムSPIを作るときはこちらを使う

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 21
SPI Info
 管理コンソールのServer Info
画面より、SPIの種類・ロードさ
れているProviderを確認でき
る
 デプロイしたカスタムの
Provider実装も表示される
 付けたProvider IDで表示

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 22
注意点
 Internal SPIを拡張すると、起動時にWARNログが
出る
 将来予告なく変更される可能性があるため、バー
ジョンアップ時に要注意
 Red Hat SSOだと、Internal SPIを使っている箇所
はサポート対象外
 サポート問い合わせ時に自分達で切り分ける必要があるかも！？
WARN [org.keycloak.services] (ServerService Thread Pool -- 57) KC-SERVICES0047: freemark
er (jp.openstandia.keycloak.forms.login.freemarker.FreeMarkerLoginFormsProviderExtFactory) i
s implementing the internal SPI login. This SPI is internal and may change without notice

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 23
4. カスタムSPIの追加
 Keycloak本体の開発、カスタマイズ時にしか基本
使わないはず
 例えば、提案中のOAuth 2.0 Device Authorization Grant対応の
中で、User Codeのフォーマットを利用者がカスタマイズできるよう
にSPIを追加している
 ドキュメント
 https://www.keycloak.org/docs/latest/server_development/i
ndex.html#_extensions_spi
 SPI追加サンプル
 https://github.com/keycloak/keycloak/tree/master/examples
/providers/domain-extension

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 24
参考となるリソース 1/2
 開発者向けガイド (Server Developer Guide)
 (英語版)
https://www.keycloak.org/docs/latest/server_development/index.html
 (日本語版)
https://keycloak-
documentation.openstandia.jp/master/ja_JP/server_development/index.h
tml
 keycloak-quickstarts
 UserStorage SPI などのサンプルコードあり
 https://github.com/keycloak/keycloak-quickstarts
 keycloak Examples
 テーマによるUIカスタマイズ例やSPI実装サンプルあり
 https://github.com/keycloak/keycloak/tree/master/examples

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 25
参考となるリソース 2/2
 keycloak.org の Community > Extensions のページ
 https://www.keycloak.org/extensions.html
 コミュニティで開発された拡張機能の紹介ページ
 https://github.com/keycloak/keycloak-web にプルリクエストを出すと掲載され
ます！！
 awesome-keycloak
 Keycloak contributorの一人である @thomasdarimont 氏によるまとめリンク集
 拡張に関する情報もあります
 Keycloakソース
 特にマイナーなSPIを拡張する場合は、各種SPIのデフォルト実装を参考にする と
よい

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 26
拡張事例の紹介

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 27
拡張事例
 初級編
 動的にログイン画面の表示を制御したい
 中級編
 「○○でログイン」に対応したい
 上級編
 ○○ ADのように、SSO時にサービス利用権限がないユーザーは
エラーとしたい

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 28
初級編

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 29
初級編
動的にログイン画面の表示を制御したい
 よくある背景
 Identity Brokeringを使って複数の外部IdPから認証可能にしてい
るが、UX向上のためアクセス経路に応じて、利用可能なIdPに絞っ
て表示としたい
 環境変数の値に応じて表示を切り替えたい (STG / PROD)
社内LANからアクセス時
インターネットでアクセス時

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 30
初級編
動的にログイン画面の表示を制御したい
 標準機能
 ThemeでHTMLのカスタマイズは可能なものの、環境変数やリクエ
スト情報をFreeMarkerテンプレート内で参照できない

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 31
初級編
動的にログイン画面の表示を制御したい
 対応方法
 ログイン画面のテンプレート処理は、LoginFormsProvider のSPI実
装にて行われている
 このデフォルトSPI実装である FreeMarkerLoginFormsProvider
を独自クラスのProviderに切り替える
▪オリジナルを継承して作ると作成コード量はかなり抑えられる
 独自クラス内で、参照させたいオブジェクトをバインド

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 32
Providerの切り替え方法
 $KEYCLOAK_HOME/standalone/deployment
s/standalone(-ha).xml にて デフォルトプロバイ
ダーを切り替える
 もしくは、上級編で紹介する同名Provider ID上書き方式で切り替え
るのも可

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 33
中級編

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 34
中級編
「○○でログイン」に対応したい
 よくある背景
 KeycloakのSocial Loginで用意されていない外部IdPを使って、
Keycloakにログインできるようにしたい
▪LINEで認証
▪Login with Amazonで認証
▪Discordで認証
▪・・・

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 35
中級編
「○○でログイン」に対応したい
 標準機能
 ビルトインはメジャーなIdPs + OIDC/SAML2
 メンテ大変なので、Keycloakチームとしてはもう増やしたくないかも
▪http://lists.jboss.org/pipermail/keycloak-dev/2019-
April/011992.html
We've not had any requests for vk.com until now so we would probably not
accept it into the core Keycloak codebase. This is simply down to
maintenance. If you want to develop a plugin though we can link to it from
the extensions list on keycloak.org.

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 36
中級編
「○○でログイン」に対応したい
 対応方法
 OIDC/SAML2 に対応している場合
▪設定のみで対応できるはず
▪OIDCに対応したLINEは設定のみで繋がりました
 OAuth2 に対応している場合
▪Identity Brokerのカスタム開発
▪SocialIdentityProviderFactory SPIを実装する
▪AbstractOAuth2IdentityProvider を継承して開発すると大幅に
カスタムコードを削減できる
▪OIDCのUserInfo Endpoint相当のAPIをコールして属性マッピ
ングする処理を書くだけで良い
▪Discordを例に、以前記事を書いたので詳しくはコチラ
https://qiita.com/wadahiro/items/d327ff65388d68b25e0a

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 37
上級編

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 38
上級編
○○ ADのように、SSO時にサービス利用権限がないユーザーはエラーとしたい
 よくある背景
 特定のグループやロールに所属しているユーザーにのみ、あるアプ
リケーションの利用（SSOによるアクセス）を許可したい
 ○○ AD だと「条件付きアクセスによるアクセス制御」で、様々な条
件を元に動的にアクセス制御が可能になっている
 同じことをKeycloakでもやりたい！

特定グループ所属ユーザーの場合 特定グループに所属していないユーザーの場合

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 40
上級編
○○ ADのように、SSO時にサービス利用権限がないユーザーはエラーとしたい
 標準機能
 過去にメーリングリストで、細かくアクセス制御したい場合は
Keycloakの認可機能を使いましょう、と回答されていた
（記憶が正しければ...
 しかし、認可機能はクライアントアプリケーション(=RPやSP) 側で
KeycloakのAPIをコールしてアクセスコントロールしないといけない
はず
 つまり、アプリケーション側に手が入る
 連携先がSaaSとかの場合どうするの？ という問題が・・・

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 41
上級編
○○ ADのように、SSO時にサービス利用権限がないユーザーはエラーとしたい
 対応方法 ※今回はSAMLだけ対応
 LoginProtocol SPIを拡張してSAML用の実装を入れ替える
▪デフォルトのSAML用実装、SamlProtocolを継承することで大幅
に実装コードを削減できる
 LoginProtocol SPIのProviderFactoryクラスにて、SAMLエンドポ
イントクラスの実装を決定しているので、ここをオーバーライドして
カスタムエンドポイントを組み込む
 カスタムエンドポイントにて、ユーザーの認証処理の後にアクセス
制御処理を追加する
 個別のアクセス制御処理を容易に追加・削除できるように、SAML
Mapperの仕組みを活用する
▪ProtocolMapper SPI を拡張して実装する

例えば、abcdefg グループ所属
ユーザーを許可する設定を書く
ProtocolMapper SPIとして作成
すると標準の管理画面の
Mapper定義で設定可能になる

クライアントに設定されたアク
セスコントロール用の
Protocol Mapperを集める
集めたMapperでユーザーの
権限チェックを実施
NG一つでもあれば、
Forbiddenページへ遷移
認証成功時にコールバックされるメソッドをオー
バーライドしてアクセス制御処理を追加
Forbiddenページ追加のため
に、拡張したLoginFormsProvi
derを使って画面遷移

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 44
LoginProtocolの入れ替え方法
 初級編で紹介したLoginFormsProviderと異なり、
LoginProtocolにはデフォルトプロバイダーはない
 SAMLの場合、 “saml” というProvider IDで登録
されており、この名前をハードコードで指定してプロ
バイダーが利用されている
 この場合、standalone(-ha).xml で上書くことがで
きない！
 このファイルでは、Provider IDの指定なしで要求されたときに返す
デフォルトプロバイダーを設定することしかできない

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 45
LoginProtocolの入れ替え方法
 現状の解 (4系～で動作を確認)
 カスタムのLoginProtocol実装クラスのProviderFactoryにて、同名の
Provider IDを付ける
 以下のどちらかの方式でデプロイしてビルトインのSPI実装を上書きする
1. Keycloak Deployer 方式
▪ ただし、注意点あり (次ページ参照)
2. 特殊なModule 方式
▪ 通常のModule方式でデプロイすると、同名のProvider IDは
Keycloak起動時にスルーされてしまう
▪ keycloak-dev で @thomasdarimont 氏 が紹介した方式を使う
必要がある
▪ keycloak-servicesのmodule.xmlに手を入れて優先させる
▪ http://lists.jboss.org/pipermail/keycloak-dev/2019-
February/011745.html

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 46
Keycloak Deployer による上書き方式の注意点
 今後のバージョンアップ時に要注意
 http://lists.jboss.org/pipermail/keycloak-dev/2019-
June/012107.html
 ホットデプロイ対応時に、意図せずこのKeycloak Deployer 方式で
同名Provider IDで上書き可能になった模様
 というわけで、別途JIRAチケットを作成してオフィシャル対応してい
きたいところ
This kinda works by accident and it's not fully reliable as something could
change.
I'd like to make sure only one provider is registered with a specific id,
but allow disabling built-in providers.
If that sounds like a plan please create an issue.

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 47
まとめ

Copyright（C） Nomura Research Institute, Ltd. All rights reserved. 48
まとめ
 多くの拡張ポイントが用意されている
 コアのソースに手を入れずに、機能拡張が可能
 GitHubでたくさん公開されているサンプルコード
をまずは参考にするとよい
 マイナーなSPIの拡張方法を学ぶには、
デフォルト実装のソースを読むのが近道
 ビルトインProviderの上書き方法は今後変わるか
もしれないので注意してください