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. Click Test SSO in TridentStack Control to verify everything is wired correctly.
  6. 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. The status shows Pending until you complete a successful test.

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 SSO​

Click Test SSO. A new tab opens at your IdP. Sign in. You will be returned to a success page in TridentStack Control listing the NameID, email, and groups received.

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.

After a successful test, the SAML status changes from Pending to Active.

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. 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 config.

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 non-break-glass users on this tenant must sign in via 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). The Test SSO button promotes Pending to Active automatically on first success; a fresh config that has not been tested will 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.