1 of 68

Authority

Tutorials

How-To Guides

Reference

Social Login

API endpoints for social authentication (OAuth federation).

Endpoints Overview

Method

Endpoint

Description

GET

Supported Providers

Provider

Identifier

Start the OAuth flow with a social provider.

Path Parameters

Parameter

Type

Description

Query Parameters

Parameter

Type

Required

Description

Response

Redirects to the provider's authorization page.

Example

Errors

Status

Error

Description

OAuth Callback

Handles the callback from the social provider after user authorization.

Path Parameters

Parameter

Type

Description

Query Parameters

Parameter

Type

Description

Response

On success, redirects to:

The forward_url if provided during initiation
The default post-login page otherwise

Sets session cookie for authenticated user.

Errors

Status

Error

Description

Remove a linked social account from the authenticated user.

Path Parameters

Parameter

Type

Description

Authentication

Requires active session (session cookie).

Response

Success: 302 redirect to /profile with success flash message.

Error: 302 redirect to /profile with error flash message.

Errors

Status

Error

Description

Example

User Data from Providers

Each provider returns different user information.

Google

GitHub

Facebook

Apple

Apple only provides the user's name on the first authentication.

State Parameter

The state parameter provides CSRF protection:

Authority generates a random state value
State is stored server-side with expiration
State is included in the authorization URL
Provider returns the state in the callback

State tokens expire after 10 minutes.

Session Handling

After successful authentication:

User record created or updated
Social connection record created/updated
Session created for user
Session cookie set in response

Session cookie attributes:

HttpOnly: Yes
Secure: Yes (in production)
SameSite: Lax

Configuration Settings

Social login is configured via settings:

Setting

Description

Next Steps

- Setup guide
- Account linking
- All API endpoints

Rate Limits

Authority implements rate limiting to protect against abuse.

Default Limits

Endpoint

Limit

Window

/authorize

Response Headers

Rate limit information is included in response headers:

Header

Description

Rate Limit Exceeded

When rate limit is exceeded:

Rate Limit Types

Per IP Address

Default rate limiting is per IP address:

Per Client

Rate limit by OAuth client:

Per User

Rate limit by authenticated user:

Configuration

Environment Variables

Variable

Default

Description

Per-Endpoint Configuration

Whitelist

Exclude IPs from rate limiting:

Client-Specific Limits

Configure different limits per client:

Best Practices

Client Implementation

Check headers - Monitor X-RateLimit-Remaining
Implement backoff - Use exponential backoff on 429
Cache tokens - Reduce token requests

Handling Rate Limits

Monitoring

Monitor rate limit metrics:

Rate of 429 responses
Clients hitting limits frequently
Unusual traffic patterns

Redis-Based Rate Limiting

For distributed deployments, use Redis:

This ensures consistent rate limiting across multiple Authority instances.

Next Steps

- Endpoint reference
- Error handling
- Redis setup

Client Credentials

The client credentials grant is used for machine-to-machine authentication where no user is involved.

Overview

This flow is for server-side applications that need to access resources on their own behalf, not on behalf of a user.

Use Cases

Background jobs
Microservice communication
API integrations
Scheduled tasks

Flow Diagram

Token Request

POST /token

Headers

Header

Value

Parameters

Parameter

Required

Description

Example

Response

Client credentials grant does not return a refresh token since the client can always request a new token.

Authentication Methods

HTTP Basic Authentication (Recommended)

POST Body

Complete Examples

Node.js

Python

curl

Token Caching

Since client credentials tokens have no refresh token, cache them:

Scopes

Clients can only request scopes they're authorized for:

Security Considerations

Protect credentials - Store client secret securely
Use short token lifetimes - Minimize exposure window

Differences from Other Grants

Aspect

Client Credentials

Authorization Code

Next Steps

- Token renewal
- Response format
- Secret management

Device Flow

The device authorization flow enables OAuth on devices that have limited input capabilities, such as smart TVs, IoT devices, and CLIs.

Overview

This flow allows devices without a browser to authenticate users by directing them to complete authorization on a secondary device (phone or computer).

Use Cases

Smart TVs
Media consoles
Picture frames
Printers

Flow Diagram

Device Authorization Request

POST /device

Parameters

Parameter

Required

Description

Example

Response

Field

Description

Display to User

Show the user:

Or display a QR code linking to verification_uri_complete.

Token Polling

POST /token

Poll the token endpoint while waiting for user authorization.

Parameters

Parameter

Required

Description

Example

Responses

Authorization Pending:

Slow Down (polling too fast):

Success:

Access Denied:

Expired Token:

Complete Example

CLI Application (Node.js)

Python CLI

User Experience

The activation page shows:

After entering the code, users see the standard consent screen.

Security Considerations

Protect device_code - It's equivalent to an authorization code
Respect interval - Don't poll faster than specified

Next Steps

- Response format
- Token renewal
- Error handling

Explanation

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": "rate_limit_exceeded",
  "error_description": "Too many requests. Please retry after 60 seconds.",
  "retry_after": 60
}

# Token endpoint: 60 requests per minute
RATE_LIMIT_TOKEN_MAX=60
RATE_LIMIT_TOKEN_WINDOW=60

# Login endpoint: 10 requests per minute
RATE_LIMIT_LOGIN_MAX=10
RATE_LIMIT_LOGIN_WINDOW=60

# Password reset: 3 requests per hour
RATE_LIMIT_PASSWORD_RESET_MAX=3
RATE_LIMIT_PASSWORD_RESET_WINDOW=3600

async function makeRequest(url, options, retries = 3) {
  const response = await fetch(url, options);

  if (response.status === 429) {
    if (retries > 0) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      await sleep(retryAfter * 1000);
      return makeRequest(url, options, retries - 1);
    }
    throw new Error('Rate limit exceeded');
  }

  return response;
}

{
  "sub": "google-user-id",
  "email": "user@gmail.com",
  "email_verified": true,
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "picture": "https://lh3.googleusercontent.com/..."
}

{
  "sub": "linkedin-member-id",
  "email": "john@example.com",
  "email_verified": true,
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "picture": "https://media.licdn.com/..."
}

{
  "device_code": "e2623df1-8594-47b4-b528-41ed3daecc1a",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://auth.example.com/activate",
  "verification_uri_complete": "https://auth.example.com/activate?user_code=WDJB-MJHT",
  "expires_in": 300,
  "interval": 5
}

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code=e2623df1-8594-47b4-b528-41ed3daecc1a
&client_id=cli_client

const CLIENT_ID = 'cli_client';
const AUTHORITY_URL = 'https://auth.example.com';

async function login() {
  // Step 1: Get device code
  const deviceResponse = await fetch(`${AUTHORITY_URL}/device`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      client_id: CLIENT_ID,
      scope: 'openid profile email'
    })
  });

  const device = await deviceResponse.json();

  // Step 2: Display to user
  console.log('\nTo sign in, visit:');
  console.log(`  ${device.verification_uri}`);
  console.log('\nAnd enter the code:');
  console.log(`  ${device.user_code}`);
  console.log('\nWaiting for authorization...\n');

  // Step 3: Poll for token
  const interval = device.interval * 1000;
  const expiresAt = Date.now() + (device.expires_in * 1000);

  while (Date.now() < expiresAt) {
    await sleep(interval);

    const tokenResponse = await fetch(`${AUTHORITY_URL}/token`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
        device_code: device.device_code,
        client_id: CLIENT_ID
      })
    });

    const result = await tokenResponse.json();

    if (result.access_token) {
      console.log('Login successful!');
      return result;
    }

    if (result.error === 'authorization_pending') {
      process.stdout.write('.');
      continue;
    }

    if (result.error === 'slow_down') {
      await sleep(5000); // Additional delay
      continue;
    }

    throw new Error(result.error_description || result.error);
  }

  throw new Error('Device code expired');
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

// Run
login()
  .then(tokens => console.log('Access token:', tokens.access_token))
  .catch(err => console.error('Error:', err.message));

import requests
import time

CLIENT_ID = 'cli_client'
AUTHORITY_URL = 'https://auth.example.com'

def login():
    # Step 1: Get device code
    response = requests.post(
        f'{AUTHORITY_URL}/device',
        data={
            'client_id': CLIENT_ID,
            'scope': 'openid profile email'
        }
    )
    device = response.json()

    # Step 2: Display to user
    print(f"\nTo sign in, visit:\n  {device['verification_uri']}")
    print(f"\nAnd enter the code:\n  {device['user_code']}")
    print("\nWaiting for authorization...")

    # Step 3: Poll for token
    interval = device['interval']
    expires_at = time.time() + device['expires_in']

    while time.time() < expires_at:
        time.sleep(interval)

        response = requests.post(
            f'{AUTHORITY_URL}/token',
            data={
                'grant_type': 'urn:ietf:params:oauth:grant-type:device_code',
                'device_code': device['device_code'],
                'client_id': CLIENT_ID
            }
        )

        result = response.json()

        if 'access_token' in result:
            print("\nLogin successful!")
            return result

        if result.get('error') == 'authorization_pending':
            print('.', end='', flush=True)
            continue

        if result.get('error') == 'slow_down':
            time.sleep(5)
            continue

        raise Exception(result.get('error_description', result.get('error')))

    raise Exception('Device code expired')

if __name__ == '__main__':
    tokens = login()
    print(f"Access token: {tokens['access_token']}")

Enter the code displayed on your device:

┌─────────────────────────────────┐
│          WDJB-MJHT              │
└─────────────────────────────────┘

                [Continue]

const CLIENT_ID = 'your_client_id';
const CLIENT_SECRET = 'your_client_secret';
const AUTHORITY_URL = 'https://auth.example.com';

async function getAccessToken() {
  const credentials = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64');

  const response = await fetch(`${AUTHORITY_URL}/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${credentials}`
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      scope: 'read write'
    })
  });

  const data = await response.json();
  return data.access_token;
}

// Use the token
async function callApi() {
  const token = await getAccessToken();

  const response = await fetch('https://api.example.com/data', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });

  return response.json();
}

import requests
from requests.auth import HTTPBasicAuth

CLIENT_ID = 'your_client_id'
CLIENT_SECRET = 'your_client_secret'
AUTHORITY_URL = 'https://auth.example.com'

def get_access_token():
    response = requests.post(
        f'{AUTHORITY_URL}/token',
        data={
            'grant_type': 'client_credentials',
            'scope': 'read write'
        },
        auth=HTTPBasicAuth(CLIENT_ID, CLIENT_SECRET)
    )

    return response.json()['access_token']

# Use the token
def call_api():
    token = get_access_token()

    response = requests.get(
        'https://api.example.com/data',
        headers={'Authorization': f'Bearer {token}'}
    )

    return response.json()

# Get token
TOKEN=$(curl -s -X POST https://auth.example.com/token \
  -u "client_id:client_secret" \
  -d "grant_type=client_credentials" \
  -d "scope=read" \
  | jq -r '.access_token')

# Use token
curl https://api.example.com/data \
  -H "Authorization: Bearer $TOKEN"

class TokenCache {
  constructor() {
    this.token = null;
    this.expiresAt = null;
  }

  async getToken() {
    // Return cached token if still valid
    if (this.token && Date.now() < this.expiresAt - 60000) {
      return this.token;
    }

    // Get new token
    const response = await fetchToken();
    this.token = response.access_token;
    this.expiresAt = Date.now() + (response.expires_in * 1000);

    return this.token;
  }
}

const tokenCache = new TokenCache();

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
  "scope": "openid profile email",
  "id_token": "eyJhbGciOiJSUzI1NiIs..."
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImF1dGhvcml0eS1rZXktMSJ9.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyLXV1aWQiLCJhdWQiOiJhYmMxMjMiLCJleHAiOjE2OTk5OTk5OTksImlhdCI6MTY5OTk5NjM5OSwic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBlbWFpbCJ9.signature

const jwt = require('jsonwebtoken');
const jwksClient = require('jwks-rsa');

const client = jwksClient({
  jwksUri: 'https://auth.example.com/.well-known/jwks.json'
});

function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    callback(err, key?.getPublicKey());
  });
}

function validateToken(token) {
  return new Promise((resolve, reject) => {
    jwt.verify(token, getKey, {
      algorithms: ['RS256'],
      issuer: 'https://auth.example.com',
      audience: 'your_client_id'
    }, (err, decoded) => {
      if (err) reject(err);
      else resolve(decoded);
    });
  });
}

const jwt = require('jsonwebtoken');
const jwksClient = require('jwks-rsa');

const client = jwksClient({
  jwksUri: 'https://auth.example.com/.well-known/jwks.json',
  cache: true,
  cacheMaxAge: 600000, // 10 minutes
  rateLimit: true,
  jwksRequestsPerMinute: 10
});

function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    if (err) {
      callback(err);
      return;
    }
    callback(null, key.getPublicKey());
  });
}

