SAML 2.0 single sign-on

Connect a SAML 2.0 identity provider (IdP) so employees sign in to your workspace with their corporate account. OnTrackio acts as the SAML service provider (SP); your IdP signs assertions, and OnTrackio maps the groups it sends to OnTrackio roles and provisions users on first sign-in.

The mechanics are the same for every IdP — Okta, Microsoft Entra (as SAML), Auth0, Ping, JumpCloud, OneLogin, Authentik, Keycloak, ADFS. Only your IdP's admin console differs.

:::note Before you begin

• A super-admin account on your workspace. The SAML screens live under Admin → Settings → Integrations.
• Admin access to your SAML IdP, so you can create an app and read its metadata.
• Your workspace slug. Every URL below is anchored to https://<slug>.app.ontrackio.com — replace <slug> with yours.
• The IdP groups you want to map to OnTrackio roles, or the ability to create them. :::

note

Each workspace is its own SAML SP, anchored to its own subdomain. That per-workspace perimeter is what blocks an assertion issued for one workspace from being replayed against another.

The values you exchange

SAML setup is an exchange of metadata in both directions. Give your IdP OnTrackio's SP values; bring your IdP's values back into OnTrackio.

OnTrackio's SP endpoints (give these to your IdP):

SP endpoint	Common IdP-side label
https://<slug>.app.ontrackio.com/saml/metadata	SP entity ID / audience URI / audience restriction
https://<slug>.app.ontrackio.com/saml/acs	ACS URL / reply URL / assertion consumer service / single sign-on URL
https://<slug>.app.ontrackio.com/saml/sls	single logout URL / SLO URL (optional)
EmailAddress	NameID format

OnTrackio publishes its SP metadata XML at https://<slug>.app.ontrackio.com/saml/metadata. If your IdP can import SP metadata, point it there to skip manual entry. You can also download the same XML from the IdP's edit page in OnTrackio with Download SP metadata.

Your IdP's values (bring these into OnTrackio):

IdP-side label	OnTrackio field
IdP issuer / entity ID	IdP entity ID
single sign-on URL / login URL	SSO URL (SingleSignOnService)
single logout URL (optional)	SLO URL (SingleLogoutService)
X.509 / signing certificate (PEM)	IdP signing certificate (X.509 PEM)

What OnTrackio requires from your IdP

OnTrackio enforces the constraints below on every assertion. If your IdP can't meet them, sign-in fails.

Requirement	Default	Notes
Signature algorithm RSA-SHA256 or stronger	—	SHA-1 is rejected.
Assertions are signed	Required	Signing the outer Response wrapper is optional.
Audience matches your SP metadata URL	—	Defends against cross-workspace replay.
Destination matches your ACS URL	—	Prevents assertion replay against another SP.
Assertion is within its NotBefore / NotOnOrAfter window	—	A small clock skew is tolerated. Keep both servers on NTP.
NameID format EmailAddress	Recommended	Other formats work if an email resolves through attribute mapping.
Groups attribute	Optional	Required for role mapping. Without it, every user provisions with the default role.

Step 1 — Create the SAML app in your IdP

In your IdP, create a new SAML 2.0 application (the menu path varies — for example, Okta uses Applications → Create App Integration → SAML 2.0; Entra uses Enterprise applications → New application → Create your own → SAML). Then set:

1. SP entity ID / audience to https://<slug>.app.ontrackio.com/saml/metadata.
2. ACS / reply URL to https://<slug>.app.ontrackio.com/saml/acs.
3. NameID format to EmailAddress (or Persistent if your IdP has no email option — then make sure an email resolves through attribute mapping).
4. Signature algorithm to RSA-SHA256 with a SHA-256 digest.
5. Sign assertions on. Signing the response as well is optional.

Step 2 — Send the user attributes

OnTrackio reads these attributes from the assertion. The default attribute mapping already accepts the candidate names below, so configuring your IdP to emit any one of them works without changes on the OnTrackio side.

OnTrackio field	Default candidate names	Required
Email	mail, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	Yes
First name	givenName, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	No
Last name	sn, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	No
Groups	memberOf, http://schemas.microsoft.com/ws/2008/06/identity/claims/groups	For role mapping

Configure your IdP to send at least an email attribute. First and last name improve the display name. The groups attribute is required only if you map groups to roles.

note

Most IdPs need a separate "group attribute statement" step to emit group memberships (for example, Okta's Group Attribute Statements, or Entra's Add a group claim). The attribute name your IdP sends must match one of the Groups candidates above, or you add your IdP's name to the Groups field in step 4.

tip

Microsoft Entra emits group object IDs (GUIDs), not group names, by default. Either map those IDs in step 6, or set the group claim's source attribute to a name field so Entra sends display names instead.

Step 3 — Read your IdP's metadata

After you save the app, your IdP exposes its metadata. Copy three values:

• IdP issuer / entity ID — a URL or URN such as urn:example:idp.
• Single sign-on URL — the IdP's SSO endpoint.
• X.509 certificate — the full PEM, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

If your IdP only offers a metadata XML download, those three values are inside it.

Step 4 — Assign users to the app

Most IdPs issue assertions only for users (or groups) assigned to the SAML app. Assign the relevant users or groups in your IdP now. A later sign-in that fails with a "user not assigned" message usually means this step was skipped.

Step 5 — Add the IdP in OnTrackio

1. In OnTrackio, open Admin → Settings → Integrations and select the SAML 2.0 SSO card. The SAML SSO page opens.

2. Select Add IdP.

