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