如何在Next.js中使用NextAuth配置Azure AD SSO SAML

一、映射Azure AD提供的信息到BoxyHQ SAML参数 #

BoxyHQ的SAML Provider所需的核心参数，可通过管理员给出的信息直接填充或获取：

• issuer：直接使用Microsoft Entra Identifier的值，即 https://sts.windows.net/1111111/
• clientId：这是你在Azure AD中注册应用的「应用（客户端）ID」，找管理员从Azure Entra的应用注册页面获取即可，不要用临时值替代
• clientSecret：让管理员在Azure Entra的应用注册页面生成一个「客户端密钥」（路径：Certificates & secrets > New client secret），生成后的密钥值就是要填的clientSecret

二、补充SAML端点配置 #

除了上述三个参数，还需添加对应管理员提供URL的配置项：

• idpSignInUrl：填入管理员给的Login URL：https://login.microsoftonline.com/11111111/saml2
• idpSignOutUrl：填入管理员给的Logout URL：https://login.microsoftonline.com/111111/saml2
• idpIssuer：与前面的issuer保持一致，即 https://sts.windows.net/1111111/

另外，务必把你的应用回调URL（开发环境为http://localhost:3000/api/auth/callback/saml，生产环境替换为你的域名对应路径）告知管理员，让其添加到Azure AD应用的「回复URL（Assertion Consumer Service URL）」中，否则登录会失败。

三、解决元数据缺失问题 #

没有元数据文件的话，手动编写一个简化版的SAML元数据XML即可，保存为aad-saml-metadata.xml放在项目根目录：

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://sts.windows.net/1111111/">
  <md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://login.microsoftonline.com/11111111/saml2"/>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://login.microsoftonline.com/111111/saml2"/>
  </md:IDPSSODescriptor>
</md:EntityDescriptor>

之后在NextAuth配置中，通过idpMetadata参数读取这个文件，或者直接传入XML字符串即可。

四、NextAuth配置代码示例 #

Pages Router（pages/api/auth/[...nextauth].js） #

import NextAuth from "next-auth";
import BoxyHQSAML from "@boxyhq/saml-nextauth/provider";
import fs from "fs";

export default NextAuth({
  providers: [
    BoxyHQSAML({
      issuer: "https://sts.windows.net/1111111/",
      clientId: "你的Azure应用客户端ID", // 替换为管理员提供的值
      clientSecret: "你的Azure应用客户端密钥", // 替换为管理员提供的值
      idpSignInUrl: "https://login.microsoftonline.com/11111111/saml2",
      idpSignOutUrl: "https://login.microsoftonline.com/111111/saml2",
      idpIssuer: "https://sts.windows.net/1111111/",
      // 启用手动元数据，取消下面注释
      // idpMetadata: fs.readFileSync("./aad-saml-metadata.xml", "utf8"),
      callbackUrl: "http://localhost:3000/api/auth/callback/saml",
    }),
  ],
  secret: process.env.NEXTAUTH_SECRET, // 在.env中设置，可用`openssl rand -hex 32`生成随机值
});

App Router（app/api/auth/[...nextauth]/route.js） #

import NextAuth from "next-auth";
import BoxyHQSAML from "@boxyhq/saml-nextauth/provider";
import fs from "fs";
import path from "path";

const handler = NextAuth({
  providers: [
    BoxyHQSAML({
      issuer: "https://sts.windows.net/1111111/",
      clientId: "你的Azure应用客户端ID",
      clientSecret: "你的Azure应用客户端密钥",
      idpSignInUrl: "https://login.microsoftonline.com/11111111/saml2",
      idpSignOutUrl: "https://login.microsoftonline.com/111111/saml2",
      idpIssuer: "https://sts.windows.net/1111111/",
      idpMetadata: fs.readFileSync(path.join(process.cwd(), "aad-saml-metadata.xml"), "utf8"),
      callbackUrl: "https://你的生产域名/api/auth/callback/saml",
    }),
  ],
  secret: process.env.NEXTAUTH_SECRET,
});

export { handler as GET, handler as POST };

关键注意事项 #

• 必须让管理员将你的回调URL添加到Azure AD应用的SAML回复URL列表中，否则登录请求会被拒绝
• 如果Azure AD使用证书签名SAML断言，需要让管理员下载Azure AD的SAML证书，提取公钥后添加到BoxyHQ配置的idpPublicCert参数中
• NEXTAUTH_SECRET是必填环境变量，没有它NextAuth无法正常运行，生成方式为在终端执行openssl rand -hex 32，将输出的随机字符串填入.env文件

内容的提问来源于stack exchange，提问作者Kyaw Soe Hein