Express SDK

Official Express.js middleware for OAuth 2.1, OIDC, and MFA authentication.

Overview

The authsafe-express package provides production-ready middleware and route handlers for implementing authentication in Express.js applications. Built with TypeScript, it offers complete OAuth 2.1 and OpenID Connect support with automatic token management and JWT verification.

Modern Authentication Made Simple

Drop-in middleware with PKCE, automatic token refresh, and scope-based authorization.

Features

🔐 OAuth 2.1 & OIDC - Full compliance with latest standards
🛡️ PKCE Flow - Automatic code challenge generation
🔄 Token Management - Automatic refresh with secure cookie storage
🎯 Scope-based Auth - Fine-grained permission control
⚡ JWT Verification - JWKS caching for optimal performance
🍪 Secure Cookies - HttpOnly, SameSite, Secure flags
📦 Middleware First - Express-native design patterns
🔧 TypeScript - Full type safety and IntelliSense

Installation

npm install authsafe-express cookie-parser

yarn add authsafe-express cookie-parser

pnpm add authsafe-express cookie-parser

The SDK requires cookie-parser middleware for session management.

Quick Start

1. Configure Environment

# .env
AUTHSAFE_CLIENT_ID=your_client_id
AUTHSAFE_CLIENT_SECRET=your_client_secret
AUTHSAFE_DOMAIN=https://auth.yourapp.com
APP_URL=http://localhost:3000

2. Initialize Middleware

import express from 'express';
import cookieParser from 'cookie-parser';
import { initAuthSafe, requireAuth } from 'authsafe-express';

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

// Initialize AuthSafe
initAuthSafe({
  clientId: process.env.AUTHSAFE_CLIENT_ID!,
  clientSecret: process.env.AUTHSAFE_CLIENT_SECRET!,
  domain: process.env.AUTHSAFE_DOMAIN!,
  redirectUri: `${process.env.APP_URL}/auth/callback`,
});

3. Add Authentication Routes

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

// Sign in route
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`,
  });
});

// OAuth callback
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`,
  });
});

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

4. Protect Routes

import { requireAuth } from 'authsafe-express';

// Protected route
app.get('/dashboard', requireAuth(), (req, res) => {
  res.json({
    message: `Welcome ${req.auth.email}`,
    user: req.auth,
  });
});

5. Start Server

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

SDK Reference

Middleware

Function	Description
`initAuthSafe()`	Initialize global configuration
`requireAuth()`	Require authentication for route
`optionalAuth()`	Attach auth session if available
`requireScope()`	Require specific scopes
`requireAnyScope()`	Require any of specified scopes

See Middleware documentation for details.

Route Handlers

Function	Route	Description
`handleSignIn()`	GET /auth/signin	Initiate OAuth flow
`handleCallback()`	GET /auth/callback	Process OAuth callback
`handleLogout()`	POST /auth/logout	Sign out and clear session
`handleRefresh()`	POST /auth/refresh	Refresh access tokens

See Route Handlers documentation for details.

Session Management

Function	Description
`setAuthCookies()`	Store tokens in secure cookies
`getAuthCookies()`	Retrieve tokens from cookies
`clearAuthCookies()`	Clear all auth cookies
`refreshTokens()`	Refresh using refresh token

See Session Management documentation for details.

JWT Utilities

Function	Description
`verifyToken()`	Verify JWT signature with JWKS
`decodeToken()`	Decode JWT without verification
`extractUserId()`	Extract user ID from subject
`isClientToken()`	Check if token is M2M client
`isTokenExpired()`	Check token expiration
`shouldRefreshToken()`	Check if refresh needed

See JWT Utilities documentation for details.

Complete Example

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

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

// Initialize AuthSafe
initAuthSafe({
  clientId: process.env.AUTHSAFE_CLIENT_ID!,
  clientSecret: process.env.AUTHSAFE_CLIENT_SECRET!,
  domain: process.env.AUTHSAFE_DOMAIN!,
  redirectUri: `${process.env.APP_URL}/auth/callback`,
  scopes: ['openid', 'email', 'profile', 'offline_access'],
});

// Auth routes
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`,
  });
});

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`,
  });
});

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

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!,
  });
});

// Public route
app.get('/', optionalAuth(), (req, res) => {
  if (req.auth) {
    res.json({ message: `Hello ${req.auth.email}` });
  } else {
    res.json({ message: 'Hello guest' });
  }
});

// Protected route
app.get('/dashboard', requireAuth(), (req, res) => {
  res.json({
    message: 'Dashboard',
    user: req.auth,
  });
});

// Protected with scope
app.delete(
  '/admin/users/:id',
  requireAuth(),
  requireScope('admin:delete'),
  (req, res) => {
    res.json({ message: 'User deleted' });
  },
);

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

TypeScript Support

Full TypeScript support with type definitions:

import type {
  AuthSafeConfig,
  AuthSession,
  AuthTokens,
  AuthenticatedRequest,
  AuthSafeJWTPayload,
} from 'authsafe-express';

// Extend Express Request
app.get('/profile', requireAuth(), (req: AuthenticatedRequest, res) => {
  const { userId, email, scopes } = req.auth;
  res.json({ userId, email, scopes });
});

Security Best Practices

Use HTTPS in production - Enable secure cookies
Store secrets safely - Use environment variables
Enable CSRF protection - Use POST for logout/refresh
Implement rate limiting - Protect auth endpoints
Set cookie security - HttpOnly, SameSite, Secure
Validate scopes - Use requireScope() middleware
Handle errors - Implement proper error handling

Browser Support

Node.js 18+
Express 4.x and 5.x

Next Steps

Ready to Build!

Start with the Setup Guide for detailed configuration options.

Setup & Configuration - Complete setup guide
Middleware - Authentication middleware
Route Handlers - OAuth flow handlers
Session Management - Cookie and token management
JWT Utilities - Token verification utilities

Support

📚 Documentation: AuthSafe Docs
💬 Community: Discord Server
🐛 Issues: GitLab Issues
📧 Email: support@authsafe.in