> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Okta SSO
> Set up SAML Single Sign-On between Okta and StackOne.
export const idp_0 = "Okta"
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. Go to [**Organization > Security > SSO**](https://app.stackone.com/organization/security/sso).
2. Click **Get started**.
3. Select **Okta** as the provider.
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.
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. In the **Okta Admin Console**, go to **Applications > Applications**.
2. Click **Create App Integration**.
3. Choose **SAML 2.0**.
4. Click **Next**.
1. On **General Settings**, enter an **App name**, for example `StackOne SSO`.
2. Click **Next**.
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`.
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](/secure/identity-and-access/manage-team/scim/okta).
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.
Open the app's **Sign On** tab, then get the values StackOne needs.
Download the **Identity Provider metadata** XML.
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.
Supply the three values from Okta.
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.
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.
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.
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}
```
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.
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.
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.
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.
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**.
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](https://toolbox.googleapps.com/apps/dig/#TXT/).
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**](https://app.stackone.com/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 {idp_0}, see [Require SSO](/secure/identity-and-access/authentication/sso/overview#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 {idp_0} then fails with `401` until you link SCIM again and paste the new token into {idp_0}. Users already provisioned keep their access.
To add, update and deactivate users automatically from Okta, set up [Okta SCIM Provisioning](/secure/identity-and-access/manage-team/scim/okta) 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](#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](https://toolbox.googleapps.com/apps/dig/#TXT/). |
| 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
How SSO, domain verification, and SCIM Provisioning fit together.
Set up SAML SSO with Entra ID instead of Okta.
Connect any SAML 2.0 identity provider.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.