Skip to main content

Set up SSO with Microsoft Entra ID

This guide connects Autoheal to Microsoft Entra ID (formerly Azure Active Directory) with SAML 2.0, so your team signs in to Autoheal with their Microsoft accounts. It walks through both sides, the Autoheal Authentication page and the Microsoft Entra admin center, in the order you need them.

For how SSO works in Autoheal (connection states, enforcement, break-glass access, and just-in-time provisioning), see Single Sign-On (SAML).

Before you begin​

You need:

  • Org Admin in Autoheal. See Roles & Permissions.
  • Cloud Application Administrator, Application Administrator, or Global Administrator in your Microsoft Entra tenant.
  • To know where your users' email addresses live in Entra. Autoheal signs people in by email, and Entra only sends an email address if the attribute behind it has a value. Step 5, Configure the email claim, covers this. It is the step most setups get wrong.
  • Your organization's break-glass URL, recorded somewhere you can reach without signing in to Autoheal. Enabling a connection requires SSO for every member of the organization.

Values you exchange​

FromValueTo
AutohealSP Entity ID / AudienceEntra Identifier (Entity ID)
AutohealACS (Reply) URLEntra Reply URL (Assertion Consumer Service URL)
EntraApp Federation Metadata UrlAutoheal Metadata URL

Both Autoheal values are unique to each connection. Copy them from Autoheal; don't type them.

