Skip to main content

​
OAuth Broker

The OAuth Broker is a standalone, security-focused service that centralizes OAuth/OIDC flows across vendors (e.g., GitHub, Asana, Ramp, Datadog). It is deployed as shared infrastructure (e.g., oauth.runlayer.com) to provide a single, vendor-approved redirect URI and standardized flows, removing the need to register separate OAuth apps and redirect URIs per customer deployment.

​
Why an OAuth Broker

  • Allow-list problem: Many vendors require pre-approved redirect URIs. Self-hosted or per-tenant deployments often have unique domains that are not allow-listed, causing OAuth failures. The broker solves this by using a pre-registered, vendor-allow-listed domain.
  • Operational simplicity: Centralizes vendor app registrations, scopes, and callbacks—no more per-deployment manual configuration.
  • Security: Uses PKCE for the MCP↔Broker hop and for the Broker↔Vendor hop when the vendor supports it.
  • Consistency: Normalizes provider differences and offers a single integration surface for the platform.

​
How It Works (High Level)

The broker sits between Runlayer (MCP) and vendors, handling the user-facing authorization and the token exchange. Runlayer initiates the flow via the broker; the broker redirects to the vendor; upon completion, the broker exchanges the authorization code and returns tokens back to Runlayer.

​
PKCE-Protected Flow

The client-to-broker leg always uses PKCE. A second verifier protects the upstream leg when the vendor supports PKCE:
  • PKCE #1: MCP ↔ OAuth Broker
  • PKCE #2, when supported: OAuth Broker ↔ Vendor
An intercepted code on a PKCE-protected leg cannot be exchanged without its matching verifier. See the overall system diagram and components in Architecture.

​
Dynamic Client Registration (DCR)

The broker can perform Dynamic Client Registration (DCR) on behalf of clients for vendors that support it (like Ramp MCP). This simplifies onboarding by automatically registering OAuth applications with the vendor: For vendors that support DCR, the broker registers an OAuth client with the vendor on your behalf during onboarding, so you do not need to create a vendor OAuth app manually. The resulting vendor credentials are returned to your Runlayer deployment, which stores them encrypted as its BYOC configuration and uses them for subsequent authorization flows. For vendors without DCR, credentials come from your BYOC configuration. See How Runlayer Stores Credentials for how these credentials are protected at rest.

​
Security Considerations

  • State JWT: The broker validates a signed state to bind requests to vendors and sessions.
  • PKCE: Protects the client-to-broker hop and the upstream hop when the vendor supports it.
  • Token handling: Tokens are exchanged at the broker and returned to Runlayer. Production deployments can enable token encryption at rest and in transit.
  • Refresh and revocation: The broker exposes standardized refresh and revocation paths when acting on behalf of Runlayer.
  • OIDC validation: If OIDC is used, the broker validates ID tokens against provider JWKS.

​
Integration in Runlayer

  • In the server configuration UI, enable “Use OAuth Broker” for vendors that support it.
  • Ensure your deployment exposes the appropriate callback endpoint expected by the broker (the platform will compute this automatically when the broker URL is configured).
  • For vendors requiring manual approval/whitelisting, leverage the broker’s pre-registered redirect URI.

​
Manual OAuth Endpoint Overrides

