Authentication Patterns

Comprehensive guidance for implementing secure authentication systems, covering JWT, OAuth 2.0, OIDC, Passkeys, MFA, and session management.

When to Use This Skill

Use this skill when:

Implementing JWT-based authentication
Setting up OAuth 2.0 or OpenID Connect flows
Implementing passwordless authentication (Passkeys/FIDO2)
Adding multi-factor authentication (MFA/2FA)
Designing session management and secure cookies
Implementing SSO (Single Sign-On)
Reviewing authentication security
Choosing between authentication approaches

Authentication Method Selection

Method	Best For	Security Level	UX
Passkeys/WebAuthn	Primary auth, passwordless	★★★★★	Excellent
OAuth 2.0 + PKCE	Third-party login, SPAs	★★★★☆	Good
JWT + Refresh Tokens	APIs, microservices	★★★★☆	Good
Session Cookies	Traditional web apps	★★★☆☆	Excellent
Password + MFA	Legacy systems upgrade	★★★★☆	Moderate

Recommendation: Prefer Passkeys for new applications. Use OAuth 2.0 + PKCE for SPAs. Always add MFA as a second factor.

JWT Best Practices Quick Reference

Algorithm Selection

Algorithm	Use Case	Recommendation
RS256	Public key verification, distributed systems	✅ Recommended
ES256	Smaller tokens, ECDSA-based	✅ Recommended
HS256	Simple systems, same-party verification	⚠️ Use carefully
None	Never use	❌ Prohibited

Token Structure

// Header
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-for-rotation"  // Key ID for key rotation
}

// Payload (Claims)
{
  "iss": "https://auth.example.com",  // Issuer
  "sub": "user-123",                   // Subject (user ID)
  "aud": "https://api.example.com",   // Audience
  "exp": 1735300000,                   // Expiration (short-lived)
  "iat": 1735296400,                   // Issued at
  "jti": "unique-token-id",            // JWT ID (for revocation)
  "scope": "read write"                // Permissions
}

Token Lifetimes

Token Type	Recommended Lifetime	Storage
Access Token	5-15 minutes	Memory only
Refresh Token	7-30 days	Secure HttpOnly cookie or encrypted storage
ID Token	Match access token	Memory only

For detailed JWT security: See JWT Security Reference

OAuth 2.0 Flow Selection

Flow	Use Case	PKCE Required
Authorization Code + PKCE	SPAs, mobile apps, web apps	✅ Yes
Client Credentials	Service-to-service	N/A
Device Authorization	Smart TVs, CLI tools	N/A
~~Implicit~~	Deprecated - don't use	N/A
~~Resource Owner Password~~	Deprecated - don't use	N/A

Authorization Code + PKCE Flow

┌──────────┐                              ┌───────────────┐
│  Client  │                              │ Auth Server   │
└────┬─────┘                              └───────┬───────┘
     │                                            │
     │ 1. Generate code_verifier (random)         │
     │    code_challenge = SHA256(code_verifier)  │
     │                                            │
     │ 2. Authorization Request ─────────────────>│
     │    (response_type=code, code_challenge)    │
     │                                            │
     │ 3. User authenticates & consents           │
     │                                            │
     │ 4. <────────── Authorization Code ─────────│
     │                                            │
     │ 5. Token Request ─────────────────────────>│
     │    (code, code_verifier)                   │
     │                                            │
     │ 6. <────────── Access + Refresh Tokens ────│
     └────────────────────────────────────────────┘

For detailed OAuth flows: See OAuth Flows Reference

Passkeys/WebAuthn Quick Start

Passkeys provide phishing-resistant, passwordless authentication using public key cryptography.

Registration Flow

// 1. Get challenge from server
const options = await fetch('/api/webauthn/register/options').then(r => r.json());

