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 uses Microsoft Entra ID (formerly Azure AD) for single sign-on.

What you need​

  • A licence that includes the sso feature (SSO is a paid feature).
  • 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. The tab always shows; without an SSO licence the form is locked, with a note saying why.
  2. The provider is Microsoft Entra ID. 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. 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 (Viewer or Editor, never Admin). 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.

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 Microsoft sign-in before turning this on. See Roles and access for how the roles and the break-glass account fit together.

Notes and limits​

  • Seats. An SSO user counts against the licence seat cap like any other user. If there is no free seat, or the instance is not licensed for SSO, the sign-in 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. The in-app config takes precedence when both are set.
  • 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 instance is not licensed for SSO, or 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 in Entra 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 org is not licensed for SSO, or the config did not load; check the licence and restart.
  • A seat message on sign-in: the licence seat cap is reached. Free a seat or raise the plan, then try again.