xDev Asia

熟悉管理控制台、建立第一個管理員使用者、建立和設定領域、領域設定（常規、登入、電子郵件、主題、在地化、金鑰、安全防禦）、管理 CLI (kcadm.sh) 和基本管理 REST API。

鑰匙斗篷從基礎到高級

第 1 部分：Keycloak 平台

亞洲開發網

1. 存取管理控制台

安裝Keycloak（單機或Docker）後，即可存取管理控制台— 整個 Keycloak 系統的集中管理介面。

造訪網址

預設情況下，管理控制台位於：

http://localhost:8080/admin

如果您使用具有不同連接埠對映的 Docker 執行 Keycloak：

http://localhost:<PORT>/admin

建立第一個管理員用戶

當你第一次造訪Keycloak時，你需要創建一個初始管理員用戶登入管理控制台。有兩種方法：

方法一：透過環境變數（建議用於Docker/Production）

docker run -d --name keycloak \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  -p 8080:8080 \
  quay.io/keycloak/keycloak:26.2.4 start-dev

方法2：透過歡迎頁面（僅從本地主機造訪時）

使用權http://localhost:8080，您將看到管理員使用者建立表單。輸入使用者名稱和密碼，然後按一下創造.

方法3：透過命令列

# Standalone
export KC_BOOTSTRAP_ADMIN_USERNAME=admin
export KC_BOOTSTRAP_ADMIN_PASSWORD=admin
bin/kc.sh start-dev

管理控制台介面

登入後，您將看到管理控制台介面，其主要元件如下：

領域選擇器（左上角）— 選擇您正在管理的領域
左側邊欄— 主導航選單：用戶端、用戶端範圍、領域角色、使用者、群組、會話、事件、領域設定、身份驗證、身分提供者、使用者聯合
主要內容區— 顯示所選項目的詳細內容
用戶下拉選單(右上角) — 管理管理員帳戶，退出

2.建立第一個Realm

主域與自訂域

安裝Keycloak時，領域有一個名稱掌握。掌握預製的。主域是一個特殊的域，用來管理其他域—主領域不應用於應用程式.

最佳實踐：

使用大師境界僅超級管理員可以管理Keycloak系統
創造自訂領域特定於每個組織、專案或環境
命名realm的含義是：我的公司開發, mycompany 分期, 我的公司產品

透過管理控制台創建領域

點選領域選擇器（左上角的下拉式選單，顯示“master”）
點選創建領域
輸入資訊：
- 領域名稱: 我的公司（僅含小寫字母、數字、連字號）
- 啟用：在
點選創造

從 JSON 檔案建立 Realm

您可以從 JSON 檔案匯入領域 - 對於在環境之間複製配置很有用：

{
  "realm": "my-company",
  "enabled": true,
  "displayName": "My Company",
  "displayNameHtml": "<strong>My Company</strong>",
  "sslRequired": "external",
  "registrationAllowed": false,
  "loginWithEmailAllowed": true,
  "duplicateEmailsAllowed": false,
  "resetPasswordAllowed": true,
  "editUsernameAllowed": false,
  "bruteForceProtected": true,
  "permanentLockout": false,
  "maxFailureWaitSeconds": 900,
  "minimumQuickLoginWaitSeconds": 60,
  "waitIncrementSeconds": 60,
  "quickLoginCheckMilliSeconds": 1000,
  "maxDeltaTimeSeconds": 43200,
  "failureFactor": 5,
  "defaultSignatureAlgorithm": "RS256",
  "accessTokenLifespan": 300,
  "ssoSessionIdleTimeout": 1800,
  "ssoSessionMaxLifespan": 36000
}

透過管理控制台匯入：建立領域時，按一下瀏覽選擇 JSON 檔案。

3.領域設置詳細信息

創建realm後，訪問領域設定從側邊欄了解詳細配置。

3.1 常規選項卡

環境	描述	建議值
顯示名稱	登入頁面顯示的名稱	公司/專案名稱
HTML 顯示名稱	HTML 對顯示名稱的支持	標誌+名稱
前端網址	用戶端用於連線的 URL	https://auth.mycompany.com
需要 SSL	請求需要 SSL	`外部的`（開發）/`全部`（產品）
用戶管理的訪問	允許使用者管理資源 (UMA)	關閉（除非需要 UMA）
ACR 到 LoA 映射	映射身份驗證上下文類別參考	需要升級身份驗證時進行配置

