Auth

Authentication (AuthN) answers "who are you?" — verifying a user's or service's identity. Authorization (AuthZ) answers "what are you allowed to do?" — determining what resources and actions the authenticated identity can access. These two concerns are distinct but tightly coupled in every production system.

Protocols covered

This guide covers the major authentication and authorization protocols you will encounter in production systems:

• OAuth 2.0 — the authorization framework for delegated access (scopes, tokens, grants)
• OpenID Connect (OIDC) — the identity layer on top of OAuth 2.0 (ID tokens, user info, discovery)
• SAML 2.0 — XML-based SSO protocol widely used in enterprise environments
• LDAP — directory protocol for user lookups and bind-based authentication
• Kerberos — ticket-based authentication protocol, the backbone of Active Directory auth

OAuth 2.0 (RFC 6749) is an authorization framework that enables applications to obtain limited access to user accounts on third-party services. Instead of sharing passwords, users grant applications specific scopes of access. The application receives an access token that represents these permissions.

Roles

• Resource Owner — the user who owns the data and grants access
• Client — the application requesting access (web app, mobile app, CLI tool)
• Authorization Server — issues tokens after authenticating the resource owner (e.g., Okta, Auth0, Microsoft Entra ID, Keycloak)
• Resource Server — hosts the protected resources; validates access tokens (e.g., your API)

Grant types

Access tokens vs refresh tokens

Scopes

Scopes limit the access granted to a token. The client requests specific scopes, the user consents, and the issued token only grants those permissions.

# Authorization request with scopes
GET /authorize?
  response_type=code&
  client_id=myapp&
  redirect_uri=https://myapp.com/callback&
  scope=read:users write:posts&
  state=xyzabc123

Token introspection & revocation

# Token introspection (RFC 7662) - check if token is active
curl -X POST https://auth.example.com/oauth/introspect \
  -d "token=eyJhbGciOiJSUzI1NiIs..." \
  -d "client_id=myapp" \
  -d "client_secret=secret123"

# Response
# { "active": true, "scope": "read:users", "sub": "user123", "exp": 1711000000 }

# Token revocation (RFC 7009)
curl -X POST https://auth.example.com/oauth/revoke \
  -d "token=eyJhbGciOiJSUzI1NiIs..." \
  -d "token_type_hint=access_token" \
  -d "client_id=myapp" \
  -d "client_secret=secret123"

Authorization code flow

OpenID Connect (OIDC) is an identity layer built on top of OAuth 2.0. While OAuth 2.0 only handles authorization (what can this token access?), OIDC adds authentication (who is this user?). OIDC introduces the ID token — a JWT that contains claims about the authenticated user.

ID tokens

The ID token is a signed JWT issued by the authorization server after successful authentication. It is intended for the client application, not for API access.

// Decoded ID token payload
{
  "iss": "https://auth.example.com",
  "sub": "user-12345",
  "aud": "myapp-client-id",
  "exp": 1711003600,
  "iat": 1711000000,
  "nonce": "n-0S6_WzA2Mj",
  "auth_time": 1710999900,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "email_verified": true,
  "picture": "https://cdn.example.com/jane.jpg"
}

UserInfo endpoint

The UserInfo endpoint returns claims about the authenticated user. It requires an access token (not the ID token) and provides additional profile information beyond what's in the ID token.

# Fetch user profile from the UserInfo endpoint
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  https://auth.example.com/userinfo

# Response
# {
#   "sub": "user-12345",
#   "name": "Jane Doe",
#   "email": "jane@example.com",
#   "email_verified": true,
#   "groups": ["engineering", "platform-team"]
# }

Discovery

OIDC providers publish their configuration at a well-known URL. Clients use this to auto-configure endpoints, supported scopes, signing algorithms, and more.

# Fetch OIDC discovery document
curl https://auth.example.com/.well-known/openid-configuration

# Key fields in the response:
# {
#   "issuer": "https://auth.example.com",
#   "authorization_endpoint": "https://auth.example.com/authorize",
#   "token_endpoint": "https://auth.example.com/oauth/token",
#   "userinfo_endpoint": "https://auth.example.com/userinfo",
#   "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
#   "scopes_supported": ["openid", "profile", "email", "groups"],
#   "response_types_supported": ["code", "id_token", "token id_token"],
#   "id_token_signing_alg_values_supported": ["RS256"]
# }

Standard scopes

How OIDC adds authentication to OAuth

