agentleFS
Sign inStart free
ScaleDockHQScaleDockHQ/scaledock-skills/skills/oauth/SKILL.md

oauth

Skill1 starsChanged 31 days agoMITView on GitHub

OAuth 2.1: secure resource servers, clients and ASes. Covers RFC 6749, RFC 6750 bearer tokens, the OAuth 2.1 draft, the RFC 9700 Security BCP, PKCE (RFC 7636), DPoP (RFC 9449), mTLS-bound tokens (RFC 8705), Rich Authorization Requests (RFC 9396), token exchange (RFC 8693), resource indicators (RFC 8707), AS metadata (RFC 8414), protected resource metadata (RFC 9728), the iss parameter (RFC 9207), step-up (RFC 9470), dynamic client registration (RFC 7591/7592), Client ID Metadata Documents, introspection (RFC 7662), revocation (RFC 7009) and the device grant (RFC 8628), plus transaction tokens, identity chaining and RAR remediation drafts. Use when protecting an API with access tokens, validating tokens, writing WWW-Authenticate challenges, adding PKCE, DPoP or mTLS, publishing /.well-known metadata, building an authorization server or OAuth client, delegating with token exchange or authorization_details, or reviewing an OAuth design against current best practice.

We split this skill into the rules it gives an agent

2 rules. 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 13 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Fix the role and the token model: Write down who issues tokens, who validates them, the token format, and whether tokens are bound.

    line 41
  2. Distinctive:

    Validate tokens at the resource server: Read the token from the header, validate it as a JWT or through introspection, then check audience, …

    line 43

“Common” is measured: kept by at least 6 in 10 of the 13 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

OAuth

OAuth 2.0 (RFC 6749) and its IETF extensions let a client obtain an access token from an authorization server (AS) and present it to a resource server (RS). OAuth 2.1, still an IETF draft, folds in the security fixes of RFC 9700. With this skill the agent builds or reviews a resource server, client or authorization server that follows those rules, with resource servers as the main focus.

Follow the workflow below step by step. Every rule here comes from a source in Sources, with the section it cites. When a rule and the pinned source disagree, the source wins; when the source has a newer revision than the pin, follow the refresh steps.

Inputs (fill in, or ask before starting)

  • Role: resource server, client, authorization server, or a service that does more than one (for example an RS that exchanges tokens to call another RS).
  • Token format and binding: JWT access tokens or opaque tokens with introspection; bearer, DPoP-bound or mTLS-bound.
  • Revision: the pinned revisions in Sources, unless the user names another. Drafts apply only at the posture recorded there.
  • Sources: when refreshing this skill or when a rule looks out of date, re-read every URL in Sources first, check the IETF datatracker for a newer draft revision or a published RFC, and update the pins.

Invariants

  1. The resource server validates every token fully (OAuth 2.1 draft -16 § 5.2). Not expired, issued for this resource, with the scope or authorization details the operation needs. A token meant for another resource MUST be refused (RFC 9700 § 2.3).
  2. Tokens never travel in the URL query. Clients MUST NOT send them there and resource servers MUST ignore them (OAuth 2.1 draft -16 § 5.1; RFC 6750 § 2.3).
  3. Failures answer with WWW-Authenticate (RFC 6750 § 3). invalid_token with 401, insufficient_scope with 403, no error code when no credentials were sent (RFC 6750 § 3.1), and insufficient_user_authentication for step-up (RFC 9470 § 3).
  4. Bound tokens need their proof on every request. A DPoP-bound token is accepted only when all RFC 9449 § 4.3 checks pass and its key matches cnf.jkt (§ 7.1); it MUST be rejected when sent as Bearer (§ 7.2). An mTLS-bound token MUST match the TLS client certificate (RFC 8705 § 3).
  5. The authorization code grant uses PKCE with S256. Public clients MUST use it; the AS MUST enforce it and MUST prevent PKCE downgrade (RFC 9700 § 2.1.1; RFC 7636 § 4.2).
  6. Redirect URIs match exactly, except the localhost port for native apps (RFC 9700 § 2.1).
  7. No implicit grant and no password grant. The implicit grant SHOULD NOT be used (RFC 9700 § 2.1.2); the password grant MUST NOT be used (RFC 9700 § 2.4).
  8. Clients check where responses came from. With more than one AS, a mix-up defense is REQUIRED (RFC 9700 § 2.1): compare iss to the expected issuer (RFC 9207 § 2.4). Metadata whose issuer or resource does not match is not used (RFC 8414 § 3.3; RFC 9728 § 3.3).
  9. Refresh tokens for public clients are sender-constrained or rotated (RFC 9700 § 2.2.2).
  10. Introspection is authenticated and never cached past exp (RFC 7662 § 2.1, § 4).
  11. Delegated tokens are authorized on the subject and the current actor only (RFC 8693 § 4.1).
  12. Unknown authorization details are refused with invalid_authorization_details (RFC 9396 § 5).