function verifyToken(token) {
  return new Promise((resolve, reject) => {
    jwt.verify(token, getKey, {
      algorithms: ['RS256'],
      issuer: 'https://auth.example.com'
    }, (err, decoded) => {
      if (err) reject(err);
      else resolve(decoded);
    });
  });
}

import jwt
from jwt import PyJWKClient

jwks_client = PyJWKClient(
    "https://auth.example.com/.well-known/jwks.json"
)

def verify_token(token):
    signing_key = jwks_client.get_signing_key_from_jwt(token)

    return jwt.decode(
        token,
        signing_key.key,
        algorithms=["RS256"],
        issuer="https://auth.example.com",
        audience="your_client_id"
    )

import (
    "github.com/golang-jwt/jwt/v5"
    "github.com/MicahParks/keyfunc/v2"
)

func verifyToken(tokenString string) (*jwt.Token, error) {
    jwks, err := keyfunc.Get("https://auth.example.com/.well-known/jwks.json", keyfunc.Options{})
    if err != nil {
        return nil, err
    }

    return jwt.Parse(tokenString, jwks.Keyfunc, jwt.WithIssuer("https://auth.example.com"))
}

const jwksClient = require('jwks-rsa');

const client = jwksClient({
  jwksUri: 'https://auth.example.com/.well-known/jwks.json',
  cache: true,
  cacheMaxAge: 600000,  // 10 minutes
  timeout: 30000        // 30 seconds timeout
});

const crypto = require('crypto');

async function manualVerify(token) {
  const [headerB64, payloadB64, signatureB64] = token.split('.');

  // Decode header to get kid
  const header = JSON.parse(Buffer.from(headerB64, 'base64url'));

  // Fetch JWKS
  const response = await fetch('https://auth.example.com/.well-known/jwks.json');
  const jwks = await response.json();

  // Find matching key
  const jwk = jwks.keys.find(k => k.kid === header.kid);
  if (!jwk) throw new Error('Key not found');

  // Convert JWK to PEM
  const pem = jwkToPem(jwk);

  // Verify signature
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(`${headerB64}.${payloadB64}`);

  const signature = Buffer.from(signatureB64, 'base64url');
  const isValid = verifier.verify(pem, signature);

  if (!isValid) throw new Error('Invalid signature');

  return JSON.parse(Buffer.from(payloadB64, 'base64url'));
}

Security Model

Understanding Authority's security architecture and design principles.

Security Architecture

Defense in Depth

Authority implements multiple security layers:

Authentication Security

Password Security

Passwords are:

Hashed - Using bcrypt with cost factor 12
Salted - Unique salt per password
Validated - Against policy requirements

Multi-Factor Authentication

TOTP-based MFA provides:

Something you know - Password
Something you have - Authenticator app

MFA protects against:

Credential stuffing
Phishing
Password breaches

Account Lockout

Progressive lockout:

Protects against brute-force attacks while limiting denial-of-service impact.

Token Security

JWT Signing

Tokens are signed with RS256:

Private key - Signs tokens (server only)
Public key - Verifies tokens (anyone)
Key rotation - Periodic key changes

Token Lifetimes

Token

Lifetime

Purpose

Token Rotation

Refresh tokens rotate on use:

If a refresh token is stolen, the attacker races with the legitimate client.

Token Revocation

Tokens can be revoked:

User logout
Password change
Admin action
Security concern

Session Security

Session Binding

Sessions are bound to:

User agent
IP address (optional)
Expiration time

Session Limits

Absolute timeout - Maximum session lifetime
Idle timeout - Inactivity limit
Single session - One active session per user (optional)

OAuth Security

Redirect URI Validation

Exact match required
No wildcards
HTTPS in production
Pre-registered only

State Parameter

Prevents CSRF:

PKCE

Protects public clients:

Data Protection

Sensitive Data

Data

Storage

Access

Database Security

Connection encryption (SSL)
Prepared statements (SQL injection prevention)
Principle of least privilege

Audit and Compliance

Logged Events

Authentication attempts (success/failure)
Token operations (issue/revoke)
Admin actions
Configuration changes

Log Contents

Each log entry includes:

Timestamp
Actor (user/client/system)
Action
Resource

Retention

Default: 90 days
Configurable per compliance requirements
Export for external systems

Threat Mitigation

Threat

Mitigation

Best Practices

Deployment

Always use HTTPS - No exceptions
Use strong secrets - Cryptographically random
Enable MFA - At least for admins

Client Implementation

Validate tokens - Always verify signatures
Use PKCE - For all public clients
Store securely - No localStorage for sensitive tokens

Next Steps

- Token management details
- System design
- MFA setup guide

┌─────────────────────────────────────────┐
│        Network Security (HTTPS)          │
├─────────────────────────────────────────┤
│           Rate Limiting                  │
├─────────────────────────────────────────┤
│         Input Validation                 │
├─────────────────────────────────────────┤
│   Authentication (Password + MFA)        │
├─────────────────────────────────────────┤
│       Session Management                 │
├─────────────────────────────────────────┤
│     Authorization (Scopes)               │
├─────────────────────────────────────────┤
│         Audit Logging                    │
└─────────────────────────────────────────┘

Name: My Test App

Choosing Grant Types

A guide to selecting the right OAuth 2.0 grant type for your application.

Decision Flowchart

Quick Reference

Scenario

Grant Type

Security

Authorization Code

When to Use

Web applications with server-side code
You can securely store a client secret
Users need to authenticate

How It Works

The backend exchanges the code for tokens, keeping secrets secure.

Example Scenarios

Traditional web applications (Rails, Django, Express)
Server-rendered applications
Applications with session-based auth

Considerations

Requires backend infrastructure
Client secret must be protected
Full OAuth security guarantees

Authorization Code + PKCE

When to Use

Single-page applications (React, Vue, Angular)
Mobile applications (iOS, Android)
Desktop applications

How It Works

Example Scenarios

React/Vue/Angular SPAs
React Native / Flutter apps
Electron desktop apps
Browser extensions

Considerations

No client secret required
Proof of possession via PKCE
Recommended for all new public clients

Client Credentials

When to Use

Backend services calling APIs
Microservice communication
Scheduled jobs / cron tasks
No user context needed

How It Works

Example Scenarios

Payment processing service
Data synchronization jobs
Inter-service authentication
API integrations

Considerations

No user involved
No refresh tokens (just request new token)
Client must protect its credentials
Scopes limited to service-level access

Device Code

When to Use

Devices without browsers
Limited input capability
Smart TVs, game consoles
CLI applications

How It Works

Example Scenarios

Smart TV streaming apps
Game console apps
CLI tools (gh, aws-cli style)
IoT devices

Considerations

User must have secondary device
Requires polling mechanism
Codes expire (typically 5-15 minutes)

Password Grant (Legacy)

When to Use

Only for first-party, trusted applications where other grants are not feasible.

Migrating from legacy systems
Highly trusted first-party apps
When redirect flow is impossible

How It Works

Considerations

User enters password in your app
App sees user's credentials
No consent flow
MFA may be bypassed

Grant Type Comparison

Security

Grant

Secret Protection

Token Exposure

Phishing Risk

User Experience

Grant

User Steps

Complexity

Best For

Migration Paths

From Password to PKCE

Add PKCE support to your app
Implement authorization flow
Migrate users gradually
Disable password grant

From Implicit to PKCE

Add PKCE code exchange
Update authorization request (response_type=code)
Handle code callback

Common Mistakes

Using Implicit Grant

Don't: Use implicit for new applications Do: Use Authorization Code + PKCE

Password Grant for Third-Party Apps

Don't: Let third-party apps collect passwords Do: Use authorization flow with consent

No PKCE for Public Clients

Don't: Use auth code without PKCE in SPAs/mobile Do: Always use PKCE for public clients

Long-Lived Tokens Without Refresh

Don't: Issue 24-hour access tokens without refresh Do: Short access tokens + refresh tokens

Next Steps

- Protocol fundamentals
- Security considerations
- Implementation details

Client generates: code_verifier (random)
Client sends: code_challenge = SHA256(code_verifier)
Authority returns: authorization code
Client proves: code_verifier
Authority validates: SHA256(code_verifier) == code_challenge
Authority issues: tokens

Device → Authority: Request device code
Authority → Device: device_code + user_code + URL
Device → User: "Visit URL, enter code"
User → Browser → Authority: Enter code, authenticate
Device → Authority: Poll for token
Authority → Device: Access token

<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
  <style>
    .btn-google {
      display: inline-flex;
      align-items: center;
      padding: 12px 24px;
      background: #4285f4;
      color: white;
      border-radius: 4px;
      text-decoration: none;
      font-family: sans-serif;
      font-weight: 500;
    }
    .btn-google:hover {
      background: #357abd;
    }
    .btn-google svg {
      margin-right: 12px;
    }
  </style>
</head>
<body>
  <h1>Welcome to My App</h1>

  <a href="http://localhost:4000/auth/google" class="btn-google">
    <svg width="18" height="18" viewBox="0 0 18 18" fill="none">
      <path d="M17.64 9.2c0-.637-.057-1.251-.164-1.84H9v3.481h4.844c-.209 1.125-.843 2.078-1.796 2.717v2.258h2.908c1.702-1.567 2.684-3.874 2.684-6.615z" fill="#4285F4"/>
      <path d="M9.003 18c2.43 0 4.467-.806 5.956-2.18l-2.909-2.26c-.806.54-1.836.86-3.047.86-2.344 0-4.328-1.584-5.036-3.711H.957v2.332A8.997 8.997 0 009.003 18z" fill="#34A853"/>
      <path d="M3.964 10.712A5.41 5.41 0 013.682 9c0-.593.102-1.17.282-1.71V4.958H.957A8.996 8.996 0 000 9c0 1.452.348 2.827.957 4.042l3.007-2.33z" fill="#FBBC05"/>
      <path d="M9.003 3.58c1.321 0 2.508.454 3.44 1.345l2.582-2.58C13.464.891 11.428 0 9.002 0A8.997 8.997 0 00.957 4.958L3.964 7.29c.708-2.127 2.692-3.71 5.036-3.71z" fill="#EA4335"/>
    </svg>
    Sign in with Google
  </a>
</body>
</html>

// Encode your callback URL
const callbackUrl = 'http://localhost:3000/dashboard';
const encodedUrl = btoa(callbackUrl);

// Build the auth URL with forward_url
const authUrl = `http://localhost:4000/auth/google?forward_url=${encodedUrl}`;

// Use this URL for your button
document.querySelector('.btn-google').href = authUrl;

const params = new URLSearchParams({
  response_type: 'code',
  client_id: CLIENT_ID,
  redirect_uri: REDIRECT_URI,
  scope: 'openid profile email',  // OpenID Connect scopes
  state: state,
  code_challenge: codeChallenge,
  code_challenge_method: 'S256'
});

function parseIdToken(idToken) {
  const parts = idToken.split('.');
  const payload = JSON.parse(atob(parts[1]));
  return payload;
}

// Result:
// {
//   "iss": "http://localhost:4000",
//   "sub": "user-uuid",
//   "aud": "your_client_id",
//   "exp": 1699999999,
//   "iat": 1699996399,
//   "name": "John Doe",
//   "email": "john@example.com",
//   "email_verified": true
// }

async function validateIdToken(idToken) {
  const payload = parseIdToken(idToken);

  // 1. Verify issuer
  if (payload.iss !== AUTHORITY_URL) {
    throw new Error('Invalid issuer');
  }

  // 2. Verify audience
  if (payload.aud !== CLIENT_ID) {
    throw new Error('Invalid audience');
  }

  // 3. Verify expiration
  if (payload.exp < Date.now() / 1000) {
    throw new Error('Token expired');
  }

  // 4. Verify signature (use JWKS)
  await verifySignature(idToken);

  return payload;
}

async function getUserInfo(accessToken) {
  const response = await fetch(`${AUTHORITY_URL}/userinfo`, {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });

  if (!response.ok) {
    throw new Error('Failed to fetch user info');
  }

  return response.json();
}

// Result:
// {
//   "sub": "user-uuid",
//   "name": "John Doe",
//   "given_name": "John",
//   "family_name": "Doe",
//   "email": "john@example.com",
//   "email_verified": true,
//   "picture": "https://..."
// }

class AuthSession {
  constructor() {
    this.tokens = null;
    this.user = null;
  }

  login(tokens, user) {
    this.tokens = tokens;
    this.user = user;

    // Store refresh token securely (httpOnly cookie recommended)
    localStorage.setItem('auth_session', JSON.stringify({
      accessToken: tokens.access_token,
      expiresAt: Date.now() + (tokens.expires_in * 1000),
      user: user
    }));
  }

  getAccessToken() {
    const session = JSON.parse(localStorage.getItem('auth_session'));
    if (!session) return null;

    if (Date.now() > session.expiresAt) {
      // Token expired - need to refresh
      return null;
    }

    return session.accessToken;
  }

  getUser() {
    const session = JSON.parse(localStorage.getItem('auth_session'));
    return session?.user;
  }

