> ## 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.
# Microsoft Entra SSO
> Set up SAML Single Sign-On between Microsoft Entra ID and StackOne.
export const idp_0 = "Microsoft Entra"
Connect Microsoft Entra ID (formerly Azure AD) as the organization's SAML 2.0 identity provider (IdP), so users sign in to StackOne with their Entra credentials.
Before setting up Microsoft Entra SSO, you need:
* The **Organization Admin** role in StackOne.
* Access to the **Microsoft Entra admin center** with permission to create enterprise applications, such as the **Application Administrator** or **Cloud Application Administrator** role.
* 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 **Microsoft Entra ID** as the provider.
On the **Connection details** step, fill in both fields, then select **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.
The **Configure your identity provider** step has the values you need when you create the app in Entra:
* **Reply URL (ACS URL)**: where Entra posts the SAML assertion.
* **Identifier (Entity ID)**: identifies StackOne to Entra.
* **Default RelayState**: the dashboard URL, where an Entra-initiated sign-in lands.
Keep this StackOne tab open. You return to the wizard to register the provider after you build the Entra app.
## Create the SAML app in Microsoft Entra
1. In the **Microsoft Entra admin center**, go to **Identity > Applications > Enterprise applications**.
2. Select **New application > Create your own application**.
3. Enter a name, for example `StackOne SSO`.
4. Choose **Integrate any other application you don't find in the gallery (Non-gallery)**, then select **Create**.
1. Open the new application and go to **Single sign-on**.
2. Select **SAML**.
1. In **Basic SAML Configuration**, select **Edit**.
2. Set the following:
* **Identifier (Entity ID)**: the **Identifier (Entity ID)** from StackOne.
* **Reply URL (Assertion Consumer Service URL)**: the **Reply URL (ACS URL)** from StackOne.
* **Relay State (Optional)**: the **Default RelayState** from StackOne.
3. Select **Save**.
1. In **Attributes & Claims**, select **Edit**.
2. Open **Unique User Identifier (Name ID)**.
3. Set the following:
* **Name identifier format**: `Email address`.
* **Source attribute**: `user.mail`.
4. Save the claim.
`user.mail` must be set for everyone who signs in. It's often empty for cloud-only accounts without an Exchange Online mailbox, and for users synced from on-premises Active Directory without a `mail` attribute. When it's empty, sign-in fails with "Unable to extract user ID or email from SAML response".
If users' UPN matches their email address, use `user.userprincipalname` as the source attribute instead. Otherwise, set `mail` for each user before they sign in.
1. In **Attributes & Claims**, select **Add new claim**.
2. Set **Name** to `givenName`, leave **Namespace** blank, and set **Source attribute** to `user.givenname`. Select **Save**.
3. Repeat with **Name** set to `surname` and **Source attribute** set to `user.surname`.
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](/secure/identity-and-access/manage-team/scim/microsoft-entra).
1. Go to **Users and groups** and select **Add user/group**.
2. Assign the people or groups who should sign in to StackOne through Entra.
Only assigned users can complete SSO.
On the **Single sign-on** page, get the values StackOne needs.
In **SAML Certificates**, download the **Federation Metadata XML**.
1. From **Set up \[App name]**, copy the **Login URL** and the **Microsoft Entra Identifier**.
2. In **SAML Certificates**, download the **Certificate (Base64)**.
## 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 Entra.
1. Select **Upload SAML metadata file**.
2. Select the **Federation 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.
Set the following:
* **Entity ID (Issuer)**: the **Microsoft Entra Identifier**.
* **SSO URL (Entry Point)**: the **Login URL**.
* **X.509 Certificate**: the contents of the **Certificate (Base64)** file.
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 Microsoft Entra, set up [Microsoft Entra SCIM Provisioning](/secure/identity-and-access/manage-team/scim/microsoft-entra) once the domain is verified.
## Troubleshooting
| Symptom | Likely cause | Fix |
| - | - | - |
| Sign-in fails with "Unable to extract user ID or email" | The Name ID is empty because `user.mail` isn't set for that user. | Populate `user.mail`, or set the Name ID source to `user.userprincipalname` if it matches the user's email. |
| `ERROR_UNMATCH_CERTIFICATE_DECLARATION_IN_METADATA` | The registered certificate doesn't match the one Entra signs with, usually after Entra rotated or renewed it. | Download a fresh **Federation Metadata XML** (or **Certificate (Base64)**) from **SAML Certificates** and update it via **Edit SAML**. Entra signing certificates expire on a schedule, roughly every three years. |
| `ERR_UNMATCH_ISSUER` | The **Entity ID (Issuer)** doesn't match the issuer Entra sends. | Copy the **Microsoft Entra Identifier** and update it via **Edit SAML**. |
| "Provider domain has not been verified" | Domain verification hasn't completed. | Finish [Verify the domain](#verify-the-domain). |
| 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 Entra | The domain isn't verified, or the user isn't assigned in Entra. | Verify the domain, and confirm the user is under **Users and groups** on the enterprise application. |
| `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
See how SSO, domain verification, and SCIM Provisioning fit together.
Set up the same SAML connection with Okta instead of Entra.
Connect any other identity provider that supports SAML 2.0.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.