OAuth2 Authentication

A comprehensive skill for implementing secure authentication and authorization using OAuth2 and OpenID Connect. This skill covers all major authorization flows, token management strategies, security best practices, and real-world implementation patterns for web, mobile, and API applications.

When to Use This Skill

Use this skill when:

• Implementing user authentication in web applications, SPAs, or mobile apps
• Building API authorization with access tokens and refresh tokens
• Integrating social login (Google, GitHub, Facebook, Twitter, etc.)
• Creating secure machine-to-machine (M2M) authentication
• Implementing single sign-on (SSO) across multiple applications
• Building an OAuth2 authorization server or identity provider
• Adding delegated authorization to allow third-party access
• Securing APIs with token-based authentication
• Implementing passwordless authentication flows
• Adding multi-tenant authentication with organization-specific rules
• Migrating from session-based to token-based authentication
• Implementing fine-grained access control with OAuth2 scopes

Core Concepts

OAuth2 Fundamentals

OAuth2 is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service. It works by delegating user authentication to the service that hosts the user account and authorizing third-party applications to access that account.

Key Terminology:

• Resource Owner: The user who owns the data or resources
• Client: The application requesting access to resources (web app, mobile app, SPA)
• Authorization Server: Issues access tokens after authenticating the resource owner
• Resource Server: Hosts protected resources, accepts and validates access tokens
• Access Token: Short-lived credential used to access protected resources
• Refresh Token: Long-lived credential used to obtain new access tokens
• Scope: Permission granted to access specific resources or perform actions
• Authorization Code: Temporary code exchanged for an access token
• State Parameter: Prevents CSRF attacks during authorization flow
• Redirect URI: Callback URL where the user is redirected after authorization

OAuth2 Grant Types (Authorization Flows)

OAuth2 defines several grant types for different use cases:

1. Authorization Code Flow

Most Secure Flow - Recommended for Server-Side Applications

The authorization code flow is the most secure and widely used OAuth2 flow. It involves exchanging an authorization code for an access token on the server side.

Flow Steps:

1. Client redirects user to authorization server with client_id, redirect_uri, scope, and state
2. User authenticates and consents to requested permissions
3. Authorization server redirects back to client with authorization code
4. Client exchanges code for access token using client secret (server-side)
5. Client uses access token to access protected resources

When to Use:

• Traditional server-side web applications
• Applications that can securely store client secrets
• When you need maximum security
• When refresh tokens are required

Security Benefits:

• Access token never exposed to browser
• Client authentication via client secret
• Authorization code is single-use and short-lived
• State parameter prevents CSRF attacks

2. Authorization Code Flow with PKCE

Secure Flow for Public Clients (SPAs and Mobile Apps)

PKCE (Proof Key for Code Exchange, pronounced "pixy") is an extension to the authorization code flow designed for public clients that cannot securely store client secrets.

Flow Steps:

1. Client generates code_verifier (random string) and code_challenge (SHA256 hash)
2. Client redirects to authorization server with code_challenge
3. User authenticates and consents
4. Authorization server returns authorization code
5. Client exchanges code + code_verifier for access token
6. Server validates code_verifier matches code_challenge

When to Use:

• Single Page Applications (SPAs)
• Mobile applications (iOS, Android)
• Desktop applications
• Any public client that cannot store secrets

Security Benefits:

• Prevents authorization code interception attacks
• No client secret required
• Protects against malicious apps intercepting redirect
• Recommended by OAuth2 security best practices (RFC 8252)

3. Client Credentials Flow

Machine-to-Machine Authentication

The client credentials flow is used when the client itself is the resource owner, typically for service-to-service communication.

Flow Steps:

1. Client authenticates with client_id and client_secret
2. Authorization server validates credentials
3. Authorization server issues access token
4. Client uses token to access protected resources

When to Use:

• Backend services communicating with APIs
• Cron jobs or scheduled tasks
• Microservices authentication
• CI/CD pipelines accessing APIs
• System-level operations without user context

Characteristics:

• No user involvement
• Client is the resource owner
• No refresh tokens (just request new access token)
• Typically long-lived or cached tokens

4. Implicit Flow (Deprecated)

Legacy Flow - No Longer Recommended

The implicit flow returns tokens directly in the URL fragment without an authorization code exchange. This flow is now considered insecure and should be avoided.