配置登入頁面的行為：

環境	描述	預設
用戶註冊	允許新帳戶註冊	離開
忘記密碼	顯示連結“忘記密碼”	離開
記住帳號	複選框“記住登入”	離開
電子郵件作為使用者名稱	使用電子郵件作為使用者名稱	離開
使用電子郵件登入	允許透過電子郵件登入	在
重複的電子郵件	允許重複的電子郵件	離開
驗證電子郵件	需要電子郵件驗證	離開
編輯使用者名稱	允許更改使用者名稱	離開

生產建議：

User registration: OFF (hoặc ON với reCAPTCHA)
Forgot password: ON
Remember me: ON
Email as username: Tùy yêu cầu
Login with email: ON
Verify email: ON
Edit username: OFF

3.3 電子郵件選項卡

設定 SMTP 伺服器發送電子郵件（驗證、密碼重設、通知）：

環境	描述
從	發送電子郵件地址（例如[email protected]）
來自顯示名稱	電子郵件中顯示的姓名
大聲回覆	回覆地址（例如 [email protected]）
主持人	SMTP 伺服器主機名
港口	SMTP 連接埠（STARTTLS 為 587，SSL 為 465）
加密	啟用 SSL 或 STARTTLS
驗證	SMTP 的使用者名稱和密碼

Gmail SMTP 的設定範例：

Host: smtp.gmail.com
Port: 587
From: [email protected]
Enable StartTLS: ON
Authentication: ON
Username: [email protected]
Password: app-specific-password

3.4 主題選項卡

自訂不同頁面的外觀：

登入主題— 登入、註冊、密碼重設頁面
帳戶主題— 使用者的帳戶管理頁面
管理控制台主題— 管理控制台介面
電子郵件主題— 電子郵件模板

Keycloak提供主題鑰匙斗篷（預設）和鑰匙斗篷.v2（帳戶控制台 v3，基於 React）。您可以建立自訂主題 - 這將在下一篇文章中介紹。

3.5 本地化選項卡

登入、帳戶、電子郵件頁面的多語言支援：

打開國際化：在
選擇支援的語言環境：en、vi、ja、zh-CN、...
選擇預設區域設定: vi (預設越南語介面)
如果需要，為每個區域設定自訂訊息包

3.6 選項卡鍵

管理領域的加密金鑰－用於簽署和加密令牌：

活動鍵- 密鑰用於簽署令牌
被動按鍵— 舊金鑰仍用於驗證先前簽署的令牌
停用按鍵— 鑰匙不再使用

預設密鑰提供者：

提供者	演算法	目的
rsa 產生的	RS256	簽署 JWT 令牌
RSA-enc-生成	RSA-OAEP	加密令牌
hmac 產生的	HS512	HMAC 簽名
aes 產生的	AES	對稱加密
ecdsa 產生的	ES256	橢圓曲線簽名

密鑰輪換：新增新的金鑰提供者→新金鑰變成主動→舊金鑰變成被動→一段時間後停用舊金鑰。

3.7 代幣選項卡

配置令牌的生命週期和行為：

環境	描述	建議值
預設簽名演算法	JWT 簽章演算法	RS256
撤銷刷新令牌	使用後撤銷刷新令牌	開（生產）
SSO 會話空閒	最大會話空閒時間	30分鐘
SSO 最大會話數	最大會話時間	10點
訪問令牌的有效期	訪問令牌的生命週期	5分鐘
客戶端登入逾時	登入流程最長時間	5分鐘

3.8 安全防禦選項卡

領域的安全配置：

標題：

標頭	預設值	描述
X 框架選項	同源	防點擊劫持
內容安全策略	框架-src'自我'； ...	CSP頭
X-內容類型選項	不聞	防止 MIME 嗅探
X-XSS-保護	1;模式=區塊	XSS過濾器
嚴格的運輸安全	最大年齡=31536000	需要 HTTPS
推薦人政策	無推薦人	控制 Referrer 標頭

暴力檢測：

啟用：ON（開啟防暴力破解）
永久停工：關閉（到時間後自動解鎖）
最大登入失敗次數：5（5次登入失敗後將被鎖定）
等待增量：60秒（等待時間逐漸增加）
最長等待時間：900秒（最長等待時間15分鐘）
快速登入檢查：1000毫秒（偵測到登入速度太快）

4. 管理 CLI (kcadm.sh)