  logout() {
    localStorage.removeItem('auth_session');
    this.tokens = null;
    this.user = null;
  }
}

const auth = new AuthSession();

<div id="profile" style="display: none;">
  <img id="avatar" src="" alt="Profile picture">
  <h2 id="name"></h2>
  <p id="email"></p>
  <button id="logout">Logout</button>
</div>

<script>
function showProfile(user) {
  document.getElementById('profile').style.display = 'block';
  document.getElementById('avatar').src = user.picture || '/default-avatar.png';
  document.getElementById('name').textContent = user.name;
  document.getElementById('email').textContent = user.email;
}

document.getElementById('logout').onclick = () => {
  auth.logout();
  window.location.href = '/';
};
</script>

function logoutWithRedirect() {
  auth.logout();

  const params = new URLSearchParams({
    post_logout_redirect_uri: 'http://localhost:3000',
    client_id: CLIENT_ID
  });

  window.location.href = `${AUTHORITY_URL}/logout?${params}`;
}

class AuthClient {
  constructor(config) {
    this.clientId = config.clientId;
    this.redirectUri = config.redirectUri;
    this.authorityUrl = config.authorityUrl;
    this.session = new AuthSession();
  }

  async login() {
    const codeVerifier = this.generateCodeVerifier();
    const codeChallenge = await this.generateCodeChallenge(codeVerifier);
    const state = this.generateCodeVerifier();

    sessionStorage.setItem('pkce_verifier', codeVerifier);
    sessionStorage.setItem('oauth_state', state);

    const params = new URLSearchParams({
      response_type: 'code',
      client_id: this.clientId,
      redirect_uri: this.redirectUri,
      scope: 'openid profile email',
      state: state,
      code_challenge: codeChallenge,
      code_challenge_method: 'S256'
    });

    window.location.href = `${this.authorityUrl}/authorize?${params}`;
  }

  async handleCallback() {
    const params = new URLSearchParams(window.location.search);
    const code = params.get('code');
    const state = params.get('state');

    if (state !== sessionStorage.getItem('oauth_state')) {
      throw new Error('Invalid state');
    }

    const codeVerifier = sessionStorage.getItem('pkce_verifier');
    const tokens = await this.exchangeCode(code, codeVerifier);
    const user = await this.getUserInfo(tokens.access_token);

    this.session.login(tokens, user);

    // Clean up
    sessionStorage.removeItem('pkce_verifier');
    sessionStorage.removeItem('oauth_state');
    window.history.replaceState({}, '', window.location.pathname);

    return user;
  }

  async exchangeCode(code, codeVerifier) {
    const response = await fetch(`${this.authorityUrl}/token`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'authorization_code',
        code: code,
        redirect_uri: this.redirectUri,
        client_id: this.clientId,
        code_verifier: codeVerifier
      })
    });
    return response.json();
  }

  async getUserInfo(accessToken) {
    const response = await fetch(`${this.authorityUrl}/userinfo`, {
      headers: { 'Authorization': `Bearer ${accessToken}` }
    });
    return response.json();
  }

  logout() {
    this.session.logout();
  }

  isAuthenticated() {
    return this.session.getAccessToken() !== null;
  }

  getUser() {
    return this.session.getUser();
  }

  // PKCE helpers
  generateCodeVerifier() {
    const array = new Uint8Array(32);
    crypto.getRandomValues(array);
    return this.base64URLEncode(array);
  }

  async generateCodeChallenge(verifier) {
    const data = new TextEncoder().encode(verifier);
    const hash = await crypto.subtle.digest('SHA-256', data);
    return this.base64URLEncode(new Uint8Array(hash));
  }

  base64URLEncode(buffer) {
    return btoa(String.fromCharCode(...buffer))
      .replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
  }
}

// Usage
const auth = new AuthClient({
  clientId: 'your_client_id',
  redirectUri: 'http://localhost:3000/callback',
  authorityUrl: 'http://localhost:4000'
});

if (window.location.search.includes('code=')) {
  auth.handleCallback().then(user => {
    console.log('Logged in as:', user.name);
  });
}

const jwt = require('jsonwebtoken');
const jwksClient = require('jwks-rsa');

const client = jwksClient({
  jwksUri: 'http://localhost:4000/.well-known/jwks.json',
  cache: true,
  rateLimit: true
});

function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    callback(err, key?.getPublicKey());
  });
}

async function validateToken(token) {
  return new Promise((resolve, reject) => {
    jwt.verify(token, getKey, {
      algorithms: ['RS256'],
      issuer: 'http://localhost:4000'
    }, (err, decoded) => {
      if (err) reject(err);
      else resolve(decoded);
    });
  });
}

import jwt
import requests
from jwt import PyJWKClient

jwks_client = PyJWKClient("http://localhost:4000/.well-known/jwks.json")

def validate_token(token):
    signing_key = jwks_client.get_signing_key_from_jwt(token)
    return jwt.decode(
        token,
        signing_key.key,
        algorithms=["RS256"],
        issuer="http://localhost:4000"
    )

async function authMiddleware(req, res, next) {
  const authHeader = req.headers.authorization;

  if (!authHeader?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing token' });
  }

  const token = authHeader.substring(7);

  try {
    const decoded = await validateToken(token);
    req.user = decoded;
    next();
  } catch (err) {
    return res.status(401).json({ error: 'Invalid token' });
  }
}

// Use it
app.get('/api/protected', authMiddleware, (req, res) => {
  res.json({ message: `Hello, ${req.user.sub}` });
});

