Route Handlers

Pre-built handlers for OAuth authentication flow in Express.js applications.

Overview

AuthSafe provides ready-to-use route handlers for all OAuth 2.1 flows:

handleSignIn() - Initiate OAuth sign in
handleCallback() - Process OAuth callback
handleLogout() - Sign out and clear session
handleRefresh() - Refresh access tokens

Import

import {
  handleSignIn,
  handleCallback,
  handleLogout,
  handleRefresh,
} from 'authsafe-express';

handleSignIn()

Initiate OAuth sign in by redirecting to AuthSafe authorization endpoint.

async function handleSignIn(
  req: Request,
  res: Response,
  config: AuthSafeConfig,
): Promise<void>;

Parameters

Parameter	Type	Description
`req`	Request	Express request object
`res`	Response	Express response object
`config`	AuthSafeConfig	AuthSafe configuration

Basic Usage

app.get('/auth/signin', (req, res) => {
  handleSignIn(req, res, {
    clientId: process.env.AUTHSAFE_CLIENT_ID!,
    domain: process.env.AUTHSAFE_DOMAIN!,
    redirectUri: `${process.env.APP_URL}/auth/callback`,
  });
});

With Return URL

The returnTo query parameter specifies where to redirect after sign in:

// User visits: /auth/signin?returnTo=/dashboard
app.get('/auth/signin', (req, res) => {
  handleSignIn(req, res, {
    clientId: process.env.AUTHSAFE_CLIENT_ID!,
    domain: process.env.AUTHSAFE_DOMAIN!,
    redirectUri: `${process.env.APP_URL}/auth/callback`,
  });
});
// After successful authentication, redirects to /dashboard

Custom Scopes

app.get('/auth/signin', (req, res) => {
  handleSignIn(req, res, {
    clientId: process.env.AUTHSAFE_CLIENT_ID!,
    domain: process.env.AUTHSAFE_DOMAIN!,
    redirectUri: `${process.env.APP_URL}/auth/callback`,
    scopes: ['openid', 'email', 'profile', 'admin:read'],
  });
});

What It Does

Generates PKCE code challenge
Generates nonce for ID token validation
Creates state parameter with returnTo URL
Stores code verifier in cookie
Redirects to AuthSafe authorization endpoint

handleCallback()

Process OAuth callback and exchange authorization code for tokens.

async function handleCallback(
  req: Request,
  res: Response,
  config: AuthSafeConfig,
): Promise<void>;

Usage

app.get('/auth/callback', (req, res) => {
  handleCallback(req, res, {
    clientId: process.env.AUTHSAFE_CLIENT_ID!,
    clientSecret: process.env.AUTHSAFE_CLIENT_SECRET!,
    domain: process.env.AUTHSAFE_DOMAIN!,
    redirectUri: `${process.env.APP_URL}/auth/callback`,
  });
});

Client Secret Required

The callback handler requires clientSecret for token exchange.

OAuth Flow

User clicks sign in
Redirected to /auth/signin
Redirected to AuthSafe
After authentication, redirected to /auth/callback?code=...&state=...
handleCallback exchanges code for tokens
Tokens stored in secure HttpOnly cookies
User redirected to original destination

Error Handling

The handler automatically handles OAuth errors:

// OAuth error from AuthSafe
// GET /auth/callback?error=access_denied&error_description=User cancelled

// Redirects to:
// /error?error=access_denied&description=User%20cancelled

Custom error page:

app.get('/error', (req, res) => {
  const { error, description } = req.query;
  res.render('error', { error, description });
});

handleLogout()

Sign out user and clear session cookies.

async function handleLogout(
  req: Request,
  res: Response,
  config: AuthSafeConfig,
): Promise<void>;

Usage

app.post('/auth/logout', (req, res) => {
  handleLogout(req, res, {
    clientId: process.env.AUTHSAFE_CLIENT_ID!,
    domain: process.env.AUTHSAFE_DOMAIN!,
  });
});

With Return URL

// POST /auth/logout?returnTo=/
app.post('/auth/logout', (req, res) => {
  handleLogout(req, res, {
    clientId: process.env.AUTHSAFE_CLIENT_ID!,
    domain: process.env.AUTHSAFE_DOMAIN!,
  });
});

Client-Side Logout

// Frontend logout button
async function logout() {
  await fetch('/auth/logout?returnTo=/', {
    method: 'POST',
    credentials: 'include',
  });
  window.location.href = '/';
}

What It Does

Retrieves ID token from cookies
Clears all auth cookies
Redirects to AuthSafe OIDC logout endpoint
AuthSafe redirects back to returnTo URL

handleRefresh()

Refresh expired access tokens using refresh token.

async function handleRefresh(
  req: Request,
  res: Response,
  config: AuthSafeConfig,
): Promise<void>;

Usage

app.post('/auth/refresh', (req, res) => {
  handleRefresh(req, res, {
    clientId: process.env.AUTHSAFE_CLIENT_ID!,
    clientSecret: process.env.AUTHSAFE_CLIENT_SECRET!,
    domain: process.env.AUTHSAFE_DOMAIN!,
  });
});

Requires Refresh Token

Include offline_access scope to receive refresh tokens.

Client-Side Refresh

async function refreshAccessToken() {
  const response = await fetch('/auth/refresh', {
    method: 'POST',
    credentials: 'include',
  });

  if (response.ok) {
    console.log('Token refreshed');
  } else {
    console.error('Refresh failed, redirect to login');
    window.location.href = '/auth/signin';
  }
}

Automatic Refresh

// Automatically refresh before expiration
setInterval(
  async () => {
    try {
      await fetch('/auth/refresh', {
        method: 'POST',
        credentials: 'include',
      });
    } catch (error) {
      console.error('Auto-refresh failed:', error);
    }
  },
  50 * 60 * 1000,
); // Every 50 minutes

