NestJS Swagger UI预设Azure OAuth2的ClientId与Scope实现问询

问题背景 #

需要通过Swagger UI完成Azure AD授权获取accessToken，当前手动输入ClientId并勾选Scope时流程正常。由于ClientId和Scope为静态值，希望实现两种效果之一：

1. 绕过授权弹窗直接触发「Authorize」按钮完成授权
2. 至少预填授权表单，用户仅需点击「Authorize」即可完成授权

已尝试initOAuth配置和DocumentBuilder.components.requestBodies方案，均未达到预期效果。

现有配置代码 #

// Swagger
const config = new DocumentBuilder()
  .setTitle('Auth Backend')
  .setDescription('Azure PoC backend')
  .setVersion('0.1')
  .addTag('auth')
  .addOAuth2({
    type: "oauth2",
    description: "description",
    name: "AzureAD",
    flows: {
      implicit: {
        scopes: { "User.Read": "Read user profile" },
        authorizationUrl: `https://login.microsoftonline.com/${process.env.TENANT_ID}/oauth2/v2.0/authorize`,
      }
    }
  }, "AzureAD")
  .build()

const document = SwaggerModule.createDocument(app, config)
SwaggerModule.setup('swagger', app, document, {initOAuth: {clientId: process.env.CLIENT_ID, clientSecret: process.env.CLIENT_SECRET}});

解决方案 #

1. 实现预填授权表单（官方支持方案） #

问题出在initOAuth配置不完整，且implicit flow不需要clientSecret。调整配置后可自动预填ClientId并勾选指定Scope：

修改后的代码：

// Swagger
const config = new DocumentBuilder()
  .setTitle('Auth Backend')
  .setDescription('Azure PoC backend')
  .setVersion('0.1')
  .addTag('auth')
  .addOAuth2({
    type: "oauth2",
    description: "Azure AD Implicit Flow",
    name: "AzureAD",
    flows: {
      implicit: {
        scopes: { "User.Read": "Read user profile" },
        authorizationUrl: `https://login.microsoftonline.com/${process.env.TENANT_ID}/oauth2/v2.0/authorize`,
      }
    }
  }, "AzureAD")
  .build()

const document = SwaggerModule.createDocument(app, config)
SwaggerModule.setup('swagger', app, document, {
  initOAuth: {
    clientId: process.env.CLIENT_ID,
    // Implicit Flow不需要clientSecret，移除该配置
    scopes: ["User.Read"], // 明确指定要自动勾选的Scope
    usePkceWithAuthorizationCodeGrant: false // 适配implicit flow
  }
});

配置说明：

• 移除initOAuth中的clientSecret，implicit flow不使用该参数
• 在initOAuth中添加scopes数组，Swagger UI会自动勾选对应权限
• 确保addOAuth2的第二个参数（认证方案名称）正确，Swagger UI会关联到对应的授权配置

2. 尝试自动触发授权（非官方自定义方案） #

Swagger UI官方没有提供自动触发授权的API，因为涉及用户交互安全限制，但可以通过注入自定义脚本实现页面加载后自动触发授权流程：

1. 创建自定义JS文件（比如swagger-auto-auth.js），内容如下：

// 等待Swagger UI加载完成
document.addEventListener('DOMContentLoaded', function() {
  // 监听Swagger UI的DOM变化
  const observer = new MutationObserver(function(mutations) {
    const authorizeBtn = document.querySelector('.swagger-ui .authorize-wrapper button');
    if (authorizeBtn && authorizeBtn.textContent.includes('Authorize')) {
      observer.disconnect();
      // 点击Authorize按钮
      authorizeBtn.click();
      // 等待授权弹窗加载
      setTimeout(function() {
        // 点击弹窗中的提交按钮
        const submitBtn = document.querySelector('.swagger-ui .modal-actions .btn.authorize');
        if (submitBtn) {
          submitBtn.click();
        }
      }, 500);
    }
  });
  observer.observe(document.body, { childList: true, subtree: true });
});

2. 在NestJS的Swagger配置中引入该脚本：

SwaggerModule.setup('swagger', app, document, {
  initOAuth: {
    clientId: process.env.CLIENT_ID,
    scopes: ["User.Read"],
    usePkceWithAuthorizationCodeGrant: false
  },
  // 引入自定义脚本（需确保文件在静态资源目录可访问）
  customJs: '/swagger-auto-auth.js'
});

注意事项：

• 自动触发脚本依赖Swagger UI的DOM结构，若Swagger UI版本更新可能需要调整选择器
• 部分浏览器的安全策略可能阻止自动弹窗操作，适合本地开发环境使用
• 生产环境建议仅使用预填方案，自动触发存在安全和兼容性风险

内容的提问来源于stack exchange，提问作者Branchverse