async function introspectToken(token) {
  const credentials = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64');

  const response = await fetch('http://localhost:4000/token/introspect', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${credentials}`
    },
    body: new URLSearchParams({
      token: token,
      token_type_hint: 'access_token'
    })
  });

  return response.json();
}

function requireScopes(...requiredScopes) {
  return async (req, res, next) => {
    const token = req.headers.authorization?.substring(7);

    if (!token) {
      return res.status(401).json({ error: 'Missing token' });
    }

    try {
      const decoded = await validateToken(token);
      const tokenScopes = decoded.scope?.split(' ') || [];

      const hasAllScopes = requiredScopes.every(
        scope => tokenScopes.includes(scope)
      );

      if (!hasAllScopes) {
        return res.status(403).json({
          error: 'Insufficient scope',
          required: requiredScopes,
          provided: tokenScopes
        });
      }

      req.user = decoded;
      next();
    } catch (err) {
      return res.status(401).json({ error: 'Invalid token' });
    }
  };
}

// Use it
app.get('/api/data', requireScopes('read'), (req, res) => {
  res.json({ data: '...' });
});

app.post('/api/data', requireScopes('write'), (req, res) => {
  res.json({ created: true });
});

app.delete('/api/users/:id', requireScopes('admin'), (req, res) => {
  res.json({ deleted: true });
});

function scheduleTokenRefresh(tokens) {
  const expiresIn = tokens.expires_in * 1000; // Convert to ms
  const refreshAt = expiresIn - 60000; // Refresh 1 minute early

  setTimeout(async () => {
    const newTokens = await refreshAccessToken(tokens.refresh_token);
    scheduleTokenRefresh(newTokens);
  }, refreshAt);
}

app.use((err, req, res, next) => {
  if (err.name === 'TokenExpiredError') {
    return res.status(401).json({
      error: 'token_expired',
      message: 'Access token has expired'
    });
  }
  next(err);
});

# Server
CRYSTAL_ENV=production
PORT=4000
BASE_URL=https://auth.example.com

# Database
DATABASE_URL=postgres://auth_user:secure_password@db:5432/authority_db

# Security
SECRET_KEY=your-256-bit-secret-key-here

# Token Lifetimes (seconds)
ACCESS_TOKEN_TTL=3600
CODE_TTL=600
DEVICE_CODE_TTL=300

# SSL (optional - use reverse proxy recommended)
SSL_CERT=
SSL_KEY=

version: '3.8'

services:
  authority:
    image: azutoolkit/authority:latest
    ports:
      - "4000:4000"
    environment:
      - CRYSTAL_ENV=production
      - DATABASE_URL=postgres://auth_user:${DB_PASSWORD}@db:5432/authority_db
      - SECRET_KEY=${SECRET_KEY}
      - BASE_URL=${BASE_URL}
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=auth_user
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=authority_db
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U auth_user -d authority_db"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:

server {
    listen 443 ssl http2;
    server_name auth.example.com;

    ssl_certificate /etc/letsencrypt/live/auth.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/auth.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:4000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name auth.example.com;
    return 301 https://$server_name$request_uri;
}

# docker-compose.yml addition
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.authority.rule=Host(`auth.example.com`)"
  - "traefik.http.routers.authority.tls=true"
  - "traefik.http.routers.authority.tls.certresolver=letsencrypt"

# Create database
psql -c "CREATE DATABASE authority_db;"

# Create user (optional)
psql -c "CREATE USER authority WITH PASSWORD 'secure_password';"
psql -c "GRANT ALL PRIVILEGES ON DATABASE authority_db TO authority;"

# Basic format
DATABASE_URL=postgres://user:password@host:port/database

# Examples
DATABASE_URL=postgres://localhost:5432/authority_db
DATABASE_URL=postgres://authority:password@localhost:5432/authority_db

# pgbouncer.ini
[databases]
authority_db = host=localhost port=5432 dbname=authority_db

[pgbouncer]
listen_addr = 127.0.0.1
listen_port = 6432
pool_mode = transaction
max_client_conn = 200
default_pool_size = 20

# postgresql.conf

# Memory
shared_buffers = 256MB
effective_cache_size = 768MB
work_mem = 16MB

# Connections
max_connections = 100

# Write-ahead log
wal_buffers = 16MB
checkpoint_completion_target = 0.9

# Generate secret key
kubectl create secret generic authority-secrets \
  --namespace authority \
  --from-literal=secret-key=$(openssl rand -hex 32) \
  --from-literal=db-password=$(openssl rand -hex 16)

# postgres.yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
  namespace: authority
spec:
  serviceName: postgres
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
      - name: postgres
        image: postgres:15-alpine
        ports:
        - containerPort: 5432
        env:
        - name: POSTGRES_USER
          value: authority
        - name: POSTGRES_DB
          value: authority_db
        - name: POSTGRES_PASSWORD
          valueFrom:
            secretKeyRef:
              name: authority-secrets
              key: db-password
        volumeMounts:
        - name: postgres-data
          mountPath: /var/lib/postgresql/data
        livenessProbe:
          exec:
            command: ["pg_isready", "-U", "authority"]
          initialDelaySeconds: 30
          periodSeconds: 10
  volumeClaimTemplates:
  - metadata:
      name: postgres-data
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 10Gi
---
apiVersion: v1
kind: Service
metadata:
  name: postgres
  namespace: authority
spec:
  ports:
  - port: 5432
  selector:
    app: postgres
  clusterIP: None

# authority.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: authority
  namespace: authority
spec:
  replicas: 3
  selector:
    matchLabels:
      app: authority
  template:
    metadata:
      labels:
        app: authority
    spec:
      containers:
      - name: authority
        image: azutoolkit/authority:latest
        ports:
        - containerPort: 4000
        env:
        - name: CRYSTAL_ENV
          value: production
        - name: PORT
          value: "4000"
        - name: BASE_URL
          value: "https://auth.example.com"
        - name: SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: authority-secrets
              key: secret-key
        - name: DATABASE_URL
          value: "postgres://authority:$(DB_PASSWORD)@postgres:5432/authority_db"
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: authority-secrets
              key: db-password
        livenessProbe:
          httpGet:
            path: /health
            port: 4000
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /health
            port: 4000
          initialDelaySeconds: 5
          periodSeconds: 10
        resources:
          requests:
            memory: "256Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "500m"
---
apiVersion: v1
kind: Service
metadata:
  name: authority
  namespace: authority
spec:
  ports:
  - port: 80
    targetPort: 4000
  selector:
    app: authority

# ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: authority
  namespace: authority
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
  - hosts:
    - auth.example.com
    secretName: authority-tls
  rules:
  - host: auth.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: authority
            port:
              number: 80

helm install authority authority/authority \
  --namespace authority \
  --create-namespace \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=auth.example.com \
  --set postgresql.enabled=true

replicaCount: 3

image:
  repository: azutoolkit/authority
  tag: latest

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: auth.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: authority-tls
      hosts:
        - auth.example.com

postgresql:
  enabled: true
  auth:
    database: authority_db
    username: authority
  primary:
    persistence:
      size: 10Gi

redis:
  enabled: true

resources:
  requests:
    memory: 256Mi
    cpu: 100m
  limits:
    memory: 512Mi
    cpu: 500m

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: authority
  namespace: authority
spec:
  selector:
    matchLabels:
      app: authority
  endpoints:
  - port: http
    path: /metrics

# Local development
DATABASE_URL=postgres://localhost:5432/authority_db

# With credentials
DATABASE_URL=postgres://user:password@localhost:5432/authority_db

# With SSL
DATABASE_URL=postgres://user:password@host:5432/authority_db?sslmode=require

# .env.local
CRYSTAL_ENV=development
PORT=4000
BASE_URL=http://localhost:4000
DATABASE_URL=postgres://localhost:5432/authority_db
SECRET_KEY=development-key-not-for-production
CRYSTAL_LOG_LEVEL=debug

# .env
CRYSTAL_ENV=production
PORT=4000
HOST=0.0.0.0
BASE_URL=https://auth.example.com
DATABASE_URL=postgres://user:password@db.example.com:5432/authority_db?sslmode=require
SECRET_KEY=your-256-bit-production-secret-key
ACCESS_TOKEN_TTL=3600
SESSION_DURATION_DAYS=7
CRYSTAL_LOG_LEVEL=info
CRYSTAL_WORKERS=8

# Server
CRYSTAL_ENV=development
PORT=4000
BASE_URL=http://localhost:4000

# Database
DATABASE_URL=postgres://localhost:5432/authority_db

# Security
SECRET_KEY=development-secret-key-change-in-production

# Token Lifetimes
ACCESS_TOKEN_TTL=3600
CODE_TTL=600

authority/
├── src/
│   ├── app.cr              # Application entry point
│   ├── db/
│   │   ├── migrate.cr      # Migration runner
│   │   ├── seed.cr         # Seed data
│   │   └── migrations/     # Migration files
│   ├── endpoints/          # HTTP handlers
│   ├── models/             # Data models
│   ├── services/           # Business logic
│   └── views/              # Response serializers
├── public/
│   ├── templates/          # Jinja templates
│   ├── css/                # Stylesheets
│   └── js/                 # JavaScript
├── spec/                   # Tests
├── shard.yml               # Dependencies
└── .env.example            # Environment template

server {
    listen 443 ssl http2;
    server_name auth.example.com;

    ssl_certificate /etc/letsencrypt/live/auth.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/auth.example.com/privkey.pem;

    # SSL settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # HSTS
    add_header Strict-Transport-Security "max-age=63072000" always;

    location / {
        proxy_pass http://127.0.0.1:4000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name auth.example.com;
    return 301 https://$server_name$request_uri;
}

# traefik.yml
entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
  websecure:
    address: ":443"

certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@example.com
      storage: /letsencrypt/acme.json
      httpChallenge:
        entryPoint: web

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.authority.rule=Host(`auth.example.com`)"
  - "traefik.http.routers.authority.entrypoints=websecure"
  - "traefik.http.routers.authority.tls.certresolver=letsencrypt"

# Security headers
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'" always;

Security

Set up TOTP-based two-factor authentication for Authority users.

Overview

Authority supports Time-based One-Time Passwords (TOTP) for MFA. Users can use apps like:

Google Authenticator
Authy
1Password
Microsoft Authenticator

MFA Flow

User Setup

Step 1: Navigate to Profile

Log in to Authority
Click your profile name
Select Security Settings

Step 2: Enable MFA

Click Enable Two-Factor Authentication
Authority displays a QR code

Step 3: Scan QR Code

Open your authenticator app
Tap Add Account or +
Scan the QR code

Step 4: Verify Setup

Enter the 6-digit code from your app
Click Verify
Save your backup codes in a secure location

Backup Codes

When MFA is enabled, Authority generates 10 one-time backup codes. Store these securely - they can be used if you lose access to your authenticator app.

Example backup codes:

Each code can only be used once.

Admin Configuration

Require MFA for Admins

Enforce MFA for all administrator accounts:

Require MFA for All Users

Force MFA enrollment for all users:

MFA Grace Period

Allow users time to set up MFA:

Disabling MFA

User Self-Service

Users can disable MFA from their profile if allowed:

Navigate to Security Settings
Click Disable Two-Factor Authentication
Enter current TOTP code to confirm

Admin Override

Administrators can disable MFA for users:

Go to Admin Dashboard → Users
Select the user
Click Disable MFA

This is useful when a user loses access to their authenticator.

API Integration

Check MFA Status

Response:

Require MFA in Authorization

During OAuth authorization, check if MFA is required:

Recovery

Lost Authenticator

If a user loses their phone:

Use a backup code to log in
Disable MFA
Set up MFA again with new device

Lost Backup Codes

If a user loses both authenticator and backup codes:

Admin disables MFA for the user
User logs in with password only
User sets up MFA again
User saves new backup codes

Security Considerations

Backup codes should be stored securely (password manager, safe)
Regenerate backup codes periodically

Troubleshooting

Invalid TOTP Code

Verify device time is synchronized
Ensure you're using the correct account in the authenticator
Wait for the next code cycle (30 seconds)

QR Code Won't Scan

Use the manual entry option
Enter the secret key directly into your authenticator

Locked Out

Use a backup code
Contact administrator to disable MFA

Next Steps

- Brute-force protection
- Password requirements
- Track security events

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T10:30:00Z",
  "event": "user.login",
  "actor_id": "user-uuid",
  "actor_type": "user",
  "resource_type": "session",
  "resource_id": "session-uuid",
  "ip_address": "192.168.1.100",
  "user_agent": "Mozilla/5.0...",
  "metadata": {
    "method": "password",
    "mfa_used": true
  }
}

# Splunk
AUDIT_LOG_SPLUNK_URL=https://splunk.example.com:8088
AUDIT_LOG_SPLUNK_TOKEN=your-hec-token

# Elasticsearch
AUDIT_LOG_ELASTICSEARCH_URL=https://elasticsearch.example.com:9200
AUDIT_LOG_ELASTICSEARCH_INDEX=authority-audit

# Alert after 10 failed logins in 5 minutes
grep "user.login_failed" /var/log/authority/audit.log | \
  awk -v d="$(date -d '5 minutes ago' +%Y-%m-%dT%H:%M)" '$2 > d' | \
  wc -l | \
  xargs -I {} sh -c '[ {} -gt 10 ] && echo "Alert: High failed logins"'

function generatePassword(length = 16) {
  const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%^&*';
  let password = '';
  for (let i = 0; i < length; i++) {
    password += chars.charAt(Math.floor(Math.random() * chars.length));
  }
  return password;
}

// Generate random code verifier
function generateCodeVerifier() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return base64URLEncode(array);
}

// Create code challenge from verifier
async function generateCodeChallenge(verifier) {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const hash = await crypto.subtle.digest('SHA-256', data);
  return base64URLEncode(new Uint8Array(hash));
}

function base64URLEncode(buffer) {
  return btoa(String.fromCharCode(...buffer))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}

const CLIENT_ID = 'your_client_id';
const REDIRECT_URI = 'http://localhost:3000/callback';
const AUTHORITY_URL = 'http://localhost:4000';

async function login() {
  const codeVerifier = generateCodeVerifier();
  const codeChallenge = await generateCodeChallenge(codeVerifier);
  const state = generateCodeVerifier(); // Random state for CSRF protection

  // Store for later
  sessionStorage.setItem('code_verifier', codeVerifier);
  sessionStorage.setItem('state', state);

  const params = new URLSearchParams({
    response_type: 'code',
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    scope: 'openid profile email',
    state: state,
    code_challenge: codeChallenge,
    code_challenge_method: 'S256'
  });

  window.location.href = `${AUTHORITY_URL}/authorize?${params}`;
}

// On your callback page
async function handleCallback() {
  const params = new URLSearchParams(window.location.search);
  const code = params.get('code');
  const state = params.get('state');

  // Verify state matches
  if (state !== sessionStorage.getItem('state')) {
    throw new Error('Invalid state parameter');
  }

  // Get stored code verifier
  const codeVerifier = sessionStorage.getItem('code_verifier');

  // Exchange code for tokens
  const tokens = await exchangeCode(code, codeVerifier);
  console.log('Access token:', tokens.access_token);
}

async function exchangeCode(code, codeVerifier) {
  const response = await fetch(`${AUTHORITY_URL}/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: code,
      redirect_uri: REDIRECT_URI,
      client_id: CLIENT_ID,
      code_verifier: codeVerifier
    })
  });

  if (!response.ok) {
    throw new Error('Token exchange failed');
  }

  return response.json();
}

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "scope": "openid profile email"
}

async function fetchUserInfo(accessToken) {
  const response = await fetch(`${AUTHORITY_URL}/userinfo`, {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });

  return response.json();
}

// Result:
// {
//   "sub": "user-uuid",
//   "name": "John Doe",
//   "email": "john@example.com"
// }

<!DOCTYPE html>
<html>
<head>
  <title>OAuth Demo</title>
</head>
<body>
  <button id="login">Login with Authority</button>
  <div id="user"></div>

  <script>
    const CLIENT_ID = 'your_client_id';
    const REDIRECT_URI = 'http://localhost:3000/callback';
    const AUTHORITY_URL = 'http://localhost:4000';

    // Check if this is a callback
    if (window.location.search.includes('code=')) {
      handleCallback();
    }

    document.getElementById('login').onclick = login;

    async function login() {
      const codeVerifier = generateCodeVerifier();
      const codeChallenge = await generateCodeChallenge(codeVerifier);
      const state = generateCodeVerifier();

      sessionStorage.setItem('code_verifier', codeVerifier);
      sessionStorage.setItem('state', state);

      const params = new URLSearchParams({
        response_type: 'code',
        client_id: CLIENT_ID,
        redirect_uri: REDIRECT_URI,
        scope: 'openid profile email',
        state: state,
        code_challenge: codeChallenge,
        code_challenge_method: 'S256'
      });

      window.location.href = `${AUTHORITY_URL}/authorize?${params}`;
    }

    async function handleCallback() {
      const params = new URLSearchParams(window.location.search);
      const code = params.get('code');
      const state = params.get('state');

      if (state !== sessionStorage.getItem('state')) {
        alert('Invalid state');
        return;
      }

      const codeVerifier = sessionStorage.getItem('code_verifier');

      const tokenResponse = await fetch(`${AUTHORITY_URL}/token`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({
          grant_type: 'authorization_code',
          code: code,
          redirect_uri: REDIRECT_URI,
          client_id: CLIENT_ID,
          code_verifier: codeVerifier
        })
      });

      const tokens = await tokenResponse.json();

      const userResponse = await fetch(`${AUTHORITY_URL}/userinfo`, {
        headers: { 'Authorization': `Bearer ${tokens.access_token}` }
      });

      const user = await userResponse.json();
      document.getElementById('user').textContent = `Welcome, ${user.name}!`;
    }

    function generateCodeVerifier() {
      const array = new Uint8Array(32);
      crypto.getRandomValues(array);
      return base64URLEncode(array);
    }

    async function generateCodeChallenge(verifier) {
      const data = new TextEncoder().encode(verifier);
      const hash = await crypto.subtle.digest('SHA-256', data);
      return base64URLEncode(new Uint8Array(hash));
    }

    function base64URLEncode(buffer) {
      return btoa(String.fromCharCode(...buffer))
        .replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
    }
  </script>
</body>
</html>

# redis.conf

# Memory
maxmemory 256mb
maxmemory-policy allkeys-lru

# Persistence
save 900 1
save 300 10
save 60 10000

# Security
requirepass your_redis_password
bind 127.0.0.1

# Performance
tcp-keepalive 300

version: '3.8'

services:
  authority:
    image: azutoolkit/authority
    environment:
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_data:/data
    restart: unless-stopped

volumes:
  redis_data:

API

Complete reference for all Authority API endpoints.

OAuth 2.0 Endpoints

Authorization Endpoint

GET /authorize

Initiates the OAuth 2.0 authorization flow. Displays consent form to user.

Query Parameters:

Parameter

Required

Description

Example:

Response: Redirects to login page, then to redirect_uri with code and state parameters.

Error Response: Redirects to redirect_uri with error, error_description, and state parameters.

POST /authorize

Process user consent for authorization request.

Request Body (Form-encoded):

Parameter

Required

Description

Response: 302 redirect to redirect_uri?code=<code>&state=<state>

Token Endpoint

POST /token

Exchange authorization code, refresh token, or client credentials for access tokens.

Headers:

Header

Description

Request Body (Authorization Code):

Parameter

Required

Description

Request Body (Refresh Token):

Parameter

Required

Description

Request Body (Client Credentials):

Parameter

Required

Description

Request Body (Password Grant - Legacy):

Parameter

Required

Description

Response: 201 Created

Token Introspection

POST /oauth/introspect

Validate a token and get its metadata (RFC 7662).

Headers:

Header

Description

Request Body:

Parameter

Required

Description

Response (Active Token): 200 OK

Response (Inactive Token):

Token Revocation

POST /oauth/revoke

Revoke an access or refresh token (RFC 7009).

Headers:

Header

Description

Request Body:

Parameter

Required

Description

Response: 200 OK (always succeeds per RFC 7009)

Device Authorization

POST /device/code

Start device authorization flow (RFC 8628).

Headers:

Header

Description

Request Body:

Parameter

Required

Description

Response: 201 Created

