OAuthTokenResolver

Resolve OAuth access tokens at pipeline runtime and pass them to downstream components. Use this component with Google Drive, Microsoft SharePoint, and other integrations that need a bearer token.

Key Features

• Resolves OAuth access tokens through a pluggable token source.
• Supports refresh-token grants, per-request token exchange, and static long-lived tokens.
• Emits a plain access_token string that downstream components consume through a normal connection.
• Declares a mandatory subject_token input only when the configured token source requires per-request credentials.

Configuration

Add Workspace-Level Integration

1. Click your profile icon and choose Settings.
2. Go to Workspace>Integrations.
3. Find the provider you want to connect and click Connect next to them.
4. Enter the API key and any other required details.
5. Click Connect. You can use this integration in pipelines and indexes in the current workspace.

Add Organization-Level Integration

1. Click your profile icon and choose Settings.
2. Go to Organization>Integrations.
3. Find the provider you want to connect and click Connect next to them.
4. Enter the API key and any other required details.
5. Click Connect. You can use this integration in pipelines and indexes in all workspaces in the current organization.

1. Drag the OAuthTokenResolver component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab, configure token_source with one of these strategies:
   • OAuthRefreshTokenSource: Exchanges a stored refresh token for an access token. Use for a single fixed identity backed by a refresh grant.
   • OAuthTokenExchangeSource: Exchanges a per-request subject token for an access token. Use for multi-user or multi-replica deployments.
   • OAuthStaticTokenSource: Returns a configured long-lived access token as-is. Use when the provider issues non-expiring tokens.
4. Store refresh tokens, client secrets, or static tokens as workspace secrets. For instructions, see Add Secrets.
5. Connect the resolver's access_token output to downstream components such as GoogleDriveRetriever or MSSharePointRetriever.

Connections

OAuthTokenResolver outputs an access_token string. Connect it to components that need a bearer token, such as Google Drive or Microsoft SharePoint retrievers and fetchers.

When the configured token source sets requires_subject_token = True (for example OAuthTokenExchangeSource), the resolver also accepts a mandatory subject_token input. Pass a per-request credential through the pipeline input or from an upstream component.

Source Code

To check this component's source code, open resolver.py in the Haystack Core Integrations repository.

Token source implementations live in sources.py.

Usage Examples

Refresh Token Source

Use OAuthRefreshTokenSource when a single service identity holds a refresh token:

  oauth_resolver:
    type: haystack_integrations.components.connectors.oauth.resolver.OAuthTokenResolver
    init_parameters:
      token_source:
        type: haystack_integrations.utils.oauth.sources.OAuthRefreshTokenSource
        init_parameters:
          token_url: https://oauth2.googleapis.com/token
          client_id: your-client-id
          refresh_token:
            type: env_var
            env_vars:
            - GOOGLE_REFRESH_TOKEN
            strict: false
          scopes:
          - https://www.googleapis.com/auth/drive.readonly

Token Exchange Source

Use OAuthTokenExchangeSource when each request carries a user assertion:

  oauth_resolver:
    type: haystack_integrations.components.connectors.oauth.resolver.OAuthTokenResolver
    init_parameters:
      token_source:
        type: haystack_integrations.utils.oauth.sources.OAuthTokenExchangeSource
        init_parameters:
          token_url: https://login.microsoftonline.com/common/oauth2/v2.0/token
          client_id: your-client-id
          client_secret:
            type: env_var
            env_vars:
            - MS_CLIENT_SECRET
            strict: false
          grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
          subject_token_param: assertion
          scopes:
          - https://graph.microsoft.com/Files.Read.All
          extra_token_params:
            requested_token_use: on_behalf_of

Using the Component in a Pipeline

# haystack-pipeline
components:
  oauth_resolver:
    type: haystack_integrations.components.connectors.oauth.resolver.OAuthTokenResolver
    init_parameters:
      token_source:
        type: haystack_integrations.utils.oauth.sources.OAuthRefreshTokenSource
        init_parameters:
          token_url: https://oauth2.googleapis.com/token
          client_id: your-client-id
          refresh_token:
            type: env_var
            env_vars:
            - GOOGLE_REFRESH_TOKEN
            strict: false
          scopes:
          - https://www.googleapis.com/auth/drive.readonly

  retriever:
    type: haystack_integrations.components.retrievers.google_drive.retriever.GoogleDriveRetriever
    init_parameters:
      top_k: 5

connections:
- sender: oauth_resolver.access_token
  receiver: retriever.access_token

inputs:
  query:
  - retriever.query

outputs:
  documents: retriever.documents

Parameters

Inputs

Parameter	Type	Description
subject_token	str	Per-request subject token. Required only when the configured token source sets requires_subject_token = True (for example OAuthTokenExchangeSource).

Outputs

Parameter	Type	Description
access_token	str	A bearer access token for downstream components.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
token_source	TokenSource | SubjectTokenSource		The strategy that resolves the access token. One of OAuthRefreshTokenSource, OAuthTokenExchangeSource, or OAuthStaticTokenSource.

OAuthRefreshTokenSource

Parameter	Type	Default	Description
token_url	str		The OAuth 2.0 token endpoint.
client_id	str		The OAuth client identifier.
refresh_token	Secret	Secret.from_env_var("OAUTH_REFRESH_TOKEN")	The refresh token to exchange.
client_secret	Secret | None	None	The client secret for confidential clients.
scopes	List[str] | None	None	OAuth scopes to request, joined with scope_delimiter.
scope_delimiter	str	" "	Delimiter used to join scopes.
expiry_buffer_seconds	int	300	Refresh the cached token this many seconds before expiry.
timeout	float	30.0	Timeout in seconds for token endpoint requests.

OAuthTokenExchangeSource

Parameter	Type	Default	Description
token_url	str		The OAuth 2.0 token endpoint.
client_id	str		The OAuth client identifier.
client_secret	Secret | None	None	The client secret for confidential clients.
grant_type	str	urn:ietf:params:oauth:grant-type:token-exchange	Grant type sent as the grant_type form parameter.
subject_token_param	str	subject_token	Form parameter name for the per-request subject token.
subject_token_type	str | None	None	RFC 8693 identifier for the subject token type.
requested_token_type	str | None	None	RFC 8693 identifier for the requested token type.
scopes	List[str] | None	None	OAuth scopes to request.
scope_delimiter	str	" "	Delimiter used to join scopes.
extra_token_params	Dict[str, str] | None	None	Additional form parameters for every request.
expiry_buffer_seconds	int	300	Refresh cached tokens this many seconds before expiry.
cache_max_size	int	1000	Maximum number of per-user tokens in the in-memory cache.
timeout	float	30.0	Timeout in seconds for token endpoint requests.

OAuthStaticTokenSource

Parameter	Type	Default	Description
token	Secret		The long-lived access token to return.

Run Method Parameters

Parameter	Type	Default	Description
subject_token	str		Per-request subject token. Required only when the configured token source requires it.

Related Information

• GoogleDriveRetriever
• MSSharePointRetriever
• Add Secrets