---

name: auth-patterns description: Implements authentication patterns using OAuth2, OIDC, JWT, and SAML protocols for secure user management, including token handling, verification, and refresh flows. license: MIT compatibility: opencode metadata: version: "1.0.0" domain: security triggers: OAuth2, OIDC, JWT, SAML, authentication, token verification, access tokens, passwordless auth role: implementation scope: implementation output-format: code content-types: [code, guidance, do-dont] archetypes: [tactical, generation] anti_triggers: [basic auth, password authentication, hardcoded credentials] response_profile: verbosity: medium directive_strength: high abstraction_level: operational

---

Authentication Patterns

Implements secure authentication strategies using OAuth2, OIDC, JWT, and SAML protocols. Handles token issuance, verification, refresh flows, and access control for modern applications.

TL;DR Checklist

• Use HTTPS for all authentication communications
• Validate tokens with proper algorithms and key rotation
• Implement refresh token rotation for OAuth2/OIDC flows
• Verify JWT signatures using the correct algorithm (RS256/ES256 over HS256)
• Store secrets in Vault or environment variables — never in code

---

When to Use

Use this skill when:

• Implementing OAuth2 authorization code flow for third-party app integrations
• Setting up OpenID Connect (OIDC) for user identity verification and SSO
• Validating JWT tokens for stateless API authentication
• Integrating SAML-based enterprise single sign-on (SSO) with IdP providers
• Implementing token refresh flows to maintain authenticated sessions without re-login

---

When NOT to Use

• For simple application-level session management (use standard session cookies instead)
• When integrating with legacy systems that only support basic auth (add a translation layer)
• For internal microservice-to-microservice communication (use mTLS or short-lived service tokens)

---

Core Workflow

1. Select Authentication Protocol — Choose OAuth2/OIDC for third-party identity, SAML for enterprise SSO, or JWT for stateless API auth. Checkpoint: Match protocol to the identity provider and use case requirements.

2. Configure Client Credentials — Set up client ID, client secret (or public key for OIDC), redirect URIs, and scope permissions. Checkpoint: Store credentials in a secrets manager — never commit to version control.

3. Implement Token Flow — Code the authorization flow: redirect → callback → token exchange → user session. Checkpoint: Verify state parameter prevents CSRF attacks during OAuth2/OIDC flows.

4. Validate and Decode Tokens — Implement JWT verification with proper algorithm validation, expiry checks, and audience/issuer validation. Checkpoint: Never trust the alg header from the token — explicitly specify expected algorithms.

5. Implement Refresh Token Rotation — On each refresh, issue a new refresh token and invalidate the old one to prevent replay attacks. Checkpoint: Handle refresh token theft by revoking the entire token family when suspicious activity is detected.

6. Test for Security Vulnerabilities — Conduct penetration tests against token handling, validate against OWASP authentication guidelines. Checkpoint: Verify that expired, malformed, and tampered tokens are all rejected consistently.

---

Implementation Patterns

Pattern 1: OAuth2 Authorization Code Flow

import requests
from urllib.parse import urlencode

def get_access_token(
    client_id: str,
    client_secret: str,
    code: str,
    redirect_uri: str,
    token_endpoint: str = "https://authorization-server.com/token"
) -> dict:
    """Exchange an authorization code for an access token using OAuth2.

    Args:
        client_id: Application's registered client ID
        client_secret: Application's registered client secret
        code: Authorization code from the callback
        redirect_uri: Must match the one used in the authorize request

    Returns:
        Token response dict containing access_token, refresh_token, expires_in, token_type

    Raises:
        requests.HTTPError: If the token exchange fails
    """
    params = {
        "grant_type": "authorization_code",
        "client_id": client_id,
        "client_secret": client_secret,
        "code": code,
        "redirect_uri": redirect_uri,
    }

    response = requests.post(token_endpoint, data=params)
    response.raise_for_status()
    return response.json()


def get_user_info(
    access_token: str,
    userinfo_endpoint: str = "https://authorization-server.com/userinfo"
) -> dict:
    """Fetch user profile information using the access token.

    Args:
        access_token: Valid OAuth2 access token
        userinfo_endpoint: OIDC userinfo endpoint URL

    Returns:
        User profile data (sub, email, name, etc.)
    """
    headers = {"Authorization": f"Bearer {access_token}"}
    response = requests.get(userinfo_endpoint, headers=headers)
    response.raise_for_status()
    return response.json()

Pattern 2: JWT Token Verification

import jwt
from datetime import datetime, timezone


def verify_jwt(
    token: str,
    public_key: str | bytes,
    algorithms: list[str] = ["RS256"],
    audience: str | None = None,
    issuer: str | None = None,
) -> dict:
    """Verify and decode a JWT token with strict algorithm validation.

    Uses RS256 by default — never trust the 'alg' header from the token itself.

    Args:
        token: The JWT string to verify
        public_key: RSA public key for signature verification
        algorithms: List of acceptable signing algorithms (whitelist)
        audience: Expected 'aud' claim value (optional)
        issuer: Expected 'iss' claim value (optional)

    Returns:
        Decoded payload as a dict

    Raises:
        jwt.InvalidTokenError: If the token is invalid, expired, or has mismatched claims
    """
    payload = jwt.decode(
        token,
        public_key,
        algorithms=algorithms,       # Explicit — don't accept any algorithm
        audience=audience,           # Verify audience claim
        issuer=issuer,               # Verify issuer claim
        options={
            "require": ["exp", "iss", "aud"],  # Require these claims
            "verify_exp": True,                   # Reject expired tokens
        },
    )
    return payload