Device Token Polling

POST /device/token

Poll for device authorization completion.

Request Body:

Parameter

Required

Description

Response (Pending): 400 Bad Request

Response (Success): 201 Created

Device Activation

GET /activate

Display device activation form for user to enter code.

Query Parameters:

Parameter

Required

Description

Response: HTML form for user to enter device code.

POST /activate

Process device activation.

Request Body:

Parameter

Required

Description

Response: HTML confirmation page.

OpenID Connect Endpoints

UserInfo

GET /oauth2/userinfo

Get authenticated user's claims.

Headers:

Header

Description

Response: 200 OK

Discovery

GET /.well-known/openid-configuration

OpenID Connect discovery document.

Response: 200 OK

Caching: public, max-age=3600

JWKS

GET /.well-known/jwks.json

JSON Web Key Set for token verification.

Response: 200 OK

Caching: public, max-age=3600

Dynamic Client Registration

Register Client

POST /register

Dynamically register an OAuth client (RFC 7591).

Request Body:

Response: 201 Created

Validation:

redirect_uris must use HTTPS (except localhost for development)
redirect_uris must not contain URL fragments

Authentication Endpoints

GET /signin

Display sign-in form.

Query Parameters:

Parameter

Required

Description

Response: HTML sign-in form

POST /signin

Authenticate user.

Request Body (Form-encoded):

Parameter

Required

Description

Response (Success): 302 redirect to profile or forward_url

Response (MFA Required): 302 redirect to /mfa/verify

Response (Account Locked): 423 Locked with Retry-After header

Response (Invalid Credentials): 401 Unauthorized

Sign Out

POST /signout

End user session.

Response: 302 redirect to sign-in page

Account Endpoints

Forgot Password

GET /forgot-password

Display forgot password form.

POST /forgot-password

Request password reset email.

Request Body (Form-encoded):

Parameter

Required

Description

Response: Always shows success (prevents email enumeration)

Password Reset

POST /account/password/reset

Request password reset token.

Request Body:

Parameter

Required

Description

Response: 200 OK (always, to prevent enumeration)

POST /account/password/confirm

Complete password reset.

Request Body:

Parameter

Required

Description

Response (Success): 200 OK

Response (Error): 400 Bad Request

Email Verification

POST /account/email/verify

Verify email address.

Request Body:

Parameter

Required

Description

Response: 200 OK or 400 Bad Request

POST /account/email/resend

Resend verification email.

Request Body:

Parameter

Required

Description

Response: 200 OK

MFA Endpoints

MFA Setup

GET /mfa/setup

Display MFA setup with QR code.

Response: HTML page with:

QR code for authenticator app
Secret key (manual entry)
Backup codes

Authentication Required: Yes (session)

Enable MFA

POST /mfa/enable

Enable MFA for account.

Request Body:

Parameter

Required

Description

Response: 302 redirect

Authentication Required: Yes (session)

Verify MFA

POST /mfa/verify

Verify MFA code during login.

Request Body:

Parameter

Required

Description

Response: 302 redirect to profile

Disable MFA

POST /mfa/disable

Disable MFA for account.

Request Body:

Parameter

Required

Description

Response: 302 redirect

Authentication Required: Yes (session)

User Profile

View Profile

GET /profile

Display user profile page.

Response: HTML profile page with:

User details
Email verification status
MFA status
Connected social accounts

Authentication Required: Yes (session)

Health Check

GET /health_check

Check server health.

Response: 200 OK

See for social authentication endpoints.

Next Steps

- Social authentication endpoints
- Error response reference
- Rate limiting details

// After successful password authentication
if (user.mfa_enabled) {
  // Show TOTP input form
  showMFAPrompt();
} else if (settings.require_mfa) {
  // Redirect to MFA setup
  redirectToMFASetup();
}