Security Assertion Markup Language 2.0 (SAML) is an XML-based framework for exchanging authentication and authorization data between an Identity Provider (IdP) and a Service Provider (SP). SAML is the dominant SSO protocol in enterprise environments, particularly for web-based applications.

SP-initiated vs IdP-initiated flows

SAML assertions

A SAML assertion is an XML document containing statements about a subject (user). There are three types of statements:

• Authentication statement — confirms the user was authenticated by the IdP at a specific time using a specific method
• Attribute statement — provides user attributes (email, name, groups, roles) to the SP
• Authorization decision statement — indicates whether the user is authorized to access a resource (rarely used in practice)

<!-- Simplified SAML Assertion -->
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="_abc123" IssueInstant="2026-03-20T10:00:00Z" Version="2.0">
  <saml:Issuer>https://idp.example.com</saml:Issuer>
  <ds:Signature>...</ds:Signature>
  <saml:Subject>
    <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
      jane@example.com
    </saml:NameID>
    <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
      <saml:SubjectConfirmationData
        Recipient="https://app.example.com/saml/acs"
        NotOnOrAfter="2026-03-20T10:05:00Z"
        InResponseTo="_request456" />
    </saml:SubjectConfirmation>
  </saml:Subject>
  <saml:Conditions NotBefore="2026-03-20T09:59:00Z" NotOnOrAfter="2026-03-20T10:05:00Z">
    <saml:AudienceRestriction>
      <saml:Audience>https://app.example.com</saml:Audience>
    </saml:AudienceRestriction>
  </saml:Conditions>
  <saml:AuthnStatement AuthnInstant="2026-03-20T10:00:00Z">
    <saml:AuthnContext>
      <saml:AuthnContextClassRef>
        urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
      </saml:AuthnContextClassRef>
    </saml:AuthnContext>
  </saml:AuthnStatement>
  <saml:AttributeStatement>
    <saml:Attribute Name="email">
      <saml:AttributeValue>jane@example.com</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="groups">
      <saml:AttributeValue>engineering</saml:AttributeValue>
      <saml:AttributeValue>platform-team</saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
</saml:Assertion>

XML signing & metadata

SAML responses and assertions are signed using XML Digital Signatures (XMLDSig). The SP validates the signature using the IdP's public certificate, which is exchanged via SAML metadata. Both the IdP and SP publish metadata XML files containing endpoints, certificates, and supported bindings.

# Download IdP metadata
curl -o idp-metadata.xml https://idp.example.com/saml/metadata

# Download SP metadata (your app)
curl -o sp-metadata.xml https://app.example.com/saml/metadata

Bindings

SP-initiated SSO flow

Both OIDC and SAML achieve single sign-on, but they differ significantly in design philosophy, transport, and ideal use cases. Understanding when to use each is critical for making the right architectural decision.

Comparison

When to use which

LDAP (Lightweight Directory Access Protocol) is a protocol for accessing and maintaining distributed directory information services. It organizes data in a hierarchical tree structure and is the foundation of Active Directory, OpenLDAP, and other directory services used for user authentication and group-based authorization.

Directory structure

LDAP directories use a tree structure called the Directory Information Tree (DIT). Each entry is identified by a Distinguished Name (DN).

dc=example,dc=com                    (domain root)
  |
  +-- ou=People                       (organizational unit)
  |     |
  |     +-- cn=Jane Doe               (common name)
  |     |     uid=jdoe
  |     |     mail=jane@example.com
  |     |     memberOf=cn=engineering,ou=Groups,dc=example,dc=com
  |     |
  |     +-- cn=John Smith
  |           uid=jsmith
  |           mail=john@example.com
  |
  +-- ou=Groups
  |     |
  |     +-- cn=engineering
  |     |     member=cn=Jane Doe,ou=People,dc=example,dc=com
  |     |
  |     +-- cn=admins
  |           member=cn=John Smith,ou=People,dc=example,dc=com
  |
  +-- ou=ServiceAccounts
        |
        +-- cn=app-reader

Key terminology

Bind operations (authentication)

LDAP authentication works via bind operations. The client sends a DN and password, and the LDAP server verifies the credentials.

# Simple bind (authenticate as a user)
ldapsearch -x -H ldap://ldap.example.com \
  -D "cn=Jane Doe,ou=People,dc=example,dc=com" \
  -W \
  -b "dc=example,dc=com" \
  "(uid=jdoe)"

