Ubuntu 26.04 Keycloak CLI の基本設定 – kcadm.sh を使う管理ツールを配置する

Keycloak を運用するときは、Web 管理画面だけでなく CLI で realm、client、user、role などを確認・変更できる状態にしておくと、作業の再現性を高めやすくなります。

この記事では、Ubuntu 26.04 に Keycloak の配布アーカイブを配置し、kcadm.sh や kc.sh などの管理ツールを使うための基本設定をまとめます。ここで扱うのは管理ツールの配置であり、Keycloak サーバーを systemd service として起動する手順ではありません。

この記事で扱うこと

Keycloak 管理 CLI を用意する目的
Keycloak 26.6.4 の配布アーカイブ取得
/opt/keycloak-26.6.4 への展開
/opt/keycloak current link の作成
kcadm.sh と kc.sh の確認

対象 OS	Ubuntu 26.04 Server
Keycloak version	`26.6.4`
取得元	`https://github.com/keycloak/keycloak/releases/download`
作業ディレクトリ	`/usr/local/src`
展開先	`/opt/keycloak-26.6.4`
current link	`/opt/keycloak`

参考書籍

認証と認可 Keycloak入門

Keycloak、OIDC、SAML、認証基盤の設計を体系的に確認したい場合の参考書籍です。価格や在庫はリンク先で確認してください。

Amazon で見る

このリンクは Amazon アソシエイトリンクです。

Keycloak CLI を分けて用意する理由

Keycloak の管理作業は Web UI でも実行できますが、同じ作業を何度も行う場合や、環境間で設定を比較する場合は CLI が便利です。特に kcadm.sh は realm や client の確認、設定変更、export/import 前後の確認に使えます。

管理画面だけに依存しない
realm や client の状態をコマンドで確認できる
作業手順をログに残しやすい
Keycloak サーバー本体の起動設定とは分けて管理できる

必要なパッケージを用意する

アーカイブ取得と展開に必要なパッケージを入れます。Keycloak への HTTPS 接続で内部 CA を使う場合は、OS 側の信頼ストアも先に確認します。

sudo apt update
sudo apt install -y curl tar ca-certificates default-jre-headless
java -version

配布アーカイブを取得する

Keycloak の release から固定バージョンの tar.gz を取得します。ここでは 26.6.4 を例にします。

keycloak_version="26.6.4"
work_dir="/usr/local/src"
archive="keycloak-${keycloak_version}.tar.gz"
base_url="https://github.com/keycloak/keycloak/releases/download"
sudo install -d -o root -g root -m 0755 "$work_dir"
curl -fsSL -o "/tmp/$archive" "${base_url}/${keycloak_version}/${archive}"
sudo install -o root -g root -m 0644 "/tmp/$archive" "$work_dir/$archive"

/opt に展開する

取得したアーカイブを /opt 配下へ展開します。展開先は version を含むディレクトリにし、後で /opt/keycloak から参照できるようにします。

sudo install -d -o root -g root -m 0755 /opt
sudo tar -xzf "$work_dir/$archive" -C /opt
sudo chown -R root:root "/opt/keycloak-${keycloak_version}"
ls -ld "/opt/keycloak-${keycloak_version}"
ls -l "/opt/keycloak-${keycloak_version}/bin"

shell script に実行権限を付ける

Keycloak の bin 配下には kc.sh や kcadm.sh などの shell script があります。実行できるように mode を確認します。

sudo find "/opt/keycloak-${keycloak_version}/bin" -type f -name "*.sh" -exec chmod 0755 {} \;
find "/opt/keycloak-${keycloak_version}/bin" -maxdepth 1 -type f -name "*.sh" -printf "%m %p\n"

current link を作成する

バージョン付きディレクトリを直接参照すると、更新時にパスが変わります。運用では /opt/keycloak を current link として使い、実体を /opt/keycloak-26.6.4 へ向けます。

sudo ln -sfn "/opt/keycloak-${keycloak_version}" /opt/keycloak
ls -l /opt/keycloak
readlink /opt/keycloak

CLI の存在を確認する

管理ツールとして使う主なコマンドは kcadm.sh です。Keycloak の起動や build に関わる kc.sh も同じ配布物に含まれます。

test -x /opt/keycloak/bin/kcadm.sh
test -x /opt/keycloak/bin/kc.sh
/opt/keycloak/bin/kcadm.sh help
/opt/keycloak/bin/kc.sh --help

管理先へ接続する

kcadm.sh で管理先 Keycloak へ接続する場合は、server URL、realm、管理ユーザーを指定します。認証情報を shell history に残さない運用も検討します。

read -rs KEYCLOAK_ADMIN_PASSWORD
/opt/keycloak/bin/kcadm.sh config credentials --server https://keycloak.example.com --realm master --user admin --password "$KEYCLOAK_ADMIN_PASSWORD"
unset KEYCLOAK_ADMIN_PASSWORD
/opt/keycloak/bin/kcadm.sh get realms
/opt/keycloak/bin/kcadm.sh get clients -r example

本番環境では、管理者パスワードや client secret をコマンド履歴、ログ、共有ディレクトリに残さないようにします。必要に応じて一時的な管理ユーザー、短い作業時間、端末ログの扱いを決めます。

TLS と proxy を確認する

Keycloak が内部 CA の証明書を使っている場合、Ubuntu 側で CA を信頼していないと CLI 接続に失敗します。proxy 環境では HTTPS_PROXY と NO_PROXY の扱いも確認します。

curl -I https://keycloak.example.com/
printenv HTTPS_PROXY
printenv NO_PROXY
/opt/keycloak/bin/kcadm.sh get serverinfo --server https://keycloak.example.com

更新するときの考え方

Keycloak tools を更新するときは、新しい version を別ディレクトリへ展開し、/opt/keycloak のリンク先を切り替えると戻しやすくなります。CLI だけを使う場合でも、管理先サーバーの version と大きく離れすぎないようにします。

ls -ld /opt/keycloak-*
readlink /opt/keycloak
/opt/keycloak/bin/kcadm.sh help

確認ポイント

/usr/local/src/keycloak-26.6.4.tar.gz を保存している
/opt/keycloak-26.6.4 が root 所有になっている
/opt/keycloak が current link として正しい実体を指している
/opt/keycloak/bin/kcadm.sh が実行できる
内部 CA、proxy、管理者認証情報の扱いを確認している

まとめ

Ubuntu 26.04 で Keycloak CLI を使う場合、Keycloak サーバー本体の起動設定と、管理ツールの配置を分けて考えると扱いやすくなります。

/usr/local/src に配布アーカイブを保存し、/opt/keycloak-26.6.4 へ展開し、/opt/keycloak の current link を作ることで、固定バージョンの kcadm.sh を安定して使えます。接続時は TLS、proxy、管理者認証情報の扱いを合わせて確認します。

Ubuntu 26.04 Keycloak CLI の基本設定 – kcadm.sh を使う管理ツールを配置する

Ubuntu 26.04 Keycloak CLI の基本設定 – kcadm.sh を使う管理ツールを配置する

Keycloak CLI を分けて用意する理由

必要なパッケージを用意する

配布アーカイブを取得する

/opt に展開する

shell script に実行権限を付ける

current link を作成する

CLI の存在を確認する

管理先へ接続する

TLS と proxy を確認する

更新するときの考え方

確認ポイント

まとめ

関連記事

コメントを残す コメントをキャンセル

コメントを残すコメントをキャンセル