// Fetch user's linked providers
const response = await fetch('https://your-authority-domain/userinfo', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const userInfo = await response.json();
// Check for linked providers in user profile

<div class="linked-accounts">
  <h3>Linked Accounts</h3>

  <div class="provider">
    <span class="icon">🔵</span>
    <span class="name">Google</span>
    <span class="email">user@gmail.com</span>
    <button onclick="unlinkProvider('google')">Disconnect</button>
  </div>

  <div class="provider">
    <span class="icon">⚫</span>
    <span class="name">GitHub</span>
    <span class="status">Not connected</span>
    <a href="/auth/github?link=true">Connect</a>
  </div>
</div>

async function unlinkProvider(provider) {
  if (!confirm(`Disconnect ${provider}?`)) return;

  try {
    const response = await fetch(`/auth/${provider}/unlink`, {
      method: 'POST',
      credentials: 'include'
    });

    const result = await response.json();

    if (result.success) {
      // Refresh UI
      location.reload();
    } else {
      alert(result.message);
    }
  } catch (error) {
    alert('Failed to unlink account');
  }
}

{
  "event": "social_account_linked",
  "user_id": "user-uuid",
  "provider": "google",
  "provider_user_id": "google-user-id",
  "timestamp": "2024-01-15T10:30:00Z"
}

{
  "event": "social_account_unlinked",
  "user_id": "user-uuid",
  "provider": "github",
  "timestamp": "2024-01-15T11:45:00Z"
}

POST /api/users
Content-Type: application/json
Authorization: Bearer {admin_token}

{
  "email": "newadmin@example.com",
  "name": "New Admin",
  "password": "SecurePassword123",
  "role": "admin"
}

APPLE_OAUTH_ENABLED=true
APPLE_CLIENT_ID=com.yourcompany.yourapp.auth
APPLE_TEAM_ID=XXXXXXXXXX
APPLE_KEY_ID=XXXXXXXXXX
APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIGTAgEA...
-----END PRIVATE KEY-----"

Return URLs: https://your-authority-domain/auth/apple/callback

# Example: Update Kubernetes secret
kubectl create secret generic oauth-secret \
  --from-literal=client-secret=NEW_SECRET \
  --dry-run=client -o yaml | kubectl apply -f -

# Rolling restart
kubectl rollout restart deployment/my-app

#!/bin/bash
# rotate-secrets.sh

CLIENT_ID="abc123def456"
ADMIN_TOKEN="your_admin_token"
AUTHORITY_URL="https://auth.example.com"

# Rotate secret
NEW_SECRET=$(curl -s -X POST \
  "${AUTHORITY_URL}/register/${CLIENT_ID}/renew_secret" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  | jq -r '.client_secret')

# Update Kubernetes secret
kubectl create secret generic oauth-secret \
  --from-literal=client-secret="${NEW_SECRET}" \
  --dry-run=client -o yaml | kubectl apply -f -

# Restart application
kubectl rollout restart deployment/my-app

# Notify team
echo "Client secret rotated for ${CLIENT_ID}" | \
  slack-notify --channel "#security"

{
  "data": [
    {
      "id": "session-uuid",
      "created_at": "2024-01-15T10:30:00Z",
      "last_activity": "2024-01-15T14:20:00Z",
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
      "device": "Chrome on macOS",
      "location": "San Francisco, CA"
    }
  ]
}

# Revoke sessions older than 30 days
DELETE /api/sessions?older_than=30d
Authorization: Bearer {admin_token}

# Revoke sessions from specific IP
DELETE /api/sessions?ip=192.168.1.100
Authorization: Bearer {admin_token}

{
  "active": true,
  "client_id": "abc123",
  "username": "user@example.com",
  "scope": "openid profile email",
  "sub": "user-uuid",
  "token_type": "Bearer",
  "exp": 1699999999,
  "iat": 1699996399
}

{
  "device_code": "e2623df1-8594-47b4-b528-41ed3daecc1a",
  "user_code": "56933A",
  "verification_uri": "https://auth.example.com/activate",
  "verification_uri_complete": "https://auth.example.com/activate?user_code=56933A",
  "audience": "My Application",
  "expires_in": 300,
  "interval": 5
}

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/authorize",
  "token_endpoint": "https://auth.example.com/token",
  "userinfo_endpoint": "https://auth.example.com/oauth2/userinfo",
  "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
  "introspection_endpoint": "https://auth.example.com/oauth/introspect",
  "revocation_endpoint": "https://auth.example.com/oauth/revoke",
  "device_authorization_endpoint": "https://auth.example.com/device/code",
  "scopes_supported": ["openid", "profile", "email", "read", "write"],
  "response_types_supported": ["code", "token"],
  "grant_types_supported": [
    "authorization_code",
    "client_credentials",
    "password",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "code_challenge_methods_supported": ["S256", "plain"],
  "claims_supported": [
    "sub", "iss", "aud", "exp", "iat",
    "email", "email_verified", "name",
    "given_name", "family_name"
  ]
}

{
  "client_name": "My Application",
  "redirect_uris": ["https://app.example.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_basic",
  "scope": "openid profile email",
  "logo_uri": "https://app.example.com/logo.png",
  "client_uri": "https://app.example.com",
  "tos_uri": "https://app.example.com/tos",
  "policy_uri": "https://app.example.com/privacy",
  "contacts": ["admin@example.com"]
}

{
  "client_id": "abc123-uuid",
  "client_secret": "xyz789-secret",
  "client_id_issued_at": 1699996399,
  "client_secret_expires_at": 0,
  "client_name": "My Application",
  "redirect_uris": ["https://app.example.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_basic",
  "scope": "openid profile email"
}

POST /register
Content-Type: application/json
Authorization: Bearer {admin_token}

{
  "client_name": "My Application",
  "redirect_uris": [
    "https://myapp.com/callback",
    "https://myapp.com/auth/callback"
  ],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types": ["code"],
  "scope": "openid profile email",
  "token_endpoint_auth_method": "client_secret_basic"
}

{
  "client_id": "abc123def456",
  "client_secret": "xyz789ghi012",
  "client_name": "My Application",
  "redirect_uris": [
    "https://myapp.com/callback",
    "https://myapp.com/auth/callback"
  ],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "openid profile email",
  "token_endpoint_auth_method": "client_secret_basic",
  "client_id_issued_at": 1705312200,
  "client_secret_expires_at": 0
}

PATCH /register/{client_id}
Content-Type: application/json
Authorization: Bearer {admin_token}

{
  "redirect_uris": [
    "https://myapp.com/callback",
    "https://myapp.com/auth/callback",
    "https://staging.myapp.com/callback"
  ]
}

{
  "client_name": "My Application",
  "client_uri": "https://myapp.com",
  "logo_uri": "https://myapp.com/logo.png",
  "tos_uri": "https://myapp.com/terms",
  "policy_uri": "https://myapp.com/privacy",
  "contacts": ["support@myapp.com"]
}

:root {
  /* Brand colors */
  --primary-color: #7c3aed;      /* Primary purple */
  --primary-hover: #6d28d9;      /* Darker purple */
  --primary-light: #a78bfa;      /* Lighter purple */

  /* Accent colors */
  --accent-color: #06b6d4;       /* Cyan accent */

  /* Status colors */
  --success: #22c55e;
  --warning: #f59e0b;
  --error: #ef4444;
  --info: #3b82f6;
}

<!-- emails/base.html -->
<div class="header" style="background-color: #7c3aed; padding: 20px; text-align: center;">
  <img src="{{ base_url }}/images/logo-dark.png" alt="{{ app_name }}" style="max-width: 150px;">
</div>

# Branding
APP_NAME=MyAuth
APP_TAGLINE=Secure authentication
COMPANY_NAME=My Company
COMPANY_ADDRESS=123 Main St, City

# URLs
LOGO_URL=/images/logo.png
FAVICON_URL=/images/favicon.ico
TERMS_URL=https://example.com/terms
PRIVACY_URL=https://example.com/privacy
SUPPORT_URL=https://example.com/support

# Theme
THEME=dark  # dark or light
PRIMARY_COLOR=#7c3aed

public/templates/emails/
├── base.html           # Base layout
├── welcome.html        # Welcome email
├── verification.html   # Email verification
├── password-reset.html # Password reset
├── mfa-enabled.html    # MFA confirmation
└── new-login.html      # New login alert

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
      line-height: 1.6;
      color: #333;
      max-width: 600px;
      margin: 0 auto;
      padding: 20px;
    }
    .header {
      text-align: center;
      margin-bottom: 30px;
    }
    .logo {
      max-width: 150px;
    }
    .button {
      display: inline-block;
      padding: 12px 24px;
      background-color: #7c3aed;
      color: white;
      text-decoration: none;
      border-radius: 6px;
      margin: 20px 0;
    }
    .footer {
      margin-top: 40px;
      padding-top: 20px;
      border-top: 1px solid #eee;
      font-size: 12px;
      color: #666;
    }
  </style>
</head>
<body>
  <div class="header">
    <img src="{{ base_url }}/images/logo.png" alt="Authority" class="logo">
  </div>

  {% block content %}{% endblock %}

  <div class="footer">
    <p>This email was sent by {{ app_name }}.</p>
    <p>{{ company_address }}</p>
  </div>
</body>
</html>

{% extends "emails/base.html" %}

{% block content %}
<h1>Reset Your Password</h1>

<p>Hi {{ user.name }},</p>

<p>We received a request to reset your password. Click the button below to choose a new password:</p>

<p style="text-align: center;">
  <a href="{{ reset_url }}" class="button">Reset Password</a>
</p>

<p>This link will expire in {{ expiry_minutes }} minutes.</p>

<p>If you didn't request a password reset, you can safely ignore this email. Your password won't be changed.</p>

<p>
  Best regards,<br>
  The {{ app_name }} Team
</p>
{% endblock %}

{% extends "emails/base.html" %}

{% block content %}
<h1>Welcome to {{ app_name }}!</h1>

<p>Hi {{ user.name }},</p>

<p>Thanks for creating an account. We're excited to have you on board!</p>

<p>Here are a few things you can do:</p>

<ul>
  <li>Complete your profile</li>
  <li>Enable two-factor authentication</li>
  <li>Connect your applications</li>
</ul>

<p style="text-align: center;">
  <a href="{{ profile_url }}" class="button">View Your Profile</a>
</p>

<p>
  Welcome aboard,<br>
  The {{ app_name }} Team
</p>
{% endblock %}

<!-- Use inline styles -->
<p style="color: #333; font-size: 16px;">Text</p>

<!-- Use tables for layout -->
<table width="100%" cellpadding="0" cellspacing="0">
  <tr>
    <td>Content</td>
  </tr>
</table>

<!-- Simple buttons -->
<a href="{{ url }}" style="
  display: inline-block;
  padding: 12px 24px;
  background-color: #7c3aed;
  color: #ffffff;
  text-decoration: none;
">Button</a>

public/templates/emails/
├── en/
│   ├── welcome.html
│   └── password-reset.html
├── es/
│   ├── welcome.html
│   └── password-reset.html
└── fr/
    ├── welcome.html
    └── password-reset.html

Glossary

OAuth 2.0 and OpenID Connect terminology.

Core Concepts

Resource Owner

The entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.

Resource Server

The server hosting the protected resources. Also known as the API server. It accepts and responds to protected resource requests using access tokens.

Client

An application making protected resource requests on behalf of the resource owner. The term "client" does not imply any particular implementation (server, desktop, mobile, etc.).

Authorization Server

The server that issues access tokens to the client after authenticating the resource owner and obtaining authorization. Authority is an authorization server.

Token Types

Access Token

A credential used to access protected resources. Access tokens represent the authorization granted to the client. Authority issues JWTs as access tokens.

Refresh Token

A credential used to obtain new access tokens. Refresh tokens are issued with access tokens and allow clients to get new tokens without user interaction.

ID Token

A JSON Web Token (JWT) that contains claims about the authentication event and the user. Part of OpenID Connect.

Authorization Code

A short-lived code returned after user authorization. Exchanged for access tokens at the token endpoint.

Device Code

A code used in the device authorization flow. Displayed to users who authorize on a separate device.

OAuth Concepts

Grant Type

The method used to obtain an access token. Common types:

Authorization Code - Web applications
Client Credentials - Machine-to-machine
Device Code - IoT devices, CLIs

Scope

A string that defines the access level requested by the client. Examples: read, write, openid, profile.

Redirect URI

The URL where the authorization server redirects after authorization. Also called callback URL.

State

A random value used to prevent CSRF attacks during the authorization flow.

PKCE (Proof Key for Code Exchange)

An extension that protects authorization code flow against interception. Pronounced "pixie".

Code Verifier

A random string used in PKCE. Created by the client before authorization.

Code Challenge

A transformation of the code verifier. Sent in the authorization request and verified during token exchange.

Client Types

Confidential Client

A client capable of maintaining the confidentiality of its credentials. Typically server-side applications.

Public Client

A client that cannot maintain secret credentials. Mobile apps, SPAs, and native applications.

First-Party Client

A client owned by the same entity that operates the authorization server. Trusted with user credentials.

Third-Party Client

A client owned by a different entity. Should never directly handle user credentials.

OpenID Connect

Claims

Pieces of information about a user. Examples: name, email, sub.

UserInfo Endpoint

An endpoint that returns claims about the authenticated user.

Discovery

The mechanism to automatically find authorization server endpoints and capabilities.

JWKS (JSON Web Key Set)

A set of public keys used to verify token signatures.

Nonce

A random value sent in the authorization request and included in the ID token to prevent replay attacks.

Authentication

MFA (Multi-Factor Authentication)

Authentication requiring multiple verification methods. Authority supports TOTP-based MFA.

TOTP (Time-based One-Time Password)

A temporary passcode generated by an authenticator app. Changes every 30 seconds.

Session

A server-side record of a user's authentication state. Persists across requests.

Security

Token Introspection

A mechanism for resource servers to query the authorization server about a token's current state.

Token Revocation

The process of invalidating a token before its natural expiration.

The user's explicit approval of the scopes requested by a client.

Audit Log

A record of security-relevant events for compliance and monitoring.

Account Lockout

Temporarily blocking access after multiple failed authentication attempts.

JWT (JSON Web Token)

Header

The first part of a JWT containing the token type and signing algorithm.

Payload

The second part of a JWT containing claims about the subject.

Signature

The third part of a JWT used to verify the token hasn't been tampered with.

Issuer (`iss`)

The entity that issued the token. For Authority tokens, this is the server URL.

Subject (`sub`)

The identifier of the principal (user) the token is about.

Audience (`aud`)

The intended recipient of the token. Typically the client ID.

Expiration (`exp`)

The timestamp after which the token should not be accepted.

Standards

RFC 6749

The OAuth 2.0 Authorization Framework specification.

RFC 6750

OAuth 2.0 Bearer Token Usage specification.

RFC 7636

Proof Key for Code Exchange (PKCE) specification.

RFC 8628

Device Authorization Grant specification.

OpenID Connect Core 1.0

The specification for identity layer on top of OAuth 2.0.

OAuth 2.0 Concepts

Understanding the fundamentals of OAuth 2.0.

What is OAuth 2.0?

OAuth 2.0 is an authorization framework that enables applications to obtain limited access to user resources without exposing credentials.

The Problem OAuth Solves

Without OAuth, applications would need:

Direct access to user credentials
Full access to all resources
No way to revoke access without changing passwords

OAuth provides:

Delegated authorization (no password sharing)
Scoped access (limited permissions)
Revocable tokens (easy access removal)

Key Concepts

Roles

Role

Description

Tokens

Token

Purpose

Lifetime

Scopes

Scopes define what access is granted:

Clients request scopes:

Users consent to scopes:

Grant Types

Authorization Code (Most Common)

Best for: Web applications with a backend

The client never sees the user's password.

Authorization Code + PKCE

Best for: Mobile apps, single-page applications

Same as authorization code, but with proof key:

Client generates random code_verifier
Client sends code_challenge = SHA256(code_verifier)
Authority returns code

Client Credentials

Best for: Machine-to-machine

No user involved - the service itself is authorized.

Device Code

Best for: TVs, CLI tools, IoT

The Authorization Flow

Step by Step

User wants to access protected resource
User clicks "Login with Authority" in your app.
Client redirects to Authorization Server
User authenticates

Security Concepts

State Parameter

Prevents CSRF attacks:

Client generates random state
Client stores state in session
Client includes state in authorization request
Authority returns state in callback

PKCE

Prevents authorization code interception:

Token Security

Short-lived access tokens - Limit exposure window
Token rotation - New refresh token each use
Secure storage - Never store in URL or logs

Common Misconceptions

"OAuth is for authentication"

OAuth is for authorization (what you can do), not authentication (who you are). OpenID Connect adds authentication.

"The access token contains user data"

Access tokens authorize access - they don't necessarily contain user info. Use the UserInfo endpoint or ID tokens for identity.

"Longer token lifetimes are more secure"

Shorter lifetimes with refresh tokens are more secure. If a token is compromised, the damage window is limited.

Next Steps

- Identity layer
- Decision guide
- Token management

public/
├── templates/
│   ├── layout.html          # Base layout
│   ├── signin.html          # Login page
│   ├── signup.html          # Registration
│   ├── authorize.html       # OAuth consent
│   ├── activate.html        # Device activation
│   ├── forgot-password.html # Password reset request
│   ├── reset-password.html  # Password reset form
│   ├── errors.html          # Error messages
│   └── emails/              # Email templates
│       ├── verification.html
│       ├── password-reset.html
│       └── welcome.html
├── css/
│   └── styles.css           # Main stylesheet
└── js/
    └── app.js               # Client JavaScript

<!DOCTYPE html>
<html>
<head>
  <title>{% block title %}Authority{% endblock %}</title>
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  {% block body %}{% endblock %}
  <script src="/js/app.js"></script>
</body>
</html>

{% extends "layout.html" %}
{% set title = "Sign In" %}

{% block body %}
<main class="login-form">
  {% include "errors.html" %}
  <form action="/signin" method="post">
    <input type="text" name="username" placeholder="Username" required>
    <input type="password" name="password" placeholder="Password" required>
    <button type="submit">Sign In</button>
  </form>
</main>
{% endblock %}

:root {
  /* Primary colors */
  --primary-color: #7c3aed;
  --primary-hover: #6d28d9;

  /* Background colors */
  --bg-primary: #0f172a;
  --bg-secondary: #1e293b;
  --bg-card: #1e293b;

  /* Text colors */
  --text-primary: #f8fafc;
  --text-secondary: #94a3b8;

  /* Status colors */
  --success: #22c55e;
  --warning: #f59e0b;
  --error: #ef4444;

  /* Border radius */
  --radius-sm: 0.375rem;
  --radius-md: 0.5rem;
  --radius-lg: 0.75rem;
}

POST /token HTTP/1.1
Host: auth.example.com
Authorization: Basic YWJjMTIzOnNlY3JldA==
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE_HERE
&redirect_uri=https://app.example.com/callback

const express = require('express');
const crypto = require('crypto');

const app = express();

const CLIENT_ID = 'your_client_id';
const CLIENT_SECRET = 'your_client_secret';
const REDIRECT_URI = 'http://localhost:3000/callback';
const AUTHORITY_URL = 'https://auth.example.com';

// Step 1: Redirect to authorization
app.get('/login', (req, res) => {
  const state = crypto.randomBytes(16).toString('hex');
  req.session.state = state;

  const params = new URLSearchParams({
    response_type: 'code',
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    scope: 'openid profile email',
    state: state
  });

  res.redirect(`${AUTHORITY_URL}/authorize?${params}`);
});

// Step 2: Handle callback
app.get('/callback', async (req, res) => {
  const { code, state } = req.query;

  // Verify state
  if (state !== req.session.state) {
    return res.status(400).send('Invalid state');
  }

  // Exchange code for tokens
  const credentials = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64');

  const tokenResponse = await fetch(`${AUTHORITY_URL}/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${credentials}`
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: code,
      redirect_uri: REDIRECT_URI
    })
  });

  const tokens = await tokenResponse.json();
  req.session.tokens = tokens;

  res.redirect('/profile');
});

from flask import Flask, redirect, request, session
import requests
import secrets

app = Flask(__name__)

CLIENT_ID = 'your_client_id'
CLIENT_SECRET = 'your_client_secret'
REDIRECT_URI = 'http://localhost:5000/callback'
AUTHORITY_URL = 'https://auth.example.com'

@app.route('/login')
def login():
    state = secrets.token_urlsafe(16)
    session['state'] = state

    params = {
        'response_type': 'code',
        'client_id': CLIENT_ID,
        'redirect_uri': REDIRECT_URI,
        'scope': 'openid profile email',
        'state': state
    }

    return redirect(f"{AUTHORITY_URL}/authorize?{urlencode(params)}")

@app.route('/callback')
def callback():
    code = request.args.get('code')
    state = request.args.get('state')

    if state != session.get('state'):
        return 'Invalid state', 400

    token_response = requests.post(
        f"{AUTHORITY_URL}/token",
        data={
            'grant_type': 'authorization_code',
            'code': code,
            'redirect_uri': REDIRECT_URI
        },
        auth=(CLIENT_ID, CLIENT_SECRET)
    )

    session['tokens'] = token_response.json()
    return redirect('/profile')

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="The access token expired"
Content-Type: application/json

{
  "error": "invalid_token",
  "error_description": "The access token expired"
}

{
  "error": "validation_error",
  "error_description": "Request validation failed",
  "details": [
    {
      "field": "email",
      "message": "Email format is invalid"
    },
    {
      "field": "password",
      "message": "Password must be at least 12 characters"
    }
  ]
}

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": "rate_limit_exceeded",
  "error_description": "Rate limit exceeded. Retry after 60 seconds.",
  "retry_after": 60
}

function generateCodeVerifier() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return base64URLEncode(array);
}

async function generateCodeChallenge(verifier) {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const hash = await crypto.subtle.digest('SHA-256', data);
  return base64URLEncode(new Uint8Array(hash));
}