Why Deprecated:

• Access tokens exposed in browser history
• No client authentication
• No refresh token support
• Vulnerable to token theft
• Use Authorization Code Flow with PKCE instead

5. Resource Owner Password Credentials (ROPC)

Legacy Flow - Avoid Unless Necessary

The resource owner password credentials flow allows the client to collect username and password directly, then exchange them for tokens.

Flow Steps:

1. User provides username and password to client
2. Client sends credentials to authorization server
3. Authorization server validates and issues tokens

When to Use (Rarely):

• First-party mobile apps migrating from legacy authentication
• Trusted first-party applications only
• When no browser/redirect flow is possible

Why to Avoid:

• Client handles user credentials directly (security risk)
• No multi-factor authentication support
• Phishing vulnerability
• Violates OAuth2 principle of delegated authorization
• Use Authorization Code Flow with PKCE instead when possible

6. Device Authorization Flow

For Input-Constrained Devices

The device flow is designed for devices with limited input capabilities (smart TVs, IoT devices, CLI tools).

Flow Steps:

1. Device requests device code and user code from authorization server
2. Device displays user code and instructs user to visit URL
3. User visits URL on another device and enters user code
4. User authenticates and authorizes device
5. Device polls authorization server for access token
6. Authorization server issues access token when user completes authorization

When to Use:

• Smart TVs and streaming devices
• IoT devices without keyboards
• CLI tools and command-line applications
• Gaming consoles
• Any device where typing is difficult

Token Types and Management

Access Tokens

Short-lived credentials for accessing protected resources

Characteristics:

• Typically expire in 15 minutes to 1 hour
• Bearer token format: Authorization: Bearer <access_token>
• Can be opaque tokens or JWTs (JSON Web Tokens)
• Should be treated as sensitive credentials
• Never log or expose in URLs
• Validate on every API request

JWT Structure (when using JWTs):

Header.Payload.Signature

JWT Payload Claims:

• sub: Subject (user ID)
• iat: Issued at time
• exp: Expiration time
• iss: Issuer (authorization server)
• aud: Audience (resource server)
• scope: Granted permissions
• Custom claims (user metadata, roles, etc.)

Token Validation:

• Verify signature using public key
• Check expiration (exp claim)
• Verify issuer (iss claim)
• Validate audience (aud claim)
• Check token has required scopes

Refresh Tokens

Long-lived credentials for obtaining new access tokens

Characteristics:

• Typically expire in days, weeks, or months
• Single-use or reusable (depending on implementation)
• Must be stored securely (never in localStorage in browsers)
• Should be encrypted at rest
• Can be revoked by authorization server
• Subject to rotation policies

Refresh Token Rotation:

• Each refresh issues a new refresh token
• Old refresh token is invalidated
• Prevents token replay attacks
• Detects token theft (multiple refresh attempts)
• Recommended security practice

Token Storage Best Practices:

Web Applications:

• Access tokens: Memory (React context, Vuex, Redux)
• Refresh tokens: HttpOnly, Secure, SameSite cookies
• Alternative: Store refresh token on backend, use session

Mobile Applications:

• Use platform secure storage
• iOS: Keychain Services
• Android: EncryptedSharedPreferences or Keystore
• Never store in plaintext files

SPAs:

• Store access tokens in memory only
• Use BFF (Backend for Frontend) pattern for refresh tokens
• Consider Token Handler pattern
• Avoid localStorage (XSS vulnerability)

ID Tokens (OpenID Connect)

Tokens containing user identity information

Characteristics:

• Always JWT format
• Contains user profile information
• Used for authentication (not authorization)
• Returned alongside access tokens
• Should be validated before use

Standard Claims:

• sub: Subject (unique user ID)
• name: Full name
• email: Email address
• email_verified: Email verification status
• picture: Profile picture URL
• iat, exp: Issued/expiration times

OAuth2 Scopes

Fine-grained permissions for access control

Scopes define what access the client is requesting and what the access token permits.

Scope Naming Conventions:

• read:users - Read user data
• write:users - Create/update users
• delete:users - Delete users
• admin:all - Full administrative access
• openid - Request OpenID Connect ID token
• profile - Access user profile information
• email - Access user email address

Best Practices:

