Skip to main content

Single sign-on (SAML)

Configure SAML 2.0 single sign-on so your team signs into TridentStack Control with their corporate credentials. Access is managed in your identity provider, your security team enforces policies like multifactor authentication centrally, and offboarding a user in your IdP locks them out of TridentStack Control immediately.

Before you begin​

You will need:

  • A TridentStack Control admin account.
  • An identity provider that supports SAML 2.0 (Okta, Microsoft Entra ID, Google Workspace, JumpCloud, OneLogin, ADFS, or any other compliant IdP).
  • Permission in your IdP to register a new SAML application.

Setup overview​

The end-to-end flow is:

  1. Copy the service-provider details from TridentStack Control.
  2. Create a SAML application in your IdP using those details.
  3. Copy the IdP details (entity ID, sign-on URL, X.509 certificate) back into TridentStack Control.
  4. Map your IdP's groups to TridentStack Control roles.
  5. Save the configuration and test sign-in.
  6. Activate SSO after a successful test.
  7. Optional: turn on Require SSO after configuring at least one break-glass admin.

Step 1: Get the service-provider details​

In TridentStack Control, go to Settings -> Authentication -> SAML Single Sign-On. The "Service Provider Metadata" panel shows three values:

  • Entity ID identifies TridentStack Control to your IdP.
  • ACS URL is where your IdP sends the sign-in response.
  • Metadata URL is a URL your IdP can fetch to import all of the above at once.

Copy these or download the metadata XML if your IdP supports importing it directly.

Step 2: Create the SAML application in your IdP​

Pick the section that matches your provider.

Okta​

  1. Sign in to your Okta admin console.
  2. Applications -> Applications -> Create App Integration. Choose SAML 2.0.
  3. Name the app "TridentStack Control" and continue.
  4. Paste the TridentStack Control Entity ID into Okta's Audience URI (SP Entity ID).
  5. Paste the TridentStack Control ACS URL into Okta's Single sign-on URL.
  6. Set Name ID format to EmailAddress.
  7. Add an attribute statement named groups with filter "Matches regex" and value .* (or whatever pattern matches the groups you want to send).
  8. Save. On the Sign On tab, copy the Identity Provider Single Sign-On URL, Identity Provider Issuer, and X.509 Certificate. You will paste these into TridentStack Control next.

