xDev Asia

建立和管理使用者、設定憑證、使用者屬性架構、使用者設定檔配置、自訂屬性和驗證器、建立群組和子群組、群組屬性、群組角色對應、使用者自行註冊、所需操作、模擬和個人資料管理。

Keycloak領域中使用者、群組和角色的分層模型

1. 管理用戶

使用者是Keycloak的中心實體－代表可以登入系統的使用者。每個使用者都屬於特定領域，並且可以具有屬性、憑證、角色和群組成員資格。

1.1 透過管理控制台建立用戶

選擇領域（例如：我的公司) 來自領域選擇器
點選使用者在側邊欄中
點選新增用戶
填寫資料：
- 使用者名稱: 約翰·多伊（必填）
- 電子郵件: [email protected]
- 名: 約翰
- 姓: 美國能源部
- 電子郵件已驗證：ON（如果電子郵件已通過身份驗證）
- 啟用：在
點選創造

1.2 透過管理 CLI 創建用戶

# Tạo user cơ bản
bin/kcadm.sh create users \
  -r my-company \
  -s username=john.doe \
  -s [email protected] \
  -s firstName=John \
  -s lastName=Doe \
  -s enabled=true \
  -s emailVerified=true
Lấy user ID vừa tạo
USER_ID=$(bin/kcadm.sh get users -r my-company -q username=john.doe --fields id --format csv --noquotes)
echo "User ID: $USER_ID"

1.3 透過REST API創建用戶

# Tạo user mới
curl -s -X POST \
  "http://localhost:8080/admin/realms/my-company/users" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john.doe",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "enabled": true,
    "emailVerified": true,
    "attributes": {
      "department": ["Engineering"],
      "employee_id": ["EMP001"]
    }
  }'
Lấy user ID từ response header Location
Location: http://localhost:8080/admin/realms/my-company/users/{user-id}

2. 設定憑證

2.1 透過管理控制台設定密碼

進入使用者→ 選擇使用者 → 選項卡證書
點選設定密碼
輸入新密碼
暫時的：ON（使用者首次登入時必須更改密碼）或OFF（固定密碼）
點選節省

2.2 透過CLI設定密碼

# Đặt password cố định bin/kcadm.sh set-password \ -r my-company \ --username john.doe \ --new-password "SecureP@ssw0rd!" Đặt password tạm thời (bắt đổi khi login)

bin/kcadm.sh set-password -r my-company --username john.doe --new-password "TempP@ss123" --temporary

2.3 透過REST API設定密碼

# Lấy user ID USER_ID=$(curl -s -X GET \ "http://localhost:8080/admin/realms/my-company/users?username=john.doe" \ -H "Authorization: Bearer $ACCESS_TOKEN" | jq -r '.[0].id') Đặt password

curl -s -X PUT "http://localhost:8080/admin/realms/my-company/users/$USER_ID/reset-password" -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{ "type": "password", "value": "SecureP@ssw0rd!", "temporary": false }'

2.4 密碼策略

配置領域的密碼策略驗證 → 政策 → 密碼政策:

政策	描述	範例值
最小長度	最小長度	8
大寫字符	需要大寫字母	1
小寫字符	需要小寫字母	1
數位	請求號碼	1
特殊字元	需要特殊字符	1
不是使用者名稱	密碼不能與使用者名稱相同	-
不是電子郵件	密碼不得與電子郵件匹配	-
密碼歷史記錄	不要重複使用舊密碼	3
密碼過期	密碼過期時間（天）	90
哈希演算法	演算法哈希密碼	氬氣2
哈希迭代	哈希輪數	5（氬氣2）

透過 CLI 設定：

bin/kcadm.sh update realms/my-company \
  -s 'passwordPolicy="length(8) and upperCase(1) and lowerCase(1) and digits(1) and specialChars(1) and notUsername and passwordHistory(3)"'

3. 使用者簡介

使用者資料是一項功能，可讓管理員定義使用者屬性的架構 - 控制使用者擁有哪些屬性、如何驗證這些屬性以及如何在介面上顯示這些屬性。

3.1 啟動用戶資料

從 Keycloak 24+ 開始，預設啟用使用者設定檔。對於舊版本：

進入領域設定 → 一般的
尋找已啟用使用者設定檔：在

啟用後，即可訪問領域設定 → 使用者資料進行配置。

3.2 屬性模式定義

每個屬性都有以下配置：

姓名— 屬性名稱（小寫，用於 API）
顯示名稱— UI 顯示名稱（支援 i18n：${個人資料.屬性.部門})
權限— 誰可以檢視/編輯（管理員、使用者）
驗證— 值驗證規則
註解— UI 渲染的元數據
必需的— 使用者、管理員或兩者都需要
多值— 允許多個值

