Keycloakハンズオン

Keycloak は、認証と認可を簡単に管理できるオープンソースの ID およびアクセス管理ツールです。シングルサインオン（SSO）を提供し、ユーザーが一度ログインするだけで、複数のアプリケーションにアクセスできるようにします。Keycloak は、ユーザー管理、ロールベースのアクセス制御、ソーシャルログイン（Google や Facebook など）をサポートしています。

Keycloak の主な用途は、ユーザー認証の簡素化とアプリケーションのセキュリティ向上です。シングルサインオンを使うことで、ユーザーエクスペリエンスを向上させ、管理者は安全かつ効率的にユーザー管理を行えます。また、外部の ID プロバイダーとの連携や API によるカスタマイズも容易で、さまざまなアプリケーションに柔軟に対応できます。

公式リンク

• 公式サイト Keycloak に関する基本的な情報やダウンロードリンク、最新の更新情報が掲載されています。

• GitHub リポジトリ

セットアップ方法

1. インストール

Docker を使用したセットアップ

Keycloak を簡単にセットアップする方法の一つとして、Docker を使用する方法があります。この方法では、Docker イメージを利用して Keycloak をコンテナとして起動します。以下の手順でセットアップを行います。

1. Docker のインストール

   • Docker がインストールされていない場合は、公式サイトの手順に従ってインストールします。
     • Docker 公式インストールガイド

2. Keycloak コンテナの起動

   • 以下のコマンドを使用して、Keycloak の公式 Docker イメージを取得し、コンテナを起動します。

   docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

   • -p 8080:8080: ホストのポート 8080 をコンテナのポート 8080 にマッピングします。
   • -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin: 管理者ユーザー名とパスワードを設定します（必要に応じて変更可能です）。
   • quay.io/keycloak/keycloak:latest: 最新の Keycloak イメージを使用します。
   • start-dev: 開発モードで Keycloak を起動します。

3. コンテナの確認

   • コマンドが成功すると、Keycloak はポート 8080 で実行されます。ブラウザで http://localhost:8080 にアクセスして、Keycloak の管理コンソールにアクセスできます。

バイナリからのセットアップ

※バイナリからのセットアップについては省略します。

2. 初期設定手順

管理コンソールへのアクセス

Keycloak のインストールが完了したら、次に管理コンソールにアクセスして初期設定を行います。以下に管理コンソールへのアクセス手順を示します。

1. 管理コンソールへのログイン

   • ブラウザを開き、Keycloak の管理コンソールにアクセスします。
     • URL: http://localhost:8080
   • 表示されるログイン画面で、インストール時に設定した管理者ユーザー名とパスワードを使用してログインします（例: admin / admin）。

2. 初期設定ウィザードの確認

   • ログイン後、最初に表示される管理画面で基本的な設定を確認・変更します。
   • Realm の設定: Keycloak では、ユーザー、クライアント、ロールなどをグループ化する単位として「Realm」を使用します。デフォルトの「Master Realm」以外に、必要に応じて新しい Realm を作成します。

3. 管理コンソールの概要

   • Keycloak の管理コンソールでは、ユーザー管理、クライアント設定、ロールの割り当てなどの操作を行うことができます。画面左側のメニューから各種設定にアクセスし、環境に合わせた初期設定を行います。

以上で Keycloak の基本セットアップと初期設定の手順が完了です。コンソールを使って必要なユーザーやクライアントの設定を行い、シングルサインオンなどの機能を利用できるようになります。

基本設定

Keycloak の基本設定には、Realm の作成、クライアント設定、ユーザー管理、ロールやグループの設定があります。以下では、それぞれの登場人物と関係性を図式化しながら説明します。

1. Realm の作成と管理

Realm は、Keycloak の中でユーザーやクライアントをまとめて管理するための単位です。システム全体を分割して管理したい場合、異なるプロジェクトや環境ごとに Realm を作成します。

[Realm A] - [ユーザー、クライアント、ロール、グループ]
[Realm B] - [ユーザー、クライアント、ロール、グループ]

• Realm A と Realm B は、互いに独立した空間です。各 Realm 内で設定やユーザーは隔離されています。

2. クライアント設定

クライアントは、Keycloak に認証を依頼する外部のアプリケーションやサービスです。クライアント設定を行うことで、特定のアプリケーションに対する認証や認可を管理できます。

[Realm]
  └── [クライアント1] - [OpenID Connectの設定]
  └── [クライアント2] - [SAMLの設定]

• クライアント 1、クライアント 2 は、それぞれ異なるプロトコル（OpenID Connect や SAML）を使用して認証を行います。

3. ユーザーの作成と管理

ユーザーは、Keycloak を通じて認証される個々の利用者です。ユーザーごとに、認証情報（ID とパスワード）や属性（氏名、メールアドレスなど）を管理します。

[Realm]
  └── [ユーザー1] - [属性、認証情報]
  └── [ユーザー2] - [属性、認証情報]

• ユーザー 1 とユーザー 2 は、それぞれ個別に管理され、異なる属性や認証情報を持ちます。

4. ロールとグループの設定

ロールは、ユーザーに対するアクセス権限を表すもので、グループは複数のユーザーをまとめたものです。ユーザーにロールを割り当てることで、アクセスできるリソースを制御します。

[グループA]
  ├── [ユーザー1]
  ├── [ユーザー2]

[ロールX] - [特定のアクセス権限]
  └── [ユーザー1]