3. Under Identity Provider, fill in the connection details:

   Field	Required	Default	Notes
   Label	Yes	—	For your reference and the sign-in button text. Not sent to the IdP.
   IdP entity ID	Yes	—	The IdP issuer from step 3. Must be unique across your IdP connections.
   NameID format	Yes	Email address	Match what your IdP emits.
   SSO URL (SingleSignOnService)	Yes	—	The IdP's single sign-on URL.
   SLO URL (SingleLogoutService)	No	—	The IdP's single logout URL. Leave blank to fall back to local logout only.
   IdP signing certificate (X.509 PEM)	Yes	—	The full PEM from step 3. Stored encrypted at rest.

4. Under User provisioning, choose how users are created and mapped:

   Field	Required	Default	Notes
   Just-in-time (JIT) provisioning	No	Off	Creates a user the first time they sign in through this IdP. Leave off to allow only users you've already added.
   Default role for JIT-created users	No	Platform default (employee)	Never set this to an admin role — grant those through group mappings instead.
   Allowed email domains	No	Any	One domain per line. Rejects assertions for emails outside the list, even if the IdP is misconfigured.

5. Under Attribute mapping, leave the defaults unless your IdP uses custom claim names. Add one candidate per line; OnTrackio tries them in order.

6. Under Signing & hardening, keep the safe defaults unless your IdP needs otherwise:

   Setting	Default	Notes
   Require signed assertions	On	Rejects any response whose assertion isn't signed by the pinned certificate.
   Require signed Response wrapper	Off	Turn on only if your IdP also signs the outer response.
   Require signed LogoutRequests	On	Keep on. Unsigned logout requests can be abused for forced logout.

7. Leave Enable this IdP for user sign-in cleared while you stage and test. Select Create IdP.

The IdP is saved with its sign-in button hidden until you enable it. You land on its edit page, where you can add role mappings next.

note

Pasting a new certificate on the edit page rotates the signing certificate; leaving the certificate box blank keeps the existing one. Certificate changes are recorded in the audit log.

Step 6 — Map groups to roles

Open Role mappings from the IdP's row or edit page, then add one row per IdP group. There are no implicit grants: a group must be mapped explicitly, or its members fall back to the JIT default role.

1. On the SAML SSO page, select Role mappings in the IdP's row.

2. Under Add mapping, fill in:

   Field	Required	Notes
   IdP group value	Yes	The literal group value your IdP sends. Okta sends the group name; Entra sends an object ID such as 00g1.... Must match exactly, including case.
   OnTrackio role	Yes	One of super-admin, admin, it-admin, manager, or employee.

3. Select Add mapping. Repeat for each group.

warning

A group literally named admin does not grant the OnTrackio admin role unless you map it here. Map every group that should carry a role; an unmapped group grants nothing beyond the default.

Step 7 — Enable and test

1. On the SAML SSO page, select Edit in the IdP's row.
2. Select Enable this IdP for user sign-in, then select Save changes. The IdP's status changes to Live.
3. Open https://<slug>.app.ontrackio.com/login in a private browser window.
4. Select Continue with <your label>.
5. Authenticate with the IdP.

A user in a mapped group lands on the admin dashboard; a user with no mapped group lands on the personal dashboard with the default role. On first sign-in with JIT enabled, a matching user record is created with the email, name, and role resolved from the assertion.

note

Roles are re-synced on every SAML sign-in: the assertion's groups, resolved through your role mappings, replace the user's roles each time. To grant a role to a SAML user, add them to a mapped IdP group — a manual role set in Admin → People is overwritten on their next sign-in. Reserve manual roles for accounts that never sign in through SAML.

How sign-in and sign-out behave

Behavior	What happens
Sign-in button	The Continue with <label> button appears on /login only while the IdP's status is Live.
Multiple IdPs	Each enabled IdP adds its own button. The right connection is selected for you from the sign-in flow.
MFA	If your workspace requires MFA, SAML users still complete OnTrackio's two-factor challenge after the IdP unless an administrator has opted to trust the IdP's MFA signal. See Two-factor authentication.
Single logout	With an SLO URL set, signing out ends the IdP session too. Without one, OnTrackio clears the local session only.
Deleting an IdP	Removes the connection. Already-provisioned users keep their accounts and roles and can still sign in with any other method you've enabled.

Troubleshooting

Symptom	What to do
Sign-in fails with SAML sign-in failed. Contact your administrator.	The assertion was rejected. The reason is recorded in the audit log under the security channel — check it for a signature, audience, destination, or expiry mismatch.
The Continue with <label> button is missing	The IdP isn't enabled. Open its edit page, select Enable this IdP for user sign-in, and save so its status shows Live.
Your IdP refuses the assertion with a "user not assigned" message	Assign the user (or their group) to the SAML app in your IdP. See Step 4.
A user signs in but gets the wrong role	Check the audit log for the groups the IdP sent. If they're empty, your IdP isn't emitting the groups attribute — revisit Step 2. If they're present, confirm the IdP group value in your mapping matches exactly, including case.
A user you promoted manually drops back to the default role	Expected. Roles re-sync from the IdP on every sign-in. Add the user to a mapped group instead of setting the role by hand.
Sign-in loops back to /login with no error	Confirm you're on https://<slug>.app.ontrackio.com over HTTPS, and that the signing certificate matches what your IdP uses — a signature failure surfaces as a generic sign-in failure.
Can't enable the IdP — Cannot enable an IdP without an email attribute mapping	Add at least one Email candidate under Attribute mapping, or set the NameID format to Email address.

Related

Logging inSign-in methods, SSO buttons, and the two-factor challenge.Read →SCIM provisioningAuto-provision and deprovision users from your identity provider.Read →Roles and permissionsWhat each OnTrackio role can do.Read →Integrations overviewEvery connector you can wire to your workspace.Read →