# Search for a user by email
ldapsearch -x -H ldap://ldap.example.com \
  -D "cn=app-reader,ou=ServiceAccounts,dc=example,dc=com" \
  -w 'service-password' \
  -b "ou=People,dc=example,dc=com" \
  "(mail=jane@example.com)" cn uid mail memberOf

# Search for all members of a group
ldapsearch -x -H ldap://ldap.example.com \
  -D "cn=app-reader,ou=ServiceAccounts,dc=example,dc=com" \
  -w 'service-password' \
  -b "ou=Groups,dc=example,dc=com" \
  "(cn=engineering)" member

Search filters

# Exact match
(uid=jdoe)

# Wildcard
(cn=Jane*)

# AND - users in engineering who are active
(&(memberOf=cn=engineering,ou=Groups,dc=example,dc=com)(accountStatus=active))

# OR - match by email or uid
(|(uid=jdoe)(mail=jane@example.com))

# NOT - all users except service accounts
(!(ou=ServiceAccounts))

# Combined - active users in engineering or admins group
(&(objectClass=person)(|(memberOf=cn=engineering,ou=Groups,dc=example,dc=com)(memberOf=cn=admins,ou=Groups,dc=example,dc=com))(accountStatus=active))

LDAPS and StartTLS

Kerberos is a ticket-based network authentication protocol that uses symmetric-key cryptography and a trusted third party (the Key Distribution Center, or KDC) to authenticate users and services. It is the default authentication protocol in Active Directory (on-premises) and Microsoft Entra ID (cloud, for Kerberos-based Windows sign-in) environments and is widely used in enterprise networks.

Key components

The authentication flow

Common Kerberos commands

# Request a TGT (kinit)
kinit jdoe@EXAMPLE.COM

# List cached tickets
klist

# Request a service ticket manually
kvno HTTP/web.example.com@EXAMPLE.COM

# Destroy all cached tickets (logout)
kdestroy

# Create a keytab file for a service
ktutil
  addent -password -p HTTP/web.example.com@EXAMPLE.COM -k 1 -e aes256-cts
  wkt /etc/krb5.keytab
  quit

# Verify a keytab works
kinit -kt /etc/krb5.keytab HTTP/web.example.com@EXAMPLE.COM

Kerberos configuration

# /etc/krb5.conf
[libdefaults]
    default_realm = EXAMPLE.COM
    dns_lookup_realm = false
    dns_lookup_kdc = true
    ticket_lifetime = 10h
    renew_lifetime = 7d
    forwardable = true

[realms]
    EXAMPLE.COM = {
        kdc = dc1.example.com
        kdc = dc2.example.com
        admin_server = dc1.example.com
    }

[domain_realm]
    .example.com = EXAMPLE.COM
    example.com = EXAMPLE.COM

JSON Web Tokens (RFC 7519) are compact, URL-safe tokens used to represent claims between two parties. JWTs are the token format used by OIDC ID tokens, and are commonly used for OAuth 2.0 access tokens as well. A JWT has three base64url-encoded parts separated by dots: header.payload.signature.

Structure

# JWT structure
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.     <-- Header (base64url)
eyJzdWIiOiJ1c2VyLTEyMzQ1IiwiaXNzIjoiaHR0.  <-- Payload (base64url)
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c <-- Signature

// Header
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-2024-03"
}

// Payload (claims)
{
  "iss": "https://auth.example.com",
  "sub": "user-12345",
  "aud": "https://api.example.com",
  "exp": 1711003600,
  "iat": 1711000000,
  "nbf": 1711000000,
  "jti": "unique-token-id-abc",
  "scope": "read:users write:posts",
  "roles": ["admin", "editor"]
}

Signing algorithms

Standard claims

Token validation steps

1. Parse the JWT and extract the header
2. Verify alg is an expected algorithm (reject none, reject unexpected algorithms)
3. Fetch the signing key from the JWKS endpoint using the kid from the header
4. Verify the cryptographic signature
5. Check exp — reject expired tokens
6. Check nbf — reject tokens not yet valid
7. Check iss — must match expected issuer
8. Check aud — must include your API/client ID
9. Extract claims and apply authorization logic

JWKS endpoint

# Fetch the JSON Web Key Set
curl https://auth.example.com/.well-known/jwks.json

// JWKS response
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key-id-2024-03",
      "use": "sig",
      "alg": "RS256",
      "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps...",
      "e": "AQAB"
    }
  ]
}

Common pitfalls