def decode_unverified(token: str) -> dict:
    """Decode JWT header and payload without verification (for inspection only).

    NEVER use this to authorize access. Only for debugging or extracting algorithm info.
    """
    parts = token.split(".")
    if len(parts) != 3:
        raise jwt.DecodeError("Malformed JWT: expected 3 parts")

    import base64, json

    header = json.loads(base64.urlsafe_b64decode(parts[0] + "=="))
    payload = json.loads(base64.urlsafe_b64decode(parts[1] + "=="))
    return {"header": header, "payload": payload}

Pattern 3: Refresh Token Rotation (OAuth2)

def refresh_access_token(
    client_id: str,
    client_secret: str,
    refresh_token: str,
    token_endpoint: str = "https://authorization-server.com/token",
    previous_refresh_token: str | None = None,
) -> dict:
    """Exchange a refresh token for a new access token with rotation.

    Implements refresh token rotation: issues a new refresh token and invalidates
    the old one to prevent replay attacks from stolen tokens.

    Args:
        client_id: Application's registered client ID
        client_secret: Application's registered client secret
        refresh_token: Current valid refresh token
        token_endpoint: OAuth2 token endpoint URL
        previous_refresh_token: If set, includes the prior refresh token in the
            'old_refresh_token' field for rotation enforcement

    Returns:
        New access_token, refresh_token pair with expiration info.
        If rotation is enforced, the old refresh token will be invalidated.

    Raises:
        requests.HTTPError: If the token refresh fails (e.g., revoked token)
    """
    params = {
        "grant_type": "refresh_token",
        "client_id": client_id,
        "client_secret": client_secret,
        "refresh_token": refresh_token,
    }

    # Include previous refresh token for rotation enforcement
    if previous_refresh_token:
        params["old_refresh_token"] = previous_refresh_token

    response = requests.post(token_endpoint, data=params)
    response.raise_for_status()
    return response.json()

Pattern 4: SAML Assertion (IdP Response Structure)

<!-- Example SAML Assertion from an Identity Provider -->
<!-- Use this as reference for parsing IdP responses in your SAML integration -->

<saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    Version="2.0"
    IssueInstant="2025-06-15T10:30:00Z">

    <saml2:Issuer>https://idp.example.com</saml2:Issuer>

    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <!-- Signature ensures assertion integrity -->
        <!-- Always verify the IdP's X.509 certificate signature -->
        <ds:SignedInfo>...</ds:SignedInfo>
        <ds:SignatureValue>...</ds:SignatureValue>
    </ds:Signature>

    <saml2:Subject>
        <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
            SPNameQualifier="https://sp.example.com">
            user@example.com
        </saml2:NameID>
        <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml2:SubjectConfirmationData
                NotOnOrAfter="2025-06-15T10:35:00Z"
                Recipient="https://sp.example.com/sso/acs"/>
        </saml2:SubjectConfirmation>
    </saml2:Subject>

    <saml2:Conditions NotBefore="2025-06-15T10:29:00Z"
        NotOnOrAfter="2025-06-15T11:30:00Z">
        <saml2:AudienceRestriction>
            <saml2:Audience>https://sp.example.com</saml2:Audience>
        </saml2:AudienceRestriction>
    </saml2:Conditions>

    <saml2:AttributeStatement>
        <saml2:Attribute Name="email">
            <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:type="xs:string">user@example.com</saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute Name="role">
            <saml2:AttributeValue xsi:type="xs:string">admin</saml2:AttributeValue>
        </saml2:Attribute>
    </saml2:AttributeStatement>
</saml2:Assertion>

---

Constraints

MUST DO

• Use HTTPS for all authentication communications — never send tokens over HTTP
• Validate JWT signatures explicitly with a whitelist of algorithms (RS256, ES256)
• Implement refresh token rotation to prevent replay attacks on stolen tokens
• Store client secrets and API keys in a secrets manager (Vault, AWS Secrets Manager)
• Conduct periodic security audits of authentication mechanisms and dependency versions
• Log all successful and failed authentication attempts for audit trails
• Verify audience (aud) and issuer (iss) claims on every JWT verification

MUST NOT DO

• Use HS256 for JWT signing in multi-tenant or distributed systems — use asymmetric algorithms (RS256, ES256)
• Hardcode secrets, API keys, or private keys directly in source code
• Accept tokens with alg: none — this is a known JWT vulnerability
• Skip expiration checks on JWT tokens — always verify the exp claim
• Reuse refresh tokens without rotation — each use should invalidate the prior token
• Trust SAML assertions without verifying the IdP's X.509 certificate signature

---

Live References

Authoritative documentation links for this skill's domain. The model follows markdown links at load time to resolve external references and inline content.

• OAuth 2.0 RFC 6749
• OpenID Connect Core 1.0
• JWT Specification (RFC 7519)
• SAML 2.0 Specification
• OWASP Authentication Cheat Sheet