OAuth authorization server

Posit Connect includes an OAuth 2.1 authorization server that allows third-party applications to authenticate users and access Connect on their behalf. This enables AI tools, development environments, and other OAuth-compliant clients to connect to content and APIs on Connect.

Note

This documentation covers Connect’s OAuth authorization server for third-party client authentication. For other OAuth features in Connect, see:

Overview

The OAuth authorization server implements:

When a user explicitly approves a client, the client receives an access token that grants the same permissions the user has on Connect. The client can then make API calls and access content on the user’s behalf.

This provides an alternative to API keys. While API keys require users to manually generate and configure credentials, OAuth allows applications to request access through a browser-based authorization flow. OAuth tokens are short-lived and automatically refresh.

OAuth endpoints

Connect exposes the following OAuth endpoints:

Endpoint Description
/.well-known/oauth-authorization-server Server metadata (RFC 8414)
/oauth/v1/register Dynamic client registration (RFC 7591)
/oauth/v1/authorize Authorization endpoint
/oauth/v1/token Token endpoint
/oauth/v1/revoke Token revocation (RFC 7009)
/oauth/v1/device/authorize Device authorization (RFC 8628)
/oauth/v1/device/verify Device code verification

OAuth clients use these endpoints automatically during the authentication flow.

Example: MCP clients

One example of OAuth client authentication is connecting AI applications to servers deployed on Connect that use the Model Context Protocol (MCP). The following applications support MCP:

  • Claude Code, Codex, and other terminal interfaces
  • Copilot, Posit Assistant, Cursor, and other IDE-based tools
  • Other MCP-compatible AI assistants

When users connect their application to an MCP server on Connect, the OAuth flow asks them to review and explicitly authorize the application in their browser. After approval, the application can access the MCP server’s tools and resources.

For information about deploying MCP servers to Connect, see the MCP servers user guide.

Connect also includes a built-in MCP server for managing Connect content. See Connect MCP in the user guide for its endpoint and client connection instructions. The MCP reference lists the tools, descriptions, inputs, and outputs for the built-in server.

Configuration

Enabling OAuth clients

The OAuth authorization server is enabled by default. To disable it, set:

[Server]
OAuthClientsEnabled = false

See Server.OAuthClientsEnabled in the configuration reference.

Allowed redirect URIs

OAuth clients use Dynamic Client Registration (DCR) to register with Connect automatically. During registration, clients specify a redirect URI where users are sent after authorizing the connection. This registration happens automatically and is invisible to the end user.

Connect allows the following redirect URIs by default:

  • http://localhost and http://127.0.0.1 (any port) for tools running on your machine
  • https://vscode.dev/redirect and https://insiders.vscode.dev/redirect for VS Code
  • cursor://anysphere.cursor-mcp/oauth/callback for Cursor

To allow additional redirect URIs, such as for Posit Workbench or custom applications, use the OAuthAllowedRedirectURI setting. You can specify multiple URIs:

[Server]
OAuthAllowedRedirectURI = https://workbench.example.com/oauth_redirect_callback
OAuthAllowedRedirectURI = https://myapp.example.com/callback

See Server.OAuthAllowedRedirectURI in the configuration reference.

Posit Workbench environments

Some clients running inside Workbench, including Posit Assistant, use the built-in Workbench OAuth redirect relay. The relay appends /oauth_redirect_callback to the browser-reachable Workbench URL instead of using a localhost redirect. This relay supports cases where the browser and the IDE run on different machines.

To enable the browser-based OAuth sign-in flow for clients that use this relay, add the exact redirect URI that the client advertises:

[Server]
OAuthAllowedRedirectURI = https://<your-workbench-url>/oauth_redirect_callback

Connect matches non-localhost redirect URIs exactly, so include the full path, including any Workbench path segment.

Some clients support the device code flow as an alternative to browser redirects. In this flow, users authenticate in the browser and enter a verification code instead of being redirected back to the client.

Note

The localhost and 127.0.0.1 defaults apply when the browser and the client run on the same machine. Clients that use the Workbench relay require the explicit redirect URI configuration shown above for browser-based OAuth.

Security considerations

Server-wide access

When a user authorizes an OAuth client, the client gains access to all Connect content and APIs that the user can access. Clients are not limited to certain content items. To manage users’ access to MCP servers and other content via the OAuth flow, use the same access-control mechanisms used more generally in Connect.

Users must explicitly approve each authorization request in the browser. The consent page names the application, but the name supplied during dynamic client registration is not verified by Connect. Connect does not endorse or review the application. If the application name is unexpected or the user did not initiate the request, the user should deny it.

Redirect URI validation

Connect validates redirect URIs to prevent authorization code interception attacks. Connect only accepts URIs matching the allowed list (localhost, the default URIs, and any URIs you configure) during client registration.

Be cautious when adding redirect URIs. Only add URIs for applications you trust, as they will be able to obtain access tokens for any user who authorizes them.

Token security

Access tokens issued by the OAuth server:

  • Are short-lived and automatically refresh
  • Cannot be used to obtain the user’s password or other credentials

Token revocation

Connect supports OAuth 2.0 Token Revocation (RFC 7009). Clients can revoke refresh tokens by sending a POST request to the /oauth/v1/revoke endpoint. This allows clients to invalidate tokens that are no longer needed, for example during a logout flow.

Revocation is limited to refresh tokens.

Troubleshooting

Redirect URI not allowed

When an OAuth client attempts to register with Connect, Connect can return this error:

Redirect URI not allowed: <uri>. Only localhost redirect URIs are allowed by default. Configure Server.OAuthAllowedRedirectURI to allow additional URIs.

  • Cause: The redirect URI that the client sent is not in the Connect allowed list.

  • Solution: Add the exact URI to Server.OAuthAllowedRedirectURI. Connect compares non-localhost redirect URIs as strings, so the configured value must match the URI the client sends character for character, including the scheme, the host, the full path, and a port only when the client’s URI carries one. See allowed redirect URIs.

Unsupported redirect target

Positron versions before 2026.07.0 can show this error during OAuth sign-in from Workbench:

Unsupported redirect target: <host>
  • Solution: Upgrade to Positron 2026.07.0 or later. No Connect setting corrects this error in earlier versions. In Positron 2026.07.0 and later, Connect might instead report “Redirect URI not allowed”. Add the exact Workbench callback URI from that error to Server.OAuthAllowedRedirectURI. See redirect URI not allowed.