oauth2_provider_design v1.0.0

name: "oauth2_provider_design" description: "Designs the OAuth 2 side a platform offers to third party apps: a current baseline flow set, scope groups a user can understand, consent screens, app review tiers, token lifetimes, and revocation that works when an app misbehaves. Triggers when someone is building an authorization server, adding OAuth to a platform or API, designing scopes or a consent screen, setting token policy, reviewing third party apps, or planning how to cut off a misbehaving app."

OAuth 2 Provider Design

Design the provider side of OAuth 2: the part a platform runs so third party apps can act for its users. The client side has plenty of guides. This skill covers the decisions only the provider can make, and the ones that are painful to change after apps ship against them.

Purpose

Turn "we need OAuth for our API" into a reviewable provider design: which flows are on and which are refused, a scope catalog written in language a user can judge, a consent screen spec, app review tiers matched to scope risk, a token lifetime policy, and revocation paths that work on a bad day, all checked against the current IETF baseline and validated with bin/provider_check.py.

Workflow

1. Set the baseline flow set. Enable the authorization code flow with PKCE (S256) for user facing apps, client credentials for machine to machine calls with no user, the refresh token flow, and the device authorization grant (RFC 8628) only if input constrained clients are real for the platform. Refuse the implicit grant and the resource owner password credentials grant. RFC 9700, the OAuth 2.0 Security Best Current Practice from January 2025, is the enforceable source for each of those calls. OAuth 2.1 states the same rules but is still a draft, so cite RFC 9700 in developer facing docs. Read references/standards-map.md before finalizing the set.

1. Fix the non negotiable mechanics.

• Require PKCE for every authorization code client, public and confidential, S256 only.
• Compare redirect URIs with exact string matching against the registered list. No wildcards, no prefix rules, no pattern matching. The native app exceptions come from RFC 8252 (claimed HTTPS URIs, custom schemes, loopback with a variable port), not from loosening the match.
• Authenticate the user in the system browser or platform browser for native apps, never inside an app controlled webview.
• Keep bearer tokens out of URL query strings.
• Bind each authorization code to one client and one PKCE challenge, expire it within 10 minutes per RFC 6749, and make it single use.
• Return the RFC 9207 iss parameter in authorization responses so clients can detect mix-up attacks.

1. Design the scope catalog before any screen. Work through the worksheet in references/scope-and-consent.md. One scope is one permission a user can describe back to you. Split read from write, give every scope a plain language user label, mark sensitive scopes, assign each scope a review tier, and ban wildcards and catch all scopes. Use the RFC 8707 resource parameter and RFC 9068 audience claims once more than one API accepts your tokens, so a token for one API is refused at another. Reach for RFC 9396 authorization_details only when a permission depends on the specific object or transaction.

1. Spec the consent screen from the catalog. The screen shows the verified app identity, the signed in account, one toggleable line per scope using the worksheet labels, a separate line for offline access when a refresh token will be issued, links to the app privacy policy on the developer domain, and Approve and Deny at equal weight. Write scopes are never prechecked. Remember grants per user and app, and use incremental consent when an app later asks for new scopes. The full spec and two worked flows, standard and device, are in references/scope-and-consent.md.

1. Set app registration and review tiers. Collect the full app record at registration and gate public use by scope risk: automated checks for basic scopes, review for content and write scopes, full justification with a demo for sensitive scopes, and a security assessment with periodic revalidation for restricted and admin scopes. Run unverified apps under a user cap with a warning on the consent screen and no sensitive scopes. Any change to scopes, redirect URIs, ownership, name, or logo goes back through review. The tier definitions and checks are in references/review-and-revocation.md.

1. Publish the provider surface. Serve the RFC 8414 metadata document at /.well-known/oauth-authorization-server with every endpoint and capability, including code_challenge_methods_supported and scopes_supported. Add dynamic client registration (RFC 7591) only when the client count or client type demands it, and gate it when you do. Offer pushed authorization requests (RFC 9126) for confidential and high value clients. Each resource server gets RFC 9728 protected resource metadata once you run more than one API.

1. Set token policy as a table, and say which numbers are yours. Pick the access token format on purpose: JWT per RFC 9068 for local verification with revocation lag bounded by short lifetimes, or opaque tokens with RFC 7662 introspection for instant status checks. Rotate refresh tokens on every use for public clients, or sender constrain them with DPoP (RFC 9449) or mTLS (RFC 8705), and treat reuse of a rotated out token as theft: revoke the family. Confidential clients authenticate with private_key_jwt or mTLS where you can support it, secrets only as the fallback. references/review-and-revocation.md holds the starting lifetime table and the rule for labeling policy numbers versus standard numbers.

1. Build revocation before you need it. Ship all four triggers from references/review-and-revocation.md: a user disconnect page, the RFC 7009 revocation endpoint, an operator kill switch per client that stops issuance and revokes refresh families without a deploy, and scope level suspension for one bad scope on an otherwise fine app. Define the blast radius for password change, account takeover, developer termination, and signing key compromise. State how fast revocation reaches resource servers, measure it in a kill switch test with a throwaway app, and audit log every grant, issuance, reuse event, and revocation with token material redacted.

1. Validate the design, then write the developer docs. Run bin/provider_check.py design.json on the design file built from the worksheet example. Fix every failure; answer every warning in the design notes. The developer docs then state, in plain terms: the supported flows, how to register, the scope catalog with labels, the review tiers and what each one asks for, token lifetimes, and how revocation and the kill switch affect apps. Docs that hide the review bar produce apps that fail it by surprise.

Output Contract

Produce a provider design pack containing: the baseline flow set with the RFC behind each on or off decision, the non negotiable mechanics checklist, the scope catalog worksheet (name, user label, data touched, access, sensitive flag, review tier, default, offline), the consent screen spec plus the standard and device flow walkthroughs, the app review tier table with unverified mode rules, the endpoint and metadata inventory, the token policy table with standard mandated numbers separated from policy choices, the revocation plan covering all four triggers with measured propagation time, and the audit logging minimums. Include the design JSON and the passing bin/provider_check.py output. A design that fails the checker does not ship.

Operating Rules

1. Every protocol claim, limit, and requirement in the design must trace to an RFC or an official provider document listed in references/standards-map.md. Unverifiable claims come out, or get labeled as a local policy choice.
2. OAuth 2.1 is a draft. Design to its direction, cite RFC 9700 for rules a developer must follow today, and never call the draft a published standard.
3. Numbers an RFC sets (the 10 minute authorization code guidance in RFC 6749, the 43 to 128 character PKCE verifier in RFC 7636) are quoted as standard. Every other lifetime or cap is presented as a policy choice with a reason, never dressed up as a standard requirement.
4. Scopes are a user facing product surface, not an API inventory. If a user cannot say what a scope allows after reading its label, the scope or the label is wrong.
5. Review rigor follows scope risk, not developer size or fame. A well known developer gets the same sensitive scope bar as a new one.
6. Never weaken a baseline rule to onboard one app. If an app cannot do PKCE or exact redirect matching, the app changes, or it stays in a capped test mode.
7. Credentials and token values never appear in the design pack, logs, or examples. Use placeholders such as <access_token> and example domains such as example.com.
8. Revocation and the kill switch get tested with a throwaway app before launch and on a schedule after. An untested kill switch is listed in the design as a gap, not as a control.