Configure OAuth Providers for External ConnectionsBeta
Register OAuth providers in Haystack Enterprise Platform so users can authorize access to third-party services with their corporate or workspace accounts.
About This Task
You can enable external connections for OAuth 2.0 providers for your Haystack Platform organization. After you register a provider, users can complete OAuth flows from the platform, for example when a pipeline or MCP tool needs access to Microsoft 365, Google Workspace, Slack, or Notion.
You can register multiple providers. Each provider appears in External Connections in your organization settings. Deleting a provider disconnects every user who authenticated through it.
Only organization admins can add or remove OAuth providers. If you don't see External Connections under Integrations, the feature isn't available for your organization or you don't have the necessary permissions.
Prerequisites
- You're a Haystack Platform organization admin.
- You can create and configure OAuth applications in your identity provider or SaaS vendor console.
- You have the client credentials your provider issues: a client ID and client secret, or a client ID with a PEM private key and certificate thumbprint for private key JWT.
- You know which OAuth scopes your use case needs. Provider templates prefill common scopes; you can change them before you save.
Choose an Authentication Method
When you register a provider, choose how Haystack Enterprise Platform authenticates to the token endpoint:
- Client Secret — paste the secret your provider issued. Most SaaS OAuth apps use this method.
- Private Key JWT — paste a PEM-encoded private key and the certificate thumbprint (SHA-1). Microsoft Entra ID supports this method for confidential clients.
Register a Provider
Follow the guide for your provider. Each guide explains how to create the OAuth app, where to copy the client ID and secret, and which redirect URI to register.
- Set Up OAuth for Microsoft Entra ID
- Set Up OAuth for Google
- Set Up OAuth for Slack
- Set Up OAuth for Notion
- Set Up a Custom OAuth Provider for any other OAuth 2.0 provider
The Add OAuth Provider dialog also lists Google Workspace MCP templates (Gmail, Drive, Calendar, and others). Each template uses the same Google Cloud OAuth client setup as Set Up OAuth for Google, with scopes tailored to that service.
Set the Environment Variable Name
Pipeline components can read the access token of the person who runs the pipeline from an environment variable, in the same way they read a secret. Each provider you register through this dialog has its own variable name, so a component knows which provider's token to read. Providers created before this setting existed have no name until you set one.
When you add a provider, the Environment Variable Name field in the Add OAuth Provider dialog is filled in for you. The default is USER_CONNECTION_ followed by the provider type. To use a different name, type your own in the field.
A valid name starts with an uppercase letter or an underscore and contains only uppercase letters, digits, and underscores. Names that match reserved system variable names, which secret names can't use either, are rejected. The name must be unique in your organization. If another provider or an existing secret already uses the name, the platform rejects it. After you save, the provider card shows the name with a copy button, so you can paste it into your pipeline.
Providers that were registered from an MCP server have no environment variable name, and their tokens are never added to pipeline runs.
To learn who receives a token and how components read it, see Secrets and Integrations.
Send Users a Connect Link
A user who hasn't connected yet has no token to pass to the pipeline. To let them connect from a link, for example one that an agent shows when the token is missing, build the link with the connect endpoint and your provider's ID: GET /connections/{provider_id}/connect?return_to=<URL>. Set return_to to the page where the user should land after connecting.
The link starts the consent flow for the user who is signed in to the platform in that browser. When the connection is stored, the user is sent to the return_to address. Without return_to, the user sees a success page that closes itself. Only members of your organization who aren't external users can connect. The return_to address must use https and point to the platform host or one of its subdomains. Any other address is rejected.
Manage a Provider
After you register a provider, you can remove it when you no longer need it:
What To Do Next
Was this page helpful?