Đăng nhập SSO (OIDC)
Tara đăng nhập được bằng bất kỳ nhà cung cấp OpenID Connect nào có đường dẫn .well-known/openid-configuration, như Keycloak, Azure AD (Entra ID) hay ADFS. Tara không viết cứng nhà cung cấp nào, nên khác biệt giữa chúng chỉ nằm ở cấu hình: issuer, scope và tên claim. Trang này hướng dẫn cho người quản trị Tara bật SSO và ánh xạ nhóm trên SSO sang vai trò trong tổ chức.
SSO riêng của từng tổ chức nằm trên Portal
Trang này nói về nhà cung cấp bạn khai trong môi trường của máy chủ, cho một bản tự cài. Nếu muốn tổ chức của bạn trên dịch vụ dùng chung dùng Okta, Entra ID hay Keycloak, kèm bắt buộc SSO cho tên miền email đã xác minh, hãy cài trên Portal: SSO của tổ chức.
Tara dùng Authorization Code với PKCE (S256) và nonce. Sau khi người dùng đăng nhập, Tara kiểm tra id_token (chữ ký, iss, aud, thời hạn, nonce), chỉ lấy các claim cần thiết rồi bỏ token của nhà cung cấp. Nếu id_token thiếu nhóm hoặc login, Tara hỏi thêm userinfo. Phiên Tara tạo ra sau đó dùng như mọi cách đăng nhập khác, nên Portal, ph tara login và web app của nền tảng đều đăng nhập được qua SSO.
Đăng ký ứng dụng trên nhà cung cấp
Bạn tạo một client kiểu confidential trên nhà cung cấp, với callback là <TARA_PUBLIC_URL>/auth/oidc/<id>/callback. Trong đó <id> là mã bạn đặt ở cấu hình Tara, ví dụ sso.
Trên Keycloak, bạn làm như sau.
- Vào Clients, tạo client kiểu
OpenID Connectvới Client IDtara. Bật Client authentication và chỉ bật Standard flow. - Đặt Valid redirect URIs đúng bằng callback ở trên, từng ký tự một. Để trống Web origins.
- Trong Advanced, đặt Proof Key for Code Exchange Code Challenge Method là
S256. - Vào Credentials, lấy Client secret để đặt vào biến môi trường của Tara.
- Thêm nhóm vào token. Trong client scope
tara-dedicated, thêm mapper kiểu Group Membership với Token Claim Name làgroups, bật Full group path, và bật Add to ID token cùng Add to userinfo.
Issuer của Keycloak có dạng https://<keycloak>/realms/<realm>. Bản Keycloak trước 17 có thêm /auth/ ở đầu. Bạn kiểm tra bằng curl <issuer>/.well-known/openid-configuration. Users cần có email, và bật Email verified nếu muốn Tara dùng email cho thông báo.
Trên Azure AD, bạn tạo App registration, thêm Redirect URI loại Web là callback ở trên rồi tạo client secret. Issuer là https://login.microsoftonline.com/<tenant-id>/v2.0. Trong Token Configuration, bạn thêm groups claim (nên chọn Groups assigned to the application). Claim groups của Azure chứa object ID của nhóm, nên bạn khai báo object ID ở phần ánh xạ. Nếu người dùng thuộc quá 200 nhóm thì Azure bỏ claim này, Tara sẽ hỏi thêm userinfo.
Trên ADFS, bạn tạo Application Group loại Server application, đặt Redirect URI là callback, và issuer là https://<adfs>/adfs. Thêm rule để ADFS phát claim nhóm vào id_token, rồi đặt claims.groups đúng tên claim phát ra.
Biến cấu hình
TARA_OIDC_PROVIDERS là một mảng JSON, và bạn bật được song song với đăng nhập GitHub hay GitLab. Client secret nên truyền qua biến môi trường riêng để khỏi nằm trong cấu hình.
export OIDC_SSO_SECRET=...
export TARA_OIDC_PROVIDERS='[
{ "id": "sso", "name": "SSO của tổ chức",
"issuer": "https://sso.example.com/realms/org",
"clientId": "tara", "clientSecretEnv": "OIDC_SSO_SECRET",
"scopes": ["openid", "profile", "email"],
"claims": { "login": "preferred_username", "email": "email", "name": "name", "groups": "groups" },
"groups": { "org/ba": "viewer", "org/dev": "member", "org/leads": "admin" } }
]'Trên Kubernetes, bạn đặt OIDC_SSO_SECRET trong Secret của chart chứ không ghi ra file. Các trường của mỗi nhà cung cấp như sau.
| Trường | Ghi chú |
|---|---|
id | Chỉ gồm [a-z0-9-]. Callback là <TARA_PUBLIC_URL>/auth/oidc/<id>/callback |
name | Chữ trên nút đăng nhập, mặc định SSO <id> |
issuer | Phải khớp nguyên văn issuer trong discovery và claim iss. Bắt buộc https, riêng localhost được dùng http để thử |
clientId, clientSecret hoặc clientSecretEnv | Nên dùng clientSecretEnv |
scopes | Mặc định openid profile email, và luôn có openid. Thêm scope nếu nhà cung cấp cần nó để đưa nhóm vào token |
claims | Tên claim dùng làm login, email, tên và nhóm. Tên có dấu chấm như realm_access.roles được đọc lồng nhau |
groups | Ánh xạ giá trị nhóm sang vai trò trong tổ chức, xem mục dưới |
Ánh xạ nhóm sang vai trò
Trường groups nối nhóm trên SSO với vai trò trong tổ chức trên Tara (admin, member hoặc viewer; nhóm không cấp được owner), cùng cơ chế như nhóm GitLab. Ai thuộc đúng nhóm đó, hoặc nhóm con của nó, thì đăng nhập được và nhận vai trò đã ánh xạ trong tổ chức (tổ chức ghi ở TARA_SINGLE_ORG). Người khớp nhiều nhóm thì được vai trò cao nhất. viewer là chỗ chỉ dùng trình duyệt cho BA, PO, PM và không tính vào giới hạn seat. Ví dụ org/ba/team-1 khớp khóa org/ba. Tara so theo tiền tố, không phân biệt hoa thường và bỏ dấu / ở hai đầu.
Nếu người dùng rời nhóm thì lần đăng nhập sau Tara gỡ vai trò đã tự cấp. Vai trò do quản trị viên cấp tay thì Tara không bao giờ tự gỡ. Tara kiểm khi khởi động rằng mọi giá trị đều là vai trò hợp lệ. Nếu tổ chức hết seat thì người dùng vẫn đăng nhập được nhưng chưa vào tổ chức, cho tới khi có seat trống.
Người không thuộc nhóm nào được phép sẽ thấy thông báo "Your SSO account isn't in an allowed group: ask your SSO administrator to add you to …" cùng danh sách nhóm cần có, và Tara không tạo tài khoản cho họ.
Login trên Tara lấy từ claim login. Nếu claim có dạng email, như UPN của Azure hay ADFS, Tara lấy phần trước @. Login chỉ nhận chữ, số, _, . và -, và nếu trùng với người khác thì Tara thêm hậu tố -<id>. Tara không tự gộp tài khoản theo email. Email chỉ để hiển thị và gửi thông báo, và Tara bỏ email khi nhà cung cấp báo email_verified=false.
Kiểm tra nhanh
Sau khi đặt cấu hình và khởi động lại Tara, bạn kiểm tra theo ba bước.
- Xem log khởi động. Tara in
sign-in with <name>nếu cấu hình đúng. Nếu sai issuer, log báoSSO provider not reachable yet, và Tara tự thử lại ở lần đăng nhập sau. - Gọi
GET /auth/providers. Kết quả phải có{"id":"sso","kind":"oidc"}, và Portal hiện nút "Continue with …" theonamecủa bạn. - Đăng nhập bằng một tài khoản thuộc nhóm được phép. Bạn sẽ có phiên và vai trò đã ánh xạ trong tổ chức.
ph tara logincũng mở trình duyệt, qua SSO rồi quay về CLI.