# Configure an OAuth Provider > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Configure an OAuth Provider latest-operator-version: v26.2.1 latest-console-tag: v3.9.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: oauth-providers page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: oauth-providers.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/oauth-providers.adoc description: Register an OAuth provider in Agentic Data Plane so MCP servers can authenticate users (or service accounts) against an upstream system like Slack, Jira, GitHub, or Salesforce. page-topic-type: how-to personas: platform_engineer, security_compliance_lead learning-objective-1: Register an OAuth provider for an upstream system you want MCP servers to authenticate against learning-objective-2: Grant the right permissions so principals can attach the provider to MCP servers learning-objective-3: Edit, rotate credentials on, or delete an OAuth provider page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-04" --- Register an OAuth provider so AI Gateway can authenticate against an upstream system on behalf of users or service accounts. Any MCP server for that upstream attaches to the provider instead of managing its own credentials. After completing this guide, you will be able to: - Register an OAuth provider for an upstream system you want MCP servers to authenticate against - Grant the right permissions so principals can attach the provider to MCP servers - Edit, rotate credentials on, or delete an OAuth provider > ❗ **IMPORTANT** > > OAuth providers and OAuth clients govern **opposite directions** of authentication and are separate resources. > > - An **OAuth provider** (this page) governs **outbound** authentication: AI Gateway authenticating to an upstream system (GitHub, Slack, Salesforce, and so on) on a user’s behalf so MCP servers can call that upstream. > > - An **OAuth client** governs **inbound** authentication: an external app (Claude Desktop, ChatGPT, Copilot Studio) authenticating to AI Gateway so the app’s users can invoke MCP tools. > > > Both are managed under the **Integrations setup** entry in the sidebar: OAuth providers on the **Outbound providers** tab, OAuth clients on the **Inbound clients** tab. They remain separate resources with separate API definitions, permissions, and lifecycles. To register or manage an OAuth client (including revoking its refresh tokens to force a re-sign-in), see [Connect remote MCP clients to AI Gateway](https://docs.redpanda.com/agentic-data-plane/connect/remote-mcp-clients/). ## [](#prerequisites)Prerequisites Before you register the provider, make sure you have: - An OAuth 2.0 application registered with the upstream provider, with the gateway’s redirect URI configured. The redirect URI is the AI Gateway’s OAuth callback (typically `https://aigw..clusters.rdpa.co/oauth/v1/callback`). - The OAuth app’s **client ID** and **client secret**. - A secret already created in the Redpanda Agentic Data Plane secret store for the client secret. Secret references must be `UPPER_SNAKE_CASE`, for example `SLACK_CLIENT_SECRET`. - The list of **scopes** the upstream API needs. Include every scope any MCP server attached to this provider may need; users re-consent when scopes are added later. ## [](#required-permissions)Required permissions OAuth providers are governed by their own permission set. Among the built-in roles only Admin holds these permissions, so anyone else acts on OAuth providers through an [access policy](https://docs.redpanda.com/agentic-data-plane/control/access-policies/). A policy names the matching `OAuthProvider` actions: `get`, `list`, `create`, `update`, `delete`, and `attach`. The `attach` action is worth separating from the rest. A policy can grant someone the ability to bind an existing provider to an MCP server without also letting them create or edit providers. | Permission | Allows | | --- | --- | | dataplane_aigateway_oauthprovider_create | Create new OAuth providers. | | dataplane_aigateway_oauthprovider_get | Read existing OAuth providers. | | dataplane_aigateway_oauthprovider_update | Edit an existing OAuth provider’s endpoints, scopes, or credentials. | | dataplane_aigateway_oauthprovider_delete | Delete an OAuth provider. | | dataplane_aigateway_oauthprovider_attach | Required to attach this provider to an MCP server. Enforced as a sub-resource check in CreateMCPServer and UpdateMCPServer whenever authConfig.userOauth.provider_name is set or swapped. Without this permission, a principal with mcpserver_update could otherwise bind any provider’s token vault to an MCP they control and indirectly consume its tokens. | > 📝 **NOTE** > > The `_attach` permission is independent from `_get`, `_create`, `_update`, and `_delete`. Grant it only to the principals that need to bind a given provider’s token vault to an MCP server, and scope the policy to that provider with `resource == OAuthProvider::""`. ## [](#browse-oauth-providers)Browse OAuth providers Open **Integrations setup** in the sidebar and select the **Outbound providers** tab. The tab lists every provider registered in your organization. (The older `/oauth-providers` path still works but redirects here.) The list shows the following columns: | Column | What it shows | | --- | --- | | Name | The provider’s machine identifier (used in MCP server configuration to attach this provider). | | Grant types | A badge per grant type. Typically Browser consent for user-delegated OAuth. | | Status | Enabled or Disabled. | | Scopes | A chip list of the supported scopes, for example read:user, repo, read:org for a GitHub provider. | A **Filter** button narrows the list. The **Create provider** button opens the create form. ## [](#register-an-oauth-provider-in-the-ui)Register an OAuth provider in the UI Walk through the create form to register the upstream: 1. Open **Integrations setup** in the sidebar and select the **Outbound providers** tab. 2. Click **Create provider**. 3. Pick how to configure the provider: - Choose a preset from the catalog to pre-fill the standard authorization and token endpoints and recommended scopes. - Choose **Custom Provider** to enter the endpoints yourself. - Choose **Discover from MCP server URL** to point the gateway at a remote MCP server and let it detect the OAuth configuration for you. See [Discover a provider from an MCP server URL](#discover-a-provider-from-an-mcp-server-url). The catalog groups presets into categories you can filter with the category chips: **Identity & SSO**, **Code & Dev**, **Productivity**, **Files & Storage**, **Communication**, **CRM & Support**, **Data Platform**, **Observability**, **Infrastructure**, and **HR & Legal**. It covers common providers across these categories, such as GitHub, Google, Okta, Microsoft, and Slack, with more added over time. For any upstream without a preset, use **Custom Provider** and enter its endpoints manually. 4. Fill in the identity fields: | Field | Required | Notes | | --- | --- | --- | | Name | Yes | Lowercase letters, numbers, and hyphens only. Used to reference the provider in MCP server configuration. Immutable after create. | | Display name | Yes | Human-readable label shown in the UI. | | Authorization endpoint | Yes | The upstream’s OAuth authorize URL, for example https://slack.com/oauth/v2/authorize. | | Token endpoint | Yes | The upstream’s OAuth token URL, for example https://slack.com/api/oauth.v2.access. | | Revocation endpoint | No | RFC 7009 token-revocation URL. When set, the gateway calls it on disconnect (best-effort). Not all providers support this. | 5. Pick a `Grant type`: - **Browser Consent**: The user approves access in their browser (OAuth 2.0 Authorization Code flow). The default for user-delegated OAuth. - **Token Exchange**: RFC 8693 server-to-server token exchange. Shown in the form but not yet functional (future release); the gateway exchanges the user’s identity-provider JWT for a provider-scoped token without browser interaction. 6. Pick a `Token-endpoint authentication method`: - **HTTP Basic**: `client_id:client_secret` sent as the Basic authentication header. Most common. - **POST body**: Credentials sent as form fields in the token-request body. - **None**: For public clients that rely on PKCE only. Pick this when the upstream OAuth app is registered as a public client and AI Gateway authenticates by proving possession of a PKCE code verifier rather than a stored client secret. Leave the client-secret reference unset. 7. Provide the `Client ID` and a `Client Secret Ref` (a secret-store key in `UPPER_SNAKE_CASE`, for example `SLACK_CLIENT_SECRET`). Use the **Existing** tab to pick a secret already in the store, or **New** to create one inline. Leave the reference empty only for public clients that authenticate with PKCE. 8. Define the `Scopes`. Include every scope any MCP server may need. 9. Optionally turn on `Require PKCE` to add PKCE (RFC 7636) to the consent flow. Leave `Enabled` on so the provider can start consent flows. 10. Click **Create Provider**. The provider appears in the **Outbound providers** list. ## [](#discover-a-provider-from-an-mcp-server-url)Discover a provider from an MCP server URL When you connect to a remote MCP server that authenticates users over OAuth, you can let AI Gateway detect the server’s OAuth configuration instead of entering endpoints and credentials by hand. If the remote server supports client metadata documents, AI Gateway identifies itself with an HTTPS URL and does not create a registration. If the server instead supports dynamic client registration, the gateway registers itself automatically. In either case, you have no endpoints or client credentials to paste. > 📝 **NOTE** > > This is the _outbound_ direction: AI Gateway identifies itself to a remote MCP server’s OAuth server. It is distinct from the inbound direction, where external MCP clients identify themselves to AI Gateway. To let clients such as Claude Code or ChatGPT connect to the gateway, see [Connect remote MCP clients to AI Gateway](https://docs.redpanda.com/agentic-data-plane/connect/remote-mcp-clients/). To discover a provider: 1. Open **Integrations setup** in the sidebar and select the **Outbound providers** tab. 2. Click **Create provider**, then select the **Discover from MCP server URL** card. 3. Enter the remote MCP server’s URL and start the discovery probe. 4. Review the result and finish the setup. The gateway takes one of these paths, depending on what the probe finds: | Result | What happens | | --- | --- | | Server supports client metadata documents | The gateway identifies itself with the client metadata document it publishes and pre-fills the provider. No client registration or shared client secret is required. Confirm the details to create the provider. | | Server supports dynamic client registration | The gateway registers itself as an OAuth client with the remote server’s authorization server and pre-fills the provider. Confirm the details to create the provider. | | A matching provider already exists | The gateway points you at the provider already registered for that server so you can attach it instead of creating a duplicate. | | Server has no OAuth, or OAuth without client metadata documents or dynamic client registration | The gateway falls back to the manual create form, pre-filling whatever it could detect. Complete the remaining fields as described in Register an OAuth provider in the UI. | A provider created this way is marked with a **Discovered** badge in the list and on its detail page, which distinguishes it from a provider you configured manually. Its detail page also shows a **Registration** card. See [View provider details](#view-provider-details). You can reach the same automatic setup from the other direction. When you create a self-managed MCP server that authenticates users over OAuth, Redpanda checks the server URL and sets up the OAuth client as part of creating the server, with no provider registered first. The provider it creates appears here with the same **Discovered** badge. See [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/). ## [](#register-from-the-cli)Register from the CLI Use [`rpk ai`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/) to script provider registration: ```bash rpk ai oauth-provider create \ --name ramp \ --display-name "Ramp" \ --auth-endpoint "https://app.ramp.com/v1/authorize" \ --token-endpoint "https://api.ramp.com/developer/v1/token" \ --client-id "$RAMP_CLIENT_ID" \ --client-secret-ref RAMP_CLIENT_SECRET \ --scopes "transactions:read,cards:read,users:read" ``` | Flag | Notes | | --- | --- | | --name | Resource name. Lowercase letters, numbers, hyphens. Immutable. Required. | | --display-name | Human-readable display name shown in the UI. Required. | | --auth-endpoint | OAuth authorization endpoint URL. Required. | | --token-endpoint | OAuth token endpoint URL. Required. | | --client-id | Client ID from the upstream OAuth app. Required. | | --client-secret-ref | Secret-store reference (UPPER_SNAKE_CASE). | | --scopes | Comma-separated scope list. | | --grant-types | Grant types: browser-consent (default), token-exchange. Comma-separated. | | --token-auth-method | Token-endpoint authentication method: client-secret-basic (default), client-secret-post, none. | | --pkce | Require PKCE for authorization code grants. | | --revocation-endpoint | OAuth token revocation endpoint URL. | | --enabled | Whether the provider is enabled (default true). | ## [](#list-and-filter-providers-with-the-api)List and filter providers with the API To enumerate OAuth providers programmatically, call `OAuthProviderService.ListOAuthProviders`. Beyond the `name_contains` substring match, the request accepts an AIP-160 `filter` expression and an AIP-132 `order_by`, so you can scope and sort the list on the server (for example, to fetch only enabled providers, ordered by display name) instead of filtering the loaded page. The list endpoint uses the same OIDC client-credentials authentication as the rest of AI Gateway. Mint a service-account access token using the flow in [Authenticate with OIDC client credentials](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/#authenticate-with-oidc-client-credentials), then pass it as a bearer token. The service account needs `dataplane_aigateway_oauthprovider_list`. The request’s `filter` object carries two independent fields: | Field | Meaning | | --- | --- | | name_contains | Case-insensitive substring match on the provider name. | | filter | AIP-160 expression (maximum 1024 characters) that the server ANDs with name_contains and the tenant scope. Filterable columns: name, display_name, enabled, grant_types, created_at, and updated_at. Use it for multi-value OR semantics, for example enabled = true or grant_types = "OAUTH_GRANT_TYPE_BROWSER_CONSENT". The grant_types column accepts the OAuthGrantType enum values OAUTH_GRANT_TYPE_BROWSER_CONSENT and OAUTH_GRANT_TYPE_TOKEN_EXCHANGE; enabled accepts true or false. | Set `order_by` (maximum 256 characters) to a comma-separated list of fields, each optionally suffixed with \` desc\` (ascending by default), for example `display_name` or `created_at desc`. Orderable fields are the keyset columns `name`, `display_name`, and `created_at`. An unsupported field returns `InvalidArgument`. Leave `order_by` empty to use the server default (`created_at desc`). The order is encoded into the page token, so keep it stable across a paged walk. ```bash ACCESS_TOKEN="" # from the client_credentials flow DATAPLANE_BASE="https://aigw..clusters.rdpa.co" curl -s --request POST \ --url "${DATAPLANE_BASE}/redpanda.api.adp.v1alpha1.OAuthProviderService/ListOAuthProviders" \ --header "Authorization: Bearer ${ACCESS_TOKEN}" \ --header 'Content-Type: application/json' \ --data '{ "filter": { "filter": "enabled = true" }, "order_by": "display_name", "page_size": 50 }' | jq ``` The response carries the matching `oauth_providers`, a `next_page_token` for the next page, an estimated `total_size` (AIP-158) of all providers matching the filter (ignoring pagination), and the gateway-wide `callback_url` (the OAuth redirect URI to register with your identity provider). ## [](#attach-to-an-mcp-server)Attach to an MCP server To attach an OAuth provider to an MCP server, the principal needs `dataplane_aigateway_oauthprovider_attach` on the named provider plus the usual `mcpserver_create` / `mcpserver_update` permission. See [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) for the full attach flow and [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) for the consent flow that runs on first call. ## [](#view-provider-details)View provider details Click a provider in the list to open its detail page. The header shows the display name, status badge, and resource name, with **Connect**, **Edit**, and **Delete** actions. A provider that was set up through discovery also shows a **Discovered** badge. The page groups the configuration into cards: - **Authorization Callback URL**: The gateway callback to register on the upstream OAuth app. - **OAuth Endpoints**: The authorization, token/refresh, and revocation endpoints. - **Client Configuration**: Client ID, Client Secret Ref, Auth Method, and whether PKCE is required. - **Registration** (discovered providers only): The dynamic-registration state. It shows the registration endpoint, the client-configuration URI (the RFC 7592 endpoint used to verify, refresh, or delete the registered client), and when the registration was last verified. The registration access token is a managed credential kept in the secret store, and its value is never shown. - **Scopes & Grant Types**: The default scopes and grant types. - **Metadata**: When the provider was created and last updated. ## [](#edit-and-rotate-credentials)Edit and rotate credentials You can change the provider’s configuration or rotate its client secret without re-creating the resource: - **Edit**: Open the provider’s detail page and click **Edit**. Endpoints, scopes, display name, and the client-secret reference can change. The `Name` is immutable. - **Rotate credentials**: Update the secret content in the secret store under the same name (for example, `SLACK_CLIENT_SECRET`). The provider’s reference is unchanged. Existing tokens in the vault stay valid; the new client secret is used the next time AI Gateway exchanges credentials. - **Disable temporarily**: Deleting the provider invalidates every MCP server’s connections that reference it, so disable the dependent MCP servers first if you want to pause traffic without losing user consent. ## [](#delete-a-provider)Delete a provider Deleting an OAuth provider: - Removes the provider record. - Causes every MCP server that referenced it to fail authentication on the next call (the `provider_name` reference no longer resolves). - Leaves user-stored tokens in the vault until garbage-collected, but they’re unusable without the provider definition. Plan the deletion: disable or reconfigure dependent MCP servers first, communicate the cutover to users so they can re-consent against a replacement provider, then delete. ## [](#troubleshooting)Troubleshooting Common symptoms and fixes: | Symptom | What to check | | --- | --- | | PermissionDenied when creating an MCP server with this provider attached | Nothing grants the principal dataplane_aigateway_oauthprovider_attach on this provider. Ask an admin for a policy granting Action::"OAuthProvider.attach", scoped to this provider. | | Consent flow fails with redirect_uri_mismatch | The OAuth app’s registered redirect URI doesn’t match the gateway’s callback. Update the upstream OAuth app to include https://aigw..clusters.rdpa.co/oauth/v1/callback. | | invalid_client during token exchange | Client ID or client secret is wrong, or the Token-endpoint authentication method doesn’t match what the upstream expects. Check the upstream OAuth app’s settings. | | invalid_scope during consent | A scope in Supported scopes isn’t valid for the upstream. Check the upstream’s scope reference and remove or rename the offending scope. | ## [](#next-steps)Next steps - [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) - [Plug in an App, Database, or Tool](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/)