【連載 第8回】運用とトラブルシューティング：ログ解析と緊急対応

「ログインできない」という電話が鳴り止まない朝。あなたならどうする？

こんにちは！「LINUX工房」管理人の「リナックス先生」です。
全8回にわたるSSO構築連載、ついに最終回を迎えました。
これまでに、AlmaLinux 9上にDockerで基盤を作り、Keycloakを立ち上げ、AD連携、Webアプリ連携、そしてWindows統合認証までを実現し、セキュリティ対策も施しました。

しかし、システムは「構築して終わり」ではありません。
むしろ、運用が始まってからが本当の戦いです。

「画面が真っ白になって動かない」
「特定のユーザーだけログインできない」
「管理者のパスワードを忘れて締め出された」

こうしたトラブルに直面したとき、焦らず冷静に対処できるかどうかが、プロとアマチュアの分かれ目です。

最終回となる本記事では、Keycloak運用におけるトラブル解決フロー、ログ解析のテクニック、そして管理者ロックアウトなどの緊急事態への対処法を徹底解説します。

---

1. トラブルシューティングの基本「ログ解析」

トラブルが起きた時、闇雲に再起動したり設定を変えたりするのはご法度です。
必ず「ログ」を見て、何が起きているかを特定します。

1-1. コンテナログの確認コマンド

Docker環境では、以下のコマンドが基本中の基本です。

# Keycloakのログをリアルタイム表示（直近100行）
sudo docker compose logs -f --tail=100 keycloak

# 特定の時間帯のログを確認したい場合（grep検索）
sudo docker compose logs keycloak | grep "2026-02-05 10:00"

1-2. ログレベルの詳細化 (DEBUGモード)

デフォルトのログ（INFOレベル）では、「エラーが起きた」ことは分かっても「なぜ起きたか」が分からないことがあります。
一時的に詳細なログを出力するように設定を変更します。

docker-compose.yml の keycloak サービスの環境変数に以下を追加します。

    environment:
      # 全体のログレベルをDEBUGにする（大量に出るので注意）
      # KC_LOG_LEVEL: DEBUG
      
      # 特定のカテゴリ（例：LDAP連携）だけDEBUGにする（推奨）
      KC_LOG_LEVEL: INFO,org.keycloak.storage.ldap:DEBUG,org.keycloak.events:DEBUG

修正後、コンテナを再作成します。

sudo docker compose up -d

これで、LDAP連携時の通信内容などが詳細に出力されるようになります。
※注意：本番環境で長期間DEBUGモードにするとディスクが溢れるため、調査が終わったら必ず元に戻してください。

---

2. よくあるエラー図鑑と解決策

Keycloak運用で頻発するトラブルTOP3とその解決策です。

Case 1: Invalid parameter: redirect_uri

現象： アプリからログインしようとすると、Keycloakの画面でこのエラーが出て止まる。

原因： アプリ側が要求している「戻り先URL（Redirect URI）」が、Keycloakの管理画面で許可されていない。

解決策：

1. Keycloakのログを確認します。WARN ... type=LOGIN_ERROR, ... redirect_uri=https://... のようなログが出ているはずです。
2. そのログに書かれているURLをコピーします。
3. Keycloak管理コンソール → Clients → 該当アプリ → 「Valid redirect URIs」 に、そのURLを貼り付けて保存します。
4. 末尾の / の有無も厳密に判定されるので注意してください。

Case 2: 無限リダイレクト (Too many redirects)

現象： アプリとKeycloakの間を行ったり来たりして、最終的にブラウザがエラーを吐く。

原因： SSLオフロード（Nginx）の設定不備。
Keycloakが「通信がHTTP（平文）だ！危険だからHTTPSへ転送しなきゃ！」と判断し、Nginxへリダイレクト指示 → Nginxはアプリへ転送 → Keycloakに戻る…というループ。

解決策：

1. Nginxの設定（nginx.conf）に proxy_set_header X-Forwarded-Proto https; があるか確認。
2. Keycloakの環境変数に KC_PROXY: edge が設定されているか確認。
3. 第7回の記事を見直して設定を修正してください。

Case 3: Cookie not found / 400 Bad Request

現象： ログイン直後に「Cookieが見つかりません」といったエラーになる。

原因： クライアントPCの時刻ズレ、またはCookieサイズオーバー。

解決策：

1. サーバーとクライアントPCの時刻を確認し、数分以上ズレていれば修正します（NTP同期）。
2. AD連携をしていて所属グループが多い場合、Cookieが巨大化してブラウザの上限を超えます。
   Apacheの設定（oidc.conf）に OIDCSessionType server-cache を追加して、Cookieサイズを減らしてください。

