【連載 第3回】SSOの心臓部を動かす。KeycloakのDocker構築と日本語化完全ガイド

黒い画面に「Started」の文字が出た瞬間、あなたのサーバーは認証局になる。

こんにちは！「LINUX工房」管理人の「リナックス先生」です。
前回（第2回）は、AlmaLinux 9の初期設定と、SSO構築に不可欠な「SSL証明書」の作成を行いました。
いよいよ今回、主役であるオープンソースの認証ソフトウェア「Keycloak（キークローク）」を起動させます。

Keycloakは非常に多機能ですが、その分設定項目も膨大です。
初心者が最も躓くのが「データベース接続」と「HTTPS設定」です。
今回は、現場のスタンダード構成である「Docker Compose」を使って、これらを一発でクリアする構築手順を伝授します。

本記事では、Keycloakとデータベース（PostgreSQL）を連携させ、HTTPSで安全に通信できるSSO基盤を構築します。

---

1. 構成ファイルの作成 (docker-compose.yml)

Dockerを使ってシステムを構築する場合、設計図となるのが docker-compose.yml です。
今回は以下の2つのコンテナを連携させます。

• keycloak: 認証アプリケーション本体
• postgres: ユーザー情報や設定を保存するデータベース

1-1. ファイルの作成

作業ディレクトリに移動し、ファイルを作成します。

cd ~/sso-project
vi docker-compose.yml

1-2. 設定内容（コピペ用）

以下の内容をすべてコピーして貼り付けてください。
※パスワード部分（password123 など）は、本番環境では必ず複雑なものに変更してください。

services:
  # --- データベース (PostgreSQL) ---
  postgres:
    image: postgres:16
    container_name: sso-postgres
    volumes:
      - ./postgres/data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: password123
    networks:
      - sso-net
    restart: always

  # --- 認証サーバー (Keycloak) ---
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    container_name: sso-keycloak
    command: start --optimized
    environment:
      # ホスト名設定 (重要)
      KC_HOSTNAME: sso.linuxkoubou.local
      
      # データベース接続設定
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: password123
      
      # SSL証明書設定 (コンテナ内のパスを指定)
      KC_HTTPS_CERTIFICATE_FILE: /opt/keycloak/conf/server.crt
      KC_HTTPS_CERTIFICATE_KEY_FILE: /opt/keycloak/conf/server.key
      
      # 初期管理者アカウント (初回起動時のみ有効)
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin123
    volumes:
      # 証明書のマウント (ホスト側:コンテナ側)
      - ./certs/server.crt:/opt/keycloak/conf/server.crt:ro
      - ./certs/server.key:/opt/keycloak/conf/server.key:ro
      # データの永続化などは今回はDBに任せるため不要
    ports:
      - "443:8443"  # ホストの443番をコンテナの8443番へ転送
    depends_on:
      - postgres
    networks:
      - sso-net
    restart: always

networks:
  sso-net:

1-3. 設定のポイント解説

• KC_HOSTNAME: 前回hostsファイルに設定したドメイン名と一致させる必要があります。これが食い違うと、リダイレクトループなどの不具合が発生します。
• volumes (certs): 前回作成した自己署名証明書をコンテナの中に「読み取り専用(:ro)」で見せています。これにより、KeycloakがHTTPSで通信できるようになります。
• ports “443:8443”: Keycloakはデフォルトで8443番ポートを使いますが、ブラウザからアクセスしやすいように、サーバーの443番（HTTPS標準ポート）で受け付けるようにしています。

---

2. コンテナの起動とログ確認

設定ファイルができたら、いよいよ起動です。

2-1. ビルドと起動

Keycloakは初回起動時に内部でビルド処理が走るため、少し時間がかかります。

# バックグラウンドで起動
sudo docker compose up -d

2-2. ログのリアルタイム監視

「起動したかな？」と思ってすぐにブラウザでアクセスしても繋がりません。
ログを見て、起動完了の合図を待ちましょう。

sudo docker compose logs -f keycloak

以下のようなログが流れていきます。

1. データベースへの接続成功 (Connected to repository...)
2. テーブルの作成・更新 (Updating database...)
3. サービスの開始

