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

Set Up SAML 2.0

Connect any SAML 2.0 identity provider to Haystack Enterprise Platform so your team signs in with their corporate credentials.

About This Task​

Use this guide for any SAML provider that doesn't have a dedicated template. For Microsoft Entra ID, use Set Up Microsoft Entra ID with SAML instead.

Prerequisites​

  • Before you start, review the requirements and preconditions in Enable Single Sign-On (SSO).
  • Make sure your provider meets the following requirements:
    • Signing the assertion. Haystack Platform verifies the signature on the SAML assertion. Providers configured to sign only the response envelope, leaving the assertion unsigned, are not supported.
    • Sending the email address. Haystack Platform reads the user's email from the first of these attributes that has a value, matched by exact name:
      1. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
      2. urn:oid:0.9.2342.19200300.100.1.3
      3. emailaddress
      4. email

Set Up the Connection​

  1. In Haystack Enterprise Platform, go to Settings > Organization > SSO and click Add SSO connection.
  2. Select Generic SAML.
  3. Type a display name for the connection, for example SAML 2.0. The display name must be unique in your organization.
  4. Enter your provider's SAML endpoint that receives the authentication request in the Sign-in URL field.
  5. Optional: Enter your provider's logout endpoint in the Sign-out URL field. Leave it empty to reuse the sign-in URL.
  6. Enter the identifier Haystack Platform presents to your provider in the IdP issuer / entity ID field. Whatever you enter here is what your provider must expect as the application identifier. Most providers need a URI.
  7. Paste your IdP signing certificate into the IdP signing certificate field, or upload it as a .pem, .crt, .cer, or .txt file. This is the PEM-encoded X.509 certificate your provider signs assertions with.
  8. Optional: Expand Advanced options and configure:
    • SAML binding: Choose how the authentication request is sent: HTTP-Redirect, HTTP-POST, or HTTP-POST (auto-submit). Defaults to HTTP-POST.
    • Sign AuthnRequests: Choose whether the authentication request is signed. Off by default. Most providers don't need it.
Identifier Sources

The identifier has two possible sources, and only one of them wins. If you fill in IdP issuer / entity ID, that value is what Haystack Platform sends to your provider, and the Entity ID shown on the connection details no longer applies. Configure your provider with the issuer value instead. If you leave the issuer field empty, use the displayed Entity ID. Pick one and use the identical string on both sides.

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.
  1. Copy the ACS URL from the success screen. This is the value your provider needs as the Reply URL or Assertion Consumer Service URL.
  2. Copy the Entity ID from the success screen. Your provider needs this as the Identifier or Entity ID, but only if you left the issuer field empty. It doubles as the metadata address, so providers that support metadata import can fetch it directly.
  3. Copy the Single logout URL from the success screen. Your provider needs this as the Logout URL.
  4. At your provider, configure the application with the values you copied:
    • Reply URL or Assertion Consumer Service URL: the ACS URL
    • Identifier or Entity ID: the Entity ID, only if you left the issuer field empty
    • Logout URL: the Single logout URL
  5. Sign in as a pilot user to test the connection.

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​