function base64URLEncode(buffer) {
  return btoa(String.fromCharCode(...buffer))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}

import hashlib
import base64
import secrets

def generate_code_verifier():
    return secrets.token_urlsafe(32)

def generate_code_challenge(verifier):
    digest = hashlib.sha256(verifier.encode()).digest()
    return base64.urlsafe_b64encode(digest).rstrip(b'=').decode()

GET https://auth.example.com/authorize?
  response_type=code
  &client_id=abc123
  &redirect_uri=https://app.example.com/callback
  &scope=openid%20profile%20email
  &state=xyz789
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE_HERE
&redirect_uri=https://app.example.com/callback
&client_id=abc123
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

import { useEffect, useState } from 'react';

const CLIENT_ID = 'your_client_id';
const REDIRECT_URI = 'http://localhost:3000/callback';
const AUTHORITY_URL = 'https://auth.example.com';

function App() {
  const [user, setUser] = useState(null);

  useEffect(() => {
    // Check for callback
    if (window.location.search.includes('code=')) {
      handleCallback();
    }
  }, []);

  async function login() {
    const codeVerifier = generateCodeVerifier();
    const codeChallenge = await generateCodeChallenge(codeVerifier);
    const state = generateCodeVerifier();

    // Store for callback
    sessionStorage.setItem('code_verifier', codeVerifier);
    sessionStorage.setItem('state', state);

    const params = new URLSearchParams({
      response_type: 'code',
      client_id: CLIENT_ID,
      redirect_uri: REDIRECT_URI,
      scope: 'openid profile email',
      state: state,
      code_challenge: codeChallenge,
      code_challenge_method: 'S256'
    });

    window.location.href = `${AUTHORITY_URL}/authorize?${params}`;
  }

  async function handleCallback() {
    const params = new URLSearchParams(window.location.search);
    const code = params.get('code');
    const state = params.get('state');

    // Verify state
    if (state !== sessionStorage.getItem('state')) {
      throw new Error('Invalid state');
    }

    const codeVerifier = sessionStorage.getItem('code_verifier');

    // Exchange code for tokens
    const response = await fetch(`${AUTHORITY_URL}/token`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'authorization_code',
        code: code,
        redirect_uri: REDIRECT_URI,
        client_id: CLIENT_ID,
        code_verifier: codeVerifier
      })
    });

    const tokens = await response.json();

    // Get user info
    const userResponse = await fetch(`${AUTHORITY_URL}/userinfo`, {
      headers: { 'Authorization': `Bearer ${tokens.access_token}` }
    });

    setUser(await userResponse.json());

    // Clean up
    sessionStorage.removeItem('code_verifier');
    sessionStorage.removeItem('state');
    window.history.replaceState({}, '', '/');
  }

  return (
    <div>
      {user ? (
        <p>Welcome, {user.name}!</p>
      ) : (
        <button onClick={login}>Login</button>
      )}
    </div>
  );
}

import * as AuthSession from 'expo-auth-session';
import * as Crypto from 'expo-crypto';

const CLIENT_ID = 'your_client_id';
const AUTHORITY_URL = 'https://auth.example.com';

async function login() {
  const codeVerifier = generateCodeVerifier();
  const codeChallenge = await generateCodeChallenge(codeVerifier);

  const redirectUri = AuthSession.makeRedirectUri();

  const result = await AuthSession.startAsync({
    authUrl: `${AUTHORITY_URL}/authorize?` + new URLSearchParams({
      response_type: 'code',
      client_id: CLIENT_ID,
      redirect_uri: redirectUri,
      scope: 'openid profile email',
      code_challenge: codeChallenge,
      code_challenge_method: 'S256'
    })
  });

  if (result.type === 'success') {
    const tokens = await exchangeCode(result.params.code, codeVerifier, redirectUri);
    return tokens;
  }
}

POST /token HTTP/1.1
Host: auth.example.com
Authorization: Basic YWJjMTIzOnNlY3JldA==
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=dGhpcyBpcyBhIHJlZnJlc2g

class TokenManager {
  constructor(tokens) {
    this.tokens = tokens;
    this.expiresAt = Date.now() + (tokens.expires_in * 1000);
    this.scheduleRefresh();
  }

  scheduleRefresh() {
    // Refresh 5 minutes before expiry
    const refreshIn = this.expiresAt - Date.now() - (5 * 60 * 1000);

    if (refreshIn > 0) {
      setTimeout(() => this.refresh(), refreshIn);
    }
  }

  async refresh() {
    const response = await fetch('/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Authorization': `Basic ${btoa(`${CLIENT_ID}:${CLIENT_SECRET}`)}`
      },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        refresh_token: this.tokens.refresh_token
      })
    });

    this.tokens = await response.json();
    this.expiresAt = Date.now() + (this.tokens.expires_in * 1000);
    this.scheduleRefresh();

    return this.tokens;
  }

  getAccessToken() {
    return this.tokens.access_token;
  }
}

async function apiCall(url, options = {}) {
  let response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${tokenManager.getAccessToken()}`
    }
  });

  if (response.status === 401) {
    // Token expired, refresh and retry
    await tokenManager.refresh();

    response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${tokenManager.getAccessToken()}`
      }
    });
  }

  return response;
}

async function refresh() {
  const response = await fetch('/token', {
    method: 'POST',
    // ...
  });

  if (!response.ok) {
    const error = await response.json();

    if (error.error === 'invalid_grant') {
      // Refresh token invalid - require re-login
      logout();
      redirectToLogin();
      return;
    }

    throw new Error(error.error_description);
  }

  return response.json();
}

Subject: Reset your password

Click the link below to reset your password:
https://auth.example.com/reset-password?token=abc123...

This link expires in 1 hour.

If you didn't request this, ignore this email.

{% extends "emails/base.html" %}

{% block content %}
<h1>Reset Your Password</h1>
<p>Hi {{ user.name }},</p>
<p>Click the button below to reset your password:</p>
<a href="{{ reset_url }}" class="button">Reset Password</a>
<p>This link expires in {{ expiry_minutes }} minutes.</p>
{% endblock %}

{% extends "layout.html" %}
{% set title = "Reset Password" %}

{% block body %}
<main class="reset-form">
  <h1>Choose a New Password</h1>
  <form action="/reset-password" method="post">
    <input type="hidden" name="token" value="{{ token }}">
    <input type="password" name="password" placeholder="New Password" required>
    <input type="password" name="password_confirmation" placeholder="Confirm Password" required>
    <button type="submit">Reset Password</button>
  </form>
</main>
{% endblock %}

// Request reset
const response = await fetch('/api/password-reset', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'user@example.com' })
});

// Complete reset
const response = await fetch('/api/password-reset/complete', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    token: 'reset_token_from_email',
    password: 'NewPassword123'
  })
});

{
  "sub": "user-uuid",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "preferred_username": "johnd",
  "email": "john@example.com",
  "email_verified": true,
  "picture": "https://example.com/johnd/photo.jpg",
  "locale": "en-US",
  "updated_at": 1699996399
}

async function getUserInfo(accessToken) {
  const response = await fetch('https://auth.example.com/userinfo', {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });

  if (!response.ok) {
    throw new Error('Failed to fetch user info');
  }

  return response.json();
}

// Usage
const user = await getUserInfo(tokens.access_token);
console.log(`Hello, ${user.name}!`);

import requests

def get_userinfo(access_token):
    response = requests.get(
        'https://auth.example.com/userinfo',
        headers={'Authorization': f'Bearer {access_token}'}
    )

    if response.status_code != 200:
        raise Exception('Failed to fetch user info')

    return response.json()

user = get_userinfo(tokens['access_token'])
print(f"Hello, {user['name']}!")

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="The access token is invalid"

{
  "error": "invalid_token",
  "error_description": "The access token is invalid"
}

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="The access token has expired"

{
  "error": "invalid_token",
  "error_description": "The access token has expired"
}

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="openid profile"

{
  "error": "insufficient_scope",
  "error_description": "The access token lacks the required scope"
}

class UserInfoCache {
  constructor(ttl = 60000) { // 1 minute
    this.cache = new Map();
    this.ttl = ttl;
  }

  async get(accessToken) {
    const cached = this.cache.get(accessToken);
    if (cached && Date.now() < cached.expiresAt) {
      return cached.data;
    }

    const data = await fetchUserInfo(accessToken);
    this.cache.set(accessToken, {
      data,
      expiresAt: Date.now() + this.ttl
    });

    return data;
  }
}

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/authorize",
  "token_endpoint": "https://auth.example.com/token",
  "userinfo_endpoint": "https://auth.example.com/userinfo",
  "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
  "registration_endpoint": "https://auth.example.com/register",
  "revocation_endpoint": "https://auth.example.com/token/revoke",
  "introspection_endpoint": "https://auth.example.com/token/introspect",
  "device_authorization_endpoint": "https://auth.example.com/device",

  "scopes_supported": [
    "openid",
    "profile",
    "email",
    "address",
    "phone",
    "offline_access"
  ],

  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token"
  ],

  "response_modes_supported": [
    "query",
    "fragment"
  ],

  "grant_types_supported": [
    "authorization_code",
    "refresh_token",
    "client_credentials",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],

  "subject_types_supported": [
    "public"
  ],

  "id_token_signing_alg_values_supported": [
    "RS256"
  ],

  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],

  "claims_supported": [
    "sub",
    "iss",
    "aud",
    "exp",
    "iat",
    "auth_time",
    "nonce",
    "name",
    "given_name",
    "family_name",
    "email",
    "email_verified",
    "picture",
    "locale"
  ],

  "code_challenge_methods_supported": [
    "S256",
    "plain"
  ]
}

async function discoverProvider(issuer) {
  const response = await fetch(
    `${issuer}/.well-known/openid-configuration`
  );
  return response.json();
}

// Use discovered configuration
const config = await discoverProvider('https://auth.example.com');

// Now use the endpoints
const authUrl = new URL(config.authorization_endpoint);
authUrl.searchParams.set('client_id', CLIENT_ID);
authUrl.searchParams.set('response_type', 'code');
// ...

import requests

def discover_provider(issuer):
    response = requests.get(
        f"{issuer}/.well-known/openid-configuration"
    )
    return response.json()

config = discover_provider('https://auth.example.com')
print(f"Auth endpoint: {config['authorization_endpoint']}")

class ProviderConfig {
  constructor(issuer) {
    this.issuer = issuer;
    this.config = null;
    this.expiresAt = null;
  }

  async getConfig() {
    // Cache for 1 hour
    if (this.config && Date.now() < this.expiresAt) {
      return this.config;
    }

    const response = await fetch(
      `${this.issuer}/.well-known/openid-configuration`
    );
    this.config = await response.json();
    this.expiresAt = Date.now() + (60 * 60 * 1000);

    return this.config;
  }
}

function validateConfig(config, expectedIssuer) {
  if (config.issuer !== expectedIssuer) {
    throw new Error('Issuer mismatch');
  }

  if (!config.authorization_endpoint) {
    throw new Error('Missing authorization endpoint');
  }

  if (!config.scopes_supported.includes('openid')) {
    throw new Error('OpenID scope not supported');
  }

  return true;
}

CRYSTAL_ENV=production
PORT=4000
BASE_URL=https://auth.example.com
DATABASE_URL=postgres://user:pass@db:5432/authority_db?sslmode=require
SECRET_KEY=your-production-secret-key
CRYSTAL_WORKERS=8
CRYSTAL_LOG_LEVEL=info

# Security
LOCKOUT_THRESHOLD=5
LOCKOUT_DURATION=30
PASSWORD_MIN_LENGTH=12
REQUIRE_ADMIN_MFA=true

# Tokens
ACCESS_TOKEN_TTL=3600
REFRESH_TOKEN_TTL=2592000

# Redis
REDIS_URL=redis://redis:6379

# Email
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=noreply@example.com
SMTP_PASSWORD=your-smtp-password
SMTP_FROM=noreply@example.com

// Redirect with response_type=token
window.location = '/authorize?response_type=token&client_id=...';

// Get token from URL fragment
const token = new URLSearchParams(window.location.hash.slice(1)).get('access_token');

// Generate PKCE values
const verifier = generateCodeVerifier();
const challenge = await generateCodeChallenge(verifier);

// Redirect with response_type=code
window.location = `/authorize?response_type=code&client_id=...&code_challenge=${challenge}&code_challenge_method=S256`;

// Exchange code for token
const tokenResponse = await fetch('/token', {
  method: 'POST',
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: code,
    code_verifier: verifier,
    client_id: CLIENT_ID
  })
});

POST /token HTTP/1.1
Host: auth.example.com
Authorization: Basic YWJjMTIzOnNlY3JldA==
Content-Type: application/x-www-form-urlencoded

grant_type=password
&username=user@example.com
&password=secret123
&scope=openid%20profile

