Skip to main content

Single sign-on

How to set up single sign-on so people log in to Tagaris with your identity provider instead of a Tagaris password. Tagaris speaks OpenID Connect (OIDC), so it works with Microsoft Entra ID (formerly Azure AD), Okta, Google Workspace, and any other OpenID Connect provider such as Keycloak, Authentik, JumpCloud, OneLogin or AD FS.

The walkthrough below (Parts A to D) uses Microsoft Entra ID. The steps are the same for every provider; Other providers lists the exact values for each. SAML and LDAP are not supported.

How far each has been tested:

ProviderStatus
Microsoft Entra IDUsed in production against a live tenant.
Keycloak 26Tested with real sign-ins, nested role claims and PKCE.
Authentik 2025.6Tested with real sign-ins and group mapping.
OktaBuilt to Okta's documented token format. Not yet tried against a live Okta org.
Google WorkspaceBuilt to Google's documented token format. Not yet tried against a live Workspace.

If you set up Okta or Google Workspace and anything is off, tell us and we will fix it quickly.

What you need​

  • No licence is needed for single sign-on itself; it is included on every plan. Seats work as they do everywhere else: a person who signs in as view only uses no seat, and anyone who can change something (an Admin, an Editor, or a view-only person with an access group permission) uses one. The install owner never uses a seat, however they sign in. So single sign-on for a team of people who change things needs a Team plan with enough seats; view-only sign-ins are free and unlimited.
  • The install owner (SuperAdmin) account in Tagaris.
  • Administrator access to your identity provider to register an application.

SSO is one identity provider per install (the provider belongs to the whole Tagaris instance, not to an individual). Configuration is entered in the app and the client secret is stored encrypted; it never sits in a plain-text file.

Overview​

  1. Register an application in Entra ID and note three values: tenant ID, client ID and a client secret.
  2. Enter those in Tagaris under Settings, then Application, then Single sign-on.
  3. Restart the app so the provider is wired up.
  4. Sign in from the login screen with the new button.

Part A: register the application in Microsoft Entra ID​

  1. Go to the Microsoft Entra admin centre, then Identity, then App registrations, then New registration.

  2. Name it, for example Tagaris SSO.

  3. Supported account types: choose "Accounts in this organizational directory only" (single tenant) unless you need guests from other tenants.

  4. Redirect URI: choose platform Web and enter your Tagaris callback URL, which is your Tagaris address followed by /api/auth/oauth2/callback/sso.

    • Local test: http://localhost:3000/api/auth/oauth2/callback/sso
    • Production: https://tagaris.example.com/api/auth/oauth2/callback/sso

    Entra allows an http redirect only for localhost; a real deployment must be https. The exact URL is also shown on the Tagaris SSO settings page. Copy it from there to avoid a typo.

  5. Register, then from the Overview copy the directory (tenant) ID and the application (client) ID.

  6. Go to Certificates and secrets, then New client secret. Copy the secret Value straight away (it is only shown once). The Secret ID is not what you need.

The default OpenID scopes (openid, profile, email) are delegated and need no admin consent for basic sign-in.

Part B: configure Tagaris​

  1. In Tagaris, go to Settings, then Application, then Single sign-on. Only the install owner sees this tab.
  2. Choose Microsoft Entra ID as the provider. Fill in:
    • Directory (tenant) ID: from the Entra app Overview. Tagaris builds the issuer URL from this, so there is no full URL to type.
    • Application (client) ID: from the Entra Overview.
    • Client secret: the secret Value you copied. It is stored encrypted and is not shown again; leave the field blank on a later save to keep it.
    • Secret expiry: match the lifetime you chose in Entra, so Tagaris can warn you 30, 7 and 1 days before it expires.
    • Group and role mapping: required. Map your Entra App Roles (or group IDs) to Tagaris roles, and optionally to access groups. See "Roles: who becomes what" below.
  3. Save.

Part C: restart to apply​

The sign-in provider is wired up when the app starts, so a new or changed SSO config takes effect after a restart, not immediately. Restart the app (for Docker, docker compose restart app). Normal sign-ins do not need a restart; only changes to the SSO config do.

