初めまして、7月にAstamuseにjoinしました、植木です。
ICPのエンジニアを担当しております。
私は、普段なら桜が咲いて楽しみが増える季節ですが、コロナの影響もあり外出を控えないといけないと思うと残念で仕方がない今日この頃でございます。
はじめに
今回は、Keycloakについて紹介する記事です。
弊社のICPで導入に向けて作業を進めており、非常に便利でしたので筆をとるに至りました!
下記のような方は是非見ていただいて、参考にしていただけると幸いです。
- Keycloakを知らない方
- ざっくり概要を知りたい方
- 導入を検討する方
概要
Keycloakとは、 OpenID / SAML の認証方式を用いて、「認証」「認可」を行うことができるOSS のミドルウェアです。 安全性をKeycloakが管理を担ってくれるため、アプリケーションはユーザーアクセス管理を意識することから解放され、余計な処理が不要になるため、コードがシンプルになります。 その他、シングルサインオン(1アカウントで複数のアプリケーションへのログイン)、ソーシャルログイン(FacebookやGoogle+などの、外部のIdPを使用してのログイン)にも対応しており、既存のアプリケーションにも容易に導入できます。
ICPで導入に至った経緯
機能開発や新規のプランごとに、ユーザや所属する組織に対する権限情報が増え行くことは、火を見るよりも明らかであると言えるでしょう。
例えば、API開発であれば、一般ユーザーAさんがアクセスできるエンドポイントは参照権限のみで、管理者ユーザーのBさんは参照加えて、作成/更新/削除も可能にする、といったような仕様を常に心に止めて開発する必要があります。
ICPでも同じ悩みを抱えており、1. (既存もしくは新規に)認証/認可サーバを作成する, 2. 認証/認可ミドルウェアを使用することを検討し、結論としては2を選択しました。
1に関してはSilhouette(シルエットと読みます)というライブラリを検討し、見送りました。理由は、SilhouetteはPlay Frameworkをベースとしており、リクエストが届いた際にエントリポイント単位で、認証ロジックを挟むといった形になっているため、Play Framework以外での実装となっているアプリケーションは対応できなかったためです。
起動方法
まずはローカル環境で試したいという方には、jboss/keycloakのdockerを用いて起動するが手軽でおすすめです。後の解説ではこれを使用します
# 例:最初の管理者ユーザを id=admin, password=adminで作成する場合。今回は8888ポートにしました。 $ docker run --rm --name keycloak -p 8888:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin jboss/keycloak
直接サーバで動作させる場合は、tarボールをダウンロードしてきて、./standalone.sh
を実行します。
Keycloak - Downloads
Keycloakの管理ページ、設定項目について
http://localhost:8888/にアクセスすると、KeycloakのWelcomeページをはじめに確認できます。 「Administration Console」から、管理者ユーザでログイン(今回の例ではadmin/admin)すると管理者用ページが現れ、下記のようなメニューがあることが確認できます。
1. Realm Settings
Realmというのはプロジェクトのワークスペースのようなものです。Masterというのがはじめに作成されています。ユーザのログイン方法やテーマのなどの設定ができます2. Clients
Keycloakへアクセスするクライアント(アプリケーション)の設定を行います。3. Roles
権限の名前がRoleになります。このMapping(RoleとGroups/Usersを組み合わせる)設定することで、権限制御ができます RealmにおけるRoleを設定できます。先ほどの2.ClientsでもRole設定があり、スコープが少し違います4. Groups
ユーザーをひとまとまりにする単位です5. Users
ユーザーの管理を行います
アプリケーション(Clients)の管理方法
Keycloakがアプリケーションの管理する方法として、大きく分類して2つの方法があります。
アプリケーションにKeycloak用のライブラリを組み込むクライアントアダプター
パターンと、
Keycloak Gatekeeperを使用するクライアントプロキシ
パターンがあります。
クライアントアダプター
パターンの、詳しい設定内容についてはこちらがわかりやすいです。
www.atmarkit.co.jp
クライアントプロキシパターンには、リバースプロキシ(Apache、Nginx)にOpenID Connectのモジュールを組み込む方法もあります
Keycloakで実用的なリバースプロキシ型構成を構築してみよう (1/4):Keycloak超入門(7) - @ITwww.atmarkit.co.jp
ICPでは、
- クライアントアダプターの場合は、対応されていないアダブターを自作する必要があることがわかったため(ICPの場合は、Play Framework用)
- クライアントプロキシパターン(Nginx)の場合は、Nginx Plus(有償)である必要がある
- クライアントプロキシパターン(Apache)の場合は、NginxからApacheへの切り替えコストがかかる といった理由から、Keycloak Gatekeeperを選びました。Keycloak Gatekeeperはマイクロサービスを意識してシングルバイナリで動作し、Dockerコンテナ内で動かすことも想定して設計されていると感じており、期待の意味も込めて、クライアントプロキシ(Keycloak Gatekeeper)を選択しました。
この記事では、以降、Keycloak Gatekeeperを中心に書いていきます。
Keycloak Gatekeeperを用いてクライアントプロキシを試してみよう
Keycloakを用いる場合ユーザーはKeycloakで用意しているのログインページを使用するようになります。
Keycloak Gatekeeperのバックエンドにアプリケーションが配置されるようにし、認証/認可を判断したものだけがアプリケーションへ到達できるようなハンズオンをやってみましょう。
下記に、ハンズオンのために必要最低限の設定を書いたdocker-composeを用意しました。Mac OSでのみで動作します(Docker for Mac向けのhost.docker.internalを使用しているため)
github.com
下記を打つとWordPress、Keycloak、Keycloak Gatekeeperが起動します。 ※ 今回はWordPressへ到達までが目的なので、DBの設定などは入れていません
$ docker-compose up
WordPressは読者の認証認可を想定するアプリケーションに読み替えていただけるとわかりやすいと思います
次に、テストユーザを追加しましょう パスワードの初期値を適当に決め、設定します。
設定ができたら、Keycloak Gatekeeperのアドレスhttp://localhost:3000/へアクセスしてみましょう。初回なので、ログインページへリダイレクトされることが確認できます。
先ほど登録したユーザでログインしてみると、OIDC認証されWordPressのページ http://host.docker.internal:8880/ へリダイレクトされてきたことが確認できたと思います。
このような手軽さから、既存のアプリケーションに対して使用する場合でも、プロキシパスをKeycloak Gatekeeper経由に変更さえすれば、認証を担ってくれることがメリットと言えます。
テーマについて
今回試したログインの際、テーマはKeycloakのデフォルトでしたが、Freemakerで作成したテーマを配置すれば、切り替えが可能です。
テーマはログインテーマだけでなく、アカウント管理、管理コンソール、電子メール、ウェルカムページのカスタマイズが可能です
新規に配置する際にはすぐに反映されるのですが、更新の場合はデフォルトでテーマファイルのキャッシュが効いているため、注意が必要です。
テーマに関しては、下記が参考になりました。
keycloak-documentation.openstandia.jp
qiita.com
認証後の付与情報について
Keycloak Gatekeeperを通過しアプリケーションへ向かう際に、X-Auth系のヘッダが付与されるため、アプリケーションレベルでユーザを扱うことができるようにするため、Username(ログイン時のID), Email, 姓名などKeycloakで設定したユーザ情報が送られるようになっています。
また、上記以外にも、独自で定義したフィールドに値を詰めて渡すといったこともできるため自由度は高いと言えるでしょう。
最後に
ここまで読んでみていかがでしたでしょうか?
Keycloakは多機能で、今回紹介できた部分はほんの一握りでしたが、ざっくり分かっていただけていたら幸いです。
弊社では上記のように OSS を使って問題解決が開発がしたいエンジニアや、デザイナー、プロダクトマネージャーなど絶賛大募集中です。少しでもご興味を持っていただけたら、お気軽にカジュアルランチからでも構いませんので、下のバナーや @yoshixmk へ DM 等でご連絡いただければと思います。