// Instead of collecting password in app
// Redirect to Authority's login page
const params = new URLSearchParams({
  response_type: 'code',
  client_id: CLIENT_ID,
  redirect_uri: REDIRECT_URI,
  scope: 'openid profile',
  code_challenge: challenge,
  code_challenge_method: 'S256'
});

// Open in-app browser
openAuthUrl(`${AUTHORITY_URL}/authorize?${params}`);

┌──────────────────────────────────────────────────┐
│                                                  │
│   Resource Owner         Authorization Server    │
│   (User)                 (Authority)             │
│      │                        │                  │
│      │ authorizes             │ issues tokens    │
│      ▼                        ▼                  │
│   Client ◄─────────────────────────────────►     │
│   (App)                  Resource Server         │
│                          (API)                   │
│                                                  │
└──────────────────────────────────────────────────┘

                            Attacker
                               │
┌─────────┐                    │                    ┌─────────┐
│ Client  │───code_challenge───┼───────────────────►│Authority│
│         │◄──authorization_code◄──────────────────│         │
│         │───code_verifier────┼────────────────────►│         │
│         │◄──access_token─────┼────────────────────│         │
└─────────┘                    │                    └─────────┘
                               │
                    Attacker has code,
                    but can't prove
                    they know verifier

{
  "iss": "https://auth.example.com",
  "sub": "user-uuid",
  "aud": "client-id",
  "exp": 1699999999,
  "iat": 1699996399,
  "auth_time": 1699996300,
  "nonce": "abc123",
  "name": "John Doe",
  "email": "john@example.com",
  "email_verified": true
}

// 1. Request authorization with openid scope
const params = new URLSearchParams({
  response_type: 'code',
  client_id: CLIENT_ID,
  redirect_uri: REDIRECT_URI,
  scope: 'openid profile email',
  state: state,
  nonce: nonce  // For ID token validation
});

window.location = `${AUTHORITY_URL}/authorize?${params}`;

// 2. Exchange code for tokens
const tokens = await fetch('/token', {
  method: 'POST',
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: code,
    redirect_uri: REDIRECT_URI
  })
}).then(r => r.json());

// 3. Validate and use ID token
const idToken = parseIdToken(tokens.id_token);
console.log('User:', idToken.name);

// 4. Optionally fetch more claims
const userinfo = await fetch('/userinfo', {
  headers: { 'Authorization': `Bearer ${tokens.access_token}` }
}).then(r => r.json());

┌────────────────────────────────────────┐
│           OpenID Connect               │
│         (Authentication)               │
├────────────────────────────────────────┤
│              OAuth 2.0                 │
│          (Authorization)               │
└────────────────────────────────────────┘

{
  "iss": "https://auth.example.com",
  "sub": "user-123",
  "aud": "client-abc",
  "exp": 1699999999,
  "iat": 1699996399,
  "auth_time": 1699996300,
  "nonce": "abc123",
  "name": "John Doe",
  "email": "john@example.com"
}

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/authorize",
  "token_endpoint": "https://auth.example.com/token",
  "userinfo_endpoint": "https://auth.example.com/userinfo",
  "jwks_uri": "https://auth.example.com/.well-known/jwks.json"
}

users
├── id (UUID)
├── email (unique)
├── password_hash
├── name
├── mfa_secret
├── mfa_enabled
├── locked
├── locked_at
├── failed_attempts
├── role
├── created_at
└── updated_at

clients
├── id (UUID)
├── client_id (unique)
├── client_secret_hash
├── name
├── redirect_uris (array)
├── grant_types (array)
├── scopes (array)
├── client_type
├── created_at
└── updated_at

┌─────────────────────────────────────┐
│           Rate Limiting              │
├─────────────────────────────────────┤
│          Input Validation            │
├─────────────────────────────────────┤
│         Authentication               │
├─────────────────────────────────────┤
│         Authorization                │
├─────────────────────────────────────┤
│         Business Logic               │
├─────────────────────────────────────┤
│         Data Validation              │
├─────────────────────────────────────┤
│         Audit Logging                │
└─────────────────────────────────────┘

                    ┌─────────────┐
                    │   Load      │
                    │  Balancer   │
                    └──────┬──────┘
            ┌──────────────┼──────────────┐
      ┌─────┴─────┐  ┌─────┴─────┐  ┌─────┴─────┐
      │ Authority │  │ Authority │  │ Authority │
      │ Instance  │  │ Instance  │  │ Instance  │
      └─────┬─────┘  └─────┬─────┘  └─────┬─────┘
            └──────────────┼──────────────┘
                    ┌──────┴──────┐
      ┌─────────────┴─────────────┴─────────────┐
      │              PostgreSQL                   │
      │              (Primary)                    │
      └─────────────┬─────────────┬─────────────┘
                    │             │
              ┌─────┴─────┐ ┌─────┴─────┐
              │  Replica  │ │  Replica  │
              └───────────┘ └───────────┘

{
  "iss": "https://auth.example.com",
  "sub": "user-uuid",
  "aud": "client-id",
  "exp": 1699999999,
  "iat": 1699996399,
  "auth_time": 1699996300,
  "nonce": "n-0S6_WzA2Mj",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "name": "John Doe",
  "email": "john@example.com",
  "email_verified": true
}

const jwt = require('jsonwebtoken');
const jwksClient = require('jwks-rsa');

const client = jwksClient({
  jwksUri: 'https://auth.example.com/.well-known/jwks.json'
});

async function validateIdToken(idToken, expectedNonce) {
  return new Promise((resolve, reject) => {
    const getKey = (header, callback) => {
      client.getSigningKey(header.kid, (err, key) => {
        callback(err, key?.getPublicKey());
      });
    };

    jwt.verify(idToken, getKey, {
      algorithms: ['RS256'],
      issuer: 'https://auth.example.com',
      audience: 'your_client_id'
    }, (err, decoded) => {
      if (err) {
        reject(err);
        return;
      }

      // Check nonce
      if (expectedNonce && decoded.nonce !== expectedNonce) {
        reject(new Error('Invalid nonce'));
        return;
      }

      // Check auth_time if max_age was requested
      // Check other claims as needed

      resolve(decoded);
    });
  });
}

import jwt
from jwt import PyJWKClient

jwks_client = PyJWKClient("https://auth.example.com/.well-known/jwks.json")

def validate_id_token(id_token, expected_nonce=None):
    signing_key = jwks_client.get_signing_key_from_jwt(id_token)

    claims = jwt.decode(
        id_token,
        signing_key.key,
        algorithms=["RS256"],
        issuer="https://auth.example.com",
        audience="your_client_id"
    )

    if expected_nonce and claims.get('nonce') != expected_nonce:
        raise ValueError('Invalid nonce')

    return claims

const nonce = generateRandomString();
sessionStorage.setItem('oidc_nonce', nonce);

const params = new URLSearchParams({
  response_type: 'code',
  client_id: CLIENT_ID,
  redirect_uri: REDIRECT_URI,
  scope: 'openid profile email',
  nonce: nonce
});

function validateAtHash(idToken, accessToken) {
  const claims = jwt.decode(idToken);

  if (claims.at_hash) {
    const hash = crypto.createHash('sha256').update(accessToken).digest();
    const expectedHash = hash.slice(0, hash.length / 2);
    const calculatedAtHash = base64url.encode(expectedHash);

    if (claims.at_hash !== calculatedAtHash) {
      throw new Error('at_hash mismatch');
    }
  }
}

# Strict account lockout
LOCKOUT_THRESHOLD=3
LOCKOUT_DURATION=60
PROGRESSIVE_LOCKOUT=true

# Strong passwords
PASSWORD_MIN_LENGTH=16
REQUIRE_UPPERCASE=true
REQUIRE_LOWERCASE=true
REQUIRE_NUMBERS=true
REQUIRE_SPECIAL=true
PASSWORD_EXPIRY_DAYS=90
CHECK_COMMON_PASSWORDS=true

# MFA required
REQUIRE_MFA=true
REQUIRE_ADMIN_MFA=true

# Short sessions
SESSION_DURATION_DAYS=1
IDLE_TIMEOUT_MINUTES=15
SINGLE_SESSION=true

# Notifications
NOTIFY_NEW_SESSION=true

# IP restrictions
ADMIN_ALLOWED_IPS=10.0.0.0/8

# Lenient lockout
LOCKOUT_THRESHOLD=10
LOCKOUT_DURATION=15
ENABLE_AUTO_UNLOCK=true

# Reasonable passwords
PASSWORD_MIN_LENGTH=10
REQUIRE_UPPERCASE=false
REQUIRE_LOWERCASE=false
REQUIRE_NUMBERS=false
PASSWORD_EXPIRY_DAYS=0

# MFA optional except admins
REQUIRE_MFA=false
REQUIRE_ADMIN_MFA=true

# Longer sessions
SESSION_DURATION_DAYS=30
IDLE_TIMEOUT_MINUTES=60

Time T:   Client has Refresh Token A
Time T+1: Client uses Refresh Token A
          ↓
          New Access Token issued
          New Refresh Token B issued
          Refresh Token A invalidated

Time T+2: Attacker tries Refresh Token A
          ↓
          Rejected (already used)
          Alert: Possible token theft

┌─────────────────────────────────────────┐
│            PostgreSQL                    │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│  │ Access  │ │ Refresh │ │  Auth   │   │
│  │ Tokens  │ │ Tokens  │ │  Codes  │   │
│  └─────────┘ └─────────┘ └─────────┘   │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│              Redis                       │
│  ┌─────────────────────────────────┐    │
│  │   Token Cache (optional)         │    │
│  │   Session Storage                │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘

async function apiCall(endpoint) {
  // Check token validity
  if (isExpired(accessToken)) {
    accessToken = await refresh();
  }

  return fetch(endpoint, {
    headers: { Authorization: `Bearer ${accessToken}` }
  });
}

Authority

Tutorials

How-To Guides

Reference

Social Login

hashtagEndpoints Overview

hashtagSupported Providers

hashtagInitiate Social Login

hashtagPath Parameters

hashtagQuery Parameters

hashtagResponse

hashtagExample

hashtagErrors

hashtagOAuth Callback

hashtagPath Parameters

hashtagQuery Parameters

hashtagResponse

hashtagErrors

hashtagUnlink Social Account

hashtagPath Parameters

hashtagAuthentication

hashtagResponse

hashtagErrors

hashtagExample

hashtagUser Data from Providers

hashtagGoogle

hashtagGitHub

hashtagFacebook

hashtagLinkedIn

hashtagApple

hashtagState Parameter

hashtagSession Handling

hashtagConfiguration Settings

hashtagNext Steps

Rate Limits

hashtagDefault Limits

hashtagResponse Headers

hashtagRate Limit Exceeded

hashtagRate Limit Types

hashtagPer IP Address

hashtagPer Client

hashtagPer User

hashtagConfiguration

hashtagEnvironment Variables

hashtagPer-Endpoint Configuration

hashtagWhitelist

hashtagClient-Specific Limits

hashtagBest Practices

hashtagClient Implementation

hashtagHandling Rate Limits

hashtagMonitoring

hashtagRedis-Based Rate Limiting

hashtagNext Steps

Client Credentials

hashtagOverview

hashtagUse Cases

hashtagFlow Diagram

hashtagToken Request

hashtagHeaders

hashtagParameters

hashtagExample

hashtagResponse

hashtagAuthentication Methods

hashtagHTTP Basic Authentication (Recommended)

hashtagPOST Body

hashtagComplete Examples

hashtagNode.js

hashtagPython

hashtagcurl

hashtagToken Caching

hashtagScopes

hashtagSecurity Considerations

hashtagDifferences from Other Grants

hashtagNext Steps

Device Flow

hashtagOverview

hashtagUse Cases

hashtagFlow Diagram

hashtagDevice Authorization Request

hashtagParameters

Endpoints Overview

Supported Providers

Initiate Social Login

Path Parameters

Query Parameters

Response

Example

Errors

OAuth Callback

Path Parameters

Query Parameters

Response

Errors

Unlink Social Account

Path Parameters

Authentication

Response

Errors

Example

User Data from Providers

Google

GitHub

Facebook

LinkedIn

Apple

State Parameter

Session Handling

Configuration Settings

Next Steps

Default Limits

Response Headers

Rate Limit Exceeded

Rate Limit Types

Per IP Address

Per Client

Per User

Configuration

Environment Variables

Per-Endpoint Configuration

Whitelist

Client-Specific Limits

Best Practices

Client Implementation

Handling Rate Limits

Monitoring

Redis-Based Rate Limiting

Next Steps

Overview

Use Cases

Flow Diagram

Token Request

Headers

Parameters

Example

Response

Authentication Methods

HTTP Basic Authentication (Recommended)

POST Body

Complete Examples

Node.js

Python

curl

Token Caching

Scopes

Security Considerations

Differences from Other Grants

Next Steps

Overview

Use Cases

Flow Diagram

Device Authorization Request

Parameters

Example

Response

Display to User

Token Polling

Parameters

Example

Responses

Complete Example