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.

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.

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

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

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

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

Use rpk ai to script provider registration:

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

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

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

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

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