Kết nối nhà cung cấp OpenID Connect

Hãy dùng hướng dẫn này khi nhà cung cấp danh tính của bạn nói OpenID Connect thay vì SAML. Bất kỳ issuer đạt chứng nhận OIDC nào đều dùng được — Pocket ID, Keycloak, Auth0, Zitadel, Google Workspace và nhiều nhà cung cấp tương tự khác đều theo cùng các bước; chỉ khác ở nơi nhà cung cấp của bạn hiển thị các giá trị đó.

Điều kiện tiên quyết

• một nhà cung cấp OIDC nơi bạn có thể tạo client — hãy ghi lại client ID và URL issuer của nó (địa chỉ gốc mà tài liệu .well-known/openid-configuration nằm bên dưới), cùng client secret khi client thuộc loại confidential (client PKCE công khai thì không có),
• một máy chủ Control Center mà bạn quản trị (chủ sở hữu máy chủ).

Các bước

1. Mở Cài đặt → Máy chủ → Đăng nhập một lần và chuyển sang OpenID Connect.
2. Điền URL issuer, Client ID và Client secret (tùy chọn) khi nhà cung cấp có cấp một secret. Control Center tự khám phá các endpoint từ tài liệu discovery chuẩn của issuer — không cần cấu hình riêng cho từng nhà cung cấp.
3. Tại nhà cung cấp, đăng ký redirect https://<your-server>/oidc/callback cho client đó.
4. Nếu nhóm của bạn nằm dưới một claim khác groups, hãy đặt tên Claim nhóm; ánh xạ nhóm sang vai trò nếu bạn muốn (SSO không bao giờ có thể cấp vai trò chủ sở hữu).
5. Chọn chính sách thành viên (tự động thêm vào mọi không gian làm việc, hoặc yêu cầu lời mời cho từng không gian làm việc), bật Dùng OpenID Connect để đăng nhập và nhấn Lưu kết nối.
6. Nhấn Kiểm tra kết nối — máy chủ tải tài liệu discovery của issuer và xác nhận các endpoint của nó, nên một thông báo nổi màu xanh nghĩa là mọi thứ, trừ vòng khứ hồi qua trình duyệt, đều hoạt động. Để kiểm tra cả đăng ký client, hãy dùng công cụ kiểm tra bên dưới.
7. Hãy đăng nhập thử: màn hình kết nối trên web hiển thị Đăng nhập bằng OpenID Connect, hoặc mở trực tiếp https://<your-server>/oidc/login.

Các claim (email, tên, nhóm) được máy chủ của bạn đọc từ token endpoint của issuer qua TLS — trình duyệt không bao giờ cung cấp chúng, nên không có việc xác minh chữ ký JWT cục bộ nào. Client phải được phép yêu cầu scope openid profile email, đúng những gì Control Center yêu cầu.

Vì kênh TLS đó là thứ duy nhất xác thực các claim, URL issuer phải là https — một issuer dùng văn bản thuần sẽ cho phép bất kỳ kẻ tấn công trên đường truyền nào giả mạo danh tính hàng loạt. http chỉ được chấp nhận cho issuer loopback (localhost, 127.0.0.1, ::1) và chỉ dành cho phát triển cục bộ.

Client công khai hay client confidential?

Dạng mặc định — và được khuyến nghị — là client công khai dùng luồng authorization code với PKCE (RFC 7636): code verifier dùng một lần mà máy chủ giữ sẽ thay thế secret và việc trao đổi token được gắn với yêu cầu ủy quyền đã khởi tạo nó. Không có secret nào để rò rỉ và một authorization code bị đánh cắp là vô dụng nếu thiếu verifier. Một số nhà cung cấp gọi loại client này là “SPA” hoặc “native” khi bạn tạo nó.

Nếu nhà cung cấp của bạn cấp một client confidential thay vào đó, hãy hoặc đánh dấu client là công khai tại nhà cung cấp (kiểu nào cũng vẫn bật PKCE), hoặc dán client secret vào trường Client secret (tùy chọn) của kết nối. Secret được lưu trong tệp secrets 0600 của máy chủ (không bao giờ trong cơ sở dữ liệu), được gửi tới token endpoint dưới dạng client_secret_post và không bao giờ được trả về qua RPC; để trống trường này khi lưu sẽ giữ nguyên secret đã lưu. Khi một lần đăng nhập thất bại ở bước trao đổi token, log máy chủ ghi rõ lỗi của chính nhà cung cấp (invalid_client gần như luôn nghĩa là secret bị thiếu hoặc sai).

Khả năng truy cập

Bản thân việc đăng nhập diễn ra qua trình duyệt: issuer chỉ chuyển hướng trình duyệt của người dùng trở lại /oidc/callback và máy chủ của bạn thực hiện một lệnh gọi HTTPS ra ngoài tới token endpoint — không cần kết nối vào từ phía issuer, nên một máy chủ sau NAT vẫn hoạt động miễn là trình duyệt của người dùng truy cập được nó (LAN, VPN, Tailscale hoặc một tunnel). Cấp phát SCIM là ngoại lệ: IdP gọi trực tiếp máy chủ của bạn, việc này cần một tunnel hoặc một URL công khai — xem cấp phát người dùng bằng SCIM.

Kiểm tra cấu hình của bạn ngay trên trang này

Công cụ kiểm tra bên dưới chạy trong trình duyệt của bạn. Nó tải trực tiếp tài liệu discovery của issuer, nên trang web này không bao giờ thấy tài liệu đó, rồi áp dụng các quy tắc của máy chủ: một issuer https khớp với tài liệu, các endpoint nằm trên origin của chính issuer, PKCE S256 và phương thức xác thực token mà loại client của bạn cần. Với một client ID và địa chỉ máy chủ, nó có thể mở một lần đăng nhập thử để cho biết client cùng redirect URI của nó đã được đăng ký hay chưa. Nó không bao giờ hỏi client secret.

Runs in your browserYour browser fetches the discovery document straight from your issuer. Add a server address and it also asks that server which sign-in methods it offers. This site never receives what you type.

Issuer URL

Client ID (optional)

Needed for the test sign-in.

Groups claim (optional)

Client type

Public, PKCE only Confidential, has a client secret

Never paste the secret here. The check only needs to know whether one exists.

Server address (optional)

The address your users open. Adds a reachability check and a test sign-in.

Paste the discovery document instead

Discovery document JSON

For providers that block other sites from reading it.

Check issuer