Chuyển tới nội dung chính

Cấu hình xác thực OIDC cho cluster

Thay vì dùng chung 1 kubeconfig admin (client certificate) cho cả team, bạn có thể kết nối cluster với Identity Provider (IdP) sẵn có của công ty — Keycloak, Azure AD, Okta, hoặc bất kỳ IdP chuẩn OIDC nào. Sau khi cấu hình, mỗi thành viên đăng nhập cluster bằng chính tài khoản SSO của họ.

ghi chú

Tính năng này chỉ xử lý phần xác thực (authentication: xác minh người dùng là ai). Bạn vẫn cần tự cấu hình phân quyền (authorization: người dùng được làm gì) bằng Kubernetes RBAC. Xem Đăng nhập cluster bằng SSO để có ví dụ RBAC. Sau khi bật OIDC, người dùng đăng nhập thành công nhưng chưa có RoleBinding sẽ nhận lỗi 403 Forbidden khi chạy lệnh như kubectl get pods. Đây là hành vi đúng theo thiết kế, không phải lỗi cấu hình.

Người thực hiện cấu hình này là Cluster Admin đang có sẵn kubeconfig admin. Áp dụng cấu hình không làm restart hay gây downtime cluster, và bạn có thể cập nhật hoặc gỡ bỏ cấu hình bất kỳ lúc nào.

  1. Mở mục SSO / OIDC.

    Vào Cluster Detail của cluster muốn cấu hình, cuộn tới mục SSO / OIDC (dưới mục Cluster Endpoint Access, status hiển thị Disabled cho tới khi bạn cấu hình), rồi chọn Edit.

    Mục SSO / OIDC trên trang Cluster Detail, tab Essential Properties, với badge beta và Optional, Status: Disabled, nút Edit

  2. Điền thông tin kết nối cơ bản.

    Chọn Edit sẽ mở form cấu hình SSO / OIDC, với toggle Enable SSO / OIDC ở trạng thái OFF theo mặc định. Gạt toggle sang ON (các field bên dưới sẽ được kích hoạt), sau đó điền:

    • Issuer URL (bắt buộc): địa chỉ gốc của Identity Provider — nơi cluster gửi yêu cầu xác minh token đăng nhập. Nhập URL đầy đủ bắt đầu bằng https://, không kèm dấu ? (query string) hay # (fragment) ở cuối. Thường bạn lấy nguyên URL này từ trang "Realm settings" hoặc "OIDC discovery" của IdP.
      • Keycloak: https://keycloak.mycompany.com/realms/production
      • Azure AD: https://login.microsoftonline.com/{tenant-id}/v2.0
      • Okta: https://mycompany.okta.com/oauth2/default
    • Client ID (bắt buộc): định danh của "ứng dụng" (chính là cluster này) đã đăng ký trên IdP, ví dụ trong Keycloak, ở mục Clients → Create client. Chỉ nhập 1 giá trị duy nhất — hệ thống hiện chưa hỗ trợ nhiều Client ID cho 1 cluster.
    • Username Claim (tùy chọn): tên field trong token đăng nhập dùng làm username Kubernetes. Mặc định là email. Xóa trắng field này nếu muốn hệ thống dùng sub (ID nội bộ của IdP, thường là chuỗi UUID khó đọc) thay thế. Nên chọn claim có giá trị ổn định theo thời gian — nếu email người dùng đổi, RBAC binding cũ theo giá trị cũ sẽ mất hiệu lực.
    • Groups Claim (tùy chọn): tên field trong token chứa danh sách group mà người dùng thuộc về, dùng để phân quyền theo nhóm thay vì từng người lẻ. Giá trị thường gặp: groups (mặc định Keycloak/Okta) hoặc client_roles (Keycloak client roles). Để trống để tắt phân quyền theo nhóm cho cluster này.

    Form SSO / OIDC đã mở, toggle ON, 4 field Issuer URL / Client ID / Username Claim / Groups Claim

    mẹo

    Control plane của cluster cần có đường truyền mạng tới Issuer URL. Nếu IdP nằm trong mạng nội bộ công ty, hãy xác nhận cluster truy cập được trước khi lưu.

  3. Cấu hình nâng cao (tùy chọn).

    Cả 4 field dưới đây đều không bắt buộc và độc lập với nhau — điền field này không yêu cầu phải điền field kia.

    • Username Prefix: chuỗi ký tự ngắn, thường kết thúc bằng dấu :, tự động thêm vào phía trước giá trị Username Claim khi map vào Kubernetes. Ví dụ, oidc: biến email = an.nguyen@mycompany.com thành username Kubernetes oidc:an.nguyen@mycompany.com. Cách này giúp phân biệt rõ user đăng nhập qua SSO với user hệ thống hoặc user tạo theo cách khác. Không được bắt đầu bằng system: — tiền tố này dành riêng cho nhóm hệ thống Kubernetes. Nếu để trống, Kubernetes dùng thẳng giá trị claim gốc làm username, dễ trùng với user khác.
    • Groups Prefix: tương tự Username Prefix nhưng áp dụng cho tên group — ví dụ oidc: biến group gốc platform-admins thành oidc:platform-admins trong Kubernetes. Áp dụng cùng giới hạn system: như trên.
    • CA Bundle (PEM): chứng chỉ CA để cluster tin tưởng kết nối HTTPS tới IdP. Chỉ cần thiết nếu IdP dùng chứng chỉ tự ký hoặc CA nội bộ công ty — để trống nếu IdP dùng CA public (Let's Encrypt, DigiCert...). Dán toàn bộ nội dung file .pem hoặc .crt, đúng định dạng bắt đầu bằng -----BEGIN CERTIFICATE----- và kết thúc bằng -----END CERTIFICATE-----, phần thân giữa là chuỗi base64 hợp lệ.
    • Required Claims: danh sách điều kiện bắt buộc. Token đăng nhập phải chứa đúng giá trị ở claim được khai mới được chấp nhận, ngay cả khi người dùng có tài khoản hợp lệ trên IdP. Chọn + Add claim và điền Claim (tên field trong token) và Value (giá trị bắt buộc phải khớp) cho mỗi dòng — mỗi dòng phải điền đủ cả 2 ô, không được khai trùng tên Claim ở 2 dòng khác nhau. Ví dụ: Claim hd, Value mycompany.com, chỉ tài khoản Google Workspace thuộc domain mycompany.com mới đăng nhập được, dù IdP cũng phục vụ cả tài khoản Gmail cá nhân.

    Mục Advanced mở rộng, 4 field Username Prefix / Groups Prefix / CA Bundle / Required Claims

  4. Chọn Save.

    Cluster chuyển sang trạng thái Processing trong khi áp dụng thay đổi — theo dõi qua status chung ở đầu trang Cluster Detail. Khi cluster về lại trạng thái Succeeded/Running, cấu hình đã có hiệu lực.

    Nút Save cho cấu hình SSO / OIDC

Kết quả​

Team bạn giờ có thể lấy kubeconfig dùng kubelogin/plugin OIDC, đăng nhập cluster bằng tài khoản SSO riêng thay vì dùng chung kubeconfig admin. Bạn vẫn cần tự tạo RBAC binding (RoleBinding/ClusterRoleBinding) khớp đúng với username hoặc group, kèm prefix nếu có, bằng kubeconfig admin. Bước này không được Portal tự động hóa.

Xem Đăng nhập cluster bằng SSO để biết các bước cấu hình phía người dùng cuối và ví dụ RBAC.

Cập nhật hoặc gỡ bỏ cấu hình​

Chọn Edit trên mục SSO / OIDC bất kỳ lúc nào để thay đổi cấu hình hiện có:

  • Cập nhật giá trị — sửa field bất kỳ (ví dụ đổi Issuer URL hoặc Client ID sau khi IdP thay đổi), rồi chọn Save.

  • Gỡ bỏ cấu hình — gạt toggle Enable SSO / OIDC sang OFF, rồi chọn Save. Popup Remove SSO / OIDC configuration? cảnh báo mọi session đăng nhập OIDC hiện tại sẽ ngưng hoạt động khi thay đổi có hiệu lực (vài phút sau), và kubeconfig admin (client certificate) không bị ảnh hưởng. Chọn Confirm removal để tiếp tục, hoặc Cancel để hủy.

    Popup xác nhận Remove SSO / OIDC configuration, hiện ra khi lưu lúc toggle Enable SSO / OIDC đang tắt

Gỡ bỏ cấu hình không ảnh hưởng tới kubeconfig admin — bạn luôn có thể dùng lại kubeconfig admin.

Vấn đề thường gặp​

Vấn đềNguyên nhân / cách xử lý
"This feature isn't available for your account yet"Tài khoản chưa được cấp quyền beta_user — liên hệ team FKE để đăng ký.
"This cluster is still processing" khi bấm Save hoặc xóaCluster đang xử lý một thay đổi khác — đợi vài phút rồi thử lại.
Đăng nhập SSO bị từ chối dù cấu hình đúngKiểm tra RBAC binding đã khớp đúng username/group (kèm đúng prefix nếu có) chưa; kiểm tra token có đủ Required Claims đã khai không.
Không cho nhập Prefix bắt đầu bằng system:Đây là giới hạn cố ý — tránh trùng với group hệ thống Kubernetes, gây rủi ro leo thang quyền.
Một field (Issuer URL, CA Bundle...) sai định dạng nhưng không hiện dòng báo lỗiHạn chế đã biết ở bản beta hiện tại — field chỉ đổi viền đỏ, chưa hiện text mô tả. Kiểm tra lại đúng định dạng yêu cầu: HTTPS không kèm query/fragment cho Issuer URL, đúng PEM cho CA Bundle.

Mẹo​

  • Thử kết nối IdP với 1 cluster staging trước khi áp dụng cho cluster production của cả team.
  • Giữ lại kubeconfig admin như phương án dự phòng — không bị ảnh hưởng khi bật/tắt OIDC.
  • Dùng Required Claims để giới hạn phạm vi đăng nhập — ví dụ chỉ chấp nhận token có hd = yourcompany.com, tránh user ngoài công ty (nếu IdP dùng chung nhiều tổ chức) đăng nhập được.
  • Đặt Username Prefix rõ ràng (ví dụ oidc:) để dễ phân biệt user SSO với user hệ thống khi xem log/audit.