Ubuntu 26.04 Keycloak CLI の基本設定 – 管理 CLI を使う準備を整える

Keycloak を運用する場合、管理画面だけでなく CLI から realm、client、user、role などを確認したい場面があります。Ubuntu 26.04 サーバーでは、Keycloak 本体を動かすかどうかとは別に、管理用 CLI を使える状態にしておくと、確認作業や自動化の入口を揃えやすくなります。

ただし、Keycloak の CLI だけが独立した小さなパッケージとして配布されているわけではありません。実際には Keycloak の配布アーカイブを展開し、その中に含まれる bin/kcadm.sh や bin/kc.sh を利用します。この記事では、Ubuntu 26.04 上で Keycloak の管理 CLI を配置し、最低限の確認ができる状態にする考え方を整理します。

Keycloak CLI として何を使うのか

Keycloak の運用で主に使う CLI は kcadm.sh です。これは Keycloak Admin REST API を操作するための管理 CLI で、realm や client の確認、設定変更、ユーザー管理などに利用できます。

この記事の主語は Keycloak サーバー本体の構築ではありません。Ubuntu 26.04 に Keycloak の配布物を展開し、管理 CLI を使える状態にすることです。

配布アーカイブを展開する理由

Keycloak の CLI は、単体の小さな実行ファイルとして配布されているものではなく、Keycloak のリリースアーカイブに含まれます。そのため、CLI を使うだけの場合でも、アーカイブを取得して展開する形になります。

/opt/keycloak を symbolic link にしておくと、バージョンを入れ替えても利用側のパスを固定できます。これは Terraform や Helm のような単一バイナリ配置とは少し違い、Keycloak のディレクトリ構造を維持したまま使う整理です。

アーカイブを取得して展開する

次は Keycloak 26.5.7 を例にした手動手順です。バージョンを固定し、アーカイブを /usr/local/src に置き、/opt 配下へ展開します。

keycloak_version=26.5.7
keycloak_archive="keycloak-${keycloak_version}.tar.gz"
keycloak_url="https://github.com/keycloak/keycloak/releases/download/${keycloak_version}/${keycloak_archive}"
sudo install -d -o root -g root -m 0755 /opt
sudo install -d -o root -g root -m 0755 /usr/local/src
sudo curl -fsSL -o "/usr/local/src/${keycloak_archive}" "${keycloak_url}"
sudo tar -xzf "/usr/local/src/${keycloak_archive}" -C /opt

展開後は、ディレクトリの所有者を root に揃えます。管理 CLI を複数ユーザーで使う前提にする場合でも、配置物そのものは不用意に書き換えられない方が自然です。

sudo chown -R root:root "/opt/keycloak-${keycloak_version}"
sudo find "/opt/keycloak-${keycloak_version}/bin" -type f -name "*.sh" -exec chmod 0755 {} \;
sudo ln -sfn "/opt/keycloak-${keycloak_version}" /opt/keycloak

配置を確認する

展開と symbolic link を確認します。Keycloak の CLI は /opt/keycloak/bin 配下にあるため、まずファイルが存在することを確認します。

ls -ld /opt/keycloak /opt/keycloak-26.5.7
ls -l /opt/keycloak/bin/kcadm.sh /opt/keycloak/bin/kc.sh
/opt/keycloak/bin/kcadm.sh --help
/opt/keycloak/bin/kc.sh --help

kcadm.sh は Keycloak 管理 API を操作するための CLI です。Keycloak サーバーへログインして使うため、CLI が配置できていることと、管理対象の Keycloak に到達できることは分けて考えます。

PATH を通すかどうか

/opt/keycloak/bin を PATH に追加すると、kcadm.sh を短い名前で実行できます。ただし、サーバー全体に PATH を通す必要があるかは運用次第です。明示的に /opt/keycloak/bin/kcadm.sh と書く方が、どの Keycloak CLI を使っているか分かりやすい場合もあります。

sudo tee /etc/profile.d/u70-keycloak.sh >/dev/null <<'EOF'
export PATH="/opt/keycloak/bin:${PATH}"
EOF
. /etc/profile.d/u70-keycloak.sh
which kcadm.sh
kcadm.sh --help

運用手順書や自動化では、PATH に依存しすぎない方が再現性は高くなります。対話作業では PATH を通し、自動化では絶対パスを書く、といった使い分けも現実的です。

Keycloak への接続確認

Keycloak の管理 CLI は、管理対象の Keycloak サーバーへ認証してから使います。次は例です。URL、realm、ユーザー名は環境に合わせて変更します。

/opt/keycloak/bin/kcadm.sh config credentials \
  --server https://keycloak.example.com \
  --realm master \
  --user admin

認証後は、realm や client を確認できます。最初は読み取り系のコマンドで接続、認証、権限の範囲を確認するのが安全です。

/opt/keycloak/bin/kcadm.sh get realms
/opt/keycloak/bin/kcadm.sh get clients -r master

CLI の配置と Keycloak 本体の構築は分けて考える

Keycloak の CLI を配置しただけでは、Keycloak サーバー本体が構築されたことにはなりません。ここを混同すると、記事や手順の主語が崩れます。

この記事は、Ubuntu 26.04 サーバー上で Keycloak の管理 CLI を使えるようにするための記事です。Keycloak 本体の構築、realm 設計、バックアップ設計は、別の記事として分けた方が読みやすくなります。

運用上の注意

• kcadm.sh の認証情報を不用意に共有ディレクトリへ置かない。
• 管理者アカウントを使う場合は、操作対象と権限範囲を明確にする。
• 自動化では、読み取り操作と変更操作を分ける。
• 本番 realm に対する変更コマンドは、事前に検証環境で確認する。
• CLI のバージョンと Keycloak サーバー側のバージョン差を意識する。

CLI は便利ですが、管理 API に対する入口でもあります。単に配置するだけではなく、誰が、どの realm に対して、どの操作を行うのかを運用として決めておく必要があります。

まとめ

Ubuntu 26.04 で Keycloak の管理 CLI を使う場合、CLI 単体の小さなパッケージを入れるというより、Keycloak の配布アーカイブを展開し、その中に含まれる kcadm.sh を利用する形になります。

/opt/keycloak-26.5.7 のようにバージョン付きで配置し、/opt/keycloak を current link にしておくと、手順や自動化から参照しやすくなります。

Keycloak CLI の配置は、Keycloak 本体の構築とは別の作業です。CLI を入れる目的は、管理 API を確認し、運用や自動化の入口を揃えることです。サーバー本体、realm 設計、バックアップ設計とは主語を分けて整理する方が、Ubuntu 26.04 サーバー管理の手順として扱いやすくなります。

関連記事

Ubuntu 26.04 calicoctl の基本設定 – Calico を確認する管理 CLI を整える Ubuntu 26.04 Helm の基本設定 – Kubernetes アプリケーション配備の CLI を整える Ubuntu 26.04 PHP CLI の基本設定 – コマンドラインで PHP を使う Ubuntu 22.04 KVM virt-install – 仮想マシンを CLI でデプロイする Ubuntu 22.04 Vue.js 開発環境 – npm / Vue CLI / Vite の位置づけを整理する Ubuntu 26.04 Cockpit の基本設定 – Linux サーバーを Web UI で確認する Ubuntu 26.04 Python の基本設定 – サーバー管理で使う Python 実行環境を整える Ubuntu 26.04 auditd の基本設定 – 監査ログの土台を整える