最終的に、以下のメッセージが表示されれば起動完了です。

INFO  [io.quarkus] (main) Keycloak 24.x.x on JVM (powered by Quarkus 3.x.x) started in 15.234s. Listening on: https://0.0.0.0:8443

確認できたら Ctrl + C でログ監視を抜けます。

---

3. 管理コンソールへのアクセスとログイン

ここからは、手元のPC（Windows）のブラウザでの操作になります。
※前回、hostsファイルの設定を行っていないとアクセスできません。

3-1. ブラウザでアクセス

以下のURLを入力します。

https://sso.linuxkoubou.local/

自己署名証明書を使っているため、ChromeやEdgeでは「この接続ではプライバシーが保護されません」という警告画面が出ます。
しかし、前回Windowsに証明書をインポートしていれば、警告が出ずに鍵マーク付きで表示されるはずです。

もし警告が出た場合は、「詳細設定」→「sso.linuxkoubou.local にアクセスする（安全ではありません）」をクリックして進んでください。

3-2. 管理者ログイン

Keycloakのトップページが表示されたら、「Administration Console」をクリックします。

ログイン画面が表示されます。
docker-compose.yml で設定した初期アカウントを入力します。

• Username: admin
• Password: admin123

---

4. 最初の一歩。「日本語化」と「レルム」の作成

無事にログインできましたが、画面はすべて英語です。
設定ミスを防ぐためにも、まずは日本語化を行いましょう。

4-1. 日本語ロケールの有効化

1. 左メニューの 「Realm settings」 をクリック。
2. 上部タブの 「Localization」 をクリック。
3. 「Internationalization」 を Enabled（オン）にする。
4. 「Supported locales」 のリストから 「ja」 を選択して、右の矢印で追加する。
5. 「Default locale」 を 「ja」 に変更する。
6. 画面下部の 「Save」 ボタンを押す。

保存後、画面をリロード（F5）するか、一度サインアウトして再度ログインすると、画面が日本語になります。

4-2. 業務レルムの作成

ここが重要な概念です。
現在操作しているのは 「Master」 という特別な領域（レルム）です。
Masterレルムは「Keycloak自体の管理」に使われるべきで、実際のユーザーやアプリを登録すべきではありません。

SSO用の新しいレルムを作成しましょう。

1. 左上の「Master」と書かれているプルダウンメニューをクリック。
2. 「Create realm（レルムの作成）」 をクリック。
3. Realm name に任意の名前を入力（例: DemoCorp）。
4. 「Create（作成）」 をクリック。

これで、真っさらな「DemoCorp」レルムに切り替わりました。
以降の連載では、このレルムに対して設定を行っていきます。

---

5. 管理者アカウントのセキュリティ設定

Dockerの設定ファイルに admin / admin123 と書いてしまっているのは、セキュリティ上よろしくありません。
初期設定が終わったら、この環境変数を無効化するか、パスワードを変更しておきましょう。

管理ユーザーのパスワード変更

1. （Masterレルムに戻って）左メニューの 「ユーザー」 をクリック。
2. リストにいる admin ユーザーをクリック。
3. 「クレデンシャル（Credentials）」 タブをクリック。
4. 「パスワードを設定」 ボタンを押し、新しい強力なパスワードを設定する。
5. 「一時的（Temporary）」のチェックは外しておく（次回変更を強制しない場合）。

---

まとめ：SSOの心臓が動き出した

お疲れ様でした！
これで、あなたのサーバー上に「認証局」となるKeycloakが立ち上がりました。
PostgreSQLと連携し、HTTPSで保護された、本番運用にも耐えうる構成です。

今回の達成項目：

• Docker ComposeでKeycloakとPostgreSQLを起動した。
• 自己署名証明書を使ってHTTPSアクセスに成功した。
• 管理画面を日本語化した。
• 業務用の専用レルムを作成した。

ご安心ください。次回、【第4回】ユーザー情報の統合では、社内のActive Directory (AD) とKeycloakをパイプで繋ぎます。
ADに登録されている何百人ものユーザー情報が、Keycloak上に一瞬で同期される様子は圧巻ですよ。

それでは、次回の記事でお会いしましょう！