Skill: ivangdavila/oauth (version 1.0.0)

--- name: OAuth description: Implement OAuth 2.0 and OpenID Connect flows securely. metadata: {"clawdbot":{"emoji":"🔑","os":["linux","darwin","win32"]}} --- ## 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 [REDACTED_SECRET] (minutes to hour), used for API access - Refresh [REDACTED_SECRET], 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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)