// 2. Create credential
const credential = await navigator.credentials.create({
  publicKey: {
    challenge: base64ToBuffer(options.challenge),
    rp: { name: "Example App", id: "example.com" },
    user: {
      id: base64ToBuffer(options.userId),
      name: options.username,
      displayName: options.displayName
    },
    pubKeyCredParams: [
      { type: "public-key", alg: -7 },   // ES256
      { type: "public-key", alg: -257 }  // RS256
    ],
    authenticatorSelection: {
      authenticatorAttachment: "platform",  // or "cross-platform"
      residentKey: "required",              // Discoverable credential
      userVerification: "required"          // Biometric/PIN required
    },
    timeout: 60000
  }
});

// 3. Send credential to server for storage
await fetch('/api/webauthn/register/verify', {
  method: 'POST',
  body: JSON.stringify({
    id: credential.id,
    rawId: bufferToBase64(credential.rawId),
    response: {
      clientDataJSON: bufferToBase64(credential.response.clientDataJSON),
      attestationObject: bufferToBase64(credential.response.attestationObject)
    }
  })
});

For complete Passkeys implementation: See Passkeys Implementation Guide

MFA Implementation Patterns

MFA Methods (by Security)

Method	Phishing Resistant	Security	UX
Passkeys/Security Keys	✅ Yes	★★★★★	Good
Authenticator App (TOTP)	❌ No	★★★★☆	Good
Push Notification	⚠️ Partial	★★★★☆	Excellent
SMS OTP	❌ No	★★☆☆☆	Moderate
Email OTP	❌ No	★★☆☆☆	Moderate

TOTP Implementation

using System.Security.Cryptography;
using OtpNet;  // Install: Otp.NET package

/// <summary>
/// TOTP (Time-based One-Time Password) service for MFA.
/// </summary>
public sealed class TotpService
{
    private const int SecretLength = 20;  // 160 bits

    /// <summary>
    /// Generate a new TOTP secret for user enrollment.
    /// </summary>
    public static string GenerateSecret()
    {
        var secretBytes = RandomNumberGenerator.GetBytes(SecretLength);
        return Base32Encoding.ToString(secretBytes);
    }

    /// <summary>
    /// Generate provisioning URI for authenticator apps (Google Authenticator, etc.)
    /// </summary>
    public static string GetProvisioningUri(string secret, string email, string issuer)
    {
        return $"otpauth://totp/{Uri.EscapeDataString(issuer)}:{Uri.EscapeDataString(email)}" +
               $"?secret={secret}&issuer={Uri.EscapeDataString(issuer)}&algorithm=SHA1&digits=6&period=30";
    }

    /// <summary>
    /// Verify TOTP code during login. Allows 1-step time drift.
    /// </summary>
    public static bool VerifyTotp(string secret, string otp)
    {
        var secretBytes = Base32Encoding.ToBytes(secret);
        var totp = new Totp(secretBytes, step: 30, totpSize: 6);

        // VerificationWindow allows for clock drift (1 step = 30 seconds each direction)
        return totp.VerifyTotp(otp, out _, VerificationWindow.RfcSpecifiedNetworkDelay);
    }
}

Session Management

Secure Cookie Configuration

// ASP.NET Core cookie configuration
app.UseCookiePolicy(new CookiePolicyOptions
{
    HttpOnly = HttpOnlyPolicy.Always,        // Prevent JavaScript access (XSS protection)
    Secure = CookieSecurePolicy.Always,      // HTTPS only
    MinimumSameSitePolicy = SameSiteMode.Lax // CSRF protection (or Strict for more security)
});

// Per-cookie configuration
Response.Cookies.Append("session_id", sessionId, new CookieOptions
{
    HttpOnly = true,             // Prevent JavaScript access
    Secure = true,               // HTTPS only
    SameSite = SameSiteMode.Lax, // CSRF protection
    MaxAge = TimeSpan.FromHours(1),
    Domain = ".example.com",
    Path = "/",
    IsEssential = true           // Required for GDPR essential cookies
});

Session Security Checklist

Generate cryptographically random session IDs (128+ bits)
Regenerate session ID after authentication
Set HttpOnly flag on session cookies
Set Secure flag (HTTPS only)
Set SameSite attribute (Lax or Strict)
Implement session timeout (idle and absolute)
Invalidate session on logout (server-side)
Bind session to user fingerprint (optional, consider privacy)

Password Security (When Required)

Password Hashing

