Generic SAML SSO

Set up SAML Single Sign-On with any SAML 2.0 identity provider.

Connect any SAML 2.0 identity provider (IdP) to StackOne, so users sign in with their IdP credentials.

If the IdP is Okta or Microsoft Entra ID, follow the Okta or Microsoft Entra guide instead.

Before setting up SAML SSO, you need:

• The Organization Admin role in StackOne.
• Admin access to the IdP, to create and configure a SAML application.
• The ability to add a DNS TXT record for your email domain, which proves you own it.

Start the connection in StackOne

1. Choose Other SAML 2.0 provider

   1. Go to Organization > Security > SSO.
   2. Click Get started.
   3. Select Other SAML 2.0 provider, then click Continue.
2. Name the connection and set the domain

   On the Connection details step, fill in both fields, then click Continue:

   • Connection name: a name for the connection. StackOne generates the connection’s unique ID from it.
   • Domain: the email domain your users sign in with.
3. Copy the service provider values

   The Configure your identity provider step has the values you need when you create the app in your IdP. Field names vary by IdP:

   • ACS URL (Single sign-on URL): where the IdP posts the SAML assertion. Often called Assertion Consumer Service URL or Reply URL.
   • SP Entity ID (Audience): identifies StackOne to the IdP. Often called Audience URI, Entity ID or Identifier.
   • Default RelayState: the dashboard URL, where an IdP-initiated sign-in lands. Set it only if the IdP supports IdP-initiated sign-in.

   Keep this StackOne tab open. You return to the wizard to register the provider after you build the app in your IdP.

   

Create the SAML app in your IdP

1. Create the SAML application

   1. In the IdP’s admin console, create a new SAML 2.0 application for StackOne.
   2. Set the following:
      • Single sign-on URL (or Assertion Consumer Service URL): the ACS URL from StackOne.
      • Audience URI (or Entity ID): the SP Entity ID from StackOne.
      • Relay State (optional): the Default RelayState from StackOne.
2. Set the Name ID to the user's email

   Set the following:

   • Name ID format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.
   • Name ID value: the user’s work email, not a username, UPN or object ID.

   Optionally, also send the email as an attribute named email. StackOne uses it when present, and falls back to the Name ID otherwise.

3. Send the user's name

   Add attributes named givenName and surname, or a single displayName. These set the user’s display name in StackOne.

   Adding these to an existing app only sets names for new users. To sync names for existing users, use SCIM Provisioning.

4. Sign the assertion

   Enable assertion signing in the IdP. StackOne validates the signature against the certificate you register in StackOne.

   Register the exact certificate the IdP signs with. A mismatch makes every sign-in fail with a certificate error, even when every other value is correct.

5. Assign users

   Assign the users or groups who should sign in to StackOne through this application, then save the app.

   Only assigned users can complete SSO.

6. Get the identity provider metadata

   From the IdP’s SAML settings, get the values StackOne needs.

   Metadata XML

   Download the IdP’s SAML metadata XML.

   Manual values

   Copy these values for StackOne:

   • Issuer (Entity ID): the IdP’s unique identifier.
   • Single Sign-On URL: the IdP’s login endpoint.
   • X.509 signing certificate: in PEM format.

Register the provider in StackOne

Switch back to the StackOne tab and continue to the Register your SSO provider step.

1. Provide the IdP values

   Supply the three values from the IdP.

   Metadata XML

   1. Click Upload SAML metadata file.
   2. Select the metadata XML you downloaded. StackOne fills in Entity ID (Issuer), SSO URL (Entry Point), and X.509 Certificate.
   3. Review the imported values before continuing.

   Manual values

   Set the following:

   • Entity ID (Issuer): the IdP’s Issuer (Entity ID).
   • SSO URL (Entry Point): the IdP’s Single Sign-On URL.
   • X.509 Certificate: the IdP’s X.509 signing certificate.

   
2. Register the connection

   Select Continue. The connection is registered, but stays inactive until the domain is verified.

Verify the domain

Verification proves the organization owns the domain and activates SSO. Once it’s verified, existing StackOne users on the domain are linked to the SSO connection, so they keep one account.

1. Copy the DNS TXT record

   On the wizard’s Verify your domain step, copy the record’s Name and Value. The Value has this form:

   _stackone-sso-verification-token-{providerId}={token}
   

   
