OAuth

Implement OAuth 2.0 and OpenID Connect flows securely.

Security Scan

This is an instruction-only skill giving OAuth 2.0 / OIDC best-practices; it requests no credentials, performs no installs, and is internally consistent with its stated purpose.

Purpose & Capability

The name/description match the SKILL.md content: a concise set of secure OAuth2/OIDC implementation recommendations. The skill requests no unrelated binaries, env vars, or config paths, which is appropriate for a documentation-style guidance skill.

Instruction Scope

SKILL.md contains only implementation guidance (flows, PKCE, state, redirect validation, token handling, etc.). It does not instruct the agent to read files, access environment variables, call external endpoints, or transmit data. Scope stays within describing secure OAuth/OIDC practices.

Install Mechanism

No install spec and no code files (instruction-only). This is lowest-risk: nothing is written to disk and no external packages are fetched.

Credentials

The skill declares no required environment variables or credentials. The doc discusses tokens and client secrets conceptually (which is expected) but does not request those secrets from the environment.

Persistence & Privilege

always is false and the skill has no install steps or persistent components. It does not attempt to modify other skills or system-wide configuration.

Assessment

This skill is documentation only and appears coherent and low-risk. It will not run code or ask for secrets by itself. If you use these recommendations to implement OAuth/OIDC in your application, ensure you: (1) use well-maintained OAuth libraries rather than copying ad-hoc code; (2) keep client_secrets and tokens out of client-side code and out of version control; (3) follow the checklist items (PKCE for public clients, exact redirect URIs, HTTPS, short-lived tokens, token revocation); and (4) review any code that implements these flows for secure handling/storage/transmission of credentials. If you plan to let an agent perform deployments or configure servers automatically, verify the agent's runtime environment and credential access separately — this skill itself does not request or manage secrets.

Flow Selection

• Authorization Code + PKCE: use for all clients—web apps, mobile, SPAs
• Client Credentials: service-to-service only—no user context
• Implicit flow: deprecated—don't use; was for SPAs before PKCE existed
• Device Code: for devices without browsers (TVs, CLIs)—user authorizes on separate device

PKCE (Proof Key for Code Exchange)

• Required for public clients (SPAs, mobile), recommended for all
• Generate code_verifier: 43-128 char random string, stored client-side
• Send code_challenge: SHA256 hash of verifier, sent with auth request
• Token exchange includes code_verifier—server verifies against stored challenge
• Prevents authorization code interception—attacker can't use stolen code without verifier

State Parameter

• Always include state in authorization request—prevents CSRF attacks
• Generate random, unguessable value; store in session before redirect
• Verify returned state matches stored value before processing callback
• Can also encode return URL or other context (encrypted or signed)

Redirect URI Security

• Register exact redirect URIs—no wildcards, no open redirects
• Validate redirect_uri on both authorize and token endpoints
• Use HTTPS always—except localhost for development
• Path matching is exact—/callback ≠ /callback/

Tokens

• Access token: short-lived (minutes to hour), used for API access
• Refresh token: longer-lived, used only at token endpoint for new access tokens
• ID token (OIDC): JWT with user identity claims—don't use for API authorization
• Don't send refresh tokens to resource servers—only to authorization server

Scopes

• Request minimum scopes needed—users trust granular requests more
• Scope format varies: openid profile email (OIDC), repo:read (GitHub-style)
• Server may grant fewer scopes than requested—check token response
• openid scope required for OIDC—triggers ID token issuance

OpenID Connect

• OIDC = OAuth 2.0 + identity layer—adds ID token and UserInfo endpoint
• ID token is JWT with sub, iss, aud, exp + profile claims
• Verify ID token signature before trusting claims
• nonce parameter prevents replay attacks—include in auth request, verify in ID token

Security Checklist

• HTTPS everywhere—tokens in URLs must be protected in transit
• Validate iss and aud in tokens—prevents token confusion across services
• Bind authorization code to client—code usable only by requesting client
• Short authorization code lifetime (10 min max)—single use
• Implement token revocation for logout/security events

Common Mistakes

• Using access token as identity proof—use ID token for authentication
• Storing tokens in localStorage—vulnerable to XSS; prefer httpOnly cookies or memory
• Not validating redirect_uri—allows open redirect attacks
• Accepting tokens from URL fragment in backend—fragment never reaches server
• Long-lived access tokens—use short access + refresh pattern

Token Endpoints

• /authorize: user-facing, returns code via redirect
• /token: backend-to-backend, exchanges code for tokens; requires client auth for confidential clients
• /userinfo (OIDC): returns user profile claims; requires access token
• /revoke: invalidates tokens; accepts access or refresh token

Client Types

• Confidential: can store secrets (backend apps)—uses client_secret
• Public: cannot store secrets (SPAs, mobile)—uses PKCE only
• Never embed client_secret in mobile apps or SPAs—it will be extracted