Response

Success:

{
  "success": true
}

Error:

{
  "error": "refresh_failed",
  "message": "No refresh token available"
}

Complete Setup

import express from 'express';
import cookieParser from 'cookie-parser';
import {
  handleSignIn,
  handleCallback,
  handleLogout,
  handleRefresh,
} from 'authsafe-express';

const app = express();
app.use(cookieParser());

const authConfig = {
  clientId: process.env.AUTHSAFE_CLIENT_ID!,
  clientSecret: process.env.AUTHSAFE_CLIENT_SECRET!,
  domain: process.env.AUTHSAFE_DOMAIN!,
  redirectUri: `${process.env.APP_URL}/auth/callback`,
};

// Sign in
app.get('/auth/signin', (req, res) => {
  handleSignIn(req, res, authConfig);
});

// OAuth callback
app.get('/auth/callback', (req, res) => {
  handleCallback(req, res, authConfig);
});

// Logout
app.post('/auth/logout', (req, res) => {
  handleLogout(req, res, authConfig);
});

// Token refresh
app.post('/auth/refresh', (req, res) => {
  handleRefresh(req, res, authConfig);
});

app.listen(3000);

Advanced Examples

Conditional Redirect After Sign In

app.get('/auth/callback', async (req, res) => {
  // Custom logic before callback
  const { state } = req.query;

  await handleCallback(req, res, authConfig);

  // After callback, redirect based on user role
  // (Note: handleCallback already redirects, this is pseudo-code)
});

Logging

app.get('/auth/signin', (req, res) => {
  const returnTo = req.query.returnTo || '/';
  console.log(`[Auth] Sign in initiated, returnTo: ${returnTo}`);

  handleSignIn(req, res, authConfig);
});

app.get('/auth/callback', async (req, res) => {
  const { code, state } = req.query;
  console.log(
    `[Auth] Callback received, code: ${code ? 'present' : 'missing'}`,
  );

  await handleCallback(req, res, authConfig);
});

Custom Error Handling

app.get('/auth/callback', async (req, res) => {
  try {
    await handleCallback(req, res, authConfig);
  } catch (error) {
    console.error('Auth callback error:', error);
    res.redirect('/error?message=Authentication%20failed');
  }
});

Rate Limiting

import rateLimit from 'express-rate-limit';

const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 5, // 5 requests per window
  message: 'Too many authentication attempts',
});

app.get('/auth/signin', authLimiter, (req, res) => {
  handleSignIn(req, res, authConfig);
});

URL Parameters

handleSignIn

returnTo - Where to redirect after successful sign in

GET /auth/signin?returnTo=/dashboard

handleLogout

returnTo - Where to redirect after logout

POST /auth/logout?returnTo=/

Security Considerations

Use POST for logout - Prevent CSRF attacks
Validate returnTo URLs - Prevent open redirect vulnerabilities
Set secure cookies - Enable HttpOnly, SameSite, Secure flags
Use HTTPS in production - Required for secure cookies
Implement rate limiting - Prevent brute force attacks
Log auth events - Monitor for suspicious activity

Validate Return URLs

const ALLOWED_RETURN_URLS = ['/dashboard', '/profile', '/settings'];

app.get('/auth/signin', (req, res) => {
  const returnTo = req.query.returnTo as string;

  if (returnTo && !ALLOWED_RETURN_URLS.includes(returnTo)) {
    return res.status(400).json({ error: 'Invalid return URL' });
  }

  handleSignIn(req, res, authConfig);
});

Troubleshooting

Callback Fails with "Missing code verifier"

Ensure cookies are enabled and cookie-parser is applied:

app.use(cookieParser()); // Before auth routes

Redirect Loop

Check that callback URL matches configured redirect URI:

// ✅ Correct - URLs match
redirectUri: 'http://localhost:3000/auth/callback';
app.get('/auth/callback', handleCallback);

// ❌ Wrong - URLs don't match
redirectUri: 'http://localhost:3000/callback';
app.get('/auth/callback', handleCallback);

CORS Errors

Enable credentials for cross-origin requests:

import cors from 'cors';

app.use(
  cors({
    origin: process.env.FRONTEND_URL,
    credentials: true,
  }),
);

Setup - Initial configuration
Middleware - Protect routes
Session Management - Cookie management
JWT Utilities - Token verification

Route Handlers

Overview

Import

handleSignIn()

Parameters

Basic Usage

With Return URL

Custom Scopes

What It Does

handleCallback()

Usage

OAuth Flow

Error Handling

handleLogout()

Usage

With Return URL

Client-Side Logout

What It Does

handleRefresh()

Usage

Client-Side Refresh

Automatic Refresh

Response

Complete Setup

Advanced Examples

Conditional Redirect After Sign In

Logging

Custom Error Handling

Rate Limiting

URL Parameters

handleSignIn

handleLogout

Security Considerations

Validate Return URLs

Troubleshooting

Callback Fails with "Missing code verifier"

Redirect Loop

CORS Errors

Related

Route Handlers

Overview

Import

handleSignIn()

Parameters

Basic Usage

With Return URL

Custom Scopes

What It Does

handleCallback()

Usage

OAuth Flow

Error Handling

handleLogout()

Usage

With Return URL

Client-Side Logout

What It Does

handleRefresh()

Usage

Client-Side Refresh

Automatic Refresh

Response

Complete Setup

Advanced Examples

Conditional Redirect After Sign In

Logging

Custom Error Handling

Rate Limiting

URL Parameters

handleSignIn

handleLogout

Security Considerations

Validate Return URLs

Troubleshooting

Callback Fails with "Missing code verifier"

Redirect Loop

CORS Errors

Related