自定义认证提供商

🌐 Custom Auth Providers

自定义身份验证提供程序允许你为内置提供程序未涵盖的身份系统实现身份验证。通过扩展 MastraAuthProvider 基类，可以与任何身份验证系统集成。

🌐 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.

概述

🌐 Overview

身份验证提供商处理传入请求的认证和授权：

🌐 Auth providers handle authentication and authorization for incoming requests:

• 令牌验证和用户提取
• 用户授权逻辑
• 基于路径的访问控制（公共/受保护路由）

创建自定义身份验证提供程序以支持：

🌐 Create custom auth providers to support:

• 自托管身份系统
• 自定义令牌格式或验证逻辑
• 专门授权规则
• 企业单点登录集成

创建自定义认证提供程序

🌐 Creating a Custom Auth Provider

扩展 MastraAuthProvider 类并实现所需的方法：

🌐 Extend the MastraAuthProvider class and implement the required methods:

import { MastraAuthProvider } from '@mastra/core/server';
import type { MastraAuthProviderOptions } from '@mastra/core/server';
import type { HonoRequest } from 'hono';

// 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: HonoRequest): 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: HonoRequest): Promise<boolean> {
    // Basic authorization: user must exist and have an ID
    return !!user?.id;
  }
}

必需的方法

🌐 Required Methods

authenticateToken()

验证传入的令牌，如果有效则返回用户对象，如果身份验证失败则返回 null。

🌐 Verify the incoming token and return the user object if valid, or null if authentication fails.

async authenticateToken(token: string, request: HonoRequest): Promise<TUser | null>

参数	类型	描述
token	string	从 Authorization 头部提取的承载令牌
request	HonoRequest	传入的请求对象（访问头部、Cookies 等）

返回值：如果认证成功，返回用户对象；如果失败，返回 null。

该令牌会自动从 Authorization: Bearer <token> 头中提取。如果需要访问其他头或 cookie，请使用 request 参数。

🌐 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()

确定经过身份验证的用户是否被允许访问该资源。

🌐 Determine if the authenticated user is allowed to access the resource.

async authorizeUser(user: TUser, request: HonoRequest): Promise<boolean> | boolean

参数	类型	描述
user	TUser	由 authenticateToken 返回的用户对象
request	HonoRequest	传入的请求对象

返回值：true 表示允许访问，false 表示拒绝访问（返回 403 禁止）。

配置选项

🌐 Configuration Options

MastraAuthProviderOptions 接口支持以下选项：

🌐 The MastraAuthProviderOptions interface supports these options:

选项	类型	描述
name	string	用于日志记录/调试的提供商名称
authorizeUser	(user, request) => Promise<boolean> | boolean	自定义授权函数
protected	(RegExp | string | [string, Methods | Methods[]])[]	需要身份验证的路径
public	(RegExp | string | [string, Methods | Methods[]])[]	绕过身份验证的路径

路径模式

🌐 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 Provider

在 Mastra 实例中注册你的自定义认证提供程序：

🌐 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 Utilities

@mastra/auth 包提供了常用令牌验证模式的工具：

🌐 The @mastra/auth package provides utilities for common token verification patterns:

JWT 验证

🌐 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);

示例：基于 JWKS 的提供商

🌐 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 Logic

通过提供自定义的 authorizeUser 函数来覆盖默认授权：

🌐 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 Authorization

const auth = new MyAuthProvider({
  async authorizeUser(user, request) {
    const path = request.url;
    const method = request.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 Providers

使用 Vitest 的示例测试结构：

🌐 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 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 Providers

Mastra 包含这些身份验证提供商作为参考实现：

🌐 Mastra includes these auth providers as reference implementations:

• MastraJwtAuth：使用 HMAC 密钥（@mastra/auth）的简单 JWT 验证
• MastraAuthClerk：职员认证（@mastra/auth-clerk）
• MastraAuthAuth0：Auth0 认证（@mastra/auth-auth0）
• MastraAuthSupabase：Supabase 认证（@mastra/auth-supabase）
• MastraAuthFirebase：Firebase 身份验证（@mastra/auth-firebase）
• MastraAuthWorkOS：WorkOS 认证（@mastra/auth-workos）
• MastraAuthBetterAuth：更好的身份验证集成（@mastra/auth-better-auth）
• SimpleAuth：用于开发的令牌到用户映射（@mastra/core/server）

有关实现细节，请参见源代码。

🌐 See the source code for implementation details.

相关

🌐 Related

• 认证概述 - 认证概念和配置
• JWT 认证 - 简单的 JWT 身份验证
• Clerk Auth - Clerk 集成
• 自定义 API 路由 - 控制自定义端点的身份验证