Dùng nhà cung cấp SAML qua OIDC
Tara không hỗ trợ SAML. SSO của tổ chức chỉ dùng OpenID Connect (OIDC). Hầu hết nhà cung cấp danh tính (IdP) mà người ta gọi là "SAML" cũng có OIDC. Nếu IdP của bạn có, hãy đăng ký Tara làm ứng dụng OIDC ở đó. Nếu IdP chỉ có SAML, đặt Keycloak ở giữa: Keycloak đăng nhập với IdP SAML của bạn, còn Tara đăng nhập với Keycloak.
Trang này liệt kê những gì Tara cần, rồi hướng dẫn từng nhà cung cấp. Phần bên Tara (dán giá trị ở đâu, chạy test, role, Require SSO) xem SSO của tổ chức (OIDC).
Tara cần gì
| Mục | Đưa gì cho Tara |
|---|---|
| Callback (redirect) URI | https://tara.phillipcli.cloud/auth/sso/<org>/callback, trong đó <org> là slug tổ chức. Đăng ký đúng nguyên văn ở nhà cung cấp. |
| Issuer | Địa chỉ issuer của nhà cung cấp. Tara đọc <issuer>/.well-known/openid-configuration, nên địa chỉ này phải mở được. Phải là địa chỉ https công khai (địa chỉ riêng tư, loopback và nội bộ bị từ chối) và khớp nguyên văn với iss trong token. Dấu / ở cuối được bỏ. |
| Client ID và client secret | Lấy từ ứng dụng OIDC. Dùng ứng dụng confidential (web). Secret được lưu mã hóa và không hiện lại. |
| Luồng | Authorization code với PKCE (S256) và nonce. Tara kiểm chữ ký id_token bằng khóa ký của nhà cung cấp (JWKS), cùng iss, aud và hạn dùng. |
| Scope | Mặc định openid profile email (openid luôn được gửi). Chỉ đổi được trên terminal: ph org sso set --scopes. |
| Claim | Login: preferred_username (nếu có @, Tara giữ phần trước nó). Không có claim này thì lấy phần email trước @. Email: email. Tên: name. Chỉ đổi tên claim được trên terminal: --claim-login, --claim-email, --claim-name. |
Cần biết:
- Login phải bắt đầu bằng chữ hoặc số, chỉ gồm chữ, số,
_,.và-. Nếu không, đăng nhập lỗi và thông báo nêu tên claim. - Email chỉ được giữ khi thuộc một tên miền đã xác minh của bạn, và dù vậy Tara cũng không coi là đã xác minh. Require SSO cũng cần tên miền đã xác minh.
- Với SSO của tổ chức, Tara không đọc group từ nhà cung cấp. Role lấy từ role bạn chọn cho người mới, và từ mục Members.
- Portal chỉ hỏi issuer, client ID và secret. Scope và tên claim đặt bằng
ph org sso set. ph org sso test(hoặc nút test trên Portal) lấy cấu hình và khóa của nhà cung cấp. Nếu lỗi thì không lưu gì.
Microsoft Entra ID
Entra ID có OIDC sẵn.
- Trong Microsoft Entra admin center, mở App registrations và tạo một registration mới. Chọn loại tài khoản phù hợp với tenant, rồi thêm redirect URI loại Web là callback của Tara.
- Chép Application (client) ID.
- Ở Certificates & secrets, tạo client secret và chép giá trị.
- Ở Token configuration, thêm optional claim
emailvào token ID, để Tara đọc được địa chỉ email. - Trong Tara, issuer là
https://login.microsoftonline.com/<tenant-id>/v2.0. Dùng tenant ID của bạn, đừng dùngcommon, vì issuer phải khớp với token. - Muốn giới hạn người được đăng nhập, dùng Enterprise applications của ứng dụng này và gán người dùng hoặc nhóm.
Entra gửi user principal name trong preferred_username. Tara giữ phần trước @ làm login.
Okta
- Trong Okta Admin Console, tạo app integration loại OIDC - OpenID Connect, kiểu ứng dụng Web Application.
- Thêm callback của Tara vào Sign-in redirect URI.
- Gán ứng dụng cho những người hoặc nhóm được đăng nhập.
- Chép Client ID và Client secret ở tab General của ứng dụng.
- Trong Tara, issuer là
https://<your-company>.okta.com. Nếu bạn dùng authorization server tự đặt, dùng issuer của nó, ví dụhttps://<your-company>.okta.com/oauth2/default.
Google Workspace
- Trong Google Cloud console, mở APIs & Services và cài màn hình đồng ý OAuth. Chọn loại người dùng Internal để chỉ người dùng Workspace của bạn đăng nhập được.
- Ở Credentials, tạo OAuth client ID loại Web application. Thêm callback của Tara vào Authorized redirect URI.
- Chép client ID và client secret.
- Trong Tara, issuer là
https://accounts.google.com.
Google không gửi preferred_username, nên Tara lấy phần email trước @ làm login.
AD FS (Windows Server 2016 trở lên)
- Trong AD FS Management, tạo một Application Group có Server application (client confidential). Thêm callback của Tara làm redirect URI.
- Chép client identifier và tạo shared secret cho ứng dụng.
- Cho phép các scope
openid,profilevàemailcho ứng dụng. - Trong Tara, issuer là
https://<adfs-host>/adfs. - Đảm bảo
id_tokencó tên đăng nhập và email. Trong phần cấu hình của application group, thêm một issuance transform rule gửi UPN và địa chỉ email của người dùng thành claim. Sau đó nói cho Tara tên các claim đó bằngph org sso set --claim-login <tên> --claim-email <tên>. Claim có tên là một URL được đọc nguyên văn.
Nếu Tara báo claim bị thiếu hoặc không phải login hợp lệ, nghĩa là id_token không có claim mà Tara được bảo đọc. Kiểm tra lại rule và tên claim.
Keycloak làm cầu nối cho nhà cung cấp chỉ có SAML
Dùng cách này khi IdP của bạn chỉ có SAML. Keycloak là nhà cung cấp OIDC mà Tara nói chuyện, còn IdP SAML của bạn là một identity provider của Keycloak (identity brokering).
- Trong Keycloak, tạo hoặc chọn một realm cho Tara.
- Mở Identity providers và thêm nhà cung cấp SAML v2.0. Nhập metadata của IdP (URL hoặc file). Keycloak hiện metadata service provider SAML của chính nó cho nhà cung cấp này. Đưa metadata đó cho quản trị viên IdP để họ đăng ký Keycloak làm ứng dụng SAML.
- Thêm attribute mapper cho nhà cung cấp đó để mỗi người dùng có email và một username mà Tara dùng được. Ánh xạ các attribute SAML mà IdP gửi sang email và username của Keycloak.
- Tạo client OIDC cho Tara: loại
OpenID Connect, bật Client authentication, chỉ bật standard flow, và điền callback của Tara vào Valid redirect URIs. Lấy secret ở Credentials. - Trong Tara, issuer là
https://<keycloak>/realms/<realm>(Keycloak trước bản 17 có thêm/auth).
Trên terminal
echo "$CLIENT_SECRET" | ph org sso set --issuer https://login.microsoftonline.com/<tenant-id>/v2.0 \
--client-id <client-id> --client-secret-stdin --jit-role member --enable
ph org sso testGiới hạn
- Tara không có endpoint SAML, không có metadata SAML và không nhận assertion SAML. Nếu cần SAML, cầu nối ở trên là đường được hỗ trợ.
- Mỗi tổ chức một nhà cung cấp OIDC.