3.3 內建屬性

Keycloak 具有可用屬性：

屬性	描述	預設
使用者名稱.使用者名稱	登入名	必需的、獨特的
電子郵件	電子郵件	必需（可以關閉）
名	姓名	必需的
姓	姓	必需的

3.4 建立自訂屬性

建立屬性的範例電話號碼:

進入領域設定 → 使用者資料
點選建立屬性
配置：
- 姓名: 電話號碼
- 顯示名稱: 電話號碼
- 屬性組:(選擇或建立新的)
- 啟用時間：總是
- 必需的：用戶必填

3.5 驗證器

Keycloak提供了許多驗證器來檢查屬性值：

驗證器	描述	配置範例
長度。長度	長度限制	最小值：3，最大值：50
電子郵件	檢查電子郵件格式	-
圖案。圖案	檢查正規表示式模式	^\\+[0-9]{10,15}$
整數	檢查整數	最小值：0，最大值：999999
雙倍的	檢查真實數字	最小值：0.0，最大值：100.0
烏裡	檢查 URL 是否有效	-
選項	列表中的限制值	[“越南”，“美國”，“日本”]
人名禁止字符	阻止名稱中的特殊字符	-
使用者名稱禁止字符	封鎖使用者名稱中的特殊字符	-
多值的	驗證值的數量	最小值：1，最大值：5

屬性配置範例電話號碼透過 JSON（使用者設定檔標籤 → JSON 編輯器）：

{
  "attributes": [
    {
      "name": "phone_number",
      "displayName": "Phone Number",
      "validations": {
        "length": {
          "min": 10,
          "max": 15
        },
        "pattern": {
          "pattern": "^\\+[0-9]{10,15}$",
          "error-message": "Phone number must start with + and contain 10-15 digits"
        }
      },
      "required": {
        "roles": ["user"]
      },
      "permissions": {
        "view": ["admin", "user"],
        "edit": ["admin", "user"]
      },
      "annotations": {
        "inputType": "tel",
        "inputHelperTextBefore": "Enter your phone number with country code (e.g., +84901234567)"
      }
    }
  ]
}

3.6 UI渲染的註解

註釋允許自訂屬性在註冊/帳戶頁面上的顯示方式：

註解	描述	價值
輸入類型	HTML 輸入類型	文字、電子郵件、電話、號碼、日期、選擇、多選、文字區域、html5-*
輸入說明文字之前	幫助文字顯示在輸入之前	文字字串
輸入幫助文字之後	輸入後顯示幫助文字	文字字串
來自驗證的輸入選項	從驗證器取得選項	驗證名稱（例如“選項”）

3.7 漸進式分析

漸進式分析允許逐步收集用戶信息，而不是在註冊時詢問所有信息：

建立屬性必需的 → 用戶需要：在
當使用者登入時，如果該屬性沒有值，Keycloak將顯示一個要求填寫的表單
結合“啟用時間”範圍— 僅當客戶端要求特定範圍時才需要該屬性

例如：屬性電話號碼僅當客戶請求範圍時才需要電話。電話:

{
  "name": "phone_number",
  "required": {
    "roles": ["user"],
    "scopes": ["phone"]
  }
}

4. 小組和小組

群組有助於組織使用者並將角色和屬性一次性應用到使用者群組，而不是單獨分配每個使用者。

4.1 透過管理控制台建立群組

點選團體在側邊欄中
點選建立群組
進入姓名: 工程
點選創造

4.2 建立子群組

子組繼承父組的屬性和角色映射：

點選群組工程
點選建立子群組
輸入姓名：後端, 前端, 開發營運

群組結構範例：

Engineering/ ├── Backend/ │ ├── Java Team │ └── Go Team ├── Frontend/ │ ├── Web Team │ └── Mobile Team └── DevOps/ ├── SRE └── Platform

Operations/ ├── HR ├── Finance └── Legal

4.3 透過 CLI 建立群組

# Tạo top-level group
bin/kcadm.sh create groups -r my-company -s name="Engineering"
Lấy group ID
GROUP_ID=$(bin/kcadm.sh get groups -r my-company --fields id,name | jq -r '.[] | select(.name=="Engineering") | .id')
Tạo sub-group
bin/kcadm.sh create groups/$GROUP_ID/children -r my-company -s name="Backend"
bin/kcadm.sh create groups/$GROUP_ID/children -r my-company -s name="Frontend"
bin/kcadm.sh create groups/$GROUP_ID/children -r my-company -s name="DevOps"

4.4 組屬性

群組可以包含鍵值屬性－對於元資料、群組配置有用：

