​

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 outside of customer environments (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: Implements a dual-PKCE flow so that both hops are protected: MCP↔Broker and Broker↔Vendor.
• 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.

​

Dual-PKCE Flow

Two PKCE verifiers are used for two distinct legs:

• PKCE #1: MCP ↔ OAuth Broker
• PKCE #2: OAuth Broker ↔ Vendor

This ensures that even if an auth code is intercepted on either leg, it cannot be exchanged without the matching verifier.

​

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:

​

How DCR Works in the Broker

1. Client registers with the broker: POST /register with vendor: "ramp" (no vendor credentials provided).
2. Broker performs DCR: Internally calls the vendor’s DCR endpoint (e.g., POST https://app.ramp.com/v1/public/customer/oauth/applications).
3. Vendor returns credentials: Dynamically generated vendor client_id and client_secret.
4. Broker returns DCR response to the caller: The raw DCR response (including vendor client_id and client_secret) is returned to the client, which is responsible for securely storing and managing these credentials (e.g., as BYOC configuration).
5. Client authorization: Subsequent authorization flows can use either shared broker credentials or BYOC vendor credentials, depending on how the client configures the integration.

​

Security Considerations

• Single DCR hop: The broker performs DCR once and returns credentials to the caller; it does not retain or re-use those credentials on its own.
• Stateless Design: The broker does not persist DCR-generated vendor credentials; long-term storage is the responsibility of the caller.
• Dynamic Resolution: Vendor credentials can be configured later as BYOC (or environment variables) when needed for OAuth flows.
• Environment Fallback: For non-DCR vendors, credentials come from environment variables or BYOC configuration.

​

Security Considerations

• State JWT: The broker validates a signed state to bind requests to vendors and sessions.
• Dual PKCE: Prevents code interception on either hop from becoming useful.
• 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.

​

Deployment Model

• Hosted: oauth.runlayer.com (recommended) with vendor apps allow-listing this redirect URI.
• Production: AWS ECS Fargate behind ALB; optional Redis for sessions, KMS/Vault for encryption.

See the overall system diagram and components in Architecture.

​

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.

​

Vendor Scenarios

​

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.

​

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

​

FAQ

Q: Do we proxy vendor API calls through the broker?
A: No. The broker returns real vendor tokens to Runlayer. The platform calls the vendor APIs directly using those tokens. Q: What if the vendor changes their OAuth endpoints?
A: Prefer OIDC discovery where available. The broker and platform can discover and cache endpoints. Q: How are tokens protected?
A: In production, enable encryption-at-rest (e.g., KMS/Vault) and never log tokens. The dual-PKCE flow also limits code theft risk. Q: Does every tenant need its own vendor app?
A: It depends on the vendor and your policy. The broker supports shared apps and DCR-based per-tenant apps when supported. Q: What if a user cancels authorization?
A: The broker relays a standardized error back to Runlayer, which surfaces it in the UI. Q: Is the broker mandatory?
A: No. If a vendor fully supports your deployment’s redirect URIs and you prefer direct integration, you can disable the broker. Q: How does Initial Access Token (IAT) fit in?
A: Some vendors require an IAT to allow DCR. Provide an org-level IAT to the broker for automated client onboarding. Q: Which vendors are supported?
A: Currently supported vendors include GitHub, Asana, Ramp, and Datadog. Check release notes for updates as support grows over time. Q: What is BYOC and when should I use it?
A: 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. Even with BYOC, the OAuth Broker still handles the authorization flow, solving redirect URI allow-listing challenges. Q: Can I switch between shared credentials and BYOC?
A: Yes. You can edit a server configuration at any time to enable/disable BYOC. When switching, users will need to re-authorize as the OAuth app changes. Q: Do BYOC credentials work with all vendors?
A: BYOC is supported as an optional configuration for GitHub and Asana. All vendors (GitHub, Asana, Ramp, and Datadog) work automatically through the broker without requiring BYOC configuration. Q: How secure is BYOC?
A: BYOC credentials are encrypted at rest and only used by the OAuth broker during the authorization flow. The dual-PKCE flow provides the same security guarantees whether using shared or BYOC credentials. Q: What happens if my BYOC credentials expire or are revoked?
A: 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. Q: What is the redirect URI allow-listing problem and how does the broker solve it?
A: 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. The OAuth Broker solves this by providing a single, centralized redirect URI (https://oauth.runlayer.com/v1/callback) that all vendors can allow-list. When you create your OAuth app (BYOC or otherwise), you only register this one broker URL. The broker handles the authorization callback and securely returns tokens to your specific Runlayer deployment, meaning all customer deployments work through the same allow-listed URI without needing vendor approval for their unique domains. Q: What is DCR (Dynamic Client Registration) and how does the broker help?
A: 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.