cloudflare/workers-oauth-provider

cloudflare/workers-oauth-provider

Description: OAuth provider library for Cloudflare Workers

Language: TypeScript

License: MIT

Stars: 1788

Forks: 122

Open issues: 20

Created: 2025-03-11T15:10:09Z

Pushed: 2026-06-09T10:56:52Z

Default branch: main

Fork: no

Archived: no

README:

OAuth 2.1 Provider Framework for Cloudflare Workers

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.

Benefits of this library

• The library acts as a wrapper around your Worker code, which adds authorization for your API endpoints.
• All token management is handled automatically.
• Your API handler is written like a regular fetch handler, but receives the already-authenticated user details as a parameter. No need to perform any checks of your own.
• The library is agnostic to how you manage and authenticate users.
• The library is agnostic to how you build your UI. Your authorization flow can be implemented using whatever UI framework you use for everything else.
• The library's storage does not store any secrets, only hashes of them.

Usage

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…