Skip to main content

​
Overview

The createExpressAuthMiddleware function creates an Express middleware that automatically verifies Logto authentication tokens and attaches authentication context to the request object.

​
Signature

function createExpressAuthMiddleware(
  options: VerifyAuthOptions
): (req: ExpressRequest, res: ExpressResponse, next: ExpressNext) => void

​
Parameters

​
options
VerifyAuthOptions
required
Configuration options for token verification

​
Returns

​
middleware
ExpressMiddleware
Express middleware function that can be used with app.use() or route handlers

​
Request Enhancement

The middleware adds an auth property to the Express request object: 
req.auth: AuthContext

​
Examples

​
Basic Setup

import express from 'express'
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE
})

// Apply to all routes
app.use(authMiddleware)

app.get('/profile', (req, res) => {
  res.json({
    userId: req.auth.userId,
    authenticated: req.auth.isAuthenticated
  })
})

app.listen(3000)

​
Protected Routes Only

import express from 'express'
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE
})

// Public route (no auth required)
app.get('/public', (req, res) => {
  res.json({ message: 'Public endpoint' })
})

// Protected routes
app.get('/api/user', authMiddleware, (req, res) => {
  res.json({ userId: req.auth.userId })
})

app.post('/api/data', authMiddleware, (req, res) => {
  const userId = req.auth.userId
  // Handle authenticated request
  res.json({ success: true })
})

​
With Guest Support

import express from 'express'
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE,
  allowGuest: true // Allow unauthenticated access
})

app.use(authMiddleware)

app.get('/api/content', (req, res) => {
  if (req.auth.isGuest) {
    res.json({
      message: 'Limited content for guests',
      guestId: req.auth.guestId
    })
  } else {
    res.json({
      message: 'Full content for authenticated users',
      userId: req.auth.userId
    })
  }
})

​
With Required Scope

import express from 'express'
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const app = express()

const adminAuthMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE,
  requiredScope: 'admin:write'
})

// Admin-only endpoint
app.delete('/api/users/:id', adminAuthMiddleware, (req, res) => {
  // Only users with admin:write scope can access this
  res.json({ success: true })
})

import express from 'express'
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE,
  cookieName: 'my_custom_auth_cookie'
})

app.use(authMiddleware)

​
Error Handling

import express from 'express'
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE
})

app.use(authMiddleware)

// Authentication errors return 401 automatically
// Add error handler for custom error responses
app.use((err, req, res, next) => {
  if (err.status === 401) {
    res.status(401).json({
      error: 'Unauthorized',
      message: 'Please sign in to access this resource'
    })
  } else {
    next(err)
  }
})

​
Behavior

​
Token Extraction

The middleware extracts tokens in this order:
  1. Cookie (using cookieName option, defaults to logto_authtoken)
  2. Authorization header (Bearer token)

​
Authentication Responses

When allowGuest: false (default):
  • No token found: Returns 401 with error message
  • Invalid token: Returns 401 with error details
  • Valid token: Attaches AuthContext to req.auth and calls next()
When allowGuest: true:
  • No token found: Attaches guest AuthContext to req.auth and calls next()
  • Invalid token: Attaches guest AuthContext to req.auth and calls next()
  • Valid token: Attaches authenticated AuthContext to req.auth and calls next()
The middleware automatically handles cookie parsing:
  • If cookies are not already parsed, it applies cookie-parser internally
  • No need to manually add cookie-parser middleware when using this middleware

​
TypeScript Support

Extend the Express request type to include the auth property: 
import type { AuthContext } from '@ouim/logto-authkit/server'

declare global {
  namespace Express {
    interface Request {
      auth: AuthContext
    }
  }
}

​
See Also