@cloudflare/workers-oauth-provider
Advanced tools
This is a TypeScript library that implements the provider side of the OAuth 2.1 protocol with PKCE support. The library is intended to be used on Cloudflare Workers.
A Worker that uses the library might look like this:
import { OAuthProvider } from '@cloudflare/workers-oauth-provider';
import { WorkerEntrypoint } from 'cloudflare:workers';
// We export the OAuthProvider instance as the entrypoint to our Worker. This means it
// implements the `fetch()` handler, receiving all HTTP requests.
export default new OAuthProvider({
// Configure API routes. Any requests whose URL starts with any of these prefixes will be
// considered API requests. The OAuth provider will check the access token on these requests,
// and then, if the token is valid, send the request to the API handler.
// You can provide:
// - A single route (string) or multiple routes (array)
// - Full URLs (which will match the hostname) or just paths (which will match any hostname)
apiRoute: [
'/api/', // Path only - will match any hostname
'https://api.example.com/', // Full URL - will check hostname
],
// When the OAuth system receives an API request with a valid access token, it passes the request
// to this handler object's fetch method.
// You can provide either an object with a fetch method (ExportedHandler)
// or a class extending WorkerEntrypoint.
apiHandler: ApiHandler, // Using a WorkerEntrypoint class
// For multi-handler setups, you can use apiHandlers instead of apiRoute+apiHandler.
// This allows you to use different handlers for different API routes.
// Note: You must use either apiRoute+apiHandler (single-handler) OR apiHandlers (multi-handler), not both.
// Example:
// apiHandlers: {
// "/api/users/": UsersApiHandler,
// "/api/documents/": DocumentsApiHandler,
// "https://api.example.com/": ExternalApiHandler,
// },
// Any requests which aren't API request will be passed to the default handler instead.
// Again, this can be either an object or a WorkerEntrypoint.
defaultHandler: defaultHandler, // Using an object with a fetch method
// This specifies the URL of the OAuth authorization flow UI. This UI is NOT implemented by
// the OAuthProvider. It is up to the application to implement a UI here. The only reason why
// this URL is given to the OAuthProvider is so that it can implement the RFC-8414 metadata
// discovery endpoint, i.e. `.well-known/oauth-authorization-server`.
// Can also be specified as just a path (e.g., "/authorize").
authorizeEndpoint: 'https://example.com/authorize',
// This specifies the OAuth 2 token exchange endpoint. The OAuthProvider will implement this
// endpoint (by directly responding to requests with a matching URL).
// Can also be specified as just a path (e.g., "/oauth/token").
tokenEndpoint: 'https://example.com/oauth/token',
// This specifies the RFC-7591 dynamic client registration endpoint. This setting is optional,
// but if provided, the OAuthProvider will implement this endpoint to allow dynamic client
// registration.
// Can also be specified as just a path (e.g., "/oauth/register").
clientRegistrationEndpoint: 'https://example.com/oauth/register',
// Optional list of scopes supported by this OAuth provider.
// If provided, this will be included in the RFC 8414 metadata as 'scopes_supported'.
// If not provided, the 'scopes_supported' field will be omitted from the metadata.
scopesSupported: ['document.read', 'document.write', 'profile'],
// Optional: Controls whether the OAuth implicit flow is allowed.
// The implicit flow is discouraged in OAuth 2.1 but may be needed for some clients.
// Defaults to false.
allowImplicitFlow: false,
// Optional: Controls whether the plain PKCE code_challenge_method is allowed.
// OAuth 2.1 recommends using S256 exclusively as plain offers no cryptographic protection.
// When false, only S256 is accepted and advertised in the metadata endpoint.
// Defaults to true for backward compatibility.
allowPlainPKCE: true,
// Optional: Controls whether public clients (clients without a secret, like SPAs)
// can register via the dynamic client registration endpoint.
// When true, only confidential clients can register.
// Note: Creating public clients via the OAuthHelpers.createClient() method
// is always allowed regardless of this setting.
// Defaults to false.
disallowPublicClientRegistration: false,
// Optional: Time-to-live for refresh tokens in seconds.
// Defaults to 30 days (2,592,000 seconds).
// Set to 0 to disable refresh tokens (only access tokens will be issued).
// Set to `undefined` explicitly for refresh tokens that never expire.
refreshTokenTTL: 2592000, // 30 days (the default)
// Optional: Time-to-live for access tokens in seconds.
// Defaults to 1 hour (3600 seconds) if not specified.
accessTokenTTL: 3600,
// Optional: Time-to-live for dynamically registered clients in seconds.
// Defaults to 90 days (7,776,000 seconds).
// Clients created via OAuthHelpers.createClient() are not affected.
// Set to `undefined` explicitly for clients that never expire.
clientRegistrationTTL: 7776000, // 90 days (the default)
// Optional: Controls whether OAuth 2.0 Token Exchange (RFC 8693) is allowed.
// When false, the token exchange grant type will not be advertised in metadata
// and token exchange requests will be rejected.
// Defaults to false.
allowTokenExchangeGrant: false,
// Optional: Experimental MCP Enterprise-Managed Authorization support.
// When enabled, the token endpoint accepts ID-JAG JWTs with the JWT bearer grant.
enterpriseManagedAuthorization: undefined,
// Optional: Explicitly enable Client ID Metadata Document (CIMD) support.
// When true, URL-formatted client_ids will be fetched as metadata documents.
// Requires the 'global_fetch_strictly_public' compatibility flag.
// See the CIMD section below for details. Defaults to false.
clientIdMetadataDocumentEnabled: false,
});
// The default handler object - the OAuthProvider will pass through HTTP requests to this object's fetch method
// if they aren't API requests or do not have a valid access token
const defaultHandler = {
// This fetch method works just like a standard Cloudflare Workers fetch handler
//
// The `request`, `env`, and `ctx` parameters are the same as for a normal Cloudflare Workers fetch
// handler, and are exactly the objects that the `OAuthProvider` itself received from the Workers
// runtime.
//
// The `env.OAUTH_PROVIDER` provides an API by which the application can call back to the
// OAuthProvider.
async fetch(request: Request, env, ctx) {
let url = new URL(request.url);
if (url.pathname == '/authorize') {
// This is a request for our OAuth authorization flow UI. It is up to the application to
// implement this. However, the OAuthProvider library provides some helpers to assist.
// `env.OAUTH_PROVIDER.parseAuthRequest()` parses the OAuth authorization request to extract the parameters
// required by the OAuth 2 standard, namely response_type, client_id, redirect_uri, scope, and
// state. It returns an object containing all these (using idiomatic camelCase naming).
let oauthReqInfo = await env.OAUTH_PROVIDER.parseAuthRequest(request);
// `env.OAUTH_PROVIDER.lookupClient()` looks up metadata about the client, as definetd by RFC-7591. This
// includes things like redirect_uris, client_name, logo_uri, etc.
let clientInfo = await env.OAUTH_PROVIDER.lookupClient(oauthReqInfo.clientId);
// At this point, the application should use `oauthReqInfo` and `clientInfo` to render an
// authorization consent UI to the user. The details of this are up to the app so are not
// shown here.
// After the user has granted consent, the application calls `env.OAUTH_PROVIDER.completeAuthorization()` to
// grant the authorization.
let { redirectTo } = await env.OAUTH_PROVIDER.completeAuthorization({
// The application passes back the original OAuth request info that was returned by
// `parseAuthRequest()` earlier.
request: oauthReqInfo,
// The application must specify the user's ID, which is some sort of string. This is needed
// so that the application can later query the OAuthProvider to enumerate all grants
// belonging to a particular user, e.g. to implement an audit and revocation UI.
userId: '1234',
// The application can specify some arbitary metadata which describes this grant. The
// metadata can contain any JSON-serializable content. This metadata is not used by the
// OAuthProvider, but the application can read back the metadata attached to specific
// grants when enumerating them later, again e.g. to implement an udit and revocation UI.
metadata: { label: 'foo' },
// The application specifies the list of OAuth scope identifiers that were granted. This
// may or may not be the same as was requested in `oauthReqInfo.scope`.
scope: ['document.read', 'document.write'],
// `props` is an arbitrary JSON-serializable object which will be passed back to the API
// handler for every request authorized by this grant.
props: {
userId: 1234,
username: 'Bob',
},
});
// `completeAuthorization()` will have returned the URL to which the user should be redirected
// in order to complete the authorization flow. This is the requesting client's OAuth
// redirect_uri with the appropriate query parameters added to complete the flow and obtain
// tokens.
return Response.redirect(redirectTo, 302);
}
// ... the application can implement other non-API HTTP endpoints here ...
return new Response('Not found', { status: 404 });
},
};
// The API handler object - the OAuthProivder will pass authorized API requests to this object's fetch method
// (because we provided it as the `apiHandler` setting, above). This is ONLY called for API requests
// that had a valid access token.
class ApiHandler extends WorkerEntrypoint {
// This fetch method works just like any other WorkerEntrypoint fetch method. The `request` is
// passed as a parameter, while `env` and `ctx` are available as `this.env` and `this.ctx`.
//
// The `this.env.OAUTH_PROVIDER` is available just like in the default handler.
//
// The `this.ctx.props` property contains the `props` value that was passed to
// `env.OAUTH_PROVIDER.completeAuthorization()` during the authorization flow that authorized this client.
fetch(request: Request) {
// The application can implement its API endpoints like normal. This app implements a single
// endpoint, `/api/whoami`, which returns the user's authenticated identity.
let url = new URL(request.url);
if (url.pathname == '/api/whoami') {
// Since the username is embedded in `ctx.props`, which came from the access token that the
// OAuthProivder already verified, we don't need to do any other authentication steps.
return new Response(`You are authenticated as: ${this.ctx.props.username}`);
}
return new Response('Not found', { status: 404 });
}
}
By default, completeAuthorization() revokes existing grants for the same user and client after storing the new
grant. This prevents stale tokens from continuing to use old props after a user re-authorizes. Set
revokeExistingGrants: false only if your application intentionally allows multiple concurrent grants for the same
user and client.
For users with many grants, revokeExistingGrantsBatchSize controls the KV page size used while scanning existing
grants for revocation. It defaults to 50, must be a positive integer, and is capped at Cloudflare KV's maximum page
size of 1000.
This implementation requires that your worker is configured with a Workers KV namespace binding called OAUTH_KV, which is used to store token information. See the file storage-schema.md for details on the schema of this namespace.
The env.OAUTH_PROVIDER object available to the fetch handlers provides some methods to query the storage, including:
lookupClient(), already shown in the example code).Note that deleteClient() cascades: it revokes all grants (and their associated tokens) for the deleted client across all users.
See the OAuthHelpers interface definition for full API details.
This library allows you to update the props value during token exchanges by configuring a callback function. This is useful for scenarios where the application needs to perform additional processing when tokens are issued or refreshed.
For example, if your application is also a client to some other OAuth API, you might want to perform an equivalent upstream token exchange and store the result in the props. The callback can be used to update the props for both the grant record and specific access tokens.
To use this feature, provide a tokenExchangeCallback in your OAuthProvider options:
new OAuthProvider({
// ... other options ...
tokenExchangeCallback: async (options) => {
// options.grantType is either 'authorization_code' or 'refresh_token'
// options.props contains the current props
// options.clientId, options.userId, and options.scope are also available
if (options.grantType === 'authorization_code') {
// For authorization code exchange, might want to obtain upstream tokens
const upstreamTokens = await exchangeUpstreamToken(options.props.someCode);
return {
// Update the props stored in the access token
accessTokenProps: {
...options.props,
upstreamAccessToken: upstreamTokens.access_token,
},
// Update the props stored in the grant (for future token refreshes)
newProps: {
...options.props,
upstreamRefreshToken: upstreamTokens.refresh_token,
},
};
}
if (options.grantType === 'refresh_token') {
// For refresh token exchanges, might want to refresh upstream tokens too
const upstreamTokens = await refreshUpstreamToken(options.props.upstreamRefreshToken);
return {
accessTokenProps: {
...options.props,
upstreamAccessToken: upstreamTokens.access_token,
},
newProps: {
...options.props,
upstreamRefreshToken: upstreamTokens.refresh_token || options.props.upstreamRefreshToken,
},
// Optionally override the default access token TTL to match the upstream token
accessTokenTTL: upstreamTokens.expires_in,
};
}
},
});
The callback can:
accessTokenProps and newProps to update bothaccessTokenProps to update just the current access tokennewProps to update both the grant and access token (the access token inherits these props)accessTokenTTL to override the default TTL for this specific access tokenrefreshTokenTTL to override the default TTL for this specific refresh tokenThe accessTokenTTL override is particularly useful when the application is also an OAuth client to another service and wants to match its access token TTL to the upstream access token TTL. This helps prevent situations where the downstream token is still valid but the upstream token has expired.
The props values are end-to-end encrypted, so they can safely contain sensitive information.
Throw OAuthError from tokenExchangeCallback to return a structured OAuth /token error ({ error, error_description }) instead of a generic 500:
import { OAuthError, OAuthProvider } from '@cloudflare/workers-oauth-provider';
new OAuthProvider({
// …
tokenExchangeCallback: async (options) => {
if (options.grantType === 'refresh_token') {
return { newProps: await refreshUpstream(options.props) };
}
},
});
async function refreshUpstream(props) {
const res = await fetch(/* upstream token endpoint */);
if (res.status === 401) {
throw new OAuthError('invalid_grant', {
description: 'upstream refresh token is invalid',
});
}
if (res.status === 429) {
throw new OAuthError('temporarily_unavailable', {
description: 'upstream rate limited',
statusCode: 429,
headers: { 'Retry-After': res.headers.get('retry-after') ?? '60' },
});
}
return await res.json();
}
OAuthError(code, options) takes:
code — OAuth error code returned in the error field. This may be a standard code (OAuthTokenErrorCode) or an application-defined string.options.description — human-readable text returned in error_description.options.statusCode — HTTP status code (default 400).options.headers — additional response headers, such as Retry-After for transient failures. There is no implicit Retry-After default for callback-thrown errors.Only OAuthError from this package is converted into a structured /token response. Plain errors, plain objects with a code field, and app-local error classes continue to surface as 500s so unexpected failures stay visible. Import OAuthError from @cloudflare/workers-oauth-provider rather than copying or re-implementing it.
Accepts ID-JAG assertions at /token per the MCP Enterprise-Managed Authorization extension. The enterprise IdP issues an ID-JAG JWT and the MCP client exchanges it here for an opaque access token.
new OAuthProvider({
// ... other options ...
resourceMetadata: { resource: 'https://mcp.example.com/mcp' },
enterpriseManagedAuthorization: {
trustedIssuers: async ({ iss }) =>
iss === 'https://idp.example.com'
? { issuer: iss, jwksUri: 'https://idp.example.com/.well-known/jwks.json', algorithms: ['RS256'] }
: null,
async mapClaims({ claims, requestedScope }) {
return {
// Opaque tokens use ':' as a separator — encode subjects that may contain it.
userId: `enterprise-${claims.sub}`,
scope: requestedScope,
metadata: { enterpriseIssuer: claims.iss, enterpriseSubject: claims.sub },
props: { enterprise: true, subject: claims.sub, email: claims.email },
};
},
},
});
Setup:
resourceMetadata.resource to the MCP endpoint URL (required when EMA is enabled).trustedIssuers as a resolver — for multi-tenant deployments it can read env / clientInfo to look up per-tenant IdP config without redeploying.The AS enforces resolved.issuer === iss (confused-deputy guard) and validates ID-JAG typ, signature, audience, client binding, resource, exp / iat / nbf, max lifetime, and jti replay. Refresh tokens are not issued for this grant — the ID-JAG itself is the renewable assertion.
By default the EMA grant requires client authentication, so public clients (token_endpoint_auth_method: 'none') are rejected. Set allowPublicClients: true to also accept them:
enterpriseManagedAuthorization: {
allowPublicClients: true,
// ... trustedIssuers, mapClaims ...
}
This is useful for clients registered via a Client ID Metadata Document (CIMD), which are always public and therefore cannot present a client secret. With this enabled, trust rests on the IdP-issued, signature-verified, short-lived, single-use ID-JAG assertion (audience-, resource-, and client-bound) rather than on a separately presented client secret. Leave it unset (default false) to keep the spec-default behavior of requiring client authentication.
Experimental — the MCP extension is still a draft.
By using the onError option, you can emit notifications or take other actions when an error response was to be emitted:
new OAuthProvider({
// ... other options ...
onError({ code, description, status, headers }) {
Sentry.captureMessage(/* ... */);
},
});
By returning a Response you can also override what the OAuthProvider returns to your users:
new OAuthProvider({
// ... other options ...
onError({ code, description, status, headers }) {
if (code === 'unsupported_grant_type') {
return new Response('...', { status, headers });
}
// returning undefined (i.e. void) uses the default Response generation
},
});
By default, the onError callback is set to ({ status, code, description }) => console.warn(`OAuth error response: ${status} ${code} - ${description}`).
The library uses KV TTLs to automatically expire access tokens, refresh tokens (grants), and dynamically registered clients. As defense-in-depth, the library also provides a purgeExpiredData() method that cleans up orphaned and expired records. This is designed to be called from a Cron Trigger (scheduled handler):
const oauthProvider = new OAuthProvider({
// ... options ...
});
export default {
fetch(request, env, ctx) {
return oauthProvider.fetch(request, env, ctx);
},
async scheduled(event, env, ctx) {
const result = await oauthProvider.purgeExpiredData(env, { batchSize: 100 });
console.log(`Checked ${result.grantsChecked} grants, purged ${result.grantsPurged}`);
},
};
The method processes records in configurable batches (default: 50) to stay within Cloudflare's subrequest limits. It performs two sweep phases:
Call it repeatedly via a cron trigger — deleted records disappear from KV, so subsequent invocations naturally process fresh records without needing a persisted cursor. The result.done field indicates whether the full key space was scanned in this invocation.
The library automatically serves a /.well-known/oauth-protected-resource endpoint. By default, it uses the request origin as the resource identifier and the token endpoint's origin as the authorization server. You can customize this with the resourceMetadata option:
new OAuthProvider({
// ... other options ...
resourceMetadata: {
resource: 'https://api.example.com',
authorization_servers: ['https://auth.example.com'],
scopes_supported: ['read', 'write'],
bearer_methods_supported: ['header'],
resource_name: 'My API',
},
});
This library implements the following OAuth and MCP specifications:
/.well-known/oauth-authorization-server discovery endpoint/.well-known/oauth-protected-resource discovery endpointThese are the specifications required by the MCP authorization specification.
This library stores records about authorization tokens in KV. The storage schema is carefully designed such that a complete leak of the storage only reveals mundane metadata about what has been granted. In particular:
props associated with a grant (which are passed back to the application when API requests are performed) are stored encrypted with the secret token as key material. Hence, the contents of props are impossible to derive from storage unless a valid token is provided.Note that the userId and the metadata associated with each grant are not encrypted, because the purpose of these values is to allow grants to be enumerated for audit and revocation purposes. However, these values are completely opaque to the library. An application is free to omit them or apply its own encryption to them before passing them into the library, if it desires.
OAuth 2.1 requires that refresh tokens are either "cryptographically bound" to the client, or are single-use. This library currently does not implement any cryptographic binding, thus seemingly requiring single-use tokens. Under this requirement, every token refresh request invalidates the old refresh token and issues a new one.
This requirement is seemingly fundamentally flawed as it assumes that every refresh request will complete with no errors. In the real world, a transient network error, machine failure, or software fault could mean that the client fails to store the new refresh token after a refresh request. In this case, the client would be permanently unable to make any further requests, as the only token it has is no longer valid.
This library implements a compromise: At any particular time, a grant may have two valid refresh tokens. When the client uses one of them, the other one is invalidated, and a new one is generated and returned. Thus, if the client correctly uses the new refresh token each time, then older refresh tokens are continuously invalidated. But if a transient failure prevents the client from updating its token, it can always retry the request with the token it used previously.
This library supports Client ID Metadata Documents, which allow clients to use HTTPS URLs as their client_id. When a client presents an HTTPS URL with a non-root path as its client_id, the library will fetch and validate the metadata document from that URL.
CIMD support is opt-in and requires two things:
clientIdMetadataDocumentEnabled: true in your OAuthProvider options:new OAuthProvider({
// ... other options ...
clientIdMetadataDocumentEnabled: true,
});
global_fetch_strictly_public compatibility flag to your wrangler.jsonc:{
"compatibility_flags": ["global_fetch_strictly_public"],
}
The compatibility flag is required for SSRF (Server-Side Request Forgery) protection. Due to a legacy quirk, fetch() requests to URLs within your zone's domain are sent directly to the origin server, bypassing Cloudflare. The global_fetch_strictly_public flag disables this behavior. See Cloudflare's documentation for more details.
When CIMD is not enabled (the default), URL-formatted client_id values fall through to standard KV lookup. When enabled, if fetching the metadata document fails, the library logs a warning and returns an invalid_client error, allowing MCP clients to recover by falling back to Dynamic Client Registration.
The OAuth metadata endpoint reports client_id_metadata_document_supported: true only when both the option is enabled and the compatibility flag is present.
This library (including the schema documentation) was largely written with the help of Claude, the AI model by Anthropic. Claude's output was thoroughly reviewed by Cloudflare engineers with careful attention paid to security and compliance with standards. Many improvements were made on the initial output, mostly again by prompting Claude (and reviewing the results). Check out the commit history to see how Claude was prompted and what code it produced.
"NOOOOOOOO!!!! You can't just use an LLM to write an auth library!"
"haha gpus go brrr"
In all seriousness, two months ago (January 2025), I (@kentonv) would have agreed. I was an AI skeptic. I thought LLMs were glorified Markov chain generators that didn't actually understand code and couldn't produce anything novel. I started this project on a lark, fully expecting the AI to produce terrible code for me to laugh at. And then, uh... the code actually looked pretty good. Not perfect, but I just told the AI to fix things, and it did. I was shocked.
To emphasize, this is not "vibe coded". Every line was thoroughly reviewed and cross-referenced with relevant RFCs, by security experts with previous experience with those RFCs. I was trying to validate my skepticism. I ended up proving myself wrong.
Again, please check out the commit history -- especially early commits -- to understand how this went.
FAQs
OAuth provider for Cloudflare Workers
The npm package @cloudflare/workers-oauth-provider receives a total of 0 weekly downloads. As such, @cloudflare/workers-oauth-provider popularity was classified as not popular.
We found that @cloudflare/workers-oauth-provider demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Research
/Security News
Socket uncovered two malicious VS Code themes in a GlassWorm-linked cluster with thousands of installs across VS Code Marketplace and Open VSX.
Security News
/Company News
Capital One is partnering with Socket to proactively secure its open source supply chain.
Security News
Socket CTO Ahmad Nassri discusses how to keep AI agents from bypassing package blocks, limit credential access, and monitor their actions.