【付録】SSO構築・運用チートシート。コマンド集とトラブルシューティング総まとめ

困ったときは、この記事に戻ってくればいい。

こんにちは！「LINUX工房」管理人の「リナックス先生」です。
全8回にわたるSSO構築連載、本当にお疲れ様でした。
あなたはすでに、AlmaLinux 9上にKeycloakを構築し、Active Directoryと連携させ、Windows統合認証まで実現するスキルを持っています。

しかし、人間の記憶は儚いものです。
半年後、証明書の更新時期が来たとき、あるいは急なトラブルでサーバーが止まったとき、「あれ？ どのコマンドを叩けばいいんだっけ？」と焦る瞬間が必ず来ます。

本記事は、SSO構築連載の付録として、運用に必要なコマンド、設定値、トラブル対応フローを一元化したリファレンスガイドです。

---

1. 【必須】Docker運用コマンド集

日々の運用で最も頻繁に使うコマンドです。
cd ~/sso-project で作業ディレクトリに移動してから実行することを前提としています。

基本操作（起動・停止・再起動）

設定ファイルを書き換えた後は、必ず再起動が必要です。

# コンテナ群の起動（バックグラウンド）
sudo docker compose up -d

# 特定のコンテナだけ再起動（例：Keycloakのみ）
# 設定変更を反映させたい時に便利
sudo docker compose restart keycloak

# コンテナ群の停止
sudo docker compose stop

# コンテナ群の削除（データボリュームは残る）
sudo docker compose down

状態確認とログ

「動かない！」と思ったら、まずはこれを確認します。

# 稼働状態の確認（Upになっているか？）
sudo docker compose ps

# リアルタイムログ監視（全体）
sudo docker compose logs -f

# 特定コンテナのログ監視（直近100行）
# トラブル時はまずこれを叩け！
sudo docker compose logs -f --tail=100 keycloak

# ログをファイルに書き出す（調査用）
sudo docker compose logs keycloak > keycloak_error.log

コンテナ内部への侵入

設定ファイルの確認や、ネットワーク疎通確認に使います。

# Keycloakコンテナに入る
sudo docker exec -it sso-keycloak /bin/bash

# DBコンテナに入る
sudo docker exec -it sso-postgres /bin/bash

# Webアプリコンテナに入る
sudo docker exec -it sso-webapp /bin/bash

---

2. 【設定】Keycloak環境変数リファレンス

docker-compose.yml に記述する環境変数のうち、特に重要なものをまとめました。
設定変更が必要になった時の参考にしてください。

DB設定の変更方法

PostgreSQLのパスワードを変更したい場合は、Keycloak側とPostgreSQL側の両方の環境変数を同時に変更し、コンテナを再作成（down -> up）する必要があります。

---

3. 【緊急】バックアップとリストア手順

データ消失は突然やってきます。手順書が手元になくて焦ることがないよう、ここに再掲します。

バックアップ（ダンプ取得）

PostgreSQLのデータを丸ごとSQLファイルに書き出します。

# バックアップ用ディレクトリ作成
mkdir -p ~/sso-project/backups

# ダンプ実行（日付つきファイル名）
docker exec sso-postgres pg_dump -U keycloak keycloak > ~/sso-project/backups/db_backup_$(date +%Y%m%d).sql

# 確認
ls -lh ~/sso-project/backups/

リストア（復元）

注意：既存のデータはすべて上書きされます。
Keycloakコンテナを停止してから実行するのが安全です。

# 1. Keycloakを停止
sudo docker compose stop keycloak

# 2. 既存DBを削除して再作成（コンテナ内コマンド）
sudo docker exec sso-postgres psql -U keycloak -d postgres -c "DROP DATABASE keycloak;"
sudo docker exec sso-postgres psql -U keycloak -d postgres -c "CREATE DATABASE keycloak;"

# 3. バックアップファイルを流し込み
cat ~/sso-project/backups/db_backup_20260201.sql | sudo docker exec -i sso-postgres psql -U keycloak -d keycloak

# 4. Keycloakを起動
sudo docker compose start keycloak

---

4. 【解析】トラブルシューティング・フローチャート

「ユーザーから『ログインできない』と連絡が来た！」
そんな時は、以下のフローチャートに沿って原因を切り分けてください。

Step 1. 画面は表示されるか？

• NO（タイムアウト/接続拒否）:
  • サーバーは落ちていないか？ (ping)
  • Dockerコンテナは動いているか？ (docker compose ps)
  • Nginxのログにエラーはないか？
• NO（502 Bad Gateway）:
  • Keycloakコンテナが起動中、または再起動を繰り返していないか？
  • KeycloakとDBの接続は正常か？ (docker compose logs keycloak でDBエラーを確認)
• YES（Keycloak画面は出る）: Step 2へ。

Step 2. ログイン試行時のエラー内容は？

• 「Invalid username or password」:
  • AD連携の設定ミスか、ユーザーのパスワード間違い。
  • AD側でアカウントがロックされていないか確認。
• 「Invalid parameter: redirect_uri」:
  • アプリ側のURL設定と、Keycloakの「Valid redirect URIs」が不一致。
  • 末尾のスラッシュ(/)やhttp/httpsの違いを凝視する。
• 「Cookie not found」 / 「400 Bad Request」:
  • クライアントPCの時刻ズレ（NTP確認）。
  • Cookieサイズオーバー（AD所属グループが多すぎる）。Webアプリ側でOIDCSessionType server-cacheを設定。

Step 3. ログに「Error」はあるか？

ログに以下のキーワードがないか検索してください。

sudo docker compose logs keycloak | grep -E "ERROR|WARN"

• DNS lookup failed: 名前解決エラー。/etc/hosts やDNS設定を見直す。
• Certificate expired: SSL証明書の期限切れ。
• Checksum failed (Kerberos): Keytabファイルの作成ミス、またはドメイン名の大文字/小文字間違い。

---

5. 【保守】SSL証明書更新と定期メンテ

システムを長く使うためのメンテナンス手順です。

SSL証明書の更新（オレオレ証明書）

有効期限が切れる前に実施します。

cd ~/sso-project/certs

# 新しい証明書を作成（上書き）
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout server.key -out server.crt \
  -config openssl.cnf

# Nginxコンテナを再起動して読み込ませる
sudo docker compose restart nginx

※クライアントPCへの再インポートも忘れずに。

不要なDockerイメージの削除

何度もビルドやアップデートをしていると、古いイメージが溜まってディスクを圧迫します。

# 使われていないイメージを一括削除
sudo docker image prune -a

---

さいごに：エンジニアとしての成長

このチートシートは、あなたがこのSSO環境の「守護者」として活躍するための武器です。
しかし、ここに書かれていない未知のトラブルも必ず起きるでしょう。

その時こそ、本連載で学んだ「ログを見る」「仕組みを理解する」「仮説を立てて検証する」というプロセスを思い出してください。
トラブルを一つ解決するたびに、あなたはエンジニアとして確実にレベルアップしています。

「認証基盤」という、システムの最も重要な心臓部を構築・運用できるようになったあなたなら、この先のどんなインフラ案件も自信を持って対応できるはずです。

あなたのエンジニアライフが、トラブル少なく、称賛多きものになることを祈っています。
また別の連載でお会いしましょう！