Keycloak: 使用 CLI 自動化操作

透過 Stackhero CLI 程式化啟動 Keycloak、取得其認證資料，以及變更其設定

👋 歡迎瀏覽 Stackhero 文件！

Stackhero 提供 Keycloak cloud 服務，讓您只需 2 分鐘即可輕鬆部署一個可用於生產環境的身份認證服務：

無限用戶、realms 及 clients

支援 OpenID Connect、OAuth 2.0、SAML 2.0、社交登入、LDAP 及 Active Directory 聯合

自訂網域名稱，內建 HTTPS，確保安全連線（例如 https://login.your-company.com）

自訂主題：可利用內置的線上編輯器輕鬆為登入頁面、帳戶控制台及電郵加上您的品牌風格

專屬 電郵伺服器，支援 SPF、DKIM 及 DMARC，協助您自動處理帳戶確認及重設密碼

內建 PostgreSQL 資料庫，管理控制台可於獨立且可關閉的連接埠上存取

一鍵更新，讓您的系統隨時保持最新，無需手動操作

專注於開發，無需煩惱設定：您可以在 5 分鐘內體驗 Stackhero 的 Keycloak cloud 解決方案。

本指南將說明如何以純命令列方式建立 Keycloak 服務、讀取其認證資料，以及更新其設定，完全無需在控制台點擊操作。這非常適合用於腳本、自動化流程（CI pipeline）及 AI agent。

我們將會使用 Stackhero CLI 來執行所有操作。如果您尚未安裝，可以透過以下指令安裝：

curl -fsSL https://www.stackhero.io/install.sh | sh

1. 認證登入

最簡單的開始方式是透過瀏覽器登入。當您執行登入指令時，CLI 會自動開啟網頁，讓您授權存取權限。您無需在 CLI 輸入密碼或 2FA 驗證碼。

stackhero login

登入後，您的認證資料會儲存在本機，之後所有 CLI 指令都會自動使用。

若您是在完全自動化的環境（如腳本或 CI pipeline）中操作，建議使用非互動式的 access token。您可以在控制台（帳戶 > Access tokens）建立，然後將其設為環境變數。CLI 及所有腳本都會自動讀取該變數。

export STACKHERO_TOKEN="usr-xxxxxx:your-token"

2. 查找 Keycloak 服務 store

接下來，您可以列出帳戶下可用的 Keycloak 服務 store。CLI 可直接接受 store 名稱（keycloak），無需查找或複製任何 ID。

# 列出 Keycloak 服務 store（如管理多個組織可加上 --organization）
stackhero services-store-list --name="keycloak"

您可以在後續指令中直接使用 store 名稱 keycloak，或從清單中選擇特定的 svs-xxxxxx ID。

3. 選擇實例規格及地區

# 列出服務 store 可用的實例規格（使用 NAME 欄位作為 --instance）
stackhero instances-store-list --service-store=keycloak

# 列出可用地區（如 "europe"）
stackhero regions-list

4. 建立服務

以下是一個範例腳本，會建立一個 stack，將您的 Keycloak 服務加入其中，等待服務啟動，取得其設定（包括自動產生的認證資料），然後套用新的設定。

#!/bin/bash
set -e

export STACKHERO_TOKEN="usr-xxxxxx:your-token"

serviceStore="keycloak"   # Keycloak 服務 store 名稱（見步驟 2）
instance="..."                # 步驟 3 選擇的實例規格
region="europe"               # 步驟 3 選擇的地區名稱

# 建立服務專用的 stack（預設使用您的主要組織；如有需要可加 --organization）
stackId=$(stackhero --format=script stack-create \
  --name="My Keycloak stack")
echo "Stack created: ${stackId}"

# 將 Keycloak 加入 stack（名稱會自動解析）
serviceId=$(stackhero --format=script service-add \
  --stack="My Keycloak stack" \
  --service-store="${serviceStore}" \
  --instance="${instance}" \
  --region="${region}")
echo "Service added: keycloak"

# 等待服務完全啟動（可能需數分鐘）
stackhero service-wait-for --service="keycloak"

# 取得服務設定，包括自動產生的認證資料
stackhero service-configuration-get --service="keycloak" --format=json

5. 取得認證資料

service-configuration-get 指令會回傳服務的完整設定，包括自動產生的密碼及連線資訊。輸出為 JSON 格式，方便腳本及自動化流程使用。

stackhero service-configuration-get --service=svc-xxxxxx --format=json

6. 變更設定

您可以先查看設定 schema 及範例，再套用自訂設定。當您更新設定時，服務可能會自動重啟以套用變更。

# 查看服務的設定 schema 及範例
stackhero service-configuration-example --service=svc-xxxxxx

# 套用自訂設定（如有需要服務會自動重啟）
stackhero service-configuration-set \
  --service=svc-xxxxxx \
  --configuration='{ "...": "..." }'

# 等待新設定套用完成
stackhero service-wait-for --service=svc-xxxxxx

就是這樣。您已經完整體驗了：啟動服務、取得認證資料、並重新設定，全程可自動化及腳本化。如需更深入資訊，請參閱完整 CLI 文件，其中亦有介紹本例所用的非互動式 STACKHERO_TOKEN 認證方式。