Custom auth provider
Custom auth providers allow you to implement authentication for identity systems that aren't covered by the built-in providers. Extend the MastraAuthProvider base class to integrate with any authentication system.
OverviewDirect link to Overview
Auth providers handle authentication and authorization for incoming requests:
- Token verification and user extraction
- User authorization logic
- Path-based access control (public/protected routes)
Create custom auth providers to support:
- Self-hosted identity systems
- Custom token formats or verification logic
- Specialized authorization rules
- Enterprise SSO integrations
Creating a custom auth providerDirect link to Creating a custom auth provider
Extend the MastraAuthProvider class and implement the required methods:
import { MastraAuthProvider } from '@mastra/core/server'
import type { MastraAuthProviderOptions, MastraAuthRequest } from '@mastra/core/server'
// Define your user type
type MyUser = {
id: string
email: string
roles: string[]
}
// Define options for your provider
interface MyAuthOptions extends MastraAuthProviderOptions<MyUser> {
apiUrl?: string
apiKey?: string
}
export class MyAuthProvider extends MastraAuthProvider<MyUser> {
protected apiUrl: string
protected apiKey: string
constructor(options?: MyAuthOptions) {
// Call super with a name for logging/debugging
super({ name: options?.name ?? 'my-auth' })
const apiUrl = options?.apiUrl ?? process.env.MY_AUTH_API_URL
const apiKey = options?.apiKey ?? process.env.MY_AUTH_API_KEY
if (!apiUrl || !apiKey) {
throw new Error(
'Auth API URL and API key are required. Provide them in options or set MY_AUTH_API_URL and MY_AUTH_API_KEY environment variables.',
)
}
this.apiUrl = apiUrl
this.apiKey = apiKey
// Register any custom options (authorizeUser override, public/protected paths)
this.registerOptions(options)
}
/**
* Verify the token and return the user
* Return null if authentication fails
*/
async authenticateToken(token: string, request: MastraAuthRequest): Promise<MyUser | null> {
try {
const response = await fetch(`${this.apiUrl}/verify`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': this.apiKey,
},
body: JSON.stringify({ token }),
})
if (!response.ok) {
return null
}
const user = await response.json()
return user
} catch (error) {
console.error('Token verification failed:', error)
return null
}
}
/**
* Check if the authenticated user is authorized
* Return true to allow access, false to deny
*/
async authorizeUser(user: MyUser, request: MastraAuthRequest): Promise<boolean> {
// Basic authorization: user must exist and have an ID
return !!user?.id
}
}
Required methodsDirect link to Required methods
authenticateToken()Direct link to authenticatetoken
Verify the incoming token and return the user object if valid, or null if authentication fails.
async authenticateToken(token: string, request: MastraAuthRequest): Promise<TUser | null>
| Parameter | Type | Description |
|---|---|---|
token | string | The bearer token extracted from the Authorization header |
request | MastraAuthRequest | The incoming request. Read headers with getRequestHeader() and the underlying web Request with getWebRequest(), both exported from @mastra/core/server |
Returns: The user object if authentication succeeds, or null if it fails.
The token is automatically extracted from the Authorization: Bearer <token> header. If you need to access other headers or cookies, use the request parameter.
authorizeUser()Direct link to authorizeuser
Determine if the authenticated user is allowed to access the resource.
async authorizeUser(user: TUser, request: MastraAuthRequest): Promise<boolean> | boolean
| Parameter | Type | Description |
|---|---|---|
user | TUser | The user object returned by authenticateToken |
request | MastraAuthRequest | The incoming request |
Returns: true to allow access, false to deny (returns 403 Forbidden).
Optional methodsDirect link to Optional methods
toMastraUser()Direct link to tomastrauser
Normalize your provider-specific user object to the stable MastraUser shape that dynamic configuration callbacks (such as dynamic instructions, model, or tools) receive as the optional user argument.
toMastraUser(user: TUser): MastraUser
| Parameter | Type | Description |
|---|---|---|
user | TUser | The user object returned by authenticateToken |
Returns: A MastraUser object: { id: string, name?: string, email?: string, avatarUrl?: string, role?: string }.
The default implementation picks id from id, sub, or userId, avatarUrl from avatarUrl or picture, and passes name, email, and role through when present. Override it when your user type stores these fields elsewhere:
import type { MastraUser } from '@mastra/core/auth'
export class MyAuthProvider extends MastraAuthProvider<MyUser> {
async authenticateToken(token: string) {
/* ... */
}
toMastraUser(user: MyUser): MastraUser {
return {
id: user.accountId,
name: user.profile.displayName,
role: user.permissions.primaryRole,
}
}
}
If no id can be derived from the user object, the normalized user is omitted and callbacks receive user: undefined. The raw user object remains available on the request context.
Optional methods for MCP OAuthDirect link to Optional methods for MCP OAuth
The built-in MCP server uses two optional methods for OAuth discovery and audience checks.
getOAuthMetadata() returns the authorization servers, and optionally scopes, that MCP clients should use. server.mcp.oauth.authorizationServers and server.mcp.oauth.scopesSupported take precedence.
getOAuthMetadata(): { authorizationServers?: string[]; scopesSupported?: string[] } | undefined
verifyAudience() runs on /api/mcp when server.mcp.oauth.resource is set. It receives the value authenticateToken() returned and the resource URL, and returns whether the token was issued for it. Returning false rejects the request with a 401. Without this method the audience isn't checked, and Mastra logs a warning.
verifyAudience(user: TUser, audience: string): boolean | Promise<boolean>
For a JWT provider whose authenticateToken() returns the verified payload:
getOAuthMetadata() {
return { authorizationServers: ['https://auth.example.com/'] }
}
verifyAudience(user: JwtPayload, audience: string) {
return Array.isArray(user.aud) ? user.aud.includes(audience) : user.aud === audience
}
Configuration optionsDirect link to Configuration options
The MastraAuthProviderOptions interface supports these options:
| Option | Type | Description |
|---|---|---|
name | string | Provider name for logging/debugging |
authorizeUser | (user, request) => Promise<boolean> | boolean | Custom authorization function |
protected | (RegExp | string | [string, Methods | Methods[]])[] | Paths that require authentication |
public | (RegExp | string | [string, Methods | Methods[]])[] | Paths that bypass authentication, unless the route sets requiresAuth: true |
Path PatternsDirect link to Path Patterns
Configure which paths require authentication using pattern matching:
const auth = new MyAuthProvider({
// Paths that require authentication
protected: [
'/api/*', // Wildcard: all /api routes
'/admin/*', // Wildcard: all /admin routes
/^\/secure\/.*/, // Regex pattern
],
// Paths that bypass authentication
public: [
'/health', // Exact match
'/api/status', // Exact match
['/api/webhook', 'POST'], // Only POST requests to /api/webhook
],
})
Using your auth providerDirect link to Using your auth provider
Register your custom auth provider with the Mastra instance:
import { Mastra } from '@mastra/core'
import { MyAuthProvider } from './my-auth-provider'
export const mastra = new Mastra({
server: {
auth: new MyAuthProvider({
apiUrl: process.env.MY_AUTH_API_URL,
apiKey: process.env.MY_AUTH_API_KEY,
}),
},
})
Helper utilitiesDirect link to Helper utilities
The @mastra/auth package provides utilities for common token verification patterns:
JWT VerificationDirect link to JWT Verification
import { verifyHmac, verifyJwks, decodeToken, getTokenIssuer } from '@mastra/auth'
// Verify HMAC-signed JWT
const payload = await verifyHmac(token, 'your-secret-key')
// Verify with JWKS (for OAuth providers)
const payload = await verifyJwks(token, 'https://provider.com/.well-known/jwks.json')
// Decode without verification (for inspection)
const decoded = await decodeToken(token)
// Get the issuer from a decoded token
const issuer = getTokenIssuer(decoded)
Example: JWKS-based ProviderDirect link to Example: JWKS-based Provider
import { MastraAuthProvider } from '@mastra/core/server'
import type { MastraAuthProviderOptions } from '@mastra/core/server'
import { verifyJwks } from '@mastra/auth'
import type { JwtPayload } from '@mastra/auth'
type MyUser = JwtPayload
interface MyJwksAuthOptions extends MastraAuthProviderOptions<MyUser> {
jwksUri?: string
issuer?: string
}
export class MyJwksAuth extends MastraAuthProvider<MyUser> {
protected jwksUri: string
protected issuer: string
constructor(options?: MyJwksAuthOptions) {
super({ name: options?.name ?? 'my-jwks-auth' })
const jwksUri = options?.jwksUri ?? process.env.MY_JWKS_URI
const issuer = options?.issuer ?? process.env.MY_AUTH_ISSUER
if (!jwksUri) {
throw new Error('JWKS URI is required')
}
this.jwksUri = jwksUri
this.issuer = issuer ?? ''
this.registerOptions(options)
}
async authenticateToken(token: string): Promise<MyUser | null> {
try {
const payload = await verifyJwks(token, this.jwksUri)
// Optionally validate issuer
if (this.issuer && payload.iss !== this.issuer) {
return null
}
return payload
} catch {
return null
}
}
async authorizeUser(user: MyUser): Promise<boolean> {
// Check token hasn't expired
if (user.exp && user.exp * 1000 < Date.now()) {
return false
}
return !!user.sub
}
}
Custom authorization logicDirect link to Custom authorization logic
Override the default authorization by providing a custom authorizeUser function:
const auth = new MyAuthProvider({
apiUrl: process.env.MY_AUTH_API_URL,
apiKey: process.env.MY_AUTH_API_KEY,
// Custom authorization: require admin role for all requests
async authorizeUser(user, request) {
return user.roles.includes('admin')
},
})
Role-based AuthorizationDirect link to Role-based Authorization
import { getWebRequest } from '@mastra/core/server'
const auth = new MyAuthProvider({
async authorizeUser(user, request) {
const webRequest = getWebRequest(request)
if (!webRequest) {
return false
}
const path = new URL(webRequest.url).pathname
const method = webRequest.method
// Admin routes require admin role
if (path.startsWith('/admin/')) {
return user.roles.includes('admin')
}
// Write operations require write role
if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
return user.roles.includes('write') || user.roles.includes('admin')
}
// Read operations allowed for all authenticated users
return true
},
})
Testing custom auth providersDirect link to Testing custom auth providers
Example test structure using Vitest:
import { describe, it, expect, vi, beforeEach } from 'vitest'
import { MyAuthProvider } from './my-auth-provider'
// Mock fetch for API calls
global.fetch = vi.fn()
describe('MyAuthProvider', () => {
const mockOptions = {
apiUrl: 'https://auth.example.com',
apiKey: 'test-api-key',
}
beforeEach(() => {
vi.clearAllMocks()
})
describe('initialization', () => {
it('should initialize with provided options', () => {
const auth = new MyAuthProvider(mockOptions)
expect(auth).toBeInstanceOf(MyAuthProvider)
})
it('should throw error when required options are missing', () => {
expect(() => new MyAuthProvider({})).toThrow('Auth API URL and API key are required')
})
})
describe('authenticateToken', () => {
it('should return user when token is valid', async () => {
const mockUser = { id: 'user123', email: 'test@example.com', roles: ['read'] }
;(fetch as any).mockResolvedValue({
ok: true,
json: () => Promise.resolve(mockUser),
})
const auth = new MyAuthProvider(mockOptions)
const result = await auth.authenticateToken('valid-token', {} as any)
expect(fetch).toHaveBeenCalledWith(
'https://auth.example.com/verify',
expect.objectContaining({
method: 'POST',
body: JSON.stringify({ token: 'valid-token' }),
}),
)
expect(result).toEqual(mockUser)
})
it('should return null when token is invalid', async () => {
;(fetch as any).mockResolvedValue({ ok: false })
const auth = new MyAuthProvider(mockOptions)
const result = await auth.authenticateToken('invalid-token', {} as any)
expect(result).toBeNull()
})
})
describe('authorizeUser', () => {
it('should return true when user has valid id', async () => {
const auth = new MyAuthProvider(mockOptions)
const result = await auth.authorizeUser(
{ id: 'user123', email: 'test@example.com', roles: [] },
{} as any,
)
expect(result).toBe(true)
})
it('should return false when user has no id', async () => {
const auth = new MyAuthProvider(mockOptions)
const result = await auth.authorizeUser(
{ id: '', email: 'test@example.com', roles: [] },
{} as any,
)
expect(result).toBe(false)
})
})
describe('custom authorization', () => {
it('should use custom authorizeUser when provided', async () => {
const auth = new MyAuthProvider({
...mockOptions,
authorizeUser: user => user.roles.includes('admin'),
})
const adminUser = { id: 'user123', email: 'admin@example.com', roles: ['admin'] }
const regularUser = { id: 'user456', email: 'user@example.com', roles: ['read'] }
expect(await auth.authorizeUser(adminUser, {} as any)).toBe(true)
expect(await auth.authorizeUser(regularUser, {} as any)).toBe(false)
})
})
describe('route configuration', () => {
it('should store public routes configuration', () => {
const publicRoutes = ['/health', '/api/status']
const auth = new MyAuthProvider({
...mockOptions,
public: publicRoutes,
})
expect(auth.public).toEqual(publicRoutes)
})
it('should store protected routes configuration', () => {
const protectedRoutes = ['/api/*', '/admin/*']
const auth = new MyAuthProvider({
...mockOptions,
protected: protectedRoutes,
})
expect(auth.protected).toEqual(protectedRoutes)
})
})
})
Error handlingDirect link to Error handling
Provide descriptive errors for common failure scenarios:
export class MyAuthProvider extends MastraAuthProvider<MyUser> {
constructor(options?: MyAuthOptions) {
super({ name: options?.name ?? 'my-auth' })
const apiUrl = options?.apiUrl ?? process.env.MY_AUTH_API_URL
const apiKey = options?.apiKey ?? process.env.MY_AUTH_API_KEY
if (!apiUrl) {
throw new Error(
'Missing MY_AUTH_API_URL. Set the environment variable or pass apiUrl in options.',
)
}
if (!apiKey) {
throw new Error(
'Missing MY_AUTH_API_KEY. Set the environment variable or pass apiKey in options.',
)
}
this.apiUrl = apiUrl
this.apiKey = apiKey
this.registerOptions(options)
}
async authenticateToken(token: string): Promise<MyUser | null> {
if (!token || typeof token !== 'string') {
return null // Immediate safe fail
}
try {
const response = await fetch(`${this.apiUrl}/verify`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': this.apiKey,
},
body: JSON.stringify({ token }),
})
if (!response.ok) {
return null
}
return await response.json()
} catch (error) {
// Log error for debugging, but don't expose details to client
console.error('Auth verification error:', error)
return null
}
}
}
Built-in providersDirect link to Built-in providers
Mastra includes these auth providers as reference implementations:
- MastraJwtAuth: Simple JWT verification with HMAC secrets (
@mastra/auth) - MastraAuthClerk: Clerk authentication (
@mastra/auth-clerk) - MastraAuthAuth0: Auth0 authentication (
@mastra/auth-auth0) - MastraAuthSupabase: Supabase authentication (
@mastra/auth-supabase) - MastraAuthFirebase: Firebase authentication (
@mastra/auth-firebase) - MastraAuthWorkos: WorkOS authentication (
@mastra/auth-workos) - MastraAuthBetterAuth: Better Auth integration (
@mastra/auth-better-auth) - SimpleAuth: Token-to-user mapping for development (
@mastra/core/server)
See the source code for implementation details.
RelatedDirect link to Related
- Auth Overview: Authentication concepts and configuration
- Custom API Routes: Controlling authentication on custom endpoints