Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Keycloak拡張入門

1,377 views

Published on

OSSセキュリティ技術の会 第五回勉強会
Keycloak 拡張入門
https://secureoss-sig.connpass.com/event/130011/

Published in: Software
  • DOWNLOAD FULL eBOOK INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... 1.DOWNLOAD FULL. PDF eBook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB eBook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. doc eBook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. PDF eBook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB eBook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. doc eBook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, CookeBOOK Crime, eeBOOK Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

Keycloak拡張入門

  1. 1. Keycloak 拡張入門 OSSセキュリティ技術の会 第五回勉強会 KeycloakとWebAuthnのツインシュートの巻 2019年06月07日 株式会社野村総合研究所 和田 広之 本資料に掲載されている会社名、製品名、サービス名は各社の登録 商標、又は商標です。
  2. 2. 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も翻訳済み!
  3. 3. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 2 今日話すこと  Keycloakの拡張機能  拡張事例の紹介
  4. 4. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 3 Keycloakの拡張機能
  5. 5. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 4 Keycloakの開発ポリシー  フィーチャー・クリープを避ける  OpenID Connect / SAML のみにフォーカス  利用者が必要に応じて、機能拡張・カスタマイズ ができるようにしておく 50を超える拡張ポイントを用意
  6. 6. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 5 Keycloakの拡張機能  拡張ポイント 1. ログイン画面などのUI (テーマ) 2. スクリプトによる拡張 3. SPI (サービス・プロバイダー・インターフェイス) 実装による機能拡張 4. カスタムSPI の追加
  7. 7. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 6 1. テーマ  種類  Account: アカウント管理  Admin: 管理コンソール  Email: 送信メール  Login: ログイン画面  Welcome: ウェルカムページ
  8. 8. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 7 テーマ例 (出所) https://developers.redhat.com https://velocityfrequentflyer.com/ https://login.dbschenker.com
  9. 9. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 8 テーマの開発  $KEYCLOAK_HOME/themes/<テーマ名>/<テー マ種類> ディレクトリを作成  上記ディレクトリ内に各種リソースを格納する  管理コンソールより、適用したいレルムのテーマ設 定で切り替える
  10. 10. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 9 テーマの開発  開発時はテーマキャッシュを無効にするとよい  テーマ修正 → ブラウザリロードで即反映されるようになる  $KEYCLOAK_HOME/standalone/configuration/standalone.x ml のtheme設定を変更する
  11. 11. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 10 テーマのデプロイ方式  2方式  展開方式  アーカイブ方式  展開方式  $KEYCLOAK_HOME/themes ディレクトリ以下にリソースを配置  アーカイブ方式  リソースをJARファイルにまとめて $KEYCLOAK_HOME/standalone/deployments/ 以下にデプロイ  META-INF/keycloak-themes.json の作成が別途必要
  12. 12. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 11 2. スクリプトによる拡張  管理コンソールからJavaScriptコードを設定  以下の3つが利用可能  ScriptBasedAuthenticator ▪認証処理のカスタマイズ  ScriptBasedMapper ▪SAML利用時のマッパー処理のカスタマイズ ▪SAMLResponseに含めるAttributeをコードで処理できる  ScriptBasedOIDCProtocolMapper ▪OIDC利用時のマッパー処理のカスタマイズ ▪ID TokenのClaim設定をコードで処理できる
  13. 13. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 12 JavaScriptコードの設定  管理コンソールにて簡易エディタでコードを記述  Nashornで動作するため、 Java.type("・・・") で Javaのクラスにアクセス可能
  14. 14. 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で返す
  15. 15. 各種SPIのインターフェ イス定義、メタデータ定 義 (Internalかどうかなど) SPI拡張する人は ここだけを作って いけばOK
  16. 16. 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. デプロイ
  17. 17. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 16 提供されるSPIの例  Authenticator  RequiredActionProvider  ClientAuthenticator  FormAction  RealmResourceProvider  SocialIdentityProviderFactory  JpaEntityProvider  EventListenerProvider  UserStorageProvider  ProtocolMapper  LoginFormsProvider  LoginProtocol  ・・・
  18. 18. 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
  19. 19. 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 にモジュールをロードするための設定を追記 ▪ホットデプロイ未対応
  20. 20. 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を作るときはこちらを使う
  21. 21. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 21 SPI Info  管理コンソールのServer Info 画面より、SPIの種類・ロードさ れているProviderを確認でき る  デプロイしたカスタムの Provider実装も表示される  付けたProvider IDで表示
  22. 22. 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
  23. 23. 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
  24. 24. 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
  25. 25. 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のデフォルト実装を参考にする と よい
  26. 26. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 26 拡張事例の紹介
  27. 27. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 27 拡張事例  初級編  動的にログイン画面の表示を制御したい  中級編  「○○でログイン」に対応したい  上級編  ○○ ADのように、SSO時にサービス利用権限がないユーザーは エラーとしたい
  28. 28. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 28 初級編
  29. 29. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 29 初級編 動的にログイン画面の表示を制御したい  よくある背景  Identity Brokeringを使って複数の外部IdPから認証可能にしてい るが、UX向上のためアクセス経路に応じて、利用可能なIdPに絞っ て表示としたい  環境変数の値に応じて表示を切り替えたい (STG / PROD) 社内LANからアクセス時 インターネットでアクセス時
  30. 30. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 30 初級編 動的にログイン画面の表示を制御したい  標準機能  ThemeでHTMLのカスタマイズは可能なものの、環境変数やリクエ スト情報をFreeMarkerテンプレート内で参照できない
  31. 31. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 31 初級編 動的にログイン画面の表示を制御したい  対応方法  ログイン画面のテンプレート処理は、LoginFormsProvider のSPI実 装にて行われている  このデフォルトSPI実装である FreeMarkerLoginFormsProvider を独自クラスのProviderに切り替える ▪オリジナルを継承して作ると作成コード量はかなり抑えられる  独自クラス内で、参照させたいオブジェクトをバインド
  32. 32. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 32 Providerの切り替え方法  $KEYCLOAK_HOME/standalone/deployment s/standalone(-ha).xml にて デフォルトプロバイ ダーを切り替える  もしくは、上級編で紹介する同名Provider ID上書き方式で切り替え るのも可
  33. 33. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 33 中級編
  34. 34. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 34 中級編 「○○でログイン」に対応したい  よくある背景  KeycloakのSocial Loginで用意されていない外部IdPを使って、 Keycloakにログインできるようにしたい ▪LINEで認証 ▪Login with Amazonで認証 ▪Discordで認証 ▪・・・
  35. 35. 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.
  36. 36. 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
  37. 37. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 37 上級編
  38. 38. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 38 上級編 ○○ ADのように、SSO時にサービス利用権限がないユーザーはエラーとしたい  よくある背景  特定のグループやロールに所属しているユーザーにのみ、あるアプ リケーションの利用(SSOによるアクセス)を許可したい  ○○ AD だと「条件付きアクセスによるアクセス制御」で、様々な条 件を元に動的にアクセス制御が可能になっている  同じことをKeycloakでもやりたい!
  39. 39. 特定グループ所属ユーザーの場合 特定グループに所属していないユーザーの場合
  40. 40. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 40 上級編 ○○ ADのように、SSO時にサービス利用権限がないユーザーはエラーとしたい  標準機能  過去にメーリングリストで、細かくアクセス制御したい場合は Keycloakの認可機能を使いましょう、と回答されていた (記憶が正しければ...  しかし、認可機能はクライアントアプリケーション(=RPやSP) 側で KeycloakのAPIをコールしてアクセスコントロールしないといけない はず  つまり、アプリケーション側に手が入る  連携先がSaaSとかの場合どうするの? という問題が・・・
  41. 41. 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 を拡張して実装する
  42. 42. 例えば、abcdefg グループ所属 ユーザーを許可する設定を書く ProtocolMapper SPIとして作成 すると標準の管理画面の Mapper定義で設定可能になる
  43. 43. クライアントに設定されたアク セスコントロール用の Protocol Mapperを集める 集めたMapperでユーザーの 権限チェックを実施 NG一つでもあれば、 Forbiddenページへ遷移 認証成功時にコールバックされるメソッドをオー バーライドしてアクセス制御処理を追加 Forbiddenページ追加のため に、拡張したLoginFormsProvi derを使って画面遷移
  44. 44. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 44 LoginProtocolの入れ替え方法  初級編で紹介したLoginFormsProviderと異なり、 LoginProtocolにはデフォルトプロバイダーはない  SAMLの場合、 “saml” というProvider IDで登録 されており、この名前をハードコードで指定してプロ バイダーが利用されている  この場合、standalone(-ha).xml で上書くことがで きない!  このファイルでは、Provider IDの指定なしで要求されたときに返す デフォルトプロバイダーを設定することしかできない
  45. 45. 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
  46. 46. 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.
  47. 47. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 47 まとめ
  48. 48. Copyright(C) Nomura Research Institute, Ltd. All rights reserved. 48 まとめ  多くの拡張ポイントが用意されている  コアのソースに手を入れずに、機能拡張が可能  GitHubでたくさん公開されているサンプルコード をまずは参考にするとよい  マイナーなSPIの拡張方法を学ぶには、 デフォルト実装のソースを読むのが近道  ビルトインProviderの上書き方法は今後変わるか もしれないので注意してください

×