Contents
KeycloakによるSSO環境構築の概要
Keycloakは、OpenID ConnectとSAMLをサポートするオープンソースのアイデンティティプロバイダとして注目されています。本記事では、KeycloakによるSSO設定方法をステップバイステップで解説し、初心者でも理解できるように具体的手順と注意点を提示します。特に、認証フローの設定やトラブルシューティングが重点になります。
Keycloakのインストール手順
Keycloakの導入にはDockerまたはLinux環境での手動インストールが主な方法です。どちらもJava 17以上の実装環境を前提としています。
Dockerによるインストール
Dockerを使用すると、迅速かつ簡単にKeycloakを起動できます。以下は基本的なコマンド例です。
⚠️ 注意: 初期パスワード
adminはセキュリティリスクが高いため、導入直後に変更してください。
-
Dockerイメージの取得
bash
docker pull quay.io/keycloak/keycloak:latest -
コンテナの起動（初期パスワードは
admin）
bash
docker run -d -p 8080:8080 --name keycloak \
-e KEYCLOAK_ADMIN=admin \
quay.io/keycloak/keycloak:latest -
管理画面へのアクセス
http://localhost:8080/ を開き、初期アカウント（admin）でログインします。
Linux環境での手動インストール
手動インストールでは、Keycloakを公式サイトからダウンロードし、WildFlyサーバー上で実行します。
-
Java環境の確認
Java 17以上が必須です。java -versionで確認してください。 -
ダウンロードと解凍
bash
wget https://github.com/keycloak/keycloak/releases/download/23.0.5/keycloak-23.0.5.tar.gz
tar -xzf keycloak-23.0.5.tar.gz
cd keycloak-23.0.5/bin -
起動コマンドの実行
bash
./standalone.sh
ブラウザで http://localhost:8080 にアクセスし、初期設定を行います。
🔍 注意: Keycloakバージョン23.0.5は最新版ではありません。公式サイト（https://www.keycloak.org/downloads）で最新バージョンを確認してください。
Realmの作成プロセス
RealmはKeycloak内のロールやユーザー属性を管理する仮想ドメインです。以下に手順を示します。
初期設定項目の確認
- 管理画面にログインして「Add Realm」を選択し、適切な名称（例：
my-realm）を入力します。 - ロールの作成
- 「Roles」タブから「Create Role」で管理者用・ユーザー用など、用途に応じたロールを作成します。
カスタム設定の追加
ユーザー属性をカスタマイズする場合は、「User Federation」の設定を調整します。以下は代表的な例です。
| 設定項目 | 必須か | 補足 |
|---|---|---|
| Realm名 | ✔️ | 複数のRealmを作成できます |
| ロール | ✔️ | 管理者権限やアプリケーションごとのアクセス制御に使用します |
| ユーザー属性 | ✖️ | 必須ではないが、カスタムフィールドを追加可能です |
🔍 初心者向けガイド: ユーザー属性のカスタマイズは「Users > Attributes」タブで実行できます。ここに
custom-attributeなどのフィールド名を追加し、型や説明を指定してください。
クライアントアプリとの連携方法
クライアントアプリケーション（WebサービスやAPI）をKeycloakと連携するには、認証フローの設定が不可欠です。
クライアント登録手順
- 「Clients」タブから「Create」をクリックし、クライアントID（例：
my-app）を入力します。 - Redirect URIの設定例:
http://localhost:3000/callback - リダイレクトURIはアプリケーションのコールバックURLと一致させる必要があります。
OAuth 2.0設定の確認
- 「Access Type」で「confidential」を選択し、クライアントシークレットを生成します。
- Grant Typesには「Authorization Code」が通常使用されます。
⚠️ セキュリティベストプラクティス: Redirect URIはアプリケーション側で検証し、
https://の絶対URLを使用してください。また、http://localhost:3000/callback以外のURIを指定する場合は、信頼性のあるオリジンのみを許可するように設定してください。
認証フローの設定
Keycloakでは「Browser」や「Service Account Token」など、認証フローが選べます。
標準フローとの比較
| フロー種別 | 利点 | 限界 |
|---|---|---|
| Browser | ソーシャルログインやパスワード認証をサポート | API認証には不向き |
| Service Account Token | 補助的なAPI認証に適切 | ユーザーインターフェース向けではない |
カスタムフローの構築
- 「Authentication Flows」タブで「Duplicate」として新しいフローを作成します。
- Execution画面で「Required Action」や「User Attribute Check」を追加し、カスタマイズ可能です。
🔍 ツール活用: 「Flow Editor」で可視化しながら設定すると理解が深まります。
トラブルシューティング
Keycloakの導入時に発生する代表的なエラーとその解決策を以下にまとめます。
よくあるエラーメッセージ
| エラーコード | 原因 | 解決方法 |
|---|---|---|
| 401 Unauthorized | 認証トークンの有効期限切れ | リフレッシュトークンを再発行するか、セッションタイムアウト時間を調整 |
| 502 Bad Gateway | Keycloakサーバーとの通信エラー | サーバー起動状態やポート番号（8080）の確認 |
ログの確認手順
- 管理画面右上の「Logs」タブから、認証失敗などの詳細ログを確認できます。
- ファイルロギングも可能で、
standalone/log/server.logにアクセスしてください。
まとめと次ステップ
Keycloakインストール、Realm作成・カスタム設定、クライアントアプリとの連携、認証フローの構築、エラー対応とログ確認を通じてSSO環境を安定して構築できます。
🔁 次のステップ: 実際にKeycloakを導入し、アプリケーションに統合することで、実践的な理解が深まります。セキュリティ設定やカスタムフローの拡張にも挑戦してください。