Some OAuth providers use non-standard or tenant-specific endpoints that auto-discovery cannot resolve. When configuring an OAuth-authenticated server in manual mode, you can override the authorization and token URLs:
  • Authorization URL — Override the OAuth authorization endpoint (e.g., https://login.example.com/{TENANT}/oauth2/v2.0/authorize)
  • Token URL — Override the OAuth token endpoint (e.g., https://login.example.com/{TENANT}/oauth2/v2.0/token)
Leave these fields empty to use the provider’s auto-discovered endpoints. Both fields support {placeholder} syntax for dynamic values like tenant IDs.

​
Vendor Scenarios

The OAuth Broker is shared Runlayer infrastructure at oauth.runlayer.com. On Runlayer-hosted deployments it is used by default. On self-hosted deployments you can use the same broker when VPC egress allows oauth.runlayer.com (set oauth_broker_url accordingly); otherwise fall back to per-vendor setup — see Self-hosted deployments.

​
Self-hosted deployments

The OAuth Broker runs as shared Runlayer infrastructure (oauth.runlayer.com). Self-hosted deployments can call it when outbound HTTPS to that host is allowed — see Self-Hosted Egress Requirements. Without broker egress, each vendor falls back to its own OAuth setup:
  • GitHub — register your own OAuth app as a Pre-registered Client. See Adding GitHub MCP server.
  • Slack connector — register your own Slack app as a Pre-registered Client. See Slack.
  • Other vendors — self-hosted OAuth support varies. Contact Runlayer before enabling them on a self-hosted deployment.
oauth_broker_url is separate from WorkOS (api.workos.com / AuthKit), which handles SSO and SCIM.

​
OAuth inside a private VPC

Per-vendor OAuth does not require your deployment to be internet-facing. With a pre-registered client, the callback URL you register with the vendor (https://<your-tenant-url>/oauth/callback/) is served by your own deployment, and the vendor redirects to it via the user’s browser — the vendor never connects to it directly. So OAuth works with a VPC-internal tenant URL as long as:
  • users’ browsers can reach the deployment (e.g., corporate network or VPN) and the vendor’s authorization page, and
  • the deployment has outbound HTTPS to the vendor’s token endpoint for the code exchange.
When using the hosted broker instead, the deployment also needs outbound HTTPS to oauth.runlayer.com (see Self-Hosted Egress Requirements).

​
Vendor Setup Instructions

​
GitHub

GitHub works automatically through the OAuth Broker with no setup required. The broker handles all OAuth flows transparently.

​
Asana

Asana works automatically through the OAuth Broker with no setup required. The broker handles all OAuth flows transparently.

​
Ramp

Ramp works automatically through the OAuth Broker with no configuration required. The broker handles all OAuth flows transparently.

​
Guru

Guru works automatically through the OAuth Broker with no configuration required. The broker handles all OAuth flows transparently, including Dynamic Client Registration (DCR).

​
Box

Box works automatically through the OAuth Broker with no setup required. The broker handles all OAuth flows transparently. App-level permissions are configured on the Runlayer OAuth app in the Box Admin Console, not via OAuth scopes.

​
Datadog

To use Datadog with the OAuth Broker:
  1. Request organization access via the Datadog MCP Server preview form
  2. Once your organization is approved, Datadog works automatically through the broker

​
Microsoft Agent 365

Microsoft Agent 365 works automatically through the OAuth Broker using a shared multitenant Azure AD application. No Azure AD app registration is required. Users just need to:
  1. Enable Agent 365 access in the Microsoft Admin Center
  2. Configure their Power Platform environment ID in the server URL
See the full setup guide for details.

​
FAQ

No. The broker returns real vendor tokens to Runlayer. The platform calls the vendor APIs directly using those tokens.
Prefer OIDC discovery where available. The broker and platform can discover and cache endpoints.
The broker exchanges tokens and returns them to your Runlayer deployment — it is not the long-term token store. Tokens are never logged. PKCE protects the client-to-broker leg and the upstream leg when the provider supports it.
Vendor access and refresh tokens are stored by the Runlayer platform in PostgreSQL, in dedicated encrypted columns (application-level encryption applied before the value reaches the database). This sits on top of the database’s own AES-256 encryption at rest and TLS in transit — see Database and Security for the underlying storage and key-management configuration.
It depends on the vendor and your policy. The broker supports shared apps and DCR-based per-tenant apps when supported.
The broker relays a standardized error back to Runlayer, which surfaces it in the UI.
No. If a vendor fully supports your deployment’s redirect URIs and you prefer direct integration, you can disable the broker.
Some vendors require an IAT to allow DCR. Provide an org-level IAT to the broker for automated client onboarding.
Currently supported vendors include GitHub, Asana, Ramp, Guru, Box, Datadog, Microsoft Agent 365, and Slack. Check release notes for updates as support grows over time.
BYOC (Bring Your Own Credentials) allows you to use your own OAuth application instead of shared Runlayer credentials. Use BYOC when you need dedicated rate limits, custom scopes, or organization-specific OAuth apps for compliance reasons. For vendors that support brokered BYOC, the OAuth Broker still handles the authorization flow, solving redirect URI allow-listing challenges.
For vendors that support brokered BYOC, yes. You can edit a server configuration at any time to enable or disable BYOC. When switching, users will need to re-authorize as the OAuth app changes.
Brokered BYOC is supported as an optional configuration for GitHub and Asana. Slack intentionally uses the Pre-registered Client path for customer-owned apps, so those authorizations don’t traverse the broker. Other hosted vendors work through the broker without BYOC. On self-hosted deployments the broker isn’t available; GitHub and Slack support pre-registered clients, while other vendors vary.
BYOC credentials are encrypted at rest and only used by the OAuth broker during the authorization flow. PKCE behavior is the same whether using shared or BYOC credentials and depends on upstream vendor support.
Runlayer will display an error when attempting to authorize. You’ll need to update your credentials in the server configuration. Active user sessions may continue to work until their refresh tokens expire.
Many OAuth providers require you to pre-register exact redirect URIs in your OAuth app configuration. This becomes a problem when each customer deployment has a unique domain (https://customer1.example.com, https://customer2.example.com) or self-hosted deployments use custom domains that can’t be predicted in advance—vendors reject authorization requests if the redirect URI isn’t pre-allow-listed. For authorization flows that traverse the OAuth Broker, it provides a single, centralized redirect URI (https://oauth.runlayer.com/v1/callback) and securely returns tokens to the originating Runlayer deployment. Brokered BYOC apps register this broker URL. Customer-owned Slack apps instead use Pre-registered Client and must register the deployment-specific callback described in the Slack setup guide.
DCR (Dynamic Client Registration) is an OAuth 2.0 extension (RFC 7591) that allows programmatic creation of OAuth clients without manual setup. When vendors support native DCR (like Ramp MCP), the broker can perform DCR during the OAuth flow, calling the vendor’s DCR endpoint and returning the resulting credentials (client_id, client_secret, etc.) to the caller. The caller is then responsible for securely storing and using these vendor-specific credentials (often as BYOC configuration) in subsequent flows. This design simplifies client integration while enabling support for vendors that require DCR without forcing the broker to persist vendor credentials.