# Single sign-on with SAML or OIDC

Connect your identity provider to Tracix with OIDC or SAML, verify your email domain, map identity provider groups to roles, and require SSO.

Single sign-on (SSO) lets your team sign in to Tracix through your identity provider (IdP) with OIDC or SAML 2.0. You set it up once for your organization, and it covers the console and every workspace, because signing in to a workspace goes through the console.

## Before you begin

* You need the Owner, Admin or MSP admin role. Linking your own identity, one of the steps, needs the Owner role.
* You need one email domain, such as `example.com`, where you can add a DNS TXT record.
* Ask Tracix to approve your identity provider's HTTPS origins before you register it: for OIDC, every origin Tracix calls, including the discovery, token and key (JWKS) endpoints. [Contact support](https://tracix.io/contact) with the exact origins, such as `https://login.example.com`; wildcards and private addresses aren't accepted.

## Set up SSO

You set up SSO in the console under **Security**, in the **Enterprise SSO** section.

**1. Create an app in your identity provider**

Create an OIDC or SAML application for Tracix in your identity provider. Some providers ask for the Tracix redirect or ACS URL when you create the app; Tracix shows those values after you register, and you can add them to the app then.

* **OIDC**: note the issuer URL, client ID and client secret. The ID token must include the `email_verified` claim, set to true.
* **SAML**: note the IdP entity ID, the IdP SSO URL and the IdP's signing certificate. Tracix requires signed assertions.

**2. Register the provider in Tracix**

Under **Enterprise SSO**, choose the **Protocol** and enter your **Email domain**.

* For **OIDC**, enter the **OIDC issuer URL**, **Client ID** and **Client secret**.
* For **SAML**, enter the **IdP entity ID**, the **IdP SSO URL** and the **IdP signing certificate (PEM)**.

Select **Register provider**. Tracix always uses PKCE for OIDC.

**3. Finish the app in your identity provider**

Tracix now shows your **Provider ID**, which is `org-` followed by your organization's ID, with the callback URLs to add to the app:

| Setting in your IdP          | Value                                                                                      |
| ---------------------------- | ------------------------------------------------------------------------------------------ |
| OIDC redirect URI            | The **OIDC callback** shown: `https://cloud.tracix.io/api/auth/sso/callback/<provider ID>` |
| SAML ACS URL                 | The **SAML ACS** shown: `https://cloud.tracix.io/api/auth/sso/saml2/sp/acs/<provider ID>`  |
| SAML audience (SP entity ID) | `https://cloud.tracix.io/api/auth/sso/saml2/sp/metadata?providerId=<provider ID>`          |

**4. Verify your domain**

Select **Get DNS verification record**. Tracix shows a `domainVerificationToken` value, valid for seven days. At your DNS provider, add a TXT record:

| Name                                             | Value     |
| ------------------------------------------------ | --------- |
| `_better-auth-token-<provider ID>.<your domain>` | The token |

When the record resolves, select **Verify DNS record**. The domain then shows as **Verified**.

**5. Link your own identity**

As the Owner, link your account to your identity in the IdP before you turn SSO on. Under **Link your existing account**, enter **Your immutable IdP subject**: your OIDC `sub` claim or SAML NameID, which your IdP administrator can look up. An email address doesn't work here. Select **Link my identity**. If you signed in more than five minutes ago, sign in again first.

**6. Turn SSO on**

Select **Enable SSO**, choose the **Default role** for people who sign in for the first time, optionally set up group mappings (below), and select **Save SSO policy**.

To test, sign out, enter your email address on the Tracix sign-in page and select **Continue with SSO**.

## Map identity provider groups to roles

Group mappings give people an organization role from their groups in your IdP.

1. Set **Signed group claim (optional)** to the name of the claim or attribute that lists the person's groups, such as `groups`. For OIDC it must be in the ID token; for SAML, in the signed assertion. Its value must be a list of group names.
2. In **Group-to-role mappings (JSON)**, map each group name to a role: `MEMBER`, `ADMIN`, `MSP_ADMIN` or `MSP_VIEWER`.

```json
{
  "tracix-admins": "ADMIN",
  "tracix-users": "MEMBER"
}
```

Mappings apply at every SSO sign-in. When someone is in several mapped groups, the most privileged role wins; someone in no mapped group gets the **Default role**. Each SSO sign-in replaces the person's organization role, including any custom role, except for the Owner. Groups never make someone the Owner.

Group mappings set organization roles only. Workspace access is still granted on each workspace's **Access** tab; see [Users and roles](https://tracix.io/docs/admin/users-and-roles).

## Who can sign in with SSO

| Person                                                       | What happens at their first SSO sign-in                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New to Tracix, with an email address at your verified domain | Tracix creates their account in your organization with the role from your default role and group mappings. No invite is needed.                                                                                                                                                                                         |
| Provisioned through SCIM                                     | Tracix links them through the SCIM `externalId`, which must be their IdP subject. See [Provision users with SCIM](https://tracix.io/docs/admin/scim).                                                                                                                                                                                    |
| Already has a Tracix account, such as one with a password    | The sign-in is refused until their IdP subject is linked to the account; Tracix never links accounts by email address alone. Today the console links only the Owner's own account. For anyone else, remove them on **Team**: their next SSO sign-in creates a new account, which you then add back to their workspaces. |

The email address the IdP sends must be at your verified domain, and for OIDC the IdP must mark it as verified.

## Require SSO

To make SSO the only way into your organization, select **Require SSO for this organization** and **Save SSO policy**. Tracix only allows it when SSO is enabled, the domain is verified, and the person saving it has linked their own identity.

> **Requiring SSO ends other sessions**
>
> Policy changes apply right away. When you require SSO, every session that didn't start with SSO ends, including password sign-ins of other admins, and password sign-in stops working for your organization.

Tracix multi-factor authentication still applies to SSO sign-ins: if your organization requires MFA, or someone has turned it on for their account, they enter their authenticator code after the identity provider. See [Multi-factor authentication](https://tracix.io/docs/admin/mfa).

## Identity provider notes

| Identity provider  | Note                                                |
| ------------------ | --------------------------------------------------- |
| Microsoft Entra ID | Use OIDC. Tracix has no separate Microsoft sign-in. |

Other identity providers follow the OIDC or SAML steps above.

## Limits today

* One identity provider and one email domain per organization.
* The console can't edit or remove a registered provider yet. To change the issuer or protocol, [contact support](https://tracix.io/contact).
* The **SSO** tile at the top of **Security** always reads **Off**; the **Enterprise SSO** section shows the real state.
* **Security** shows an **IP allowlist** card marked **Preview**: restricting console sign-ins to networks isn't available yet.

## Next steps

- [Provision users with SCIM](https://tracix.io/docs/admin/scim): Create and deactivate accounts from your IdP

- [Multi-factor authentication](https://tracix.io/docs/admin/mfa): Require an authenticator app for everyone

- [Users and roles](https://tracix.io/docs/admin/users-and-roles): What each role can do