---

3. 【緊急対応】管理者パスワードを忘れた時の対処法

「久しぶりに管理画面に入ろうとしたら、パスワードが変わっていて入れない！」
「前任者がパスワードを残さずに退職した！」

絶望的な状況ですが、サーバーのOSに入ることさえできれば、Keycloakのコマンドツールを使って強制的にパスワードをリセットできます。

コンテナ内コマンドによる強制リセット

Dockerコンテナが起動している状態で、以下の手順を実行します。

1. まず、稼働中のコンテナに入ります。

sudo docker exec -it sso-keycloak /bin/bash

2. Keycloakのツール用ディレクトリに移動します。

cd /opt/keycloak/bin

3. パスワードリセットコマンドを実行します。
   （master レルムの admin ユーザーを対象にする例）

./kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password 新しいパスワード

…と言いたいところですが、実はKeycloakのバージョンによっては、稼働中にこのコマンドが使えない（ロックされている）場合があります。
その場合、データベースを直接操作するという「奥の手」を使います。

【最終奥義】SQLによる管理者ユーザー作成

既存のadminユーザーがどうしても使えない場合、DBに直接「新しい管理者」を挿入します。
※これは非常に強力な操作なので、必ずバックアップを取ってから行ってください。

Keycloakコンテナを一度停止し、特別な環境変数を付けて起動します。

# docker-compose.yml に以下を一時的に追記
    environment:
      KEYCLOAK_ADMIN: recovery_admin
      KEYCLOAK_ADMIN_PASSWORD: recovery_password

これで再起動（docker compose up -d）すると、Keycloakは起動時に「recovery_admin ユーザーが存在しなければ作成する」という動作をします。
ログインできたら、正規のadminユーザーのパスワードを変更し、docker-compose.yml の追記を削除して再起動してください。

---

4. 【緊急対応】SSL証明書の期限切れ更新手順

「証明書の有効期限が切れました」という警告が出て、ユーザーがアクセスできなくなった場合の手順です。
自己署名証明書（有効期限10年）を作っていれば当分先の話ですが、手順として残しておきます。

更新フロー

1. 証明書の再作成: 第2回の記事の手順で、新しい server.crt と server.key を作成します。
2. ファイルの配置: ~/sso-project/certs/ ディレクトリの中身を新しいファイルで上書きします。
3. コンテナの再起動: Nginx（またはKeycloak）コンテナを再起動して、新しいファイルを読み込ませます。

# 証明書上書き後
sudo docker compose restart nginx

クライアントPCへのインポート（Windowsの証明書ストアへの登録）も再度必要になるので、ユーザーへの周知を忘れずに。

---

5. Keycloakのバージョンアップ戦略

Keycloakは開発スピードが早く、数ヶ月で新しいバージョンがリリースされます。
セキュリティパッチを適用するためにも、定期的なアップデートが必要です。

Dockerならではのアップデート手順

Dockerを使っているおかげで、アップデートは非常に簡単です。
ただし、メジャーバージョンアップ（例：v24 → v25）の際はデータベースの構造が変わる可能性があるため、必ずDBバックアップを取ってから行います。

1. バックアップ: 第7回で作成したスクリプトでDBダンプを取得。
2. 設定変更: docker-compose.yml のイメージタグを書き換えます。

  keycloak:
    # image: quay.io/keycloak/keycloak:24.0.1
    image: quay.io/keycloak/keycloak:26.0.0  # 新しいバージョン

3. 適用: docker compose up -d を実行。

Keycloakは起動時に自動的にデータベースのマイグレーション（構造変更）を行ってくれます。
ログを見て Update finished と出れば完了です。

---

連載のまとめ：エンジニアとしての次のステップ

全8回、本当にお疲れ様でした！
これにて「知識ゼロからのSSO構築講座」は完結です。

皆さんは今、以下のスキルを手に入れました。

• Linux (AlmaLinux 9) のサーバー構築能力
• Docker / Docker Compose によるコンテナ運用能力
• SSL証明書とDNSに関する正しい知識
• Active Directory / LDAP / Kerberos の認証基盤知識
• OIDC / SAML によるモダンな認証連携スキル

これらは、SSOに限らず、あらゆるWebシステムの構築・運用で通用する「一生モノの技術」です。

SSOの世界は奥深く、まだまだ学ぶことは尽きません（多要素認証、ソーシャルログイン、クラスタリングなど）。
しかし、この連載で得た基礎があれば、どんな応用技術も恐れることはありません。

あなたのエンジニアライフが、より輝かしいものになることを祈っています。
それでは、また別の連載でお会いしましょう！