realm-management quyết định agent thấy và thay đổi được gì.
Điều kiện tiên quyết
- Một máy chủ Keycloak mà CloudThinker truy cập được qua mạng. Với máy chủ nằm sau firewall, xem Truy cập dịch vụ nội bộ. CloudThinker không chặn
http, nhưng khi đó client secret được gửi đi không mã hóa, nên hãy dùnghttps. - Một quản trị viên có quyền tạo client trong realm đích và gán service account role cho client đó.
- Tên realm.
- Role Admin trong workspace CloudThinker, role có quyền thêm và sửa kết nối. Xem Roles.
Mỗi workspace có một kết nối Keycloak, và kết nối đó nhắm tới một realm. Agent lấy token từ
<KEYCLOAK_URL>/realms/<KEYCLOAK_REALM>/protocol/openid-connect/token, nên base URL phải là phần đứng trước /realms.Thiết lập
Cả hai tab đều tạo cùng một thứ: confidential client têncloudthinker-svc đã bật service account, với các role realm-management gán cho service account đó.
- Admin console
- kcadm.sh
Dùng được cho Keycloak tự vận hành và Keycloak được quản lý như Phase Two.
1
Tạo client
Trong admin console, chuyển sang realm của bạn, mở Clients và chọn Create client. Đặt Client ID là
cloudthinker-svc rồi chọn Next. Bật Client authentication, chọn Service accounts roles, và để tắt các luồng còn lại. Chọn Next, rồi Save.2
Gán role realm-management
Mở client, vào Service accounts roles và chọn Assign role. Lọc theo client, tìm
realm-management và chọn role. Để rà soát chỉ đọc, chọn view-realm, view-users, query-users, view-clients, query-clients và query-groups. Để cho phép thay đổi, xem Quyền yêu cầu. Danh sách có thể dài hơn một trang.3
Sao chép client secret
Trên cùng client đó, mở Credentials và sao chép Client Secret.
1
Thêm kết nối trong CloudThinker
Mở More → Workspace settings → Connections, chọn Keycloak, và điền các trường trong Chi tiết kết nối. Nhấn Connect.Trạng thái thành công: kết nối hiện Connecting và Verifying, rồi Connected. CloudThinker đăng nhập bằng service account và đếm số user trong realm, qua đó chứng minh cả secret lẫn role
view-users đều đúng.Chi tiết kết nối
Với Phase Two, sao chép base URL từ thẻ realm trên dashboard Phase Two: chọn Details và sao chép Host.
Quyền yêu cầu
Gán client rolerealm-management cho service account. Chọn tập role hẹp nhất đủ cho nhu cầu của bạn.
realm-admin bao gồm mọi role ở trên. Đây là lựa chọn nhanh nhất nhưng cũng rộng nhất, nên chỉ dùng khi agent cần quản lý toàn bộ realm.
Khả năng của agent
Thao tác đọc chạy không cần hỏi. Allow writes trên bảng chi tiết của kết nối mặc định bật; tắt đi để từ chối mọi thay đổi. Mọi thay đổi đều đi qua Approvals trước.
Mọi thay đổi do agent thực hiện đều đi qua Approvals của workspace trước. Ở chế độ mặc định Auto · Rules + AI · Ask me, AI judgment có thể cho một thay đổi an toàn chạy mà không cần hỏi. Allow Rule cũng vậy, sau khi CloudThinker bật Rule enforcement cho workspace của bạn. Chọn Manual nếu bạn muốn tự phê duyệt mọi thay đổi.
Thao tác đọc danh sách mặc định trả về tối đa 100 mục, nên với realm lớn, hãy hỏi về một group, một client hoặc một username thay vì toàn bộ.
CloudThinker chuyển mật khẩu user mới cho Keycloak qua standard input, nên mật khẩu không xuất hiện trong log lệnh. Mật khẩu vẫn có thể hiện trong cuộc hội thoại nếu bạn gõ vào đó, nên tốt hơn là để user tự đặt lại mật khẩu qua Keycloak.
Xác minh kết nối
view-users. Để kiểm tra cả quyền truy cập client, hãy hỏi client nào đang bật direct access grants, câu hỏi này cần view-clients.
Ví dụ prompt
Khắc phục sự cố
Failed to connect to Keycloak
Failed to connect to Keycloak
CloudThinker không lấy được token hoặc không đếm được user. Kiểm tra theo thứ tự:
- KEYCLOAK_URL truy cập được từ CloudThinker và dừng trước
/realms. Thêm/authnếu máy chủ phục vụ dưới đường dẫn đó. - KEYCLOAK_REALM là realm nơi bạn đã tạo client. Tên phân biệt chữ hoa chữ thường.
- Client authentication và Service accounts roles đã bật cho client, và secret được sao chép đầy đủ.
- Service account có
view-users.
Client không có secret
Client không có secret
Client đang là public. Bật Client authentication, hoặc đặt
publicClient=false bằng kcadm.sh, rồi sao chép secret từ Credentials.403 Forbidden ở một số câu hỏi
403 Forbidden ở một số câu hỏi
Token hoạt động, nhưng service account thiếu role cho endpoint đó. Câu hỏi đọc cần role
view-* hoặc query-*, còn thay đổi cần role manage-*. Thêm role theo Quyền yêu cầu. Role áp dụng từ token kế tiếp, nên hãy hỏi lại.Agent chỉ hiện 100 user
Agent chỉ hiện 100 user
Thao tác đọc danh sách mặc định dừng ở 100. Hỏi về một username hoặc group cụ thể, hoặc yêu cầu agent phân trang để lấy thêm kết quả.
Bảo mật
- Quyền tối thiểu — chỉ cấp các quyền mà agent cần cho trường hợp sử dụng của bạn; bắt đầu với quyền chỉ đọc và mở rộng sau.
- Chỉ đọc theo mặc định — sử dụng thông tin xác thực chỉ đọc trừ khi bạn muốn agent thực hiện thay đổi qua kết nối này.
- Xoay vòng thông tin xác thực — xoay vòng khóa và token theo lịch trình thông thường của bạn; CloudThinker sẽ lấy giá trị mới khi bạn cập nhật kết nối.
- Thu hồi khi bàn giao — xóa thông tin xác thực tại nhà cung cấp khi bạn xóa một kết nối hoặc khi đồng nghiệp rời nhóm.
- Dùng client riêng: chỉ dùng
cloudthinker-svccho CloudThinker, để bạn thu hồi được mà không ảnh hưởng ứng dụng khác. - Xoay vòng secret: kết nối hỏng ngay khi bạn tạo lại secret, nên hãy làm cả hai bước cùng lúc. Keycloak là dịch vụ chỉ có một kết nối, nên dòng của nó không có biểu tượng bút chì. Tạo lại secret trong Credentials của Keycloak, rồi mở More → Workspace settings → Connections và chọn Keycloak. Khi kết nối hiện Error, nhấn Replace credentials, nhấn Replace… bên cạnh thông tin xác thực đã lưu, dán KEYCLOAK_CLIENT_SECRET mới và nhấn Save and test. Xem Xoay vòng thông tin xác thực.
- Tránh dùng
realm-adminđể rà soát: các role chỉ đọc đã đủ cho mọi câu hỏi ở các dòng đọc phía trên.
Liên quan
Approvals
Quyết định thay đổi Keycloak nào được chạy, phải chờ một người, hoặc bị từ chối.
Kết nối
Xem mọi dịch vụ bạn kết nối được và cách trạng thái kết nối hoạt động.