Workflow

  1. Fix the role and the token model. Write down who issues tokens, who validates them, the token format, and whether tokens are bound. ✓ Every party in the design has a role, and the RS knows whether it reads JWTs or calls introspection.
  2. Validate tokens at the resource server. Read the token from the header, validate it as a JWT or through introspection, then check audience, scope and authorization details for the exact operation. -> references/resource-server.md ✓ A token for another audience, an expired token and a token without the needed scope are each refused.
  3. Write the challenges. Return the right status, error code and resource_metadata for each failure. -> references/resource-server.md ✓ Each failure in the table in the reference produces its listed status and WWW-Authenticate value.
  4. Publish protected resource metadata at /.well-known/oauth-protected-resource with resource equal to the resource identifier (RFC 9728 § 2, § 3). ✓ A client can go from a 401 to the AS metadata without configuration.
  5. Add sender constraint with DPoP or mTLS where clients support it. -> references/sender-constraint.md ✓ A replayed DPoP proof, a wrong ath and a bound token sent as Bearer are each refused.
  6. Build the client side, if in scope: discovery, authorization code with PKCE, iss check, resource indicators, challenge handling, device grant. -> references/clients.md ✓ Every authorization request has a fresh S256 challenge, and every response's iss is checked.
  7. Build the authorization server side, if in scope: PKCE enforcement, codes, metadata, introspection, revocation, registration. -> references/authorization-server.md ✓ The AS metadata lists every supported feature, and the AS refuses codes reused, PKCE downgrades and unknown redirect URIs.
  8. Handle delegation and fine-grained access, if in scope: token exchange, act, resource, authorization_details. -> references/delegation.md ✓ Downstream tokens are audience-restricted and narrower than the incoming token.
  9. Apply drafts only at their posture. -> references/drafts.md ✓ Each draft feature in use names its pinned revision.

Verify before done

  • The RS refuses expired tokens, wrong-audience tokens, tokens in the query string and none-signed JWTs.
  • Each failure returns the status and WWW-Authenticate error from RFC 6750 § 3.1, RFC 9470 § 3 or RFC 9449 § 7.1, with resource_metadata.
  • /.well-known/oauth-protected-resource returns resource equal to the resource identifier.
  • DPoP: all twelve RFC 9449 § 4.3 checks run, jti replay is limited, and a DPoP-bound token sent as Bearer is rejected.
  • Clients send S256 PKCE, check iss, and send resource.
  • The AS enforces PKCE, matches redirect URIs exactly, returns iss, and publishes RFC 8414 metadata.
  • Introspection callers authenticate, and cached results expire no later than the token.
  • Every draft in use carries its pinned revision and posture.

Reference index

  • references/resource-server.md: reading and validating tokens, introspection, authorization details, act, challenges, RFC 9728 metadata, and a TypeScript example with jose.
  • references/sender-constraint.md: DPoP proofs, the RFC 9449 § 4.3 checks, nonces and replay, and mTLS certificate-bound tokens.
  • references/clients.md: discovery, authorization code with PKCE, iss, resource indicators, challenge handling, the device grant and registration.
  • references/authorization-server.md: authorization and token endpoints, codes, RAR, metadata, introspection, revocation, device grant and dynamic registration.
  • references/delegation.md: token exchange, delegation versus impersonation, resource indicators and Rich Authorization Requests.
  • references/drafts.md: OAuth 2.1, Client ID Metadata Documents, identity chaining, transaction tokens and RAR remediation, each with its posture.

Related skills

  • jwt for JWT access token formats and the JOSE verification checklist: npx skills add ScaleDockHQ/scaledock-skills --skill jwt
  • openid-connect for ID tokens and sign-in on top of OAuth: npx skills add ScaleDockHQ/scaledock-skills --skill openid-connect
  • gnap for the Grant Negotiation and Authorization Protocol: npx skills add ScaleDockHQ/scaledock-skills --skill gnap
  • mcp-authorization for the OAuth profile used by Model Context Protocol servers: npx skills add ScaleDockHQ/scaledock-skills --skill mcp-authorization

Sources

Status uses the publishing body's own maturity term. Checked is the date the source was last read.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free