KeycloakをUbuntuにインストールする

Ubuntu24でのKeycloakの構築方法です。
私は個人の開発テスト用なのでH2データベースを使ってます。
DBの変更を推奨します。
一応,MariaDBでの方法は書いておきます
※個人用もMariaDBに変更しました。

私用のメモです。一部、雑かも

今回,Oracle OCIに構築したKeycloakのページ
https://login.momijiina.tech/

開発環境としての残してます。
私みたいに構築方法とURLを一緒に公開するのはただの脆弱性になりうるのでやめましょう。
いつか気づいたら真っ赤なページが表示されそう。

※ビルド後、初期スタートにドメイン間違えたらKeycloakを再ビルドしないと間違えたドメインに飛び続けます

アップデートとか

sudo apt -y update && sudo apt -y upgrade

ポート開放(必要なら)

sudo ufw allow 80
sudo ufw allow 443
sudo ufw reload

必要なソフトのインストール

unzipはお好みです。(別にtarでも)

sudo apt -y install certbot unzip openjdk-21-jdk

証明書の取得

sudo certbot certonly --standalone -d login.momijiina.tech

Keycloakインストール

Optにいれます
好みの場所があれば変えてください

cd /opt

Keycloakダウンロード

最新版は以下を確認
zip版ですtar版の場合も確認してください。 https://github.com/keycloak/keycloak/releases

ダウンロード

10月時点での最新版26.4.2をインストール(必要に応じて変更)

sudo wget https://github.com/keycloak/keycloak/releases/download/26.4.2/keycloak-26.4.2.zip

解凍

ダウンロードしたversionに合わせて解凍

sudo unzip keycloak-26.4.2.zip

ユーザーの作成

keycloak専用ユーザーを作成

ログイン権限とホームディレクトリ等はなし

sudo useradd -r -s /bin/false keycloak

Keycloakのインストールディレクトリの所有権を変更など

作成したユーザーに所有権を変更

sudo chown -R keycloak:keycloak /opt/keycloak-26.4.2

H2データベースを使う場合

DBを設定しなければ自動的にH2になります。
あとで切り替える場合、エラーだらけで大変だったのでDB変更は推奨します。

H2のメリットは設定不要でフォルダのコピーとって別サーバー持って行ってもそのまま動いてくれます。
動作もたぶん個人利用やユーザー数100人規模とかなら気にする必要はなさそうでした。

デメリットは公式が本番環境では非推奨としているのとデータの破損の可能性です。

以下から好きなの入れておくのが安定です。

• PostgreSQL
• MySQL
• MariaDB
• Oracle
• SQL Server

DBを変更する場合(例:MariaDB)

DBを作成する。
MySQLの場合でもほぼ同じです。

MariaDBにログイン

sudo mysql -u root -p

データベースとユーザーを作成

%を指定しているので必要があればlocalhostか接続元IP(分離する場合)にしてください。
DB名は必要があれば変更、パスワードは必ず変更してください。

CREATE DATABASE keycloak CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'keycloak'@'%' IDENTIFIED BY 'keycloak_password';
GRANT ALL PRIVILEGES ON keycloak.* TO 'keycloak'@'%';
FLUSH PRIVILEGES;
EXIT;

keycloak.confを編集する

keycloak.confにDBを設定します

sudo vi conf/keycloak.conf

Databaseコメントの下に追加しました。

# Database
db=mariadb
db-url=jdbc:mariadb://localhost:3306/keycloak
db-username=keycloak
db-password=keycloak_password

build後にDBがちゃんと動いてるの確認をしました(不要)

※ここはbuild後の確認です(不要です)
起動時のステータスメッセージ

[org.mariadb.jdbc.message.server.ErrorPacket] (main) Error: 1065-42000: Query was empty

データベース上での確認

sudo mysql -u keycloak -p
USE keycloak;

SELECT id, username, email, enabled, email_verified 
FROM USER_ENTITY 
LIMIT 10;

ユーザーもちゃんとつくられてました

MariaDB [keycloak]> SELECT id, username, email, enabled, email_verified 
    -> FROM USER_ENTITY 
    -> LIMIT 10;
+--------------------------------------+---------------+-------+---------+----------------+
| id                                   | username      | email | enabled | email_verified |
+--------------------------------------+---------------+-------+---------+----------------+
| 2c9296cc-eaa9-4693-ab97-301b127c1358 | administrator | NULL  |       1 |              0 |
+--------------------------------------+---------------+-------+---------+----------------+
1 row in set (0.000 sec)

Keycloakの初期管理者アカウントの作成

とりあえず一時的なアカウントです。
あとで消すのでなんでも
削除しろと警告がでるのでとりあえず初回で使わなさそうなのがいいです。

ユーザーの確実な追加

Administratorは自由に変更してください。
パスワードを聞いてくるのでいい感じのを
環境変数による追加もありますが環境によってはできないので今回はスルー

sudo -u keycloak /opt/keycloak-26.4.2/bin/kc.sh bootstrap-admin user --username Administrator

ビルドと起動テスト

keycloakのbinに移動するかbinまで指定してください。

cd /opt/keycloak-26.4.2/bin

ビルド

ユーザーをkeycloakで指定するかbuild後に権限を再付与してください。
権限エラーで見れないページがでます。

sudo -u keycloak /opt/keycloak-26.4.2/bin/kc.sh build

一部ページがみれない場合は以下を再度実行してください。

sudo chown -R keycloak:keycloak /opt/keycloak-26.4.2

起動テスト

Listening on: http://127.0.0.1:8080 と表示されれば終了して問題なし
ポート干渉などがある場合はずらしてください。

