What it does. Configures secure OAuth 2.0 authorization flows, including Authorization Part of mukul975/Anthropic-Cybersecurity-Skills (817 security skills) (mukul975/Anthropic-Cybersecurity-Skills).
Install
npx skills add mukul975/Anthropic-Cybersecurity-Skills --skill configuring-oauth2-authorization-flow, or copy the skill folder into ~/.claude/skills/configuring-oauth2-authorization-flow/.- Raw file:
curl -sL https://raw.githubusercontent.com/mukul975/Anthropic-Cybersecurity-Skills/HEAD/skills/configuring-oauth2-authorization-flow/SKILL.md
SKILL.md (verbatim)
name: configuring-oauth2-authorization-flow
description: Configures secure OAuth 2.0 authorization flows, including Authorization
Code with PKCE, Client Credentials, and Device Authorization Grant, covering flow
selection, PKCE implementation, token lifecycle management, and scope design per
OAuth 2.1. Use when implementing or hardening OAuth 2.0 authentication/authorization
for web, mobile, SPA, or machine-to-machine clients.
domain: cybersecurity
subdomain: identity-access-management
tags:
- iam
- identity
- access-control
- authentication
- authorization
- oauth2
- oidc
- pkce
version: '1.0'
author: mahipal
license: Apache-2.0
nist_csf:
- PR.AA-01
- PR.AA-02
- PR.AA-05
- PR.AA-06
mitre_attack:
- T1528
- T1550.001
- T1539
- T1606.001
- T1212
mitre_f3:
version: '1.1'
tactics:
- initial-access
- positioning
techniques:
- id: T1550.001
name: 'Use Alternate Authentication Material: Application Access Token'
tactic: initial-access
source: attack
- id: F1004
name: Access with Stolen Session Cookie
tactic: initial-access
source: f3
- id: F1006
name: Account Takeover
tactic: initial-access
source: f3
- id: T1539
name: Steal Web Session Cookie
tactic: positioning
source: attack
Configuring OAuth 2.0 Authorization Flow
Overview
Configure secure OAuth 2.0 authorization flows including Authorization Code with PKCE, Client Credentials, and Device Authorization Grant. This skill covers flow selection, PKCE implementation, token lifecycle management, scope design, and alignment with OAuth 2.1 security requirements.
When to Use
- When deploying or configuring configuring oauth2 authorization flow capabilities in your environment
- When establishing security controls aligned to compliance requirements
- When building or improving security architecture for this domain
- When conducting security assessments that require this implementation
Prerequisites
- Familiarity with identity access management concepts and tools
- Access to a test or lab environment for safe execution
- Python 3.8+ with required dependencies installed
- Appropriate authorization for any testing activities
Objectives
- Implement Authorization Code flow with PKCE for public and confidential clients
- Configure Client Credentials flow for machine-to-machine communication
- Design least-privilege scope hierarchies
- Implement secure token storage, refresh, and revocation
- Apply OAuth 2.1 best practices and RFC 9700 security recommendations
- Validate token integrity and prevent common OAuth attacks
Key Concepts
OAuth 2.0 Grant Types
- Authorization Code + PKCE: Recommended for all client types (web, mobile, SPA). PKCE is mandatory in OAuth 2.1.
- Client Credentials: Machine-to-machine authentication without user context.
- Device Authorization Grant (RFC 8628): For input-constrained devices (smart TVs, CLI tools).
- Refresh Token: Long-lived token to obtain new access tokens without re-authentication.
PKCE (Proof Key for Code Exchange)
PKCE (RFC 7636) prevents authorization code interception attacks:
- Client generates random
code_verifier (43-128 characters, unreserved URI chars)
- Client computes
code_challenge = BASE64URL(SHA256(code_verifier))
- Authorization request includes
code_challenge and code_challenge_method=S256
- Token request includes original
code_verifier
- Server validates
SHA256(code_verifier) matches stored code_challenge
Token Types
- Access Token: Short-lived (5-60 min), bearer or DPoP-bound
- Refresh Token: Long-lived, single-use with rotation
- ID Token (OIDC): JWT containing user identity claims
Workflow
Step 1: Authorization Code Flow with PKCE
- Generate cryptographically random code_verifier (min 43 chars)
- Compute code_challenge using S256 method
- Redirect user to authorization endpoint with parameters:
- response_type=code
- client_id, redirect_uri, scope, state
- code_challenge, code_challenge_method=S256
- User authenticates and consents
- Authorization server redirects with authorization code
- Exchange code + code_verifier for tokens at token endpoint
- Validate state parameter matches original value
Step 2: Scope Design
- Define granular scopes:
read:users, write:orders, admin:settings
- Follow least-privilege: request minimum scopes needed
- Implement scope validation on resource server
- Document scope hierarchy and consent requirements
Step 3: Token Security
- Store tokens securely (httpOnly cookies for web, keychain for mobile)
- Implement token refresh with rotation (one-time-use refresh tokens)
- Set appropriate expiration: access tokens 5-15 min, refresh tokens 8-24 hrs
- Enable DPoP (Demonstration of Proof-of-Possession) for sender-constrained tokens
- Implement token revocation endpoint
Step 4: Client Credentials Flow
- Register service client with client_id and client_secret
- Request token: POST /oauth/token with grant_type=client_credentials
- Include scope for required permissions
- Store client_secret securely (vault, env vars, not code)
- Implement certificate-based client authentication for higher assurance
Step 5: Security Hardening
- Enforce PKCE for all authorization code flows
- Use exact redirect URI matching (no wildcards)
- Implement CSRF protection with state parameter
- Enable refresh token rotation and revocation on reuse detection
- Apply RFC 9700 security best practices
- Block implicit grant and ROPC (removed in OAuth 2.1)
Security Controls
| Control |
NIST 800-53 |
Description |
| Access Control |
AC-3 |
Token-based access enforcement |
| Authentication |
IA-5 |
Client credential management |
| Session Management |
SC-23 |
Token lifecycle management |
| Audit |
AU-3 |
Log all token issuance and revocation |
| Cryptographic Protection |
SC-13 |
PKCE and token signing |
Common Pitfalls
- Using implicit grant (removed in OAuth 2.1) instead of authorization code + PKCE
- Storing tokens in localStorage (XSS vulnerable) instead of httpOnly cookies
- Not validating state parameter enabling CSRF attacks
- Using wildcard redirect URIs allowing open redirect exploitation
- Not implementing refresh token rotation allowing token theft persistence
Verification
Other files in this skill
assets/template.md (verbatim)
OAuth 2.0 Authorization Flow Configuration Template
Application Registration
| Field |
Value |
| Application Name |
|
| Client ID |
|
| Client Type |
[ ] Public [ ] Confidential |
| Grant Types |
[ ] Authorization Code [ ] Client Credentials [ ] Refresh Token [ ] Device Code |
| PKCE Required |
[ ] Yes (mandatory for OAuth 2.1) |
Redirect URI Configuration
Rules:
- Exact match only - no wildcards
- HTTPS required for non-localhost URIs
- Each URI must be explicitly registered
Scope Design
| Scope |
Description |
Sensitivity |
| openid |
OpenID Connect identity |
Low |
| profile |
User profile information |
Low |
| email |
User email address |
Low |
| read:users |
Read user records |
Medium |
| write:users |
Modify user records |
High |
| admin:settings |
Modify system settings |
Critical |
Token Configuration
| Parameter |
Value |
Justification |
| Access Token Lifetime |
15 minutes |
Minimize window of exposure |
| Refresh Token Lifetime |
8 hours |
Align with business hours |
| Refresh Token Rotation |
Enabled |
Detect token theft via reuse |
| Refresh Token Absolute Expiry |
24 hours |
Force re-authentication daily |
| ID Token Lifetime |
5 minutes |
Only used for initial authentication |
| Token Format |
JWT (signed) |
Enable stateless validation |
| Signing Algorithm |
RS256 |
Asymmetric verification |
Security Checklist
Client Authentication Methods
| Method |
Use Case |
Security Level |
| none |
Public clients (SPA, mobile) |
Requires PKCE |
| client_secret_basic |
Server-side web apps |
Medium |
| client_secret_post |
Server-side web apps |
Medium |
| private_key_jwt |
High-security services |
High |
| tls_client_auth |
mTLS-capable services |
High |
Monitoring & Alerting
references/api-reference.md (verbatim)
OAuth 2.0 Authorization Flow — API Reference
Libraries
| Library |
Install |
Purpose |
| requests |
pip install requests |
HTTP client for OAuth endpoints |
| authlib |
pip install authlib |
Full OAuth 2.0 / OIDC client library |
| PyJWT |
pip install PyJWT[crypto] |
JWT token validation and inspection |
OIDC Discovery Endpoint
GET {issuer}/.well-known/openid-configuration
Returns: authorization_endpoint, token_endpoint, jwks_uri, supported grant types, scopes.
OAuth 2.0 Grant Types
| Grant Type |
Use Case |
Security |
| authorization_code |
Server-side apps |
Recommended with PKCE |
| client_credentials |
Machine-to-machine |
Service accounts only |
| implicit |
(DEPRECATED) SPAs |
Avoid — tokens in URL fragment |
| password |
(DEPRECATED) Legacy |
Avoid — credentials exposed to client |
| urn:ietf:params:oauth:grant-type:device_code |
IoT/CLI |
Approved for limited-input devices |
Security Best Practices
| Practice |
RFC |
| PKCE (Proof Key for Code Exchange) |
RFC 7636 |
| Token Binding |
RFC 8471 |
| DPoP (Demonstrating Proof of Possession) |
RFC 9449 |
| Sender-Constrained Tokens |
OAuth 2.0 Security BCP |
External References
references/standards.md (verbatim)
Standards and References - OAuth 2.0 Authorization Flow
Core OAuth Standards
- RFC 6749: The OAuth 2.0 Authorization Framework
- RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage
- RFC 7636: Proof Key for Code Exchange (PKCE)
- RFC 9700: OAuth 2.0 Security Best Current Practice
- OAuth 2.1 Draft: Consolidation of OAuth 2.0 with PKCE mandatory
Token Standards
- RFC 7519: JSON Web Token (JWT)
- RFC 7515: JSON Web Signature (JWS)
- RFC 9449: OAuth 2.0 Demonstrating Proof of Possession (DPoP)
- RFC 7009: OAuth 2.0 Token Revocation
OpenID Connect
- OpenID Connect Core 1.0: Authentication layer on OAuth 2.0
- OpenID Connect Discovery: Provider metadata discovery
Additional Grant Types
- RFC 8628: OAuth 2.0 Device Authorization Grant
NIST Standards
- NIST SP 800-63B: Digital Identity Guidelines - Authentication
- NIST SP 800-53 Rev 5:
- AC-3: Access Enforcement
- IA-5: Authenticator Management
- SC-13: Cryptographic Protection
- SC-23: Session Authenticity
- AU-3: Content of Audit Records
Implementation Guides
Security References
- OWASP OAuth 2.0 Security: Common vulnerabilities and mitigations
- OAuth Security Workshop: Annual research on OAuth attack vectors
references/workflows.md (verbatim)
OAuth 2.0 Authorization Flow Workflows
Workflow 1: Authorization Code Flow with PKCE
Client Auth Server Resource Server
| | |
|-- Generate code_verifier --| |
|-- Compute code_challenge --| |
| | |
|--- AuthZ Request --------->| |
| (code_challenge, state) | |
| |-- User Authenticates -->|
| |<- User Consents --------|
|<-- AuthZ Code + state -----| |
| | |
|--- Token Request --------->| |
| (code + code_verifier) | |
|<-- Access + Refresh Token--| |
| | |
|--- API Request (Bearer) ---|------------------------>|
|<-- API Response ---------- |<------------------------|
Step-by-Step:
- Client generates
code_verifier: random 43-128 char string (A-Z, a-z, 0-9, -._~)
- Client computes
code_challenge = BASE64URL(SHA256(code_verifier))
- Client redirects to:
GET /authorize?response_type=code&client_id=xxx&redirect_uri=xxx&scope=xxx&state=RANDOM&code_challenge=xxx&code_challenge_method=S256
- User authenticates and consents at authorization server
- Server redirects to:
redirect_uri?code=AUTH_CODE&state=RANDOM
- Client validates state matches original
- Client exchanges code:
POST /token with grant_type=authorization_code&code=AUTH_CODE&code_verifier=xxx&redirect_uri=xxx
- Server validates SHA256(code_verifier) matches stored code_challenge
- Server returns access_token, refresh_token, id_token (if OIDC)
Workflow 2: Client Credentials Flow (Machine-to-Machine)
Service A Auth Server Service B (API)
| | |
|--- Token Request --------->| |
| (client_id, secret, scope)| |
|<-- Access Token -----------| |
| | |
|--- API Request (Bearer) ---|------------------------>|
|<-- API Response ---------- |<------------------------|
Step-by-Step:
- Service registers with auth server (client_id + client_secret)
- Service requests token:
POST /token with grant_type=client_credentials&scope=api:read
- Auth server validates client credentials
- Auth server returns access_token (no refresh token, no user context)
- Service calls API with
Authorization: Bearer ACCESS_TOKEN
Workflow 3: Token Refresh with Rotation
Client Auth Server
| |
|--- Refresh Request ------->|
| (refresh_token_v1) |
|<-- New Access Token -------|
|<-- New Refresh Token (v2) -|
| (v1 invalidated) |
| |
|--- Refresh Request ------->|
| (refresh_token_v2) |
|<-- New Access Token -------|
|<-- New Refresh Token (v3) -|
| |
|--- THEFT: Reuse v1 ------->|
| (DETECTED: v1 reused) |
|<-- REVOKE ALL TOKENS ------|
Rotation Detection:
- Each refresh token is single-use
- On reuse of an old refresh token, server detects theft
- All tokens in the grant chain are revoked
- User must re-authenticate
Workflow 4: Device Authorization Grant
Device Auth Server User (Browser)
| | |
|--- Device AuthZ Request -->| |
|<-- device_code, | |
| user_code, | |
| verification_uri -------| |
| | |
|-- Display user_code ------>| |
| to user on screen | |
| |<-- User visits URI -----|
| |<-- Enters user_code ----|
| |<-- Authenticates -------|
| |<-- Consents ------------|
| | |
|--- Poll Token Endpoint --->| |
| (device_code) | |
|<-- Access Token -----------| |
Workflow 5: Token Revocation
Steps:
- Client sends revocation request:
POST /revoke with token=xxx&token_type_hint=refresh_token
- Auth server invalidates the token
- If refresh token revoked, all associated access tokens also invalidated
- Server returns 200 OK regardless of whether token was valid (prevents token fishing)
Workflow 6: Security Incident - Token Compromise Response
Steps:
- Detect suspicious token usage (unusual IP, impossible travel)
- Immediately revoke the compromised token via revocation endpoint
- If refresh token compromised, revoke entire token family
- Force re-authentication for affected user
- Audit all API calls made with compromised token
- Check for scope escalation attempts
- Review authorization logs for the compromised session
- Notify affected user and security team
Back to mukul975/Anthropic-Cybersecurity-Skills (817 security skills) or Agent skills.