Part D: sign in​

  1. Go to the login screen. A sign-in button with your configured label now appears.
  2. Complete the provider's prompt.
  3. On the first SSO sign-in, Tagaris creates the account, attaches it to the org with the default role you set, and sends the person to the dashboard.

Roles: who becomes what​

Every SSO user's role comes from your directory. When you set SSO up you map directory values (Entra App Roles, or group IDs) to Tagaris roles, and this mapping is required. Anyone who signs in without a mapped value gets the default role you choose (View only or Editor, never Admin). A directory value can also be mapped to an access group by name, to give people particular jobs without making them Editors; see Roles and access. An administrator can change a role afterwards under Settings then Users, but the mapping is re-checked on every sign-in and wins.

Set up App Roles in Entra:

  1. In the app registration, go to App roles, then Create app role, and add roles with the values Admin, Editor and Viewer. The display name can be anything; the value is what Tagaris matches.

  2. In Enterprise applications, open the app, then Users and groups, and assign people or groups to those roles. Assigning a group to an app role needs Entra ID P1; assigning individual users is free.

  3. Entra now sends a roles claim in the token with the assigned values.

  4. In Tagaris, Settings, then Application, then Single sign-on, under "Group and role mapping", set the claim name to roles and map each value:

    Admin = ADMIN
    Editor = EDITOR
    Viewer = VIEWER

  5. Save and restart.

Map at least one value to ADMIN so your directory can grant admin access. Remove someone from the Admin app role (or its group) and their next login drops them to the default role. (Viewer = VIEWER gives the View only role, which changes nothing; to let those people do one job, map the same value to an access group on another line.)

To match on raw Entra group claims instead of App Roles, set the claim name to groups and put the group object IDs on the left of each mapping line. The Tagaris roles themselves are described in Roles and access.

Requiring single sign-on​

Turn on "Require single sign-on" (Settings, then Application, then Single sign-on) to switch off password sign-in for everyone except the install owner. The owner (a SuperAdmin) keeps a local password login as the break-glass account, so you can always get back in if single sign-on breaks. Set up the mapping and test a sign-in through your provider before turning this on. See Roles and access for how the roles and the break-glass account fit together.

Other providers​

In every case: choose the provider under Settings, Application, Single sign-on; register Tagaris with your provider as a web application (a confidential client, authorization code flow) using the redirect URL shown on that page; enter the values below; restart; then sign in. Tagaris always asks for the openid, email and profile scopes and uses PKCE.

Microsoft Entra ID​

Parts A to D above. Tagaris asks for the Directory (tenant) ID and builds the issuer from it. Roles come from App Roles in the roles claim.

Okta​

  1. In the Okta admin console, create an app integration: OIDC, Web Application. Set the sign-in redirect URI to the Tagaris redirect URL. Assign the people or groups who should have access.
  2. On the app's Sign On tab, under OpenID Connect ID Token, set the groups claim filter so the groups you want are sent (for example "Starts with" tagaris-). If you use a custom authorization server instead, add a groups claim to its ID token there.
  3. In Tagaris: Okta domain is the address you sign in to Okta on, without https:// (for example your-company.okta.com, not the -admin address). To use a custom authorization server add its path: your-company.okta.com/oauth2/default. Enter the client ID and client secret from the app's General tab.
  4. Mapping: claim name groups, then one line per group, for example tagaris-admins = ADMIN.

Tagaris adds the groups scope for Okta, which Okta needs before it will put groups in the token.

Google Workspace​

  1. In the Google Cloud console, create an OAuth client ID of type Web application, with the Tagaris redirect URL as an authorised redirect URI. Set the consent screen's user type to Internal, so only your Workspace can use it.
  2. In Tagaris: enter the client ID and client secret, and the allowed domain.