2. Add the record to DNS

   In the domain’s DNS panel, add a TXT record:

   • Name/Host: the domain. Use @ if it’s the root of the DNS zone, or the subdomain label if the email domain is a subdomain.
   • Value: the full _stackone-sso-verification-token-... string, as its own value. Don’t append it to an existing TXT value, such as an SPF record.

   Add the _stackone-sso-verification-token-... string as the record’s Value, not its Name. It looks like a DNS host label, as _dmarc and _domainkey do, so it’s easy to paste into Name/Host by mistake. A record on the wrong name fails verification without an error.

   Add the record in common DNS providers

   Cloudflare

   1. Go to DNS > Records and select Add record.
   2. Set Type to TXT and Name to @ for the root domain, or the subdomain label, such as eu for eu.acme.com.
   3. Paste the token into Content.

   Cloudflare allows several TXT records at the same name, so add a new record rather than editing an existing one.

   AWS Route 53

   1. Open the hosted zone and select Create record.
   2. Set Record type to TXT. Leave Record name blank for the root domain, or enter the subdomain label, such as eu for eu.acme.com.
   3. Paste the token in quotes.

   If a TXT record already exists at that name, edit it and add the token as a new line instead.

   Google Cloud DNS

   1. Open the zone and add a standard record set.
   2. Set the type to TXT, with the DNS name set to the email domain, such as acme.com or eu.acme.com.
   3. Paste the token.

   If a TXT record set already exists, edit it and add the token as a new item instead.

   GoDaddy

   1. Open the domain’s DNS records and select Add New Record.
   2. Set Type to TXT and Name to @ for the root domain, or the subdomain label, such as eu for eu.acme.com.
   3. Paste the token into Value.

   Namecheap

   1. Open Advanced DNS and select Add New Record.
   2. Choose TXT Record, and set Host to @ for the root domain, or the subdomain label, such as eu for eu.acme.com.
   3. Paste the token into Value.

   DNS changes can take up to 48 hours to propagate, though they often complete within minutes. Check what’s publicly visible with Google Admin Toolbox Dig.

3. Verify in StackOne

   1. Select Verify. Once the record is visible, the domain is verified and SSO is active.
   2. Select Finish to close the wizard.

   If the check fails, wait for DNS to propagate and try again.

   To finish setup first, select Verify Later, then verify afterward from the Trusted Domain card on the connection’s General tab.

   

Manage the connection

Open the connection from Organization > Security > SSO. The General tab is where you maintain it after setup:

• Select Edit SAML to update the identity provider values, either by uploading new metadata XML or by editing the Entity ID (Issuer), SSO URL (Entry Point), and X.509 Certificate directly.
• Select Edit Domain to change the trusted domain. Changing it resets verification, so users stop being redirected until you verify it again. You can’t change it while SSO is enforced.

From the connection’s page header:

• Settings edits the Connection name. The Provider ID is generated at setup and can’t be changed.
• Delete removes the SSO connection. It’s disabled while SSO is enforced, so turn off enforcement on the Authentication tab first.

To require users to sign in through your IdP, see Require SSO.

Deleting the connection sends users on the domain back to email and password sign-in, so make sure they have another way in first. To change SAML values, use Edit SAML instead.

Deleting it also removes SCIM Provisioning, if linked, and revokes its token. Provisioning from your IdP then fails with 401 until you link SCIM again and paste the new token into your IdP. Users already provisioned keep their access.

To add, update and deactivate users automatically from your IdP, set up SCIM Provisioning once the domain is verified.

Troubleshooting

Symptom	Likely cause	Fix
403 Forbidden when opening SSO	You lack the Organization Admin role.	Ask an Organization Admin to make the change or to grant you the role.
ERROR_UNMATCH_CERTIFICATE_DECLARATION_IN_METADATA	The registered certificate doesn’t match the one the IdP signs with.	Re-copy the active X.509 signing certificate from the IdP and update it on the connection’s General tab via Edit SAML.
ERR_UNMATCH_ISSUER	The Entity ID (Issuer) doesn’t match the issuer the IdP sends.	Copy the issuer from the IdP’s SAML metadata and update it via Edit SAML.
Sign-in fails or signs in the wrong user	The Name ID value isn’t the user’s email, the format is set to email address, but the value is still a username, UPN, or object ID.	Set the Name ID value to the user’s work email (see Set the Name ID to the user’s email).
”Provider domain has not been verified”	Domain verification hasn’t completed.	Finish Verify the domain.
Domain verification keeps failing	The TXT record is on the wrong name, was appended to an existing value, or DNS hasn’t propagated.	Use @ for a root domain or the subdomain label otherwise, add the token as its own TXT value, and check propagation with Dig.
Users not redirected to the IdP	The domain isn’t verified, or the user isn’t assigned to the SAML application.	Verify the domain, and confirm the user is assigned in the IdP.

Next steps

Single Sign-On

How SSO, SCIM Provisioning, and domain verification fit together.

Okta SSO

The same setup with Okta’s field names and screenshots.

Microsoft Entra SSO

The same setup with Microsoft Entra ID.