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

Set Up OIDC

Connect any OpenID Connect (OIDC) identity provider to Haystack Enterprise Platform so your team signs in with their corporate credentials.

About This Task​

Use this guide for any OIDC provider that doesn't have a dedicated template. For Google Workspace and Okta, use their own guides instead.

Prerequisites​

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

  • Make sure your provider meets the following requirements:

    • Returning the user's email address. Haystack Platform matches people by email, so the sign-in must produce one. Request the standard openid, profile, and email scopes, and check that the resulting token carries an email claim. Several providers omit it unless you turn it on explicitly, or leave it empty when the user has no mail address set in the directory.
    • Publishing a discovery document. Haystack Platform reads your endpoints from the discovery URL. It must be reachable from the internet and advertise issuer, authorization_endpoint, token_endpoint, and jwks_uri. The Test connection button checks exactly this.
    • Renewing the client secret before it expires. Most providers cap secret lifetime at one to two years. When you rotate it, edit the connection and paste the new secret. Sign-in breaks the moment the old one lapses.

Set Up the Connection​

  1. In Haystack Enterprise Platform, go to Settings > Organization > SSO and click Add SSO connection.
  2. Select Generic OIDC.
  3. Type a display name for the connection, for example OIDC. The display name must be unique in your organization.
  4. Enter your OpenID discovery URL in the OpenID discovery URL field. This is your provider's .well-known/openid-configuration endpoint.
  5. Enter the client ID and client secret issued when you registered the application at your provider into the Client ID and Client secret fields. The secret is stored encrypted and never shown again.

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 redirect URI from the success screen. If you open the connection later, the same value appears as Callback URL.
  2. At your provider, register that URL, exactly as shown, as an authorized redirect URI.
  3. 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​