• Request minimum required scopes (principle of least privilege)
• Separate read and write permissions
• Create resource-specific scopes
• Document all available scopes
• Allow users to see and understand requested permissions
• Implement scope-based access control in APIs

Dynamic Scopes:

read:organization:{org_id}
write:project:{project_id}
admin:tenant:{tenant_id}

Security Considerations

State Parameter

Prevents Cross-Site Request Forgery (CSRF)

The state parameter is a random value that the client includes in the authorization request and validates in the callback.

Implementation:

1. Generate random state value (cryptographically secure)
2. Store state in session or encrypted cookie
3. Include state in authorization URL
4. Validate state matches when receiving callback
5. Reject mismatched or missing state

Example State Value:

state: crypto.randomBytes(32).toString('hex')
// "7f8a3d9e2b1c4f5a6d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"

PKCE Implementation

Proof Key for Code Exchange - Prevents Code Interception

PKCE protects the authorization code flow against authorization code interception attacks.

Code Verifier:

• Random string, 43-128 characters
• Characters: A-Z, a-z, 0-9, -, ., _, ~
• Stored securely on client

Code Challenge:

• SHA256 hash of code verifier (recommended)
• Or plain code verifier (not recommended)
• Sent in authorization request

Code Challenge Methods:

• S256: SHA256 hash (use this)
• plain: Plaintext verifier (legacy only)

Implementation Example:

// Generate code verifier
const codeVerifier = generateRandomString(64);

// Generate code challenge
const codeChallenge = base64UrlEncode(
  sha256(codeVerifier)
);

// Store code verifier for token exchange
sessionStorage.setItem('code_verifier', codeVerifier);

// Include in authorization URL
const authUrl = `${authEndpoint}?` +
  `client_id=${clientId}` +
  `&redirect_uri=${redirectUri}` +
  `&response_type=code` +
  `&scope=${scopes}` +
  `&state=${state}` +
  `&code_challenge=${codeChallenge}` +
  `&code_challenge_method=S256`;

Token Security

Protecting Access and Refresh Tokens

Do:

• Use HTTPS for all OAuth2 endpoints
• Store refresh tokens in secure storage only
• Implement token rotation
• Set appropriate token expiration times
• Validate tokens on every API request
• Use JWTs with strong signing algorithms (RS256, ES256)
• Implement token revocation
• Monitor for suspicious token usage

Don't:

• Store tokens in localStorage (XSS risk)
• Include tokens in URLs or query parameters
• Log tokens in application logs
• Use weak signing algorithms (HS256 with shared secrets)
• Share tokens between applications
• Extend access token lifetime unnecessarily
• Ignore token expiration

Redirect URI Validation

Prevent Open Redirect Vulnerabilities

Strict Validation Rules:

• Exact match required (no wildcards)
• Protocol must match exactly (https://)
• Host must match exactly
• Port must match (if specified)
• Path must match (if specified)
• Register all redirect URIs in advance

Mobile Deep Links:

• Use custom URL schemes: com.example.app://callback
• Or universal links (iOS): https://example.com/auth/callback
• Or app links (Android): https://example.com/auth/callback
• Register schemes with authorization server

Localhost Development:

• Allow http://localhost for development only
• Specify exact port: http://localhost:3000/callback
• Use 127.0.0.1 if localhost doesn't work
• Never use localhost redirects in production

OpenID Connect (OIDC)

Identity Layer Built on OAuth2

OpenID Connect adds an identity layer on top of OAuth2, providing authentication in addition to authorization.

Key Differences from OAuth2:

• Returns ID token in addition to access token
• ID token contains user identity information
• Standardized user info endpoint
• Standardized discovery endpoint (.well-known/openid-configuration)
• Session management capabilities

OIDC Flows:

1. Authorization Code Flow (recommended)

   • Same as OAuth2 but returns id_token
   • Most secure for web apps

2. Implicit Flow (deprecated)

   • Returns id_token directly
   • Insecure, use Code Flow with PKCE instead

3. Hybrid Flow

   • Combines Code and Implicit flows
   • Complex, rarely needed

OIDC Scopes:

• openid (required) - Enables OIDC
• profile - Name, picture, locale, etc.
• email - Email address and verification status
• address - Physical address
• phone - Phone number

UserInfo Endpoint:

GET /userinfo
Authorization: Bearer <access_token>