Next-Auth 与 Azure AD B2C 集成问题解析与解决方案

问题背景

在使用 Next.js 框架开发应用时，许多开发者会选择 Next-Auth 作为身份验证解决方案。当尝试将 Next-Auth 与 Azure AD B2C 集成时，开发者可能会遇到一个常见错误："Cannot read properties of undefined (reading 'substring')"。这个错误通常发生在应用启动阶段，导致整个身份验证流程无法正常工作。

错误分析

该错误的核心问题在于 oidc-token-hash 库中的 shake256.js 文件在处理某些未定义的变量时尝试调用 substring 方法。这通常表明：

1. 身份验证流程中的某些关键配置缺失或不正确
2. 中间件处理过程中出现了意外的变量状态
3. 依赖库之间的版本兼容性问题

解决方案实现

1. 创建 SessionProvider 组件

首先需要创建一个封装了 NextAuth 会话提供者的 React 组件：

'use client';
import { SessionProvider as NextAuthSessionProvider } from "next-auth/react";

export function SessionProvider({ children }: { children: React.ReactNode }) {
    return <NextAuthSessionProvider>{children}</NextAuthSessionProvider>;
}

这个组件将作为应用的身份验证上下文提供者，管理整个应用的会话状态。

2. 配置 API 路由

在 Next.js 的 API 路由中设置身份验证端点：

import NextAuth from "next-auth"
import { authOptions } from "@/lib/auth/auth-options"

const handler = NextAuth(authOptions)
export { handler as GET, handler as POST }

这里使用了 TypeScript 的 @ts-ignore 来忽略某些类型检查问题，这在开发阶段是可以接受的临时解决方案。

3. 核心身份验证配置

完整的 auth-options.ts 配置应该包含以下关键部分：

import { jwtDecode } from "jwt-decode";
import { DefaultSession } from "next-auth";
import AzureADB2C from "next-auth/providers/azure-ad-b2c"
import CredentialsProvider from "next-auth/providers/credentials"

// 环境变量配置
const B2C_TENANT = process.env.AZURE_AD_B2C_TENANT!;
const CLIENT_ID = process.env.AZURE_AD_B2C_CLIENT_ID!;
const POLICY_NAME = process.env.AZURE_AD_B2C_POLICY_NAME!;

// 类型扩展
declare module "next-auth" {
    interface Session {
        accessToken?: string;
        idToken?: string;
        user: {
            id: string;
            name?: string | null;
            email?: string | null;
            image?: string | null;
            roles?: string[];
        } & DefaultSession["user"];
    }

    interface User {
        accessToken?: string;
        idToken?: string;
        roles?: string[];
    }
}

// 身份验证选项配置
export const authOptions = {
    providers: [
        // 凭证提供者配置
        CredentialsProvider({
            id: "azure-ad-b2c-ropc",
            name: "Credentials",
            credentials: {
                email: { label: "Email", type: "text" },
                password: { label: "Password", type: "password" }
            },
            async authorize(credentials) {
                // 授权逻辑实现
            }
        }),
        // Azure AD B2C 提供者配置
        AzureADB2C({
            clientId: process.env.AZURE_AD_B2C_CLIENT_ID!,
            clientSecret: process.env.AZURE_AD_B2C_CLIENT_SECRET!,
            tenantId: process.env.AZURE_AD_B2C_TENANT!,
        })
    ],
    callbacks: {
        // JWT 回调处理
        async jwt({ token, user, profile }) {
            // JWT 处理逻辑
        },
        // 会话回调处理
        async session({ session, token }) {
            // 会话处理逻辑
        }
    },
    events: {
        // 登出事件处理
        async signOut({session, token}) {
            // 清理会话数据
        },
    }
}

关键实现细节

1. 类型扩展：通过扩展 NextAuth 的类型定义，我们能够支持 Azure AD B2C 特有的令牌和角色信息。

2. 多提供者配置：同时配置了凭证提供者和 Azure AD B2C 提供者，支持多种身份验证方式。

3. 令牌处理：在 JWT 回调中处理访问令牌和 ID 令牌，确保这些关键信息能够正确传递到会话中。

4. 用户数据持久化：在身份验证过程中自动创建或更新用户记录到数据库，并记录相关日志。

5. 会话管理：在会话回调中确保用户 ID 和角色信息能够正确传递到客户端。

最佳实践建议

1. 环境变量验证：在应用启动时验证所有必需的 Azure AD B2C 配置变量是否已设置。

2. 错误处理：增强授权逻辑中的错误处理，提供更友好的错误消息。

3. 日志记录：在关键操作点添加详细的日志记录，便于问题排查。

4. 安全考虑：确保敏感令牌信息在前端的存储和使用符合安全最佳实践。

5. 性能优化：对于频繁调用的数据库操作，考虑添加缓存层。

通过以上配置和实现，开发者可以成功解决 Next-Auth 与 Azure AD B2C 集成时的常见问题，构建稳定可靠的身份验证系统。