SSO sign-in (OIDC)
Tara can sign users in with any OpenID Connect provider that exposes a .well-known/openid-configuration path, such as Keycloak, Azure AD (Entra ID), or ADFS. Tara doesn't hard-code any provider, so the differences between them are only in configuration: issuer, scopes, and claim names. This page is for Tara administrators who enable SSO and map SSO groups to organization roles.
Per-organization SSO is in the Portal
This page covers a provider that you set up in the server's environment, for one self-hosted install. If you want your own organization on the shared service to use Okta, Entra ID, or Keycloak, with enforced SSO for a verified email domain, set it up in the Portal: Organization SSO.
Tara uses the Authorization Code flow with PKCE (S256) and a nonce. After a user signs in, Tara validates the id_token (signature, iss, aud, expiry, nonce), keeps only the claims it needs, and discards the provider's tokens. If the id_token lacks groups or a login, Tara also queries userinfo. The Tara session created afterward works like any other sign-in method, so the Portal, ph tara login, and the platform's web apps can all sign in through SSO.
Register the application with the provider
Create a confidential client on the provider, with the callback <TARA_PUBLIC_URL>/auth/oidc/<id>/callback. Here <id> is the identifier you set in the Tara configuration, for example sso.
On Keycloak, do the following.
- Go to Clients and create a client of type
OpenID Connectwith Client IDtara. Turn on Client authentication and enable only Standard flow. - Set Valid redirect URIs to exactly the callback above, character for character. Leave Web origins empty.
- Under Advanced, set Proof Key for Code Exchange Code Challenge Method to
S256. - Go to Credentials and copy the Client secret to put in Tara's environment variable.
- Add groups to the token. In the client scope
tara-dedicated, add a mapper of type Group Membership with Token Claim Namegroups, turn on Full group path, and turn on Add to ID token and Add to userinfo.
The Keycloak issuer has the form https://<keycloak>/realms/<realm>. Keycloak versions before 17 have an extra /auth/ at the start. Check it with curl <issuer>/.well-known/openid-configuration. Users must have an email address, and turn on Email verified if you want Tara to use the email for notifications.
On Azure AD, create an App registration, add a Web Redirect URI set to the callback above, and create a client secret. The issuer is https://login.microsoftonline.com/<tenant-id>/v2.0. In Token Configuration, add a groups claim (preferably Groups assigned to the application). Azure's groups claim contains group object IDs, so declare the object IDs in the mapping. If a user belongs to more than 200 groups, Azure omits this claim and Tara queries userinfo instead.
On ADFS, create an Application Group of type Server application, set the Redirect URI to the callback, and use the issuer https://<adfs>/adfs. Add a rule so ADFS emits the group claim into the id_token, then set claims.groups to the exact name of the emitted claim.
Configuration variables
TARA_OIDC_PROVIDERS is a JSON array, and you can enable it alongside GitHub or GitLab sign-in. Pass the client secret through a separate environment variable to keep it out of the configuration.
export OIDC_SSO_SECRET=...
export TARA_OIDC_PROVIDERS='[
{ "id": "sso", "name": "Organization SSO",
"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" } }
]'On Kubernetes, put OIDC_SSO_SECRET in the chart's Secret instead of writing it to a file. The fields of each provider are as follows.
| Field | Notes |
|---|---|
id | Only [a-z0-9-]. The callback is <TARA_PUBLIC_URL>/auth/oidc/<id>/callback |
name | Text on the sign-in button, default SSO <id> |
issuer | Must match the issuer in discovery and the iss claim verbatim. https is required, except localhost may use http for testing |
clientId, clientSecret or clientSecretEnv | Prefer clientSecretEnv |
scopes | Default openid profile email, and openid is always included. Add a scope if the provider needs it to put groups in the token |
claims | Claim names used for login, email, name, and groups. Names with dots, such as realm_access.roles, are read as nested |
groups | Maps group values to organization roles. See the next section |
Map groups to roles
The groups field connects SSO groups to organization roles on Tara (admin, member, or viewer; a group can't grant owner), using the same mechanism as GitLab groups. Anyone in that exact group, or in a subgroup of it, can sign in and receives the mapped role in the organization (the one named by TARA_SINGLE_ORG). If a user matches several groups, the highest role wins. A viewer is a browser-only seat for BA, PO, and PM and doesn't count against the seat limit. For example, org/ba/team-1 matches the key org/ba. Tara compares by prefix, ignores case, and trims / from both ends.
If a user leaves the group, Tara removes the automatically granted role at their next sign-in. Tara never removes a role that an administrator granted by hand. Tara checks that every value is a valid role at startup. If the organization has no free seat, the user can still sign in but doesn't join until a seat is free.
A user who belongs to none of the allowed groups sees the message "Your SSO account isn't in an allowed group: ask your SSO administrator to add you to …" along with the list of required groups, and Tara doesn't create an account for them.
The Tara login comes from the login claim. If the claim looks like an email address, such as the UPN in Azure or ADFS, Tara takes the part before the @. A login accepts only letters, digits, _, ., and -, and if it collides with another user's, Tara appends the suffix -<id>. Tara doesn't merge accounts by email. The email is only for display and notifications, and Tara drops it when the provider reports email_verified=false.
Quick check
After you set the configuration and restart Tara, check in three steps.
- Read the startup log. Tara prints
sign-in with <name>if the configuration is correct. If the issuer is wrong, the log reportsSSO provider not reachable yet, and Tara retries at the next sign-in. - Call
GET /auth/providers. The result must include{"id":"sso","kind":"oidc"}, and the Portal shows a button "Continue with …" using yourname. - Sign in with an account in an allowed group. You get a session and the mapped role in the organization.
ph tara loginalso opens the browser, goes through SSO, and returns to the CLI.