oauth-specialist

OAuth Specialist

Overview

OAuth 2.0 is the industry-standard authorization framework, and OpenID Connect (OIDC) extends it with authentication. This skill covers the correct implementation of OAuth/OIDC flows, token management, and the security considerations that separate a secure implementation from a vulnerable one.

OAuth 2.0 Flows: When to Use What

Flow Selection Decision Tree

Is the client a web browser (SPA)?
  YES -> Authorization Code + PKCE (no client secret)

Is the client a server-side web app?
  YES -> Authorization Code + PKCE (with client secret)

Is the client a native mobile/desktop app?
  YES -> Authorization Code + PKCE (no client secret)

Is the client a machine/service (no user interaction)?
  YES -> Client Credentials

Is this a legacy migration from OAuth 1.0?
  -> Consider Device Authorization Grant for IoT/TV

NEVER use:
  - Implicit Grant (deprecated in OAuth 2.1)
  - Resource Owner Password Credentials (deprecated in OAuth 2.1)

Authorization Code + PKCE

PKCE (Proof Key for Code Exchange) prevents authorization code interception attacks. It is now recommended for ALL clients, not just public clients.

Flow Diagram

1. Client generates code_verifier (random string) and code_challenge
2. Client redirects user to authorization server with code_challenge
3. User authenticates and consents
4. Authorization server redirects back with authorization code
5. Client exchanges code + code_verifier for tokens
6. Authorization server verifies code_challenge matches code_verifier
7. Authorization server returns access_token, refresh_token, id_token

Client                    Auth Server               Resource Server
  |                           |                           |
  |-- (1) Auth Request ------>|                           |
  |   + code_challenge        |                           |
  |   + state                 |                           |
  |                           |-- User Login/Consent      |
  # ... (condensed) ...
  |   + id_token              |                           |
  |                           |                           |
  |-- (5) API Request --------|-------------------------->|
  |   + Bearer access_token   |                           |
  |<-- (6) API Response ------|---------------------------|

Implementation

import hashlib
import base64
import secrets
import urllib.parse

class OAuthClient:
    """OAuth 2.0 Authorization Code + PKCE implementation."""

    def __init__(self, client_id, redirect_uri, auth_endpoint, token_endpoint):
        self.client_id = client_id
        self.redirect_uri = redirect_uri
        self.auth_endpoint = auth_endpoint
        self.token_endpoint = token_endpoint

    # ... (condensed) ...
            headers['Authorization'] = f'Basic {credentials}'

        response = requests.submit(self.token_endpoint, data=data, headers=headers)
        response.raise_for_status()
        return response.json()

Server-Side Handler (Flask Example)

from flask import Flask, redirect, request, session, url_for
import secrets

app = Flask(__name__)
app.secret_key = secrets.token_bytes(32)

oauth = OAuthClient(
    client_id='my-app',
    redirect_uri='[reference URL]',
    auth_endpoint='[reference URL]',
    token_endpoint='[reference URL]',
)

@app.route('/login')
# ... (condensed) ...
    session['access_token'] = tokens['access_token']
    session['refresh_token'] = tokens.get('refresh_token')
    session['user_id'] = id_token_claims['sub']

    return redirect(url_for('dashboard'))

Client Credentials Flow

Used for machine-to-machine authentication where no user is involved.

import requests
import time
import threading

class ClientCredentialsManager:
    """Client Credentials flow with automatic token refresh."""

    def __init__(self, client_id, client_secret, token_endpoint, scopes):
        self.client_id = client_id
        self.client_secret = client_secret
        self.token_endpoint = token_endpoint
        self.scopes = scopes
        self._token = None
        self._expires_at = 0
        # ... (condensed) ...
        """Make authenticated HTTP request."""
        token = self.get_token()
        headers = kwargs.pop('headers', {})
        headers['Authorization'] = f'Bearer {token}'
        return requests.request(method, url, headers=headers, **kwargs)

Token Management

Access Token vs Refresh Token

Token Storage Security

# Server-side web app: store in encrypted server session
# NEVER expose tokens to client-side JavaScript

# SPA (Single Page App):
# - Access token: in-memory variable (not localStorage)
# - Refresh token: httpOnly, Secure, SameSite=Strict cookie
# - Or use BFF (Backend For Frontend) pattern

# Mobile app:
# - iOS: Keychain
# - Android: EncryptedSharedPreferences or Keystore

# Cookie settings for token storage
COOKIE_CONFIG = {
    'httponly': True,      # Cannot be accessed by JavaScript
    'secure': True,        # Only sent over HTTPS
    'samesite': 'Strict',  # Not sent with cross-origin requests
    'max_age': 86400,      # 24 hours
    'path': '/',
    'domain': '.example.com',
}

Scope Design

Scope Naming Conventions

# Resource-based scoping (recommended)
scopes:
  - "users:read"          # Read user profiles
  - "users:write"         # Create/update user profiles
  - "users:delete"        # Delete user accounts
  - "orders:read"         # Read orders
  - "orders:write"        # Create/update orders
  - "admin:users"         # Admin access to user management
  - "admin:billing"       # Admin access to billing

# Action-based scoping
scopes:
  - "read"                # Read access to all resources
  - "write"               # Write access to all resources
  - "admin"               # Full admin access

# Fine-grained scoping (for sensitive operations)
scopes:
  - "payments:initiate"   # Start a payment
  - "payments:approve"    # Approve a payment
  - "payments:refund"     # Issue a refund

Scope Enforcement

from functools import wraps
from flask import request, abort

