Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Set Up Microsoft Entra ID with SAML

Connect Microsoft Entra ID as a SAML identity provider so your team signs in to Haystack Enterprise Platform with their Entra ID accounts.

About This Task​

Microsoft Entra ID has no dedicated template, so you set it up as a Generic SAML connection. Each side needs a value from the other, so create the Entra application first, then the connection in Haystack Enterprise Platform, then finish the configuration in Entra.

Prerequisites​

Before you start, review the requirements and preconditions in Enable Single Sign-On (SSO).

Set Up the Connection​

Get the URLs and Identifier from Entra​

  1. In Microsoft Entra, create a non-gallery enterprise application. For help, see Microsoft Entra documentation.
  2. In the application, go to Manage > Single sign-on > SAML and scroll to the Set up section.
  3. Record these values:
    • Login URL
    • Microsoft Entra Identifier
    • Logout URL
  4. In the SAML Certificates section, download Certificate (Base64).
Certificate Format

Download Certificate (Base64). Haystack Platform expects a certificate beginning with -----BEGIN CERTIFICATE-----. The Certificate (PEM) download is identical to Base64 and works too.

Create the Connection in Haystack Enterprise Platform​

  1. In Haystack Enterprise Platform, go to Settings > Organization > SSO and click Add SSO connection.
  2. Select Generic SAML.
  3. Fill in the fields:
    • Display name: For example Acme Entra ID. Must be unique in your organization.
    • Sign-in URL: The Login URL from Entra.
    • Sign-out URL: The Logout URL from Entra, or leave empty to reuse the sign-in URL.
    • IdP issuer / entity ID: The Microsoft Entra Identifier from Entra.
    • IdP signing certificate: Upload the Base64 certificate from Entra.
  4. Expand Advanced options and set:
    • SAML binding: Choose HTTP-POST.
    • Sign AuthnRequests: Leave off unless your security policy requires it. Entra doesn't require Haystack Platform to sign its authentication requests and ignores the signature unless you explicitly ask for it. For details, see Configure Signed Authentication Requests.

Once you've filled in the provider-specific fields, finish and test the connection:

  1. Add your corporate domains to the Email domains field. At least one domain is required.
  2. Click the toggle to enable the connection.
  3. Click Test connection to check that your provider's endpoint exists and responds. A successful connection means the address is reachable, not that sign-in works. It doesn't verify credentials, certificates, or claim mappings.
  4. Click Save.

Register the Connection in Microsoft Entra​

  1. In Haystack Enterprise Platform, copy the ACS URL from the success screen.
  2. In Microsoft Entra, open the enterprise application and go to Single sign-on > Basic SAML Configuration > Edit.
  3. In the Identifier (Entity ID) field, paste the value you entered as IdP issuer / entity ID in Haystack Enterprise Platform.
  4. In the Reply URL (Assertion Consumer Service URL) field, paste the ACS URL you copied.
  5. In the Sign on URL field, paste your Haystack Enterprise Platform URL. This is only needed if you want users to start sign-in from the Microsoft My Apps portal.
  6. In the Logout Url field, paste the Single logout URL from Haystack Enterprise Platform.
  7. Leave the Relay State field empty.
  8. Click Save.
Matching Identifiers

The Identifier (Entity ID) in Entra must match the issuer you set in Haystack Enterprise Platform, not the Entity ID shown on the connection details. The value Haystack Platform displays as Entity ID is a metadata address, and it only applies when the IdP issuer / entity ID field was left empty. Once you fill that field in, it becomes the identifier Haystack Platform presents to Entra, and Entra's Identifier must be that exact string. A mismatch produces AADSTS650056.

Check the Email Claim and Assign Users​

  1. Open Attributes & Claims and confirm the claim value matches the address the user was invited to Haystack Enterprise Platform with. By default, Entra sends the email under http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, which is exactly what Haystack Platform looks for first. If your users' user principal name differs from their mail attribute, which is common after a tenant migration or with .onmicrosoft.com names, open the emailaddress claim and set its Source attribute to user.mail.
  2. Go to Users and groups > Add user/group and assign your pilot users. If Assignment required? is set to Yes on the app's Properties page, unassigned users are rejected with AADSTS50105. Entra only honors directly assigned groups here. Nested group membership doesn't grant access.

Optional: Configure Signed Authentication Requests​

Entra doesn't require Haystack Platform to sign its authentication requests. Configure this only if your security policy requires signed authentication requests:

  1. In Haystack Enterprise Platform, go to Settings > Organization > SSO.
  2. Open the Generic SAML connection and expand Advanced options.
  3. Turn on Sign AuthnRequests and save your changes. The connection configuration closes to generate the signing certificate.
  4. Reopen the connection, go to Advanced options, and copy the signing certificate or download the .pem file. Verify the SHA-256 fingerprint out of band.
  5. In Microsoft Entra, open SAML Certificates.
  6. Turn on Require verification certificates and upload the .pem file you copied.

Renew the Signing Certificate​

Entra's SAML signing certificate is valid for three years by default, and Entra notifies you before it expires. Haystack Platform doesn't fetch renewals automatically, so upload a new certificate before the old one expires to keep the connection working:

  1. In Microsoft Entra, go to SAML Certificates, then create and activate a new certificate.
  2. Download the new Certificate (Base64).
  3. In Haystack Enterprise Platform, edit the connection and replace the IdP signing certificate with the new one.

Do this while Entra is still signing with the old certificate so sign-in isn't interrupted.

Verify the Connection​

To confirm your SSO connection works end to end, check the following:

  • You have invited the pilot user to Haystack Enterprise Platform, and their email matches what your provider sends.
  • The pilot user is assigned to the application in your provider.
  • When you open Haystack Enterprise Platform in a private browsing window and enter the pilot user's email address, you're redirected to your provider, and after authenticating, you land back in Haystack Enterprise Platform, signed in.
  • You repeated the process with a different browser to confirm.

What To Do Next​