Keycloak

Keycloak は、アプリの代わりにユーザーのログインを受け持つサーバーです。アプリごとにログイン画面やパスワードの保存を作らずに、認証を Keycloak に任せられます。

この記事は、認証の仕組みを手を動かして学びたい開発者や、社内のログインをまとめたい管理者に向けています。読み終えると、次のことができるようになります。

• 自分のパソコンで Keycloak を開発モードで起動する
• レルム、ユーザー、クライアントを作り、テスト用アプリでログインを試す
• 本番で使う前に、何を設定し直すべきかを知る

##Keycloak とは

Keycloak は Apache License 2.0 で公開されているオープンソースのソフトウェアです。CNCF（Cloud Native Computing Foundation）のプロジェクトで、2023 年 4 月 10 日に Incubating の段階で受け入れられています。

##Keycloak でできること

公式サイトは、主な機能として次のものを挙げています。

• シングルサインオン（SSO）：一度ログインすれば、Keycloak を使う別のアプリに入り直さずに済みます。ログアウトも一度で全アプリに効きます。
• 標準のプロトコル：OpenID Connect、OAuth 2.0、SAML 2.0 に対応しています。
• 外部の ID との連携：SNS アカウントでのログインや、既存の OpenID Connect・SAML 2.0 の ID プロバイダーとの連携を、管理コンソールの設定で追加できます。
• ユーザーフェデレーション：既存の LDAP や Active Directory につないで、そこにいるユーザーでログインできます。
• 管理コンソールとアカウントコンソール：管理者はユーザーやアプリを管理し、ユーザーは自分でプロフィールやパスワードを変えたり、二要素認証を設定したりできます。
• 細かい認可：ロールで足りないときは、ポリシーを定義してアクセス権を管理できます。

二要素認証の手段として、サーバー管理ガイドは認証アプリのワンタイムパスワード（OTP）とパスキー（WebAuthn）を説明しています。

##最低限の用語

サーバー管理ガイドの「Core concepts and terms」に沿って、よく出てくる言葉をまとめます。

最初からある master レルムは Keycloak 自体の管理用です。公式の手順は、アプリの管理には使わず、別のレルムを作るよう案内しています。

##安全な試し方：自分のパソコンで開発モードを動かす

公式の Getting started は、Docker 版と OpenJDK 版（zip を展開して動かす）を用意しています。ここでは Docker 版の流れを紹介します。試すのは自分のパソコンだけにしてください。

1. Docker を入れたパソコンで、次のコマンドを実行します。26.8.1 は記事を書いた時点の版です。最新の版は Getting started のページで確かめてください。

   docker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.8.1 start-dev

   127.0.0.1 を付けているので、自分のパソコンからしか接続できません。管理者のユーザー名とパスワードは両方 admin になります。練習用なので、このまま外に公開しないでください。

2. ブラウザーで http://localhost:8080/admin を開き、admin でログインします。

3. 左の列の Manage realms から Create realm を選び、myrealm という名前のレルムを作ります。

4. Users から Create new user を選び、myuser を作ります。Credentials でパスワードを設定し、Temporary をオフにします。

5. http://localhost:8080/realms/myrealm/account を開き、myuser でログインします。ここがユーザー用のアカウントコンソールです。

6. Clients から Create client を選び、Client type を OpenID Connect、Client ID を myclient にします。Valid redirect URIs に https://www.keycloak.org/app/*、Web origins に https://www.keycloak.org を入れて保存します。

7. 公式のテスト用アプリ https://www.keycloak.org/app/ を開き、Save を押してから Sign in を押します。自分の Keycloak のログイン画面が出れば、SSO の流れを試せています。

Docker を使わない場合は、OpenJDK 版の手順で zip を展開し、Linux なら bin/kc.sh start-dev、Windows なら bin\kc.bat start-dev で起動します。このとき管理者ユーザーは、初回に http://localhost:8080/ を開いて作ります。

##start-dev を本番に使わない理由

start-dev は開発モードです。公式ドキュメントによると、開発モードでは次の設定が既定になります。

• HTTP が有効になる
• ホスト名の厳密な確認がオフになる
• キャッシュがその 1 台だけになる（高可用性のための分散キャッシュを使わない）
• テーマとテンプレートのキャッシュがオフになる

本番モードは bin/kc.[sh|bat] start で起動します。本番モードは「secure by default」の考え方で、HTTP をオフにし、ホスト名と HTTPS/TLS の設定を求めます。設定がないと、わざとエラーを出して起動しません。

なお公式ドキュメントは、Windows Subsystem for Linux（WSL）で開発モードを動かすと、既定ですべてのネットワークアドレス（0.0.0.0）で待ち受けると注意しています。同じネットワークの別の機器から見える場合があるので、WSL で試すときは気をつけてください。

##動かすのに必要なもの

対応している版の細かい一覧は、サポートされる構成のページにあります。

##本番で守ること

公式の「Configuring Keycloak for production」は、次の点を挙げています。

• HTTPS を使う：Keycloak は機密データをやり取りするので、すべての通信を TLS で守ります。
• ホスト名を設定する：アプリから見える公開用のホスト名を決めます。
• 管理コンソールを外に出さない：管理用の REST API と管理コンソールは、ログイン画面とは別のホスト名やパスで出すのがよいとされています。公開しない API へのアクセスは、リバースプロキシの段階で止めます。
• リバースプロキシを置く：どのパスを公開し、どのパスを隠すかは「Configuring a reverse proxy」のガイドに書かれています。
• 本番向けのデータベースを使う：対応しているデータベースを設定します。
• 複数台で動かす：1 台が止まってもログインできるよう、2 台以上で動かすのが一般的です。

##セキュリティ更新の追い方

Keycloak の脆弱性情報は、GitHub リポジトリの Security Advisories に深刻度付きで載ります。新しい版の公開は公式サイトのブログ（News）でも告知されています。自分で動かしている場合は、この 2 つを定期的に見て、更新を当ててください。

脆弱性を見つけたときの報告先と手順は、セキュリティポリシーにあります。Keycloak 本体の脆弱性は、公開の Issue ではなく専用のメールアドレスに送るよう定められています。

##注意点

##次に読む

• cd ../zapZAP自分の Web アプリを診断するツール
• cd ../wazuhWazuhログを集めて監視するセキュリティ基盤
• cat ~/guides/lab-setup.md安全な検証環境の作り方