Agentic Data Plane

Configure User-Delegated OAuth

User-delegated OAuth means each end-user authenticates against the MCP server’s upstream system (for example, Slack, Jira, Google) with their own credentials. Redpanda stores their token in the token vault and injects it at call time. Contrast with service-account OAuth, where one shared identity is used for every caller.

After completing this guide, you will be able to:

  • Configure an MCP server to use user-delegated OAuth with a registered OAuth provider

  • Walk an end-user through the consent flow and verify the connection

  • Troubleshoot scope upgrades, token expiry, and refresh failures

Prerequisites

  • An OAuth provider resource configured in Redpanda ADP under OAuth providers. The provider declares the upstream’s authorize_url, token_url, supported scopes, and client credentials. See Configure an OAuth Provider.

  • The required scopes for the upstream API you plan to call.

  • For self-managed MCP servers: the server URL must be https:// (proto rule remote_mcp.user_oauth_requires_https). HTTP is rejected at create time.

  • For managed MCP servers: the type must support user-delegated OAuth. SQL doesn’t; Slack, Jira, and Google managed types do. Check Managed catalog before configuring.

Configure the server

  1. Create or edit your MCP server (see Create an MCP Server).

  2. In the authentication section, choose User-delegated OAuth.

  3. Pick the configured OAuth provider (UserOAuthAuth.provider_name).

  4. List the required scopes (UserOAuthAuth.required_scopes). Redpanda enforces these at consent time.

  5. (Optional) Override token injection through the API or CLI. By default Redpanda sends Authorization: Bearer <token>. To use a different header, set TokenInjection.header_name. To omit the prefix entirely (for example, an upstream that expects a bare API key as the token), set TokenInjection.header_prefix to the empty string. The create form doesn’t expose these fields; the UI’s user-delegated authentication section takes only the OAuth provider and required scopes.

  6. Save.

Choosing user-delegated OAuth instead of service-account OAuth is the credential-mode decision: there’s no separate field. User-delegated gives each caller a per-user upstream identity; service-account gives every caller one shared identity. Switching between them later requires re-consent for every active user.
To configure user-delegated OAuth from the CLI, use --user-oauth-provider and --user-oauth-scopes on rpk ai mcp create or rpk ai mcp update. See Create an MCP Server.

The user connection flow

The first time a user calls a tool that needs this server’s authentication, Redpanda doesn’t have a stored token for them. The behavior is:

  1. The MCP RPC returns FAILED_PRECONDITION with an OAuthConnectionRequired error detail. The detail carries an authorize_url.

  2. ADP surfaces a consent prompt to the user, pointing at the authorize_url.

  3. The user completes the device-authorization flow with the upstream provider.

  4. The upstream provider redirects back to Redpanda with a token. Redpanda stores it in the token vault under that user’s identity.

  5. The original tool call retries automatically. Subsequent calls reuse the stored token.

After consent, the user can see and revoke their connection under Connections in ADP.

Manage your connections

The Connections page in the sidebar is each user’s view of their own third-party connections: it lists one card per configured OAuth provider, so a user can authorize the providers their MCP servers need without waiting for a tool call to trigger the consent flow.

Each card shows the provider’s name, the scopes it requests, and a status of Not connected or connected. Click Connect to run the consent flow for that provider and store a token in the vault under your identity. Connections persist until you revoke them; remove and re-add a connection if the upstream credentials change.

Connections are per-user. Each user authorizes their own accounts, and one user’s connections are not visible to or usable by another.

Scope upgrades

If a user’s stored connection has fewer scopes than the server’s required_scopes, the gateway returns a scope_upgrade_required error and surfaces a new authorize_url requesting the additional scopes. The user re-consents; the connection is updated in place.

Refresh and expiry

Redpanda transparently refreshes tokens before they expire, using the refresh token returned at consent time.

When refresh fails (revoked token, idle too long, upstream error), the next tool call returns OAuthTokenExpired with a reason. The user must re-consent through the same flow as initial connection.

Service-account OAuth contrast

If you want one shared upstream identity for every caller (instead of per-user identities), choose Service-account OAuth on the server instead of User-delegated OAuth. With service-account OAuth, every caller of every tool sees the same upstream identity; the upstream system has no idea which ADP user invoked the tool. With user-delegated OAuth, the upstream system sees each end-user as themselves and applies their own permissions.

For the field-by-field service-account-OAuth setup, see create-server.adoc.

Worked examples

  • Slack: consumer-facing user-delegated OAuth example. Shows the consent flow against a real Slack workspace.

  • Jira: enterprise user-delegated OAuth example. Atlassian’s OAuth flow differs from Slack’s; this page calls out scope-management gotchas.

Troubleshooting

Symptom What to check

"OAuth provider not found"

The provider name on the server doesn’t match an OAuth provider in ADP. Check spelling and that the provider exists.

"HTTPS required" on save (self-managed only)

User-delegated OAuth requires https:// URLs on the MCP server (proto rule remote_mcp.user_oauth_requires_https). Switch the server’s URL to HTTPS.

OAuthConnectionRequired returned even after the user consented

The user’s vault entry might have been revoked or the token expired with no refresh. Have the user re-consent through Connections.

scope_upgrade_required returned

The required scopes on the server changed (or the user originally consented with fewer scopes). The user re-consents with the higher scope.

Connections shows stale entries

Connections persist until manually revoked. Have the user remove and re-add the connection if upstream credentials changed.

Next steps