using System.Security.Cryptography;
using Konscious.Security.Cryptography;  // Install: Konscious.Security.Cryptography.Argon2

/// <summary>
/// Argon2id password hashing service (recommended by OWASP).
/// </summary>
public sealed class PasswordHasher
{
    private const int SaltSize = 16;
    private const int HashSize = 32;
    private const int Iterations = 3;      // time_cost
    private const int MemorySize = 65536;  // 64 MB
    private const int Parallelism = 4;     // threads

    /// <summary>
    /// Hash a password using Argon2id.
    /// </summary>
    public static string HashPassword(string password)
    {
        var salt = RandomNumberGenerator.GetBytes(SaltSize);

        using var argon2 = new Argon2id(System.Text.Encoding.UTF8.GetBytes(password))
        {
            Salt = salt,
            DegreeOfParallelism = Parallelism,
            MemorySize = MemorySize,
            Iterations = Iterations
        };

        var hash = argon2.GetBytes(HashSize);

        // Combine salt + hash for storage
        var combined = new byte[SaltSize + HashSize];
        Buffer.BlockCopy(salt, 0, combined, 0, SaltSize);
        Buffer.BlockCopy(hash, 0, combined, SaltSize, HashSize);

        return Convert.ToBase64String(combined);
    }

    /// <summary>
    /// Verify a password against stored hash.
    /// </summary>
    public static bool VerifyPassword(string password, string storedHash)
    {
        var combined = Convert.FromBase64String(storedHash);
        if (combined.Length != SaltSize + HashSize) return false;

        var salt = combined[..SaltSize];
        var expectedHash = combined[SaltSize..];

        using var argon2 = new Argon2id(System.Text.Encoding.UTF8.GetBytes(password))
        {
            Salt = salt,
            DegreeOfParallelism = Parallelism,
            MemorySize = MemorySize,
            Iterations = Iterations
        };

        var actualHash = argon2.GetBytes(HashSize);

        // Timing-safe comparison
        return CryptographicOperations.FixedTimeEquals(actualHash, expectedHash);
    }
}

Password Policy

Requirement	Recommendation
Minimum length	12+ characters
Maximum length	128+ characters (prevent DoS)
Complexity	No arbitrary rules (allow all characters)
Breach check	Check against known breached passwords
Rate limiting	5 attempts, then exponential backoff
Account lockout	Temporary lockout (15-30 min) after failures

Quick Decision Tree

What authentication are you implementing?

New web/mobile app → Passkeys + OAuth 2.0 fallback
SPA with API backend → OAuth 2.0 + PKCE with JWT access tokens
Service-to-service → Client Credentials flow or mTLS
Adding MFA to existing → TOTP authenticator app (minimum), Passkeys (ideal)
Traditional web app → Session cookies + CSRF tokens
CLI/device with no browser → Device Authorization flow

Security Checklist

Token Security

Short-lived access tokens (5-15 minutes)
Secure refresh token storage
Token revocation mechanism
Proper token validation (signature, claims, expiry)

OAuth/OIDC Security

Use PKCE for all public clients
Validate redirect URIs strictly
Validate state parameter
Validate nonce for OIDC
Use exact redirect URI matching

Session Security

HttpOnly, Secure, SameSite cookies
Session regeneration after auth
Proper session invalidation
Idle and absolute timeouts

MFA Security

MFA on all accounts (enforce or encourage)
Secure recovery codes
Rate limit MFA attempts
Prefer phishing-resistant methods

References

JWT Security Deep Dive - Complete JWT implementation guide
OAuth 2.0 Flows - OAuth/OIDC flow diagrams and implementation
Passkeys Implementation - WebAuthn/FIDO2 complete guide

Related Skills

Skill	Relationship
`authorization-models`	After authentication, apply authorization (RBAC, ABAC)
`cryptography`	Underlying crypto for tokens and passwords
`api-security`	Securing API endpoints with authentication
`secure-coding`	General security patterns

Version History

v1.0.0 (2025-12-26): Initial release with JWT, OAuth 2.0, Passkeys, MFA, sessions

Last Updated: 2025-12-26

authentication-patterns