Multi-factor authentication (MFA) requires users to provide two or more verification factors to gain access. This dramatically reduces the risk of account compromise — even if a password is stolen, the attacker still needs the second factor. Passwordless authentication eliminates passwords entirely, using cryptographic credentials instead.

Authentication factors

TOTP (Time-based One-Time Password)

TOTP (RFC 6238) generates a 6-8 digit code that changes every 30 seconds. Both the server and the authenticator app share a secret key. The code is derived from the secret + current time using HMAC-SHA1 by default, though the RFC also supports HMAC-SHA-256 and HMAC-SHA-512.

# Generate a TOTP secret (base32-encoded)
# Server stores this and shares it with the user via QR code
SECRET="JBSWY3DPEHPK3PXP"

# The otpauth:// URI for QR code generation
# otpauth://totp/Example:jane@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example&digits=6&period=30

# Python example of TOTP verification
python3 -c "
import hmac, hashlib, struct, time, base64
secret = base64.b32decode('JBSWY3DPEHPK3PXP')
counter = int(time.time()) // 30
msg = struct.pack('>Q', counter)
h = hmac.new(secret, msg, hashlib.sha1).digest()
offset = h[-1] & 0x0F
code = (struct.unpack('>I', h[offset:offset+4])[0] & 0x7FFFFFFF) % 1000000
print(f'Current TOTP: {code:06d}')
"

WebAuthn / FIDO2

WebAuthn (Web Authentication API) is a W3C standard that enables passwordless authentication using public-key cryptography. The user's device generates a key pair — the private key never leaves the device, and the public key is registered with the server.

Passkeys

Passkeys are synced WebAuthn credentials stored in the platform's credential manager (iCloud Keychain, Google Password Manager, Microsoft Password Manager, 1Password). They combine the security of public-key cryptography with the convenience of cross-device availability. When a user creates a passkey on their iPhone, it syncs to their Mac, iPad, and other Apple devices automatically. Microsoft Edge and Windows also support passkey syncing via Microsoft accounts.

Recovery codes

Recovery codes are single-use backup codes generated when MFA is set up. Store them securely (password manager, printed in a safe). Best practices:

• Generate 8-10 codes, each 8+ characters
• Store hashed on the server (like passwords)
• Invalidate each code after use
• Allow regeneration (which invalidates all previous codes)
• Require identity verification before displaying recovery codes

Risk-based authentication

Rather than requiring MFA for every login, risk-based (adaptive) authentication evaluates contextual signals and only steps up when risk is elevated:

• Known device + known location — low risk, skip MFA
• New device + known location — medium risk, require MFA
• New device + new location — high risk, require stronger MFA
• Impossible travel — login from two distant locations within minutes, block and notify

The token lifecycle — issuance, validation, refresh, and revocation — is critical to the security of any auth system. Poor token management is one of the most common sources of authentication vulnerabilities.

Token lifecycle

Short-lived access tokens + long-lived refresh tokens

The standard pattern: access tokens expire quickly (5-15 minutes) so that if stolen, the attack window is small. Refresh tokens last longer (hours to days) but are stored securely and used only with the authorization server, never sent to resource servers.

// Token response from authorization server
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "v1.MRjE4ZDI1NzQtMDRh...",
  "scope": "openid profile read:data"
}

# Refresh an access token
curl -X POST https://auth.example.com/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=v1.MRjE4ZDI1NzQtMDRh..." \
  -d "client_id=myapp" \
  -d "client_secret=secret123"

Token storage

PKCE (Proof Key for Code Exchange)

PKCE (RFC 7636) protects the authorization code flow for public clients (SPAs, mobile apps) that cannot securely store a client secret. It prevents authorization code interception by binding the code to the client that requested it.

// PKCE flow implementation
// 1. Generate code_verifier (random string, 43-128 chars)
const codeVerifier = generateRandomString(64);

// 2. Generate code_challenge (SHA-256 hash of verifier, base64url-encoded)
const encoder = new TextEncoder();
const data = encoder.encode(codeVerifier);
const digest = await crypto.subtle.digest('SHA-256', data);
const codeChallenge = base64urlEncode(digest);

// 3. Authorization request includes challenge
// GET /authorize?
//   response_type=code&
//   client_id=myapp&
//   redirect_uri=https://myapp.com/callback&
//   code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
//   code_challenge_method=S256&
//   scope=openid profile

// 4. Token request includes verifier
// POST /token
//   grant_type=authorization_code&
//   code=SplxlOBeZQQYbYS6WxSbIA&
//   redirect_uri=https://myapp.com/callback&
//   client_id=myapp&
//   code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Token binding

