Agentic Data Plane

Configure an OAuth Provider

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

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 are on the Outbound providers tab, and OAuth clients are on the Inbound clients tab. They remain separate resources with separate 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.

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 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

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. 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_list

List 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. Checked when you create or update an MCP server and set or change its OAuth provider. 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.
The _attach permission is independent of _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::"<name>".

Browse OAuth providers

Open Integrations setup in the sidebar and click 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 these columns:

Column What it shows

Provider

The provider’s display name. A provider that Redpanda created while setting up an MCP server carries a Managed badge.

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 Add provider button opens the create form.

Register an OAuth provider in the UI

Walk through the create form to register the upstream:

  1. Open Integrations setup in the sidebar and click the Outbound providers tab.

  2. Click Add provider.

  3. Pick how to configure the provider:

    • Click a preset card in the catalog to fill in the standard authorization and token endpoints and recommended scopes.

    • Click Custom Provider to enter the endpoints yourself.

    • Click 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.

      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. Under Grant types, select Browser Consent. The user approves access in their browser (OAuth 2.0 Authorization Code flow). It’s the default for user-delegated OAuth.

  6. Select a Token endpoint authentication method:

    • Client Secret (Basic): client_id:client_secret sent as the Basic authentication header. Most common.

    • Client Secret (POST): Credentials sent as form fields in the token-request body.

    • None (PKCE only): For public clients that rely on PKCE only. Select 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 reference (a secret-store key in UPPER_SNAKE_CASE, for example SLACK_CLIENT_SECRET). Select Existing to use 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. For a Slack provider, select the Slack OAuth token type. This setting decides the Slack identity every MCP server attached to this provider acts as, and it can’t be changed after creation:

    • Bot User OAuth Token (the default): Tools act as the Slack app’s bot user, and the Scopes field is labeled Bot Token Scopes.

    • User OAuth Token: Tools act as the person who authorizes the connection, and the Scopes field is labeled User Token Scopes.

      The setting appears only when the authorization and token endpoints are Slack’s standard pair (https://slack.com/oauth/v2/authorize and https://slack.com/api/oauth.v2.access), so it isn’t offered on a provider created by discovery. To offer both identities, register one provider per identity. See Choose the posting identity.

  9. Define the Scopes. Click Add scope to add a field for each one, and enter a single scope per field, with no commas or spaces. Include every scope any MCP server may need. Each field checks its own value as you type, and flags an empty field, a value holding a space or a comma, a character that isn’t allowed in an OAuth scope, and a scope that another field already holds.

  10. Optionally turn on Require PKCE to add PKCE (RFC 7636) to the consent flow. Leave Enabled on so the provider can start consent flows.

  11. Click Create provider.

The provider appears in the Outbound providers list.

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.

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.

To discover a provider:

  1. Open Integrations setup in the sidebar and click the Outbound providers tab.

  2. Click Add provider, then click 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 at its own URL and fills in the provider settings. There is no client to register, no callback URL to paste, and no shared client secret. The form shows the client ID, which is that URL. Confirm the details and click Create provider.

    Server supports dynamic client registration

    The gateway registers itself as an OAuth client with the remote server’s authorization server and fills in the provider settings. Confirm the details and click Register & create 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

    The page shows No OAuth detected, with a link to configure a provider manually if you know its OAuth endpoints.

    Server supports OAuth, but not client metadata documents or dynamic client registration

    The page shows Manual setup required. Follow its link to the create form and enter the client ID and secret from the server’s OAuth app, as described in Register an OAuth provider in the UI. Nothing is filled in for you.

A provider created this way shows a Discovered badge on its detail page, which distinguishes it from a provider you configured manually. A provider that identifies the gateway by its client metadata document also shows a Metadata document badge and the client ID callout, and has no Registration card, because nothing was registered. A provider created through dynamic client registration shows a Registration card. See View provider details.

The client ID the gateway presents is the URL of the metadata document it publishes, so it’s the same for every remote server this gateway connects to. If a server accepts only approved clients, it rejects the gateway’s sign-in attempts, usually with an invalid client error, until its administrator allows that URL. Copy the URL from the callout on the discovery result or on the provider’s detail page.

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 a Managed badge. Redpanda owns a managed provider. You can’t edit, disable, or delete it, and it’s removed when you delete the MCP server. See User-delegated OAuth.

Register from the CLI

Use rpk ai to script provider registration:

rpk ai oauth-provider create ramp \
  --enabled \
  --display-name "Ramp" \
  --authorization-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" \
  --grant-types oauth-grant-type-browser-consent

The provider name is a positional argument, not a flag. A new provider is disabled unless you pass --enabled.

For every flag, see rpk ai oauth-provider create. A few things the reference page doesn’t spell out:

  • Unless you pass --register-from-url, the display name, the authorization and token endpoints, the client ID, and at least one grant type are required.

  • --register-from-url takes a remote MCP server URL and runs the same discovery as the UI. The gateway identifies itself with its client metadata document when the server accepts one, registers a client through dynamic client registration otherwise, and reports an error when the server supports neither. See Discover a provider from an MCP server URL.

  • --slack-token-type can’t be changed after creation.

List and filter providers

On the Outbound providers tab, search by provider name or filter by Status.

To filter on more than that, use rpk ai oauth-provider list. It accepts these flags:

  • --name-contains: Case-insensitive substring match on the provider name.

  • --filter: An AIP-160 expression (maximum 1024 characters) that’s combined with --name-contains. Filterable fields are name, display_name, enabled, grant_types, created_at, and updated_at. The grant_types field accepts OAUTH_GRANT_TYPE_BROWSER_CONSENT and OAUTH_GRANT_TYPE_TOKEN_EXCHANGE, and enabled accepts true or false.

  • --order-by: A comma-separated list of name, display_name, or created_at, each optionally followed by ` desc`. The default is created_at desc.

  • --page-size and --page-token: Page through a long list. The command prints the token for the next page. Keep --order-by the same on every page.

This example lists only enabled providers, ordered by display name:

rpk ai oauth-provider list --filter 'enabled = true' --order-by display_name

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 for the full attach flow and User-delegated OAuth for the consent flow that runs on first call.

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 and Edit actions and a Disable or Enable control. A provider that was set up through discovery also shows a Discovered badge, one that identifies the gateway by its client metadata document shows Metadata document, and one that Redpanda created for an MCP server shows Managed and has no Edit. A separate section deletes the provider. The configuration is grouped into cards:

  • Authorization Callback URL: The gateway callback to register on the upstream OAuth app. A provider that identifies the gateway by its client metadata document shows a Client ID Metadata Document callout here instead, with the document URL that serves as the client ID.

  • OAuth endpoints: The authorization, token/refresh, and revocation endpoints.

  • Client configuration: Client ID, Client secret reference, Authentication method, whether PKCE is required, and, for a Slack provider, the Slack OAuth token type. For a client metadata document provider, the first row is labeled Client ID (metadata document).

  • Registration (providers discovered through dynamic client registration 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 and grant types: The default scopes and grant types.

  • Metadata: When the provider was created and last updated.

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 scope fields are checked when the form loads, so a provider whose scopes were stored as one comma-separated or space-separated value has to be split into one scope per field before any other change will save. The Name and Client ID are immutable, and so is a Slack provider’s Slack OAuth token type. The edit form shows it read-only.

  • 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: Click Disable on the provider’s detail page. Users can’t complete OAuth flows through the provider until you click Enable again.

Delete a provider

Agentic Data Plane refuses to delete a provider while any MCP server still uses it. The error names the servers. Detach the provider from each server, or delete the server, first. A managed provider is removed automatically when you delete the MCP server that owns it.

Deleting an OAuth provider removes the provider and revokes every token users stored for it. Users reconnect against a replacement provider.

To delete a provider, open its detail page, click Delete in the Delete this OAuth provider section, and type delete to confirm.

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.<cluster-id>.clusters.rdpa.co/oauth/v1/callback.

invalid_client during sign-in or 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. For a provider with a Metadata document badge, the server may accept only approved clients. Ask its administrator to allow the client ID URL shown in the callout on the provider’s detail page.

invalid_scope during consent

A scope in Scopes isn’t valid for the upstream. Check the upstream’s scope reference and remove or rename the offending scope.

Next steps