Set up the connection​

  1. Start the connection in Autoheal

    Choose your organization in the project switcher, open Authentication in its sidebar, and select Add SSO.

    Select Microsoft Entra ID as the identity provider. This pre-fills the Display name, which your team sees on the sign-in screen. Change it if you like, then select Continue. The connection is created in the Needs setup state, with no effect on sign-in.

    The Add SSO connection dialog with Microsoft Entra ID selected

    The next step shows the connection's ACS URL (Reply URL) and Entity ID (Audience), each with a copy button. Keep this tab open: you paste both values into Entra, then come back for the metadata.

    You can find the same values later by expanding the connection on the Authentication page:

    An expanded connection showing the ACS (Reply) URL and SP Entity ID under Service provider

  2. Create an enterprise application in Entra

    In the Microsoft Entra admin center, go to Entra ID → Enterprise apps → New application, then select Create your own application.

    The Browse Microsoft Entra App Gallery page with Create your own application in the toolbar

    Name the application, for example Autoheal. Select Integrate any other application you don't find in the gallery (Non-gallery), then select Create.

    Entra may suggest gallery apps with similar names. Autoheal is not in the gallery, so ignore them.

    The Create your own application pane with the name Autoheal and the Non-gallery option selected

  3. Choose SAML

    In the new application, open Single sign-on and select SAML.

    Select a single sign-on method, with the SAML option

    Entra opens Set up Single Sign-On with SAML. The rest of the Entra setup happens on this page, in its numbered cards.

    The SAML-based Sign-on page with its numbered cards: Basic SAML Configuration, Attributes and Claims, and SAML Certificates

  4. Enter the Basic SAML Configuration

    On the Basic SAML Configuration card, select Edit, and fill in:

    Entra fieldValue from Autoheal
    Identifier (Entity ID)Entity ID (Audience), ending in /saml/metadata
    Reply URL (Assertion Consumer Service URL)ACS URL (Reply URL), ending in /saml/acs

    Leave Sign on URL, Relay State, and Logout Url empty. Select Save.

    The Basic SAML Configuration pane with the Identifier and Reply URL filled in

    Both values must match Autoheal's exactly, character for character, including the https:// prefix and with no trailing slash.

  5. Configure the email claim

    On the Attributes & Claims card, select Edit. Autoheal reads the claim named http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, which Entra includes by default.

    The Attributes and Claims page, with the emailaddress claim sourced from user.userprincipalname

    By default this claim's source is user.mail, the user's Email field in Entra. That field is often empty, typically for users with no Exchange Online mailbox. Entra leaves an empty claim out of the assertion entirely, so those users can't sign in to Autoheal, and the sign-in fails with error=sso_failed.

    Choose the source that holds a real email address for every user who will use Autoheal:

    • If your users' sign-in names (UPNs) are their email addresses, for example dana@acme.com: select the emailaddress claim and set Source attribute to user.userprincipalname.
    • If your UPNs are not email addresses, for example dana@acme.onmicrosoft.com: keep user.mail, and make sure every user's Email field is filled in.

    The Manage claim pane for emailaddress, with Source attribute set to user.userprincipalname

    Select Save at the top of the Manage claim pane. Closing the pane without saving discards the change, and the claims list still shows the old source.

    note

    The Unique User Identifier (Name ID) row doesn't affect Autoheal. Autoheal asks Entra for a persistent identifier, so Entra sends an opaque, stable ID as the Name ID whatever source you set here, and Autoheal doesn't read it as an email address. Leave it as it is. The email has to come from the emailaddress claim.

    The email Entra sends is the one Autoheal matches. It must be the address the person uses in Autoheal, and its domain must be on your organization's Allowed email domains for just-in-time provisioning.

  6. Copy the App Federation Metadata Url

    On the SAML Certificates card, copy App Federation Metadata Url.

    The SAML Certificates card with the App Federation Metadata Url and its copy button

    Downloading Federation Metadata XML and uploading it to Autoheal works too. Either way, Autoheal stores a copy of the metadata when you save the connection. Entra's signing certificate is valid for three years by default (see Expiration). When Entra renews it, edit the connection in Autoheal and supply the metadata again.

    Leave Token encryption (under Security in the app's menu) off. Autoheal accepts signed, unencrypted assertions only.

  7. Assign users and groups

    Open Users and groups in the application's menu, select Add user/group, and assign the people or groups who need Autoheal.

    The Users and groups page of the application, with Add user/group in the toolbar

    When Assignment required? is Yes on the application's Properties page, Entra only lets assigned users sign in. Everyone else gets error AADSTS50105 from Microsoft before they reach Autoheal.

  8. Finish in Autoheal

    Back in the Autoheal wizard, under Identity provider metadata, keep Metadata URL selected and paste the App Federation Metadata Url.

    Leave Automatically create users on first login enabled unless you pre-provision every user, then select Finish. The connection moves to Disabled: fully configured, and still with no effect on sign-in.

  9. Test, then enable

    Select Test on the connection. A new tab signs you in through Entra and shows what Autoheal received.

    Check that Email shows your email address. If it is blank, Entra sent no email: go back to step 5, Configure the email claim.

    When the test shows your email, select Enable and confirm. From then on, every member of the organization signs in through Entra. Use the break-glass URL if you get locked out.

    To check the result as a regular user, open your Autoheal URL in a private browser window and sign in with an assigned test account.

Troubleshooting​

Sign-in returns to the login page with error=sso_failed

Entra signed the user in, but the assertion had no email address Autoheal could read. With Entra, the cause is almost always the emailaddress claim's source attribute being empty for that user.

  1. Run Test on the connection. A blank Email confirms it.
  2. In Entra, open the application's Attributes & Claims, and check the emailaddress claim's source. If it is user.mail, check the user's Email field in Entra.
  3. Switch the source to user.userprincipalname if UPNs are email addresses, or fill in the user's Email field. See step 5, Configure the email claim.

Changing the Unique User Identifier (Name ID) does not fix this. See the note in step 5.

Sign-in worked before and now fails

Entra probably renewed its signing certificate. Check Expiration on the SAML Certificates card, then edit the connection in Autoheal and supply the App Federation Metadata Url again.

I changed the claim, but sign-in still fails

Open Attributes & Claims again and check the claim's Value column. If it still shows the old source, the edit wasn't saved: open the claim, change the source, and select Save at the top of the Manage claim pane.

Also confirm you edited the right application: its Basic SAML Configuration must show this connection's Identifier and Reply URL.

Microsoft shows AADSTS50011 (reply URL mismatch)

The Reply URL in Entra doesn't match the connection's ACS URL. Copy the ACS URL again from the expanded connection in Autoheal and paste it into Basic SAML Configuration.

Microsoft shows AADSTS700016 (application not found)

No application in your tenant has this connection's Entity ID as its Identifier. This usually means the connection was recreated in Autoheal and has a new Entity ID. Update Identifier (Entity ID) in Basic SAML Configuration to match.

Microsoft shows AADSTS50105 (user not assigned)

The user isn't assigned to the application, and Assignment required? is Yes. Assign them, or a group they belong to, under Users and groups.

A new user gets 'No access to this organization'

Entra signed them in, but Autoheal refused to create their account. Either just-in-time provisioning is off, or their email domain isn't in Allowed email domains. See User provisioning.