sudo -u keycloak /opt/keycloak-26.4.2/bin/kc.sh start \
  --hostname=login.momijiina.tech \
  --proxy-headers=xforwarded \
  --http-enabled=true \
  --http-host=127.0.0.1 \
  --http-port=8080

自動起動スクリプト

自動起動スクリプトの作成
2025年11月にテストしたものです。

sudo vi /etc/systemd/system/keycloak.service

ドメインと/opt/keycloak-26.4.2は必ず置き換えてください
とりあえず起動できればいい設定です。

[Unit]
Description=Keycloak Authentication Server
After=network.target

[Service]
Type=simple
User=keycloak
Group=keycloak
WorkingDirectory=/opt/keycloak-26.4.2

# Keycloak設定
Environment="KC_HOSTNAME=login.momijiina.tech"
Environment="KC_PROXY_HEADERS=xforwarded"
Environment="KC_HTTP_ENABLED=true"
Environment="KC_HTTP_HOST=127.0.0.1"
Environment="KC_HTTP_PORT=8080"

ExecStart=/opt/keycloak-26.4.2/bin/kc.sh start

ExecStop=/bin/kill -INT $MAINPID

[Install]
WantedBy=multi-user.target

要調整版(私用のテスト設定です)

テスト用なので削ったり追加したりしてください。

[Unit]
Description=Keycloak Authentication Server
After=network.target

[Service]
Type=simple
User=keycloak
Group=keycloak
WorkingDirectory=/opt/keycloak-26.4.2

# Keycloak設定
Environment="KC_HOSTNAME=login.momijiina.tech"
Environment="KC_PROXY_HEADERS=xforwarded"
Environment="KC_HTTP_ENABLED=true"
Environment="KC_HTTP_HOST=127.0.0.1"
Environment="KC_HTTP_PORT=8080"

# プロセス管理
Restart=on-failure
RestartSec=10
TimeoutStartSec=900
TimeoutStopSec=30

# セキュリティ設定
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/keycloak-26.4.2/data
ReadWritePaths=/opt/keycloak-26.4.2/providers

# ログ設定
StandardOutput=journal
StandardError=journal
SyslogIdentifier=keycloak

ExecStart=/opt/keycloak-26.4.2/bin/kc.sh start --optimized

ExecStop=/bin/kill -INT $MAINPID

[Install]
WantedBy=multi-user.target

起動スクリプトの有効化とステータス確認

sudo systemctl daemon-reload
sudo systemctl enable keycloak
sudo systemctl start keycloak
sudo systemctl status keycloak

Nginxの最新版をインストールする

最新のNginx取得に必要なものをインストール

sudo apt -y install curl gnupg2 ca-certificates lsb-release ubuntu-keyring

nginx の署名鍵をインポート

curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
    | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

最新の安定板を取得する

echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list

インストール

恐らく2025年10月現在はうまくいってれば1.28以上が入ります。

sudo apt update
sudo apt -y install nginx

有効化と起動

sudo systemctl enable nginx --now

Nginx の設定

sudo vi /etc/nginx/conf.d/kecloak.conf

セキュリティヘッダー等は調整してください

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name login.momijiina.tech;
    
    # Let's Encrypt用のみ許可
    location /.well-known/acme-challenge {
        root /var/www/html/;
    }
    
    # それ以外は全てHTTPSへリダイレクト
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name login.momijiina.tech;

    # SSL証明書
    ssl_certificate /etc/letsencrypt/live/login.momijiina.tech/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/login.momijiina.tech/privkey.pem;

    # SSL設定
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers off;
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384';
    
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_session_tickets off;

    # セキュリティヘッダー
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    #add_header X-Frame-Options "SAMEORIGIN" always;
    #add_header X-Content-Type-Options "nosniff" always;
    #add_header X-XSS-Protection "1; mode=block" always;
    #add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    location /.well-known/acme-challenge {
        root /var/www/html/;
    }

    location / {
        # プロキシバッファ設定
        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
        proxy_busy_buffers_size 256k;
        
        # Keycloak用のプロキシヘッダー
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-Port 443;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Scheme https;
        
        # タイムアウト設定
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;   

        proxy_pass http://localhost:8080;
    }

    # ログ設定（オプション）
    access_log /var/log/nginx/keycloak_access.log;
    error_log /var/log/nginx/keycloak_error.log;
}

確認と再読み込み

再読み込みできるか確認
successfulとでない場合はエラー部分を修正してください。

sudo nginx -t

再読み込み

sudo systemctl reload nginx

ログインする

ドメインにアクセスするとログイン画面が表示されます。
作成した初期管理者アカウントでログインしてください。

初期アカウントの削除

以下の警告が出ているはずです。

You are logged in as a temporary admin user. To harden security, create a permanent admin account and delete the temporary one.

ローカライズをしている場合は日本語で

一時的な管理者ユーザーとしてログインしています。セキュリティーを強化するには永続的な管理者アカウントを作成し一時的なアカウントを削除してください。

管理者アカウントの作成と一時アカウントの削除をしてください。

少し前のversionはこの警告はなかった気もします。

管理者パスワードを忘れた場合

初期管理者作成と手順は同じです。
Keycloakを止めて以下を実行
Administratorは自由に変更してください
パスワードを聞いてくるのでいい感じのを

sudo -u keycloak /opt/keycloak-26.4.2/bin/kc.sh bootstrap-admin user --username Administrator

その他

サーバー移行(H2使用時)

H2は楽です停止させた状態でzipなりに圧縮して別サーバーにもっていけば環境が整っていればそのまま動きます。
scp,rsyncとかで転送した方がいいのは間違いないですが・・
テスト用によくサーバー消すことが多いのでzipにして使いまわしてました。

sudo apt install zip

zip -r keycloak-26.4.2.zip keycloak-26.4.2