The allowed domain is required, and it is what keeps strangers out. Google will sign in any Google account, a personal Gmail address included. Tagaris only lets in accounts whose sign-in token says they belong to your Workspace domain (Google's hd claim, which personal accounts do not have). It must be your Workspace's primary domain. The check runs on every sign-in, for people who already have access as well as new ones. Anyone else sees "That account is not from this organisation's domain".

Google does not put groups or roles in its sign-in tokens, so there is no mapping with this provider. Everyone from your domain gets the role you choose for new users (View only or Editor) on their first sign-in, and an administrator promotes people, or adds them to access groups, under Settings, Users. A role changed by hand is kept on later sign-ins.

Any other OpenID Connect provider​

Enter the provider's issuer URL. Tagaris reads the rest from /.well-known/openid-configuration under it, so if you can open that address and see JSON, the issuer is right. You can set the name on the sign-in button, the claim that carries groups or roles, and any extra scope your provider needs before it sends them.

The claim name can be a dotted path into nested claims. Tagaris reads claims from the ID token, not the access token.

  • Keycloak. Issuer https://your-host/realms/your-realm. Create a client with client authentication on and the standard flow, and the Tagaris redirect URL as a valid redirect URI. Keycloak puts roles in the access token only by default: under Client scopes, roles, Mappers, open "realm roles" and turn on "Add to ID token". Claim name realm_access.roles (or resource_access.your-client.roles for client roles), then for example tagaris-admin = ADMIN.
  • Authentik. Create an OAuth2/OpenID provider and an application for it. Issuer https://your-host/application/o/your-app-slug/. Claim name groups; Authentik's profile scope already carries group names, so no extra scope is needed.
  • AD FS. Add an application group with a server application (it gives you the client ID and secret) and a web API. Issuer https://your-host/adfs. Add an issuance transform rule that sends group membership as a claim, and use that claim's name.
  • JumpCloud, OneLogin and others. Use the issuer from their OIDC application settings and the claim they put groups in, usually groups.

If roles are not arriving, decode a sign-in's ID token (your provider's admin console usually has a token preview) and check the claim is in it, with the values you mapped.

Notes and limits​

  • Seats. An SSO user uses a seat on the same terms as any other user: none as view only, one if their mapped role or access group lets them change something. The install owner never uses one. If a sign-in would need a seat and none is free, it is rejected and the just-created account is removed, so a rejected login leaves nothing behind.
  • Security. The client secret is encrypted at rest (AES-256-GCM). Checking a Tagaris licence is still offline; SSO adds a call to your identity provider at sign-in time only, which is inherent to OIDC.
  • Environment variables. Scripted or air-gapped installs can still set SSO_ISSUER, SSO_CLIENT_ID, SSO_CLIENT_SECRET and SSO_PROVIDER_NAME instead of using the UI, with any OpenID Connect provider. SSO_ROLE_CLAIM and SSO_ROLE_MAP set the mapping (pairs separated by semicolons, for example tagaris-admins = ADMIN; tagaris-editors = EDITOR), and with Google as the issuer SSO_ALLOWED_DOMAIN is required. The in-app config takes precedence when both are set.
  • One provider per install.
  • BETTER_AUTH_URL must match the address in the redirect URI, since it is used to build the callback.

Troubleshooting​

  • The button does not appear: the config was saved but the app has not been restarted.
  • "Single sign-on did not complete", or a redirect error at the provider: the redirect URI registered with your provider must exactly match your Tagaris callback URL, including http vs https and any trailing path. Copy it from the SSO settings page.
  • "Single sign-on is not enabled on this instance": the config did not load; check the single sign-on settings and restart.
  • A seat message on sign-in: the licence seat cap is reached. Free a seat or raise the plan, then try again.
  • "That account is not from this organisation's domain" (Google Workspace): the person chose a personal Google account, or one from a different Workspace, or the allowed domain is not your Workspace's primary domain.
  • Everyone arrives with the default role: the claim is missing from the ID token, or the values do not match the mapping exactly (they are case sensitive). With Keycloak, check "Add to ID token" on the roles mapper. With Okta, check the groups claim filter.
  • A redirect error naming PKCE or code_challenge: your provider is set to forbid PKCE for this client. Allow it; Tagaris always sends it.