Microsoft Entra SSO

Set up SAML Single Sign-On between Microsoft Entra ID and StackOne.

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. Choose Microsoft Entra ID as the provider

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

   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.
3. Copy the service provider values

   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. Create an enterprise application

   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.
2. Start SAML single sign-on

   1. Open the new application and go to Single sign-on.
   2. Select SAML.
3. Enter the Basic SAML Configuration

   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.

   
4. Set the Name ID to the user's email

   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.

5. Add name claims

   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.

6. Assign users and groups

   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.

7. Get the identity provider metadata

   On the Single sign-on page, get the values StackOne needs.

   Metadata XML

   In SAML Certificates, download the Federation Metadata XML.

   Manual values

   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.

1. Provide the Entra values

   Supply the three values from Entra.

   Metadata XML

   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.

   

   Manual values

   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.

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

To add, update and deactivate users automatically from Microsoft Entra, set up Microsoft Entra SCIM Provisioning 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.
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 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

Single Sign-On

See how SSO, domain verification, and SCIM Provisioning fit together.

Okta SSO

Set up the same SAML connection with Okta instead of Entra.

Generic SAML SSO

Connect any other identity provider that supports SAML 2.0.