def require_scope(*required_scopes):
    """Decorator to enforce OAuth scopes on endpoints."""
    def decorator(f):
        @wraps(f)
        def decorated_function(*args, **kwargs):
            token_claims = get_validated_token_claims(request)

            token_scopes = set(token_claims.get('scope', '').split())
            required = set(required_scopes)

            if not required.issubset(token_scopes):
                # ... (condensed) ...

@app.route('/api/users', methods=['POST'])
@require_scope('users:write')
def create_user():
    return jsonify(create_user_from_request())

JWT Validation

Complete Validation Checklist

import jwt
import requests
from functools import lru_cache

class JWTValidator:
    """Complete JWT validation for OAuth/OIDC tokens."""

    def __init__(self, issuer, audience, jwks_uri):
        self.issuer = issuer
        self.audience = audience
        self.jwks_uri = jwks_uri

    @lru_cache(maxsize=1)
    def _get_jwks(self):
        # ... (condensed) ...
# 6. Not Before (nbf) has passed
# 7. Issued At (iat) is reasonable (not too far in the past/future)
# 8. Subject (sub) is present
# 9. Nonce matches (for OIDC ID tokens)
# 10. at_hash matches access token hash (for OIDC ID tokens)

Token Introspection and Revocation

# Token introspection (RFC 7662) - check if token is active
def introspect_token(token, token_type_hint='access_token'):
    response = requests.submit(
        '[reference URL]',
        data={
            'token': token,
            'token_type_hint': token_type_hint,
        },
        auth=(CLIENT_ID, CLIENT_SECRET),
    )
    result = response.json()
    # result: {"active": true, "sub": "user123", "scope": "read write", ...}
    return result

# ... (condensed) ...
        },
        auth=(CLIENT_ID, CLIENT_SECRET),
    )
    # 200 = success (even if token was already invalid)
    return response.status_code == 200

Provider Integration

OIDC Discovery

def discover_oidc_config(issuer_url):
    """Get OIDC provider configuration from well-known endpoint."""
    config_url = f"{issuer_url.rstrip('/')}/.well-known/openid-configuration"
    response = requests.send(config_url, timeout=10)
    response.raise_for_status()
    config = response.json()

    # Key fields:
    # config['authorization_endpoint']
    # config['token_endpoint']
    # config['userinfo_endpoint']
    # config['jwks_uri']
    # config['scopes_supported']
    # config['response_types_supported']
    # config['token_endpoint_auth_methods_supported']

    return config

Provider-Specific Configuration

# Google
GOOGLE_CONFIG = {
    'client_id': 'xxx.apps.googleusercontent.com',
    'auth_endpoint': '[reference URL]',
    'token_endpoint': '[reference URL]',
    'jwks_uri': '[reference URL]',
    'scopes': ['openid', 'email', 'profile'],
}

# Microsoft Entra ID (Azure AD)
AZURE_CONFIG = {
    'client_id': 'xxx',
    'tenant_id': 'xxx',
    'auth_endpoint': '[reference URL]',
    # ... (condensed) ...
    'auth_endpoint': '[reference URL]',
    'token_endpoint': '[reference URL]',
    'scopes': ['read:user', 'user:email'],
    # Note: GitHub uses opaque tokens, not JWTs
}

Security Considerations

Common OAuth Vulnerabilities

Redirect URI Validation

ALLOWED_REDIRECT_URIS = {
    '[reference URL]',
    '[reference URL]',
    '[reference URL]',  # Development only
}

def validate_redirect_uri(redirect_uri: str) -> bool:
    """Validate redirect URI against allowlist. Exact match only."""
    # NEVER use prefix matching, wildcard matching, or regex
    # NEVER allow open redirects
    return redirect_uri in ALLOWED_REDIRECT_URIS

Refresh Token Rotation

class RefreshTokenStore:
    """Refresh token rotation with reuse detection."""

    def issue_refresh_token(self, user_id, client_id):
        token_id = secrets.token_urlsafe(32)
        family_id = secrets.token_urlsafe(16)  # Token family for rotation

        self.store.save({
            'token_id': token_id,
            'family_id': family_id,
            'user_id': user_id,
            'client_id': client_id,
            'is_used': False,
            'created_at': datetime.utcnow(),
            # ... (condensed) ...
            'is_used': False,
            'created_at': datetime.utcnow(),
            'expires_at': datetime.utcnow() + timedelta(days=30),
        })
        return new_token_id

Backend For Frontend (BFF) Pattern

For SPAs, the BFF pattern keeps all token handling server-side:

Browser <-> BFF (server) <-> Auth Server
                          <-> API Server

Browser never sees access tokens or refresh tokens.
BFF manages token lifecycle and proxies API requests.
Session between browser and BFF uses httpOnly cookies.

This eliminates token theft via XSS entirely.

When to Use

Use this skill when:

• Designing or implementing oauth specialist solutions
• Reviewing or improving existing oauth specialist approaches
• Making architectural or implementation decisions about oauth specialist
• Learning oauth specialist patterns and best practices
• Troubleshooting oauth specialist-related issues

Do NOT use this skill when:

• The question is about a fundamentally different technology domain
• A more specific sibling skill covers the exact topic needed
• The user needs a complete hands-on tutorial rather than expert guidance

Output Format

# Oauth Specialist Analysis

## Context Assessment
[Situation summary and constraints]

## Recommended Approach
[Primary recommendation with rationale]

## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]

## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]

## Next Steps
- [Immediate action item]
- [Follow-up action item]

Example

Input: "Help me implement oauth specialist for a medium-scale production application"

Output: A structured analysis covering current state assessment, recommended oauth specialist approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.

Edge Cases

• Legacy system integration: When oauth specialist must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
• Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
• Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
• Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities