workers-oauth-provider-migrate-1.0
Migrate a Cloudflare Worker from @cloudflare/workers-oauth-provider 0.x to 1.0. Use when upgrading that dependency, when OAuthProvider construction throws about resourceMetadata.resource or resourceMatchOriginOnly, or when asked to adopt the 1.0 role-based API (OAuthAuthorizationServer / OAuthResourceServer).
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
OAuth 2.1 Provider Framework for Cloudflare Workers
@cloudflare/workers-oauth-provider adds OAuth 2.1 authorization to HTTP APIs and remote MCP servers running on Cloudflare Workers.
Upgrading from 0.x, 1.0 or 1.1? Read the migration guide, which covers every change since 0.10 with code, or point your coding agent at
skills/migrate-to-1.x/, which also ships in the npm package.
Install
npm install @cloudflare/workers-oauth-provider
The authorization server needs a KV namespace bound as OAUTH_KV, and the global_fetch_strictly_public compatibility flag if it accepts Client ID Metadata Documents.
Quick start
An MCP deployment has two roles. The authorization server signs users in and issues tokens. The resource server is your MCP endpoint: it accepts those tokens and checks them with the authorization server over a Service Binding.
// auth-server/index.ts
const authorizationServer = new OAuthAuthorizationServer<Env>({
issuer: 'https://auth.example.com',
resources: ['https://mcp.example.com/mcp'],
scopesSupported: ['mcp:read', 'mcp:write', 'offline_access'], // everything this server can grant
clientIdMetadataDocumentEnabled: true,
});
export default class AuthServer extends WorkerEntrypoint<Env> {
fetch(request: Request) {
// /authorize is yours: parseAuthRequest(), sign the user in and ask for consent, completeAuthorization().
if (new URL(request.url).pathname === '/authorize') return authorize(request, this.env);
return authorizationServer.fetch(request, this.env, this.ctx); // discovery, token, revocation
}
// Resource servers call this over their Service Binding.
validateToken(resource: string, token: string) {
return authorizationServer.validateToken(resource, token, this.env);
}
}
// mcp-server/index.ts
export default new OAuthResourceServer<Env, AuthProps>({
resourceMetadata: {
resource: 'https://mcp.example.com/mcp',
authorization_servers: ['https://auth.example.com'],
},
requiredScopes: ['mcp:read'], // needed for any access; clients request these first
validateToken: (env) => env.AUTH_SERVER.validateToken,
handler: {
fetch(request, env, ctx) {
// ctx.props: what completeAuthorization() stored. ctx.auth: the verified token.
// Step-up: a 403 naming the missing scope, and the client re-authorizes for it.
const needed = request.method === 'GET' ? ['mcp:read'] : ['mcp:read', 'mcp:write'];
if (!needed.every((scope) => ctx.auth.scope.includes(scope))) return insufficientScope(ctx.auth, needed);
return Response.json({ userId: ctx.props.userId });
},
},
});
examples/split-workers has both Workers in full, including the /authorize handler and wrangler.jsonc, with an end-to-end test that runs them in workerd.
The resource server publishes its RFC 9728 metadata, answers unauthenticated requests with a challenge pointing at it, and accepts only tokens issued for its own resource. The handler owns authorization beyond that: scopes, ownership, tenancy.
On the wire both lists are called scopes_supported, as the specs name them, but they mean different things: scopesSupported is everything the authorization server can grant; a resource's requiredScopes is what any access needs, so MCP clients request it first, and more comes by step-up. The handler checks ctx.auth.scope: the library advertises the required scopes but doesn't enforce them, since only your code knows which scopes imply others. See Scopes.
One Worker: OAuthProvider
The split roles above are the recommended shape. OAuthProvider remains fully supported for one Worker that is both the authorization server and its only resource, which was the 0.x shape: it combines the roles. Requests under apiRoute reach apiHandler with ctx.props and ctx.auth; everything else goes to defaultHandler, which owns /authorize and reaches the helpers as env.OAUTH_PROVIDER:
export default new OAuthProvider<Env>({
apiRoute: '/mcp',
apiHandler: McpApiHandler,
defaultHandler, // your /authorize page
authorizeEndpoint: '/authorize',
tokenEndpoint: '/oauth/token',
scopesSupported: ['mcp:read', 'mcp:write', 'offline_access'], // everything this server can grant
resourceMetadata: {
resource: 'https://mcp.example.com/mcp',
authorization_servers: ['https://mcp.example.com'],
},
requiredScopes: ['mcp:read'], // needed for any access; clients request these first
clientIdMetadataDocumentEnabled: true,
});
Documentation
- Resource servers: more resources, both roles in one Worker, what the handler sees, other issuers.
- Consent page: what it must show, Allow and Deny, remembering consent.
- Signing in through another provider: GitHub, Google and friends as the identity step.
- Authorization server reference: the authorize endpoint, client registration (pre-registered, CIMD, DCR), PKCE and token lifetimes, resources and audiences, scopes, KV storage, every option.
- MCP authorization discovery: how a client gets from a
401to your authorization server. - Advanced configuration: external tokens, token exchange,
tokenExchangeCallback,onError, Enterprise-Managed Authorization (experimental). - Storage schema: the KV layout. Tokens, codes and secrets are stored only as hashes;
propsare encrypted with a key only the token holder can unwrap.
Standards
MCP authorization 2026-07-28, OAuth 2.1, and RFCs 6750, 7009, 7591, 7636, 8414, 8693, 8707, 9207 and 9728, plus Client ID Metadata Documents, OpenID Connect RP Metadata Choices and, experimentally, MCP Enterprise-Managed Authorization.
Development
Node 24 or newer. npm install, npm run build, npm run check. Changes that affect behavior or the public API need a Changeset; see AGENTS.md for conventions, SECURITY.md for vulnerability reporting, and HISTORY.md for how the library began.
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/migrate-to-1.0/SKILL.md3.7 KBupstream ↗
--- name: workers-oauth-provider-migrate-1.0 description: Migrate a Cloudflare Worker from @cloudflare/workers-oauth-provider 0.x to 1.0. Use when upgrading that dependency, when OAuthProvider construction throws about resourceMetadata.resource or resourceMatchOriginOnly, or when asked to adopt the 1.0 role-based API (OAuthAuthorizationServer / OAuthResourceServer). --- # Migrate @cloudflare/workers-oauth-provider 0.x → 1.0 The single source of truth for every change is the migration guide shipped with the package: `node_modules/@cloudflare/workers-oauth-provider/docs/migration-1.0.md` (also at https://github.com/cloudflare/workers-oauth-provider/blob/main/docs/migration-1.0.md). Read it fully before editing. This skill is the procedure around it; do not work from memory of 0.x or from this file alone. ## Procedure 1. **Detect the shape.** Find `new OAuthProvider(` and read its options. The common shape is one Worker acting as authorization server and resource server; that shape stays on `OAuthProvider` in 1.0. Do not introduce `OAuthAuthorizationServer`/`OAuthResourceServer` unless the user asks for a multi-Worker or multi-resource topology. 2. **Choose the canonical resource — ask the user.** `resourceMetadata: { resource }` is required in 1.0. The value is the URL MCP clients connect to (often an existing `apiRoute` on the Worker's public origin, e.g. `https://mcp.example.com/mcp`). Infer a candidate from `wrangler.jsonc` routes/custom domains plus `apiRoute`, present it, and get confirmation — it becomes the token audience, so it must be right. 3. **Apply the guide's changes** that match the code: add `resourceMetadata.resource`; delete `resourceMatchOriginOnly`; make `resolveExternalToken` return the canonical `audience`; single-string `resource`/`aud` types; check `apiRoute`s are the resource path or descendants. 4. **Bump the dependency** to `^1.0.0` and install. 5. **Verify** (below), then walk the user through the guide's "Existing stored data" section so they know what their live clients will experience (nothing, in the common case). ## Stop and ask the user - The canonical `resource` value (step 2). Never guess silently. - On a multi-resource `OAuthAuthorizationServer`: which resource is `legacyGrantResource` (the migration destination for pre-1.0 grants). Omitting it makes old grants reauthorize. - Any DCR client base registered with narrow `grant_types`: 1.0 enforces them; confirm the registered types cover what clients actually send before deploying. - Adopting new 1.0 surface (role classes, `ctx.auth`, `insufficientScope`, `onError.internal`) is optional — offer, don't do unasked. ## Verify 1. `tsc`/typecheck and the project's tests pass. 2. `wrangler dev`, then: - `curl -i http://localhost:8787<api route>` → 401 whose `WWW-Authenticate` names `resource_metadata="…/.well-known/oauth-protected-resource<resource path>"`. This works locally whatever the configured resource's origin. - The metadata document itself is origin-strict (RFC 9728 §3): its well-known URL is `<resource origin>/.well-known/oauth-protected-resource<resource path>`. When the dev config's resource is on the loopback origin (e.g. `http://localhost:8787/mcp`), `curl http://localhost:8787/.well-known/oauth-protected-resource/mcp` → 200 with the exact `resource`. A production resource origin serves its document only there — after deploy: `curl https://<host>/.well-known/oauth-protected-resource<resource path>`. - Construction errors surface on the first request and name the violated rule; fix per the guide. 3. If the deployment has live users, re-read "Existing stored data — nothing to do" in the guide and confirm no step you took contradicts it (no KV edits, no `legacyGrantResource` changes after rollout).README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/cloudflare-workers-oauth-provider-skills-migrate-to-1-0.md