# 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.1.5
latest-console-tag: v3.7.4
latest-connect-version: 4.96.1
latest-redpanda-tag: v26.1.10
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 ADP 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-06-15"
---

<!-- Source: https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers.md -->

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.
>
>
> The two live under separate sidebar entries (**OAuth Providers** and **OAuth Clients**) 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.<cluster-id>.clusters.rdpa.co/oauth/v1/callback`).

-   The OAuth app’s **client ID** and **client secret**.

-   A secret already created in the Redpanda ADP 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. Granting create/update/delete to an admin role is independent from granting attach to MCP-editor roles.

| 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 roles that need to bind a given provider’s token vault to an MCP server.

## [](#browse-oauth-providers)Browse OAuth providers

The **OAuth Providers** page lists every provider registered in your organization. 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 **OAuth Providers** in the sidebar.

2.  Click **Create provider**.

3.  Pick a preset from the catalog, or choose **Custom Provider** to enter the endpoints yourself. Picking a preset pre-fills the standard authorization and token endpoints and recommended scopes.

    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 **OAuth Providers** list.

## [](#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 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). |

## [](#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. 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.

-   **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 | The principal lacks dataplane_aigateway_oauthprovider_attach on this provider. Have an admin grant the permission, or delegate the attach to a role that already has it. |
| 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.<cluster-id>.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/)