OAuth2 Implementation

OAuth 2.0 is the industry-standard protocol for authorization, enabling 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.

OAuth2 Grant Types

OAuth2 defines several grant types for different client scenarios. Choosing the right one is the most important architectural decision.

Authorization Code Grant

The most secure and commonly used flow for server-side applications. The client redirects the user to the authorization server, which returns an authorization code after user authentication. The client exchanges this code for an access token using its client secret.

User -> Client: Click "Login with Provider"
Client -> Auth Server: Redirect with client_id, redirect_uri, scope
Auth Server -> User: Login page
User -> Auth Server: Credentials
Auth Server -> Client: Authorization code (via redirect)
Client -> Auth Server: Code + client_secret -> Access Token

PKCE (Proof Key for Code Exchange)

An extension to the authorization code flow designed for mobile and single-page applications where the client secret cannot be kept confidential. The client generates a code_verifier and sends a hash (code_challenge) in the initial request. The authorization server verifies the code verifier matches the challenge during token exchange, preventing interception attacks.

Client Credentials Grant

Used for server-to-server communication where no user is involved. The client authenticates directly with its own credentials (client ID and secret) to obtain an access token for accessing its own resources or APIs.

Implicit Grant (Deprecated)

Previously used for SPAs. It returned the access token directly in the redirect URL fragment. Now considered less secure than PKCE and should not be used in new implementations.

Token Handling and Refresh

Access Tokens

Short-lived tokens (typically 15–60 minutes) that the client sends with each API request in the Authorization header. They should never be stored in localStorage for browser applications — use httpOnly cookies or in-memory storage to prevent XSS exfiltration.

Refresh Tokens

Long-lived tokens (days to months) used to obtain new access tokens without requiring the user to re-authenticate. Refresh tokens should be stored securely and rotated on each use to limit the window of a leaked token.

Token Refresh Flow

Client -> Auth Server: Refresh Token + client_id
Auth Server -> Client: New Access Token (optional: new Refresh Token)
Client: Retry original API request with new Access Token

Security Considerations

• Always use HTTPS — Tokens and secrets transmitted over HTTP are trivially intercepted. Enforce TLS for every endpoint in the flow.
• Validate redirect URIs — The authorization server must whitelist exact redirect URIs to prevent open redirector attacks.
• Use state parameter — Bind the authorization request to the callback to prevent CSRF attacks on the redirect flow.
• Rotate refresh tokens — Issue a new refresh token each time one is used. If a stolen refresh token is used, the legitimate user's next attempt will reveal the theft.
• Never log tokens — Access tokens and refresh tokens must be excluded from logs, error messages, and stack traces.
• Implement token revocation — Provide an endpoint to revoke tokens when a user logs out or a device is compromised.

Features

• Authorization Code Grant with PKCE support (RFC 7636)
• Client Credentials Grant for machine-to-machine authentication
• Token refresh with automatic rotation and revocation
• CSRF protection via cryptographic state parameter
• Scope-based authorization with consent flow
• Configurable token expiration and signing (HMAC-SHA256)
• In-memory token store with JSON persistence
• CLI tool for server, client, and token management
• Zero dependencies — Python stdlib only