# Thêm attributes cho group
bin/kcadm.sh update groups/$GROUP_ID -r my-company \
  -s 'attributes={"cost_center":["CC-ENG-001"],"location":["HCM","HN"]}'

透過管理控制台：按一下群組 → 選項卡屬性→ 新增鍵值對。

4.5 新增用戶到群組

# Qua Admin Console: # Users → chọn user → tab Groups → Join group → chọn group Qua CLI USER_ID=$(bin/kcadm.sh get users -r my-company -q username=john.doe --fields id --format csv --noquotes) bin/kcadm.sh update users/$USER_ID/groups/$GROUP_ID -r my-company -s realm=my-company -s userId=$USER_ID -s groupId=$GROUP_ID -n Qua REST API

curl -s -X PUT "http://localhost:8080/admin/realms/my-company/users/$USER_ID/groups/$GROUP_ID" -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json"

4.6 預設組

建立帳戶或註冊時預設群組會自動新增使用者：

進入團體
選擇要設定為預設的群組
或者進來領域設定 → 用戶註冊 → 預設群組

# Qua CLI
bin/kcadm.sh update realms/my-company -s 'defaultGroups=["/Engineering/Backend"]'

5. 所需採取的行動

必需的操作是使用者在成功登入之前必須執行的操作。

5.1 可用的所需操作列表

行動	描述
更新密碼	需要修改密碼
驗證信箱	信箱認證
設定一次性密碼	設定 OTP（TOTP/HOTP）
更新個人資料	更新個人訊息
條款與條件	接受使用條款
設定WebAuthn	WebAuthn 設備註冊
更新用戶區域設定	選擇語言
刪除憑證	刪除舊憑證

5.2 為使用者指派所需的操作

# Qua Admin Console: # Users → chọn user → tab Details → Required user actions → chọn actions Qua CLI bin/kcadm.sh update users/$USER_ID -r my-company -s 'requiredActions=["UPDATE_PASSWORD","VERIFY_EMAIL","CONFIGURE_TOTP"]' Qua REST API

curl -s -X PUT "http://localhost:8080/admin/realms/my-company/users/$USER_ID" -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{ "requiredActions": ["UPDATE_PASSWORD", "VERIFY_EMAIL"] }'

5.3 預設所需操作

為所有新用戶配置預設所需的操作驗證 → 所需採取的行動:

打開列設定為預設操作為了想要的動作
每個新用戶都會自動指派預設操作

6. 用戶自助註冊

6.1 啟用自註冊

進入領域設定 → 登入
打開用戶註冊：在
登入頁面將顯示“註冊”鏈接

6.2 reCAPTCHA 註冊

為了保護您的註冊表單免受機器人攻擊，請啟用 reCAPTCHA：

註冊 Google reCAPTCHA：https://www.google.com/recaptcha
進入驗證 → 流量 → 登記
尋找步驟驗證碼→ 從停用切換到必需的
點擊齒輪圖示→進入站點密鑰和秘密鑰匙來自Google

6.3 客製化註冊表

使用使用者設定文件，您可以控制註冊表單上顯示哪些欄位：

屬性與用戶需要: ON 將會出現在表格上
顯示順序根據排序順序在使用者設定檔配置中
使用屬性組將相關欄位進行分組

7. 冒充

模擬允許管理員以不同用戶的身份「假裝」登錄，這對於調試和支援很有用。

7.1 使用模擬

進入使用者→ 找到您需要模擬的用戶
點選下拉選單（烤肉串選單）→模仿
瀏覽器將開啟一個新分頁以該使用者名稱登入
所有操作均記錄在具有事件類型的事件中模仿

7.2 透過 REST API 進行模擬

curl -s -X POST \
  "http://localhost:8080/admin/realms/my-company/users/$USER_ID/impersonation" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json"

安全說明：

只有使用者才有角色冒充在領域內領域管理可以冒充
所有模擬事件都會被記錄下來—對於審計很重要
在生產中，將權限模擬限制為僅超級管理員

8.用戶的進階搜尋與管理

8.1 搜尋用戶

# Tìm theo username bin/kcadm.sh get users -r my-company -q username=john Tìm theo email bin/kcadm.sh get users -r my-company -q email=[email protected] Tìm theo attribute bin/kcadm.sh get users -r my-company -q "q=department:Engineering" Tìm với pagination bin/kcadm.sh get users -r my-company --offset 0 --limit 20 REST API - tìm với nhiều tiêu chí

curl -s -X GET "http://localhost:8080/admin/realms/my-company/users?search=john&max=20&first=0" -H "Authorization: Bearer $ACCESS_TOKEN" | jq '.[].username'

8.2 刪除用戶