Token binding ties tokens to the TLS connection or client certificate, preventing stolen tokens from being used on different connections. Standards include DPoP (Demonstration of Proof-of-Possession, RFC 9449) and mTLS-bound tokens (RFC 8705).

# DPoP (Demonstration of Proof-of-Possession)
# Client generates a key pair and includes a DPoP proof JWT with each request
curl -H "Authorization: DPoP eyJhbGciOiJSUzI1NiIs..." \
     -H "DPoP: eyJhbGciOiJSUzI1NiIsInR5cCI6ImRwb3Arand..." \
     https://api.example.com/resource

Authentication and authorization systems are high-value targets. A single vulnerability can compromise every user account. These practices address the most common attack vectors.

OAuth 2.0 / OIDC protections

# Generate state
STATE=$(openssl rand -base64 32)
# Store in session, include in /authorize
# Verify on callback before exchanging code

Session management

// Secure cookie configuration
app.use(session({
  name: '__Host-session',           // __Host- prefix: requires Secure, no Domain
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: {
    secure: true,                   // HTTPS only
    httpOnly: true,                 // No JavaScript access
    sameSite: 'lax',                // CSRF protection
    maxAge: 3600000,                // 1 hour
    path: '/'
  }
}));

Secure cookie attributes

Brute force & account protection

• Rate limiting — limit login attempts per IP and per account (e.g., 5 attempts per minute)
• Account lockout — temporarily lock accounts after repeated failures (e.g., 15-minute lockout after 10 failures). Use exponential backoff.
• CAPTCHA — require CAPTCHA after failed attempts (not on first attempt — it degrades UX)
• Credential stuffing protection — check passwords against breach databases (HaveIBeenPwned API)
• IP blocking — block IPs with excessive failed attempts across multiple accounts

# Rate limiting configuration example (nginx)
http {
  limit_req_zone $binary_remote_addr zone=login:10m rate=5r/m;

  server {
    location /auth/login {
      limit_req zone=login burst=3 nodelay;
      limit_req_status 429;
      proxy_pass http://auth-backend;
    }
  }
}

• Use a centralized IdP — Okta, Microsoft Entra ID, Keycloak, Auth0. Never build your own auth system from scratch. Centralize all authentication through a single IdP with SSO.
• Enforce MFA for all users — at minimum TOTP, preferably WebAuthn/FIDO2/passkeys. Require phishing-resistant MFA for admin and privileged accounts.
• Use OIDC for authentication, OAuth 2.0 for authorization — do not use OAuth access tokens as proof of identity. Use OIDC ID tokens for authentication, access tokens for API authorization.
• Authorization Code flow + PKCE everywhere — never use the implicit grant. Use PKCE for all clients (public and confidential). Client credentials grant for machine-to-machine only.
• Short-lived access tokens (5-15 min) — pair with refresh token rotation. Detect refresh token reuse and invalidate the entire token family.
• Validate JWTs completely — check signature, alg, iss, aud, exp, nbf. Reject alg: none. Fetch signing keys from the JWKS endpoint. Cache keys but handle rotation.
• Store tokens securely — httpOnly + Secure + SameSite cookies for web apps. Never in localStorage. In-memory for SPAs with silent refresh.
• Include state and nonce — random state for CSRF protection in every OAuth flow. Random nonce in every OIDC request. Verify both on callback.
• Exact redirect URI matching — register all redirect URIs explicitly. No wildcards, no pattern matching. The authorization server must reject unrecognized redirect URIs.
• Encrypt all auth traffic — TLS 1.2+ everywhere (prefer TLS 1.3 for new deployments). LDAPS instead of plain LDAP. HSTS headers. Secure flag on all cookies.
• Implement rate limiting and account lockout — rate-limit login endpoints, use exponential backoff for lockouts, never reveal if a username exists.
• SAML: validate everything — check XML signatures on both response and assertion. Verify Destination, Audience, Recipient, InResponseTo, and time conditions. Defend against signature wrapping attacks.
• Audit all auth events — log every login, logout, MFA challenge, token issuance, and failed attempt. Include IP, user agent, and timestamp. Alert on anomalies (impossible travel, brute force).
• Plan for token revocation — implement a token blocklist or introspection endpoint for immediate access revocation. Short token lifetimes are your primary defense.
• Rotate secrets and certificates — rotate OIDC signing keys, SAML certificates, and client secrets on a schedule. Support key rollover (publish new key before retiring old one via JWKS).