鑰匙斗篷提供管理CLI (kcadm.sh) — 無需存取管理控制台即可管理 Keycloak 的命令列工具。

4.1 配置憑證

在使用Admin CLI之前，您需要登入：

# Đăng nhập vào Keycloak server bin/kcadm.sh config credentials \ --server http://localhost:8080 \ --realm master \ --user admin \ --password admin Với Docker

docker exec -it keycloak /opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password admin

安全說明：在生產、使用- 客戶和- 秘密而不是直接在命令列上輸入使用者名稱/密碼。

4.2 使用 CLI 進行領域管理

創建新領域：

# Tạo realm cơ bản
bin/kcadm.sh create realms \
  -s realm=my-company \
  -s enabled=true \
  -s displayName="My Company"
Tạo realm với nhiều cấu hình
bin/kcadm.sh create realms 

-s realm=my-company 

-s enabled=true 

-s displayName="My Company" 

-s registrationAllowed=false 

-s loginWithEmailAllowed=true 

-s resetPasswordAllowed=true 

-s sslRequired=external 

-s bruteForceProtected=true

查看領域列表：

# Lấy tất cả realms
bin/kcadm.sh get realms --fields realm,enabled,displayName
Output:
[ {
"realm" : "master",
"displayName" : "Keycloak",
"enabled" : true
}, {
"realm" : "my-company",
"displayName" : "My Company",
"enabled" : true
} ]

查看領域詳細資訊：

bin/kcadm.sh get realms/my-company

領域更新：

bin/kcadm.sh update realms/my-company \
  -s displayName="My Company Production" \
  -s sslRequired=all \
  -s bruteForceProtected=true \
  -s failureFactor=5

刪除領域：

bin/kcadm.sh delete realms/my-company

4.3 使用 CLI 配置領域設置

配置登入設定：

bin/kcadm.sh update realms/my-company \
  -s registrationAllowed=true \
  -s resetPasswordAllowed=true \
  -s rememberMe=true \
  -s verifyEmail=true \
  -s loginWithEmailAllowed=true \
  -s duplicateEmailsAllowed=false

配置令牌設定：

bin/kcadm.sh update realms/my-company \
  -s accessTokenLifespan=300 \
  -s ssoSessionIdleTimeout=1800 \
  -s ssoSessionMaxLifespan=36000 \
  -s revokeRefreshToken=true \
  -s refreshTokenMaxReuse=0

配置 SMTP 電子郵件：

bin/kcadm.sh update realms/my-company \
  -s 'smtpServer={"host":"smtp.gmail.com","port":"587","from":"[email protected]","fromDisplayName":"My Company","starttls":"true","auth":"true","user":"[email protected]","password":"app-password"}'

導出領域配置：

# Export realm sang file JSON
bin/kcadm.sh get realms/my-company > my-company-realm.json

5. 管理 REST API

鑰匙斗篷提供管理 REST API透過 HTTP 請求實現全面管理 - 非常適合自動化、CI/CD 以及與其他系統的整合。

5.1 取得訪問令牌

在呼叫 API 之前，您需要從 master 領域取得存取權杖：

# Lấy access token bằng admin credentials ACCESS_TOKEN=$(curl -s -X POST \ "http://localhost:8080/realms/master/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "username=admin" \ -d "password=admin" \ -d "grant_type=password" \ -d "client_id=admin-cli" | jq -r '.access_token')

echo $ACCESS_TOKEN

5.2 使用 API 進行領域管理

取得領域列表：

curl -s -X GET \
  "http://localhost:8080/admin/realms" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" | jq '.[].realm'

創建新領域：

curl -s -X POST \
  "http://localhost:8080/admin/realms" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "realm": "my-company",
    "enabled": true,
    "displayName": "My Company",
    "sslRequired": "external",
    "registrationAllowed": false,
    "loginWithEmailAllowed": true,
    "resetPasswordAllowed": true,
    "bruteForceProtected": true,
    "failureFactor": 5
  }'

取得領域詳細資訊：

curl -s -X GET \
  "http://localhost:8080/admin/realms/my-company" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq .

領域更新：

curl -s -X PUT \
  "http://localhost:8080/admin/realms/my-company" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "My Company Updated",
    "sslRequired": "all"
  }'

刪除領域：

curl -s -X DELETE \
  "http://localhost:8080/admin/realms/my-company" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

5.3 重要的API端點

端點	方法	描述
/管理/領域	得到	領域列表
/管理/領域	郵政	創造新境界
/管理/領域/{領域}	得到	領域詳細信息
/管理/領域/{領域}	放	更新領域
/管理/領域/{領域}	刪除	刪除領域
/管理/領域/{領域}/用戶	得到	使用者列表
/管理/領域/{領域}/用戶	郵政	創建用戶
/管理/領域/{領域}/客戶端	得到	客戶名單
/管理/領域/{領域}/角色	得到	領域角色列表
/管理/領域/{領域}/群組	得到	團體名單
/管理/領域/{領域}/事件	得到	事件日誌

5.4 使用郵差

Keycloak 為管理 REST API 提供 OpenAPI 規格。您可以匯入 Postman 或 Swagger UI 以輕鬆探索和測試 API：

# OpenAPI spec URL
http://localhost:8080/admin/realms/{realm}/.well-known/openid-configuration

6.練習練習

做以下練習來鞏固您的知識：

創建領域“dev-company”透過管理控制台進行設定：
- 顯示名稱：“開發公司”
- 使用電子郵件登入：開
- 用戶註冊：開
- 忘記密碼：開
- 驗證電子郵件：開
- 記住我：開
配置暴力偵測對於新創建的領域：
- 最多登入失敗次數：3
- 等待增量：120 秒
- 最長等待時間：600 秒
使用 kcadm.sh建立具有類似配置的領域“staging-company”
使用管理 REST API(curl) 建立領域「test-company」並透過取得領域清單進行驗證
出口將領域“dev-company”轉換為 JSON 並使用不同的名稱重新導入

七、總結

在本課中，您學習了：

如何存取和使用管理控制台
創造管理員用戶首先透過多種方法
建立並配置領域— Keycloak 中的主要管理單元
了解領域設定重要：常規、登入、電子郵件、主題、本地化、金鑰、令牌、安全防禦
使用管理CLI(kcadm.sh) 用於透過命令列進行管理
使用管理 REST API自動化管理

下一篇文章將提供詳細說明管理使用者、群組和使用者設定檔在鑰匙斗篷裡。

第 3 課：管理控制台和建立第一個領域

1. 存取管理控制台

造訪網址

建立第一個管理員用戶

管理控制台介面

2.建立第一個Realm

主域與自訂域

透過管理控制台創建領域

從 JSON 檔案建立 Realm

3.領域設置詳細信息

3.1 常規選項卡

3.3 電子郵件選項卡

3.4 主題選項卡

3.5 本地化選項卡

3.6 選項卡鍵

3.7 代幣選項卡

3.8 安全防禦選項卡

4. 管理 CLI (kcadm.sh)

4.1 配置憑證

Với Docker

4.2 使用 CLI 進行領域管理

Tạo realm với nhiều cấu hình

Output:

[ {

"realm" : "master",

"displayName" : "Keycloak",

"enabled" : true

}, {

"realm" : "my-company",

"displayName" : "My Company",

"enabled" : true

`} ]`

4.3 使用 CLI 配置領域設置

5. 管理 REST API

5.1 取得訪問令牌

5.2 使用 API 進行領域管理

5.3 重要的API端點

5.4 使用郵差

6.練習練習

七、總結

第 3 課：管理控制台和建立第一個領域

1. 存取管理控制台

造訪網址

建立第一個管理員用戶

管理控制台介面

2.建立第一個Realm

主域與自訂域

透過管理控制台創建領域

從 JSON 檔案建立 Realm

3.領域設置詳細信息

3.1 常規選項卡

3.2 登入選項卡

3.3 電子郵件選項卡

3.4 主題選項卡

3.5 本地化選項卡

3.6 選項卡鍵

3.7 代幣選項卡

3.8 安全防禦選項卡

4. 管理 CLI (kcadm.sh)

4.1 配置憑證

Với Docker

4.2 使用 CLI 進行領域管理

Tạo realm với nhiều cấu hình

Output:

[ {

"realm" : "master",

"displayName" : "Keycloak",

"enabled" : true

}, {

"realm" : "my-company",

"displayName" : "My Company",

"enabled" : true

} ]

4.3 使用 CLI 配置領域設置

5. 管理 REST API

5.1 取得訪問令牌

5.2 使用 API 進行領域管理

5.3 重要的API端點

5.4 使用郵差

6.練習練習

七、總結

`} ]`