# Qua CLI bin/kcadm.sh delete users/$USER_ID -r my-company Qua REST API

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

8.3 停用用戶（而非刪除）

# Disable user - vẫn giữ data nhưng không cho login
bin/kcadm.sh update users/$USER_ID -r my-company -s enabled=false

8.4 批量操作

從 CSV 建立多個使用者的範例腳本：

#!/bin/bash
# bulk-create-users.sh
REALM="my-company"
while IFS=',' read -r username email firstName lastName department; do
bin/kcadm.sh create users -r $REALM 

-s username="$username" 

-s email="$email" 

-s firstName="$firstName" 

-s lastName="$lastName" 

-s enabled=true 

-s emailVerified=true 

-s "attributes={"department":["$department"]}"
bin/kcadm.sh set-password -r $REALM 

--username "$username" 

--new-password "Welcome@123" 

--temporary
echo "Created user: $username"
done < users.csv

9. 個人資料管理

Keycloak 透過以下方式支援 GDPR 合規性：帳戶控制台，允許使用者：

查看個人資訊— 電子郵件、姓名、屬性
編輯訊息— 取決於使用者設定檔中的權限
查看會議— 活動登入會話
管理設備— 檢視並撤銷已登入的設備
查看應用— 已被授予存取權限的應用程式
刪除帳戶— 自行刪除您的帳戶（如果允許）

帳戶控制台網址：

http://localhost:8080/realms/{realm}/account

啟用帳戶刪除：

進入驗證 → 所需採取的行動
啟用操作刪除帳戶
進入領域設定 → 登入→ 打開刪除帳戶

10.練習練習

建立用戶個人資料對於領域我的公司具有自訂屬性：
- 電話號碼（必需，國際格式的正規表示式驗證器）
- 部門（必填，選項：工程、人力資源、財務、行銷）
- 員工 ID（僅限管理員編輯，模式：EMP-[0-9]{4}）
建立群組層次結構:
- 工程 → 後端、前端、DevOps
- 營運 → 人力資源、財務
創建5個用戶透過CLI，每個使用者屬於不同的群組，臨時密碼
開啟自助註冊具有電子郵件驗證和註冊測試
設定密碼策略：最少 10 個字元、1 個大寫字母、1 個數字、1 個特殊字元、5 個歷史記錄、90 天過期

11. 總結

在本課中，您學習了：

創建和管理使用者透過管理控制台、CLI 和 REST API
建立證書和密碼原則
使用使用者資料使用驗證器和註解定義屬性模式
創造團體和亞組具有層次結構、屬性和預設群組
配置所需採取的行動用戶需要的
打開自助註冊使用驗證碼
使用冒充用於偵錯
管理個人資料遵守 GDPR

下一篇文章將提供說明角色、權限和存取控制在鑰匙斗篷裡。

第 4 課：管理使用者、群組和使用者設定檔

1. 管理用戶

1.1 透過管理控制台建立用戶

1.2 透過管理 CLI 創建用戶

Lấy user ID vừa tạo

1.3 透過REST API創建用戶

Lấy user ID từ response header Location

Location: http://localhost:8080/admin/realms/my-company/users/{user-id}

2. 設定憑證

2.1 透過管理控制台設定密碼

2.2 透過CLI設定密碼

Đặt password tạm thời (bắt đổi khi login)

2.3 透過REST API設定密碼

Đặt password

2.4 密碼策略

3. 使用者簡介

3.1 啟動用戶資料

3.2 屬性模式定義

3.3 內建屬性

3.4 建立自訂屬性

3.5 驗證器

3.6 UI渲染的註解

3.7 漸進式分析

4. 小組和小組

4.1 透過管理控制台建立群組

4.2 建立子群組

4.3 透過 CLI 建立群組

Lấy group ID

Tạo sub-group

4.4 組屬性

4.5 新增用戶到群組

Qua CLI

Qua REST API

4.6 預設組

5. 所需採取的行動

5.1 可用的所需操作列表

5.2 為使用者指派所需的操作

Qua CLI

Qua REST API

5.3 預設所需操作

6. 用戶自助註冊

6.1 啟用自註冊

6.2 reCAPTCHA 註冊

6.3 客製化註冊表

7. 冒充

7.1 使用模擬

7.2 透過 REST API 進行模擬

8.用戶的進階搜尋與管理

8.1 搜尋用戶

Tìm theo email

Tìm theo attribute

Tìm với pagination

REST API - tìm với nhiều tiêu chí

8.2 刪除用戶

Qua REST API

8.3 停用用戶（而非刪除）

8.4 批量操作

9. 個人資料管理

10.練習練習

11. 總結

`Location: http://localhost:8080/admin/realms/my-company/users/{user-id}`