Contents
Keycloak認証フローの概要と選定基準
Keycloakを活用するにあたって、まずはOAuth2/OpenID Connectのフロー理解が不可欠です。認可コードフローやパスワードフローといった選択肢があり、ユースケースによって適切な方法が異なります。本セクションでは、これらのフローの動作原理と選び方を解説します。
OAuth2/OpenID Connectフローの基本動作
OAuth2は認可プロトコルとして設計され、OpenID Connect（OIDC）は認証プロトコルです。双方を組み合わせることで、外部サービスへのアクセス権付与とユーザー認証が可能です。
- 認可コードフロー：セキュリティ性が高く、主にフロントエンドアプリケーション向け
- パスワードフロー：シンプルだがセキュリティリスクがあるため、信頼できる内部システムでのみ使用推奨
以下は主なフローの比較表です。
| フロー名 | 用途 | セキュリティ性 | ユーザーインターフェース |
|---|---|---|---|
| 認可コードフロー | SPAやモバイルアプリ | 高 | ブラウザでの認証 |
| パスワードフロー | 内部ツール・管理画面 | 中 | ユーザーIDとパスワード入力 |
認可コードフローとパスワードフローの比較
認可コードフローでは、クライアントアプリケーションがユーザーに認証を依頼し、Keycloakから一時的なコードを取得します。このコードを使って最終的なアクセストークンを発行するため、第三者への機密情報漏洩リスクを最小限に抑えられます。一方、パスワードフローではユーザーIDとパスワードがアプリケーションに直接送信されるため、セキュリティ面で慎重な設計が必要です。
重要ポイント： 認可コードフローは現代のWebアプリケーションで主流ですが、単純な内部ツールであればパスワードフローも選択肢になります。
Keycloakサーバーの導入とアダプター設定
Keycloakを本格的に利用するには、まずサーバーの導入手順を理解し、クライアントアプリケーションとの連携設定を行う必要があります。Dockerや公式パッケージを使って簡単にインストールできますが、 Realmの作成やクライアント登録といった手順が不可欠です。
Keycloakのインストール手順
KeycloakはDockerイメージで簡単に導入可能です。以下に基本的な手順を示します。
- Docker HubからImage取得：
docker pull quay.io/keycloak/keycloak:latestを実行して最新バージョンを入手します。 - 起動設定の作成：
docker run -d -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=[適切なパスワード] quay.io/keycloak/keycloak:latestでコンテナを起動し、初期アカウントを作成します。 - ブラウザからアクセス：http://localhost:8080/authにアクセスしてKeycloak管理画面を開きます。
クライアントアプリケーションとの連携設定
クライアントアプリケーション（例: Webアプリ）と接続するには、Realmの作成およびクライアント登録が必要です。
- Realm作成：管理画面上「Add Realm」より任意の名前で新規作成します。
- クライアント登録：Realm内へ「Add Client」を選択し、クライアントIDやリダイレクトURIを設定します（例:
http://localhost:8081/callback）。
注意事項： リダイレクトURIはアプリケーションが実行されるURLと一致させる必要があります。誤った設定では認証フローが正常に動作しません。
Spring BootでのKeycloak認証フロー実装
Spring BootアプリケーションでKeycloakを導入するには、spring-security-oauth2-resource-serverライブラリとKeycloakアダプターを使用します。ここでは具体的な手順とコードサンプルを通じて実装方法を解説します。
Spring Securityとの統合方法
Spring SecurityはOAuth2リソースサーバーとして動作し、Keycloakのトークン検証を行います。導入に必要なライブラリは以下です。
implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'implementation 'org.keycloak:keycloak-spring-security-adapters:21.0.3'（最新バージョンを確認すること）
コードサンプル（認可コードフロー）
以下の手順でSpring Bootアプリケーションに認証を組み込みます。
-
application.ymlの設定：KeycloakのクライアントIDやRealm名を指定します。
yaml
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: http://localhost:8080/auth/realms/my-realm -
セキュリティ設定の追加：
SecurityFilterChainでアクセス制限を設定します。
java
@Configuration
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
return http
.authorizeHttpRequests(authz -> authz
.anyRequest().authenticated())
.oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt)
.build();
}
}
実装のポイント： リソースサーバーとして設定することで、Keycloakから取得したトークンで認証が可能になります。
Node.jsでのKeycloak認証フロー実装
Node.js環境ではpassport.jsライブラリを使用してOIDC（OpenID Connect）をサポートできます。以下にパスワードフローの実装例を示します。
Passport.jsによる OIDC サポート
Passport.jsは認証中間層として非常に柔軟性を持ち、Keycloakとの連携も簡単です。導入に必要なパッケージはpassportとpassport-openidconnectです。
|
1 2 |
npm install passport passport-openidconnect |
コードサンプル（パスワードフロー）
以下のようにExpressアプリケーションで認証を実装できます。
- 認証用のルート設定：Keycloakと連携するため、リダイレクトURIを事前に登録します。
javascript
const passport = require('passport');
const OpenIDConnectStrategy = require('passport-openidconnect').Strategy;
passport.use(new OpenIDConnectStrategy({
issuer: 'http://localhost:8080/auth/realms/my-realm',
clientID: 'my-client',
clientSecret: 'secret',
callbackURL: 'http://localhost:3000/callback'
}, (issuer, profile, done) => {
// ユーザー情報を処理するロジックを実装
return done(null, profile);
}));
- 認証後の処理：ユーザーが認証後、アプリケーション内でのセッション管理を行う必要があります。
注意事項： パスワードフローではユーザーIDとパスワードをアプリケーション内に直接送信するため、リソースサーバーの設定は必須ではありませんが、通信経路の暗号化（HTTPS）を徹底してください。
セキュリティベストプラクティスとトークン管理
Keycloak認証フローでは、トークンの有効期限やリフレッシュトークンの取り扱いに注意が必要です。適切な管理を行うことで、セキュリティリスクを最小限に抑えられます。
トークン有効期限の最適化
アクセストークンとリフレッシュトークンは、それぞれ独立したライフサイクルを持っています。以下がおすすめ設定です。
- アクセストークン: 15分～30分（短時間のアクセスに適する）
- リフレッシュトークン: 7日～14日（セッションの継続性を確保する）
セキュリティベストプラクティス： リフレッシュトークンはクライアントアプリケーション内に保存せず、バックエンドサーバーで管理することが望ましいです。例として、データベースに暗号化して保存し、定期的なローテーションを実施します。
リフレッシュトークンの安全な取り扱い
リフレッシュトークンを使用する場合は以下のように注意すべき点があります。
- セキュリティのため： トーケンを暗号化して保存し、不正アクセスに備える
- 有効期限設定： リフレッシュトークンにもライフタイムを設定し、長期的な保持を防ぐ
- ロギング対策： セキュリティイベント（例: トーケンの再発行）を監視・記録する
重要： リフレッシュトークンが漏洩した場合、悪意のある第三者がアクセス権を取得する可能性があるため、適切な管理が不可欠です。
実装サンプルの試してみる
本記事で紹介したSpring BootやNode.jsの実装例はGitHub上に公開しています。読者自身が環境構築・実装を行うための手順を記載します。
Spring Boot/Node.jsプロジェクトのダウンロード方法
以下のリンクよりプロジェクトを取得できます（※サンプルコード）。
- Spring Bootサンプルコード
- Node.jsサンプルコード
動作確認手順
- Docker環境でKeycloakを起動：上記の導入手順に従ってKeycloakサーバーを構築します。
- プロジェクトをクローンして実行：
git clone https://github.com/keycloak-samples/springboot.gitなど、好きな言語のプロジェクトを選択し、npm run devや./gradlew bootRunで起動します。 - ブラウザでアクセス確認：
http://localhost:8081にアクセスして、Keycloakによる認証フローが動作するか確認してください。
CTA（行動喚起）： 記載したコードを試してみてください！実装サンプルを通じてKeycloakの理解が深まります。