oauth

This skill provides guidance for OAuth 2.0 and OpenID Connect implementations.

OAuth 2.0 Flows

Authorization Code Flow (Recommended for web apps)

1. User → App: Click "Login with Google"
2. App → Auth Server: Redirect with client_id, redirect_uri, scope
3. User → Auth Server: Authenticate and consent
4. Auth Server → App: Redirect with authorization code
5. App → Auth Server: Exchange code for tokens
6. Auth Server → App: Access token + refresh token

PKCE Extension (Required for SPAs/mobile)

# Generate code verifier and challenge
code_verifier = secrets.token_urlsafe(32)
code_challenge = base64url(sha256(code_verifier))

# Include in authorization request
params = {
    "code_challenge": code_challenge,
    "code_challenge_method": "S256",
}

Token Management

@dataclass
class TokenSet:
    access_token: str
    refresh_token: str
    expires_at: datetime
    token_type: str = "Bearer"

async def refresh_tokens(refresh_token: str) -> TokenSet:
    # Exchange refresh token for new access token
    pass

Security Best Practices

1. Always use HTTPS
2. Use PKCE for public clients
3. Validate redirect URIs strictly
4. Store tokens securely (HttpOnly cookies or secure storage)
5. Implement token rotation
6. Set appropriate scopes (principle of least privilege)

OpenID Connect

Extends OAuth 2.0 with identity:

# ID token contains user identity claims
claims = {
    "sub": "user123",        # Subject (unique user ID)
    "email": "user@example.com",
    "name": "John Doe",
    "iat": 1234567890,       # Issued at
    "exp": 1234567890,       # Expiration
}

Implementation Checklist

• [ ] Use authorization code flow with PKCE
• [ ] Validate state parameter against CSRF
• [ ] Verify ID token signature
• [ ] Check token expiration
• [ ] Implement secure token storage
• [ ] Handle token refresh gracefully