​

OAuth Broker

The OAuth Broker is a standalone, security-focused service that centralizes OAuth/OIDC flows across vendors (e.g., Google, GitHub, Asana, Atlassian). 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) with Initial Access Token

When supported by vendors, the broker can perform DCR to create or map OAuth clients dynamically. This is especially useful when onboarding many tenants:

• Initial Access Token (IAT): Some vendors require an IAT to authorize client registrations.
• Client mapping: The broker stores mappings between Runlayer deployments and vendor apps, supporting either a shared vendor app or per-tenant apps.

If a vendor doesn’t support DCR, the broker still works using a pre-registered app with a static allow-listed redirect URI.

​

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.
• Local/Dev: Docker Compose; in-memory session storage for MVP.
• 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

​

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: Support grows over time. Common vendors include GitHub, Asana, Datadog, Atlassian, and Google. Check release notes for updates. 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: Only vendors that support BYOC mode (currently GitHub and Asana). Check the BYOC support table above for the latest vendor compatibility. 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 (like Asana, Atlassian) 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. The OAuth Broker implements its own DCR layer on top of the OAuth flow, providing a registration endpoint (/register) that allows automated client registration even when vendors don’t natively support DCR. This means the broker can accept client registration requests from Runlayer deployments, create and manage client credentials, and store mappings between deployments and their OAuth configurations. When vendors do support native DCR, the broker can leverage it to create vendor-side OAuth apps dynamically. Some vendors require an Initial Access Token (IAT) for their DCR endpoints—the broker can accept an org-level IAT and use it to create per-tenant OAuth clients on the vendor side.