Okta SSO

Set up SAML Single Sign-On between Okta and StackOne.

Connect Okta as the organization’s SAML 2.0 identity provider (IdP), so users sign in to StackOne with their Okta credentials.

Before setting up Okta SSO, you need:

• The Organization Admin role in StackOne.
• Administrator access to the Okta Admin Console.
• The ability to add a DNS TXT record for your email domain, which proves you own it.

Start the connection in StackOne

1. Choose Okta as the provider

   1. Go to Organization > Security > SSO.
   2. Click Get started.
   3. Select Okta as the provider.
2. Name the connection and set the domain

   On the Connection details step, fill in both fields:

   • 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 Okta:

   • ACS URL (Single sign-on URL): where Okta posts the SAML assertion.
   • Audience URI (SP Entity ID): identifies StackOne to Okta.
   • Default RelayState: the dashboard URL, where an IdP-initiated sign-in lands.

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

   

Create the SAML app in Okta

1. Create a SAML app integration

   1. In the Okta Admin Console, go to Applications > Applications.
   2. Click Create App Integration.
   3. Choose SAML 2.0.
   4. Click Next.

   
2. Name the app

   1. On General Settings, enter an App name, for example StackOne SSO.
   2. Click Next.

   
3. Enter the SAML settings

   In Configure SAML, set the following:

   • Single sign-on URL: the ACS URL from StackOne.
   • Audience URI (SP Entity ID): the SP Entity ID from StackOne.
   • Default RelayState: the Default RelayState from StackOne.
   • Name ID format: EmailAddress.
   • Application username: Email.

   
4. Add name attribute statements

   1. Further down the same Configure SAML screen, under Attribute Statements (optional), add two attributes:

      Name	Name format	Value
      givenName	Unspecified	user.firstName
      surname	Unspecified	user.lastName

      These set the user’s display name in StackOne.

   2. Click Next.

   3. Click Finish.

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

5. Assign users

   1. Open the Assignments tab.
   2. Assign the people or groups who should sign in to StackOne through Okta.

   Only assigned users can complete SSO.

   
6. Get the identity provider metadata

   Open the app’s Sign On tab, then get the values StackOne needs.

   Metadata XML

   Download the Identity Provider metadata XML.

   Manual values

   1. In the SAML Setup panel, click View SAML setup instructions.
   2. Copy these values for StackOne:
      • Identity Provider Issuer: the Entity ID, for example http://www.okta.com/exk....
      • Identity Provider Single Sign-On URL: Okta’s login endpoint.
      • X.509 Certificate: the 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 Okta values

   Supply the three values from Okta.

   Metadata XML

   1. Click Upload SAML metadata file.
   2. Select the Identity Provider metadata XML you downloaded from Okta. 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 Identity Provider Issuer from Okta.
   • SSO URL (Entry Point): the Identity Provider Single Sign-On URL from Okta.
   • X.509 Certificate: the X.509 Certificate from Okta.

   
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 Okta, 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 Okta then fails with 401 until you link SCIM again and paste the new token into Okta. Users already provisioned keep their access.

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

Troubleshooting

Symptom	Likely cause	Fix
ERROR_UNMATCH_CERTIFICATE_DECLARATION_IN_METADATA	The registered certificate doesn’t match the one Okta signs with. Okta issues a new certificate per app.	Re-copy the X.509 Certificate from this app’s View SAML setup instructions and update it via Edit SAML.
ERR_UNMATCH_ISSUER	The Entity ID (Issuer) doesn’t match the issuer Okta sends.	Copy the Identity Provider Issuer (http://www.okta.com/exk...) and update it via Edit SAML.
”Provider domain has not been verified”	Domain verification hasn’t completed.	Finish Verify the domain.
Sign-in redirects to the wrong Okta, or a domain appears already taken	StackOne doesn’t automatically reserve a domain to one organization, so another StackOne organization may have registered the same domain.	Contact StackOne support to resolve which organization should own SSO for the domain before you enforce it.
Verification keeps failing	The TXT record is on the wrong name, not its own 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 Okta	The domain isn’t verified, or the user isn’t assigned in Okta.	Verify the domain, and confirm the user is on the app’s Assignments tab.
New users show their email address as their name	The app sends no name attribute statements, so the assertion carries only the email subject.	Add the givenName / surname attribute statements to the Okta app (see the setup steps above).
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.

Next steps

Single Sign-On

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

Microsoft Entra SSO

Set up SAML SSO with Entra ID instead of Okta.

Generic SAML SSO

Connect any SAML 2.0 identity provider.