• グループ A には複数のユーザーが所属し、まとめて管理が可能です。
• ロール X は特定のアクセス権限を表し、ユーザー 1 に割り当てられています。

認証

• この記事を参考に認証について整理します。

ビルトイン認証フロー

Keycloak の認証フローは、ユーザーがどのように認証されるかを定義するプロセスです。認証フローには複数のステップがあり、それぞれのステップでユーザーに対する認証方法や条件が決定されます。認証フローはカスタマイズ可能で、アプリケーションのニーズに合わせた柔軟な認証を実現できます。

Keycloak にはデフォルトでいくつかのビルトイン認証フローが含まれています。

• Browser flow

  • ブラウザベースの認証フローで、ユーザーがブラウザを使用して認証する際に使用されます。このフローでは、ユーザー名とパスワードの入力、2 要素認証、利用規約の同意など、様々な認証手段が統合されています。一般的な Web アプリケーションのログインに使われます。

• Client authentication flow

  • クライアント（アプリケーション）が Keycloak サーバーに対して認証する際に使用されるフローです。これはクライアントシークレットやクライアント証明書を使って、クライアント自身の認証を行うためのもので、OAuth 2.0 のクライアント認証に対応しています。

• Direct grant flow

  • リソースオーナーのパスワード認証フロー（Resource Owner Password Credentials Grant）を用いる場合に使用されます。ユーザーが直接ユーザー名とパスワードを提供し、トークンを取得するためのフローです。ブラウザを介さないバックエンドのシステムやシンプルなスクリプトからの認証に利用されます。

• Docker authentication flow

  • Docker クライアントが Keycloak を ID プロバイダーとして認証するために使用するフローです。このフローを使用することで、Docker CLI を使ってプライベートな Docker レジストリにアクセスする際に Keycloak の認証を利用できます。

• First broker login flow

  • 外部のアイデンティティプロバイダー（例えば Google や Facebook）からの認証を初めて行った場合に使用されるフローです。このフローでは、外部アカウントがまだ Keycloak のユーザーアカウントにリンクされていない場合に、ユーザーに必要なアクション（アカウントのリンクや追加情報の入力など）を要求します。

• Registration flow

  • 新規ユーザー登録のためのフローです。ユーザーが Keycloak に対して新しいアカウントを作成する際に、このフローが使用され、ユーザー名、パスワード、メールアドレスなどの入力を受け付けます。必要に応じて追加の検証（例えば、メール確認や CAPTCHA など）を含むこともできます。

• Reset credentials flow

  • ユーザーがパスワードなどの資格情報を忘れた場合に、それをリセットするためのフローです。ユーザーはメールによるリンクやセキュリティの質問などを使って、新しい資格情報を設定することができます。

認証フロー設定

例えば、ビルトイン認証フローである「Browser flow」は以下のようになっています。

フローの各ステップは以下のようになっています。

認証タイプ	ネスト 1	ネスト 2	認証内容	概要
Cookie	-	-	認証クッキー認証	認証クッキー内容が有効であることをチェックします。
Kerberos	-	-	Kerberos 認証	Kerberos Distribution Center（KDC）で認証されたユーザかどうかチェックします。
Identity Provider Redirector	-	-	外部 IDP 認証	外部の IDP や SNS など第３者認証情報を利用して、SAML や OpenID Connect による認証を行います。
Forms	-	-	フォーム認証	フォーム入力による認証が使用されます。内容はネストされた認証タイプに依存します。
->	Username Password Form	-	(右記)	フォーム入力された ID とパスワードをチェックします。
->	Browser - Conditional OTP	-	(右記)	ユーザが設定された OTP クレデンシャルを持っているかチェックします。
->	->	Condition -user configured	(右記)	Keycloak がユーザに対してフロー内の他のエグゼキューションを設定しているかチェックします。
->	->	OTP Form	(右記)	フォーム入力されたワンタイムパスワードをチェックします。

実行後の動作を決定する「必要条件」が設定可能です。

Requirement	意味	概要	実行後の結果
Alternative	代替	選択された「認証タイプ」が次以降の「認証タイプ」の代替をします。	成功すると、次の「認証タイプ」に進むことなく、認証成功となります。失敗すると、次の「認証タイプ」に進みます。
Required	必須	選択された「認証タイプ」の成功が必要になります。	成功すると、次の「認証タイプ」に進みます。失敗すると、次の「認証タイプ」に進むことなく、認証失敗となります。
Conditional	条件付き	選択された「認証タイプ」はユーザ設定とその条件の可否により実行されます。	このタイプはサブフローがある場合のみ設定され、Conditional のサブフローの評価の結果によって、Required か Disabled として動作するかが決まります。（※）
Disabled	無効	選択された「認証タイプ」が無効になります。	実行されません。

以上より、「Browser flow」を図示すると以下のようになります。

設定例： WebAuthn

以下のドキュメントを参照し、WebAuthn に関する設定を行なっていきます。

https://www.keycloak.org/docs/latest/server_admin/#webauthn_server_administration_guide

こちらも参考になります

Configure > Authenticationは以下の通り

• Cookie はひとまず無効
• Kerberos は利用しないので無効
• 外部 ID も利用しないので無効
• Forms は利用する
  • Username Form は必須
  • WebAuthnPasswordless Authenticator も必須

ユーザ自身に登録を行わせたいため、User registration を On にしておきます。

また、ユーザー登録時に認証器の設定も行わせたいため Webauthn Register Passwordless を default action に設定します。