NestJS中Swagger与Keycloak OAuth2认证跳转错误问题排查

我当前使用以下Swagger配置实现Keycloak认证：

const swaggerConfig = new DocumentBuilder()
.addOAuth2({
  type: 'oauth2',
  flows: {
    implicit: {
      authorizationUrl: 'http://localhost:8080/realms/hello/protocol/openid-connect/auth',
      tokenUrl: 'http://localhost:8080/realms/hello/protocol/openid-connect/token',
      scopes: {}
    }
  }
})
.build();

Swagger界面能看到“Authorize”按钮，执行认证流程时，在Keycloak输入用户名密码并成功认证后，跳转到错误页面，但跳转后的URL包含正确的access_token等信息：

http://localhost:3300/api/oauth2-redirect.html#state=VGh1IEZ...aW1lKQ%3D%3D&session_state=679b34f5-61f5-4f45-810f-712de907cf7c&access_token=eyJhbGciOiJS...M4In0&token_type=Bearer&expires_in=900

请问这是集成配置存在问题吗？

问题原因及修复方案 #

1. 显式配置Swagger UI的OAuth2重定向URL

NestJS的SwaggerModule默认重定向路径可能和实际部署路径不匹配，需要在启动Swagger时显式指定oauth2RedirectUrl，确保与Keycloak配置的重定向URI一致：

import { SwaggerModule } from '@nestjs/swagger';

// ... 其他初始化代码

SwaggerModule.setup('api', app, swaggerConfig, {
  swaggerOptions: {
    oauth2RedirectUrl: 'http://localhost:3300/api/oauth2-redirect.html',
  },
});

2. 验证Keycloak客户端的有效重定向URI

登录Keycloak后台，进入目标Realm的客户端设置页面：

• 在Valid Redirect URIs中添加http://localhost:3300/api/oauth2-redirect.html（测试环境可临时用http://localhost:3300/*覆盖）
• 将Web Origins设置为http://localhost:3300或*（测试场景）

3. 切换到Authorization Code Flow（推荐）

Implicit Flow已被OAuth 2.1规范弃用，Swagger对Authorization Code Flow的支持更稳定，修改Swagger配置：

const swaggerConfig = new DocumentBuilder()
.addOAuth2({
  type: 'oauth2',
  flows: {
    authorizationCode: {
      authorizationUrl: 'http://localhost:8080/realms/hello/protocol/openid-connect/auth',
      tokenUrl: 'http://localhost:8080/realms/hello/protocol/openid-connect/token',
      scopes: {
        'openid': '获取用户身份信息',
        'profile': '获取用户基本资料'
      },
    },
  },
})
.build();

4. 确保Swagger静态资源可访问

如果oauth2-redirect.html无法加载，检查@nestjs/swagger和swagger-ui-express版本是否为最新，新版本会自动处理静态资源路由；若仍有问题，可手动配置静态资源映射（一般无需额外操作）。

内容的提问来源于stack exchange，提问作者dev.support