Microsoft Entra ID (Azure AD)​

  1. Azure portal -> Microsoft Entra ID -> Enterprise applications -> New application -> Create your own application.
  2. Name "TridentStack Control", then Single sign-on -> SAML.
  3. Paste the TridentStack Control Entity ID into Identifier.
  4. Paste the TridentStack Control ACS URL into Reply URL.
  5. Under User Attributes & Claims, add a group claim with Source attribute = Group ID (or Cloud-only group display names if you'd rather match by name).
  6. Download the Federation Metadata XML from the SAML Signing Certificate panel.

Google Workspace​

  1. Google Admin -> Apps -> Web and mobile apps -> Add app -> Add custom SAML app.
  2. Name "TridentStack Control". On the next screen, download the IdP metadata.
  3. On the Service Provider Details screen, paste the TridentStack Control ACS URL and Entity ID.
  4. Under Attribute mapping, map a group attribute (Google calls it a "Group membership" attribute) to groups.

JumpCloud​

  1. JumpCloud admin -> SSO -> Add Application -> Custom SAML App.
  2. Paste the TridentStack Control values into SP Entity ID, ACS URL, and Login URL.
  3. Under User Attribute Mapping, add groups mapped to the user's group memberships.

Other providers (generic SAML 2.0)​

Most providers expose the same five fields. Use the TridentStack Control SP details for the SP-side; provide your IdP's entity ID, sign-on URL, and X.509 certificate to TridentStack Control. The groups attribute must be present in the assertion for role mapping (Step 4) to work.

Step 3: Configure TridentStack Control with the IdP details​

Back in Settings -> Authentication -> SAML Single Sign-On:

  • IdP Entity ID is your IdP's issuer URL.
  • IdP Sign-On URL is where TridentStack Control sends users to sign in.
  • IdP X.509 Certificate is the PEM-formatted certificate from your IdP.
  • Groups attribute name is groups for most providers; AD FS uses http://schemas.xmlsoap.org/claims/Group, some Microsoft setups use memberOf.

If your IdP gave you metadata XML, use the Paste IdP metadata XML button to autofill all of the above at once.

Click Save. IdP URLs must use https:// addresses. The configuration status reads pending until you test the configuration successfully and activate SSO.

Step 4: Map IdP groups to TridentStack Control roles​

In Settings -> Authentication -> Group to Role Mappings, click Add mapping and enter:

  • IdP Group Name is the exact group name your IdP sends in the assertion (case-sensitive).
  • TridentStack Control Role is the role users in that group should receive.

For example, members of acme-it-admins get the Admin role, and members of acme-helpdesk get the Policy Manager role. Users not in any mapped group get the tenant's default role on first login.

Step 5: Test, then activate SSO​

After saving, click Test SSO. A pop-up opens at your IdP. Sign in, then return to TridentStack Control to see whether the test succeeded or the exact error. A successful test confirms the current settings; it does not activate SSO.

After a successful test, click Activate SSO. This action is available only after the current settings pass a test. If you change the settings while a test is running, or after a test succeeds, test the updated settings again before activating SSO.

Once SSO is active, saving a settings change takes effect immediately. Run Test SSO again after each change to confirm that sign-in still works. Keep at least one break-glass admin so an SSO configuration problem does not lock out every administrator.

Changing SSO settings, SCIM tokens, group mappings, or break-glass admins asks you to confirm your identity first.

An identity-provider portal that launches TridentStack Control directly, such as a TrustLogin portal or an Okta dashboard tile, uses IdP-initiated sign-in. Turn on Allow IdP-initiated sign-in under Advanced in the SAML settings for those launch links to work.

TridentStack Control creates a new user through SSO only when the email domain is part of your organization: your primary domain or a verified sign-in domain. Someone using another domain needs an administrator to create their account first. Once an account exists, its user can sign in with SSO from any domain.

If the test fails, the error tells you what's wrong:

  • Signature did not verify: the X.509 certificate in TridentStack Control does not match the certificate your IdP is signing with. Re-copy the certificate.
  • Audience mismatch: your IdP is sending an Audience that does not match TridentStack Control's Entity ID. Check Step 1 was copied verbatim into your IdP.
  • No groups attribute: the assertion did not include the attribute name configured in Step 3. Check your IdP's attribute statements.

Step 6 (optional): Require SSO​

By default, users on tenants with SAML configured can choose between SSO and the OAuth (Microsoft / Google) providers. To require SSO, you must first add at least one break-glass admin.

Why break-glass admins exist​

If your IdP certificate expires or is misconfigured, no one can sign in with SSO. A break-glass admin is a TridentStack Control user whose Microsoft or Google sign-in keeps working even when Require SSO is on. They are the safety net you use to fix the SSO configuration.

Pick at least one trusted admin (typically yourself plus one other person). They must have already signed in with Microsoft or Google at least once so TridentStack Control has a valid OAuth identity to honor.

Enabling Require SSO​

  1. Settings -> Authentication -> Force-SSO and Break-Glass Admins -> Add break-glass admin, pick one or two trusted admins.
  2. Toggle Require single sign-on (Force SSO) on.

Once enabled:

  • All users other than break-glass admins must sign in with SAML.
  • Existing browser sessions for non-break-glass users are invalidated immediately. They will be redirected to your company sign-in on their next request.
  • Break-glass admins can still use Microsoft or Google.

You cannot remove the last break-glass admin while Require SSO is on. To turn Require SSO off, toggle it off first.

Troubleshooting​

Login redirects in a loop: the email you are signing in with is not in the tenant the SAML config belongs to. Check that the IdP is sending the email under the right domain.

"SSO is required" error message: you tried to use Microsoft or Google on a tenant where Require SSO is on, and you are not a break-glass admin. Use SSO instead, or ask an admin to grant you break-glass access.

Test SSO worked but real logins fail: confirm the SAML status is Active (not still Pending). A successful test does not activate SSO on its own: click Activate SSO after the test passes. A configuration that has not been tested and activated does not accept real logins.

Certificate expiry warning email: your IdP certificate is within 30 days of expiring. Rotate it in your IdP, then update the certificate in TridentStack Control. Until you do, only break-glass admins will be able to sign in once it expires.

For anything not covered here, contact TridentStack support at tridentstack.com/dashboard/support.