如何将AWS Cognito集成到Swagger UI实现OAuth2认证？

一、标准OAuth2授权码流（推荐） #

AWS Cognito原生支持OAuth2授权码流程，这是最省心的集成方式，完全能实现你想要的理想流程，步骤如下：

• 配置Cognito应用客户端

  1. 登录AWS控制台，进入你的Cognito用户池，找到「应用客户端」设置
  2. 添加Swagger UI的回调URL：https://ourcompanyhostname.com/docs/oauth2-redirect.html（Swagger UI自带这个跳转页面，无需自行开发）
  3. 开启「Authorization Code Grant」授权类型
  4. 记下用户池ID、客户端ID、Cognito域名（格式一般为xxx.auth.xxx.amazoncognito.com）

• 修改OpenAPI规范
  在你的API文档中添加OAuth2安全定义，YAML示例如下：

  components:
    securitySchemes:
      cognitoOAuth2:
        type: oauth2
        flows:
          authorizationCode:
            authorizationUrl: https://<你的Cognito域名>/oauth2/authorize
            tokenUrl: https://<你的Cognito域名>/oauth2/token
            scopes:
              openid: 获取用户身份信息
              # 可按需添加API所需的其他权限scope
  security:
    - cognitoOAuth2: [openid]
  

• 配置Swagger UI初始化参数
  在加载Swagger UI的JS代码中加入OAuth相关配置：

  const ui = SwaggerUIBundle({
    url: "/你的API文档路径.yaml",
    dom_id: '#swagger-ui',
    oauth2RedirectUrl: 'https://ourcompanyhostname.com/docs/oauth2-redirect.html',
    oauth: {
      clientId: '<你的Cognito客户端ID>',
      realm: '<你的Cognito用户池ID>',
      appName: '<你的应用名称>',
      scopeSeparator: ' ',
      scopes: 'openid'
    }
  });
  

  配置完成后，点击Swagger UI的「Authorize」按钮，会直接跳转到Cognito托管登录页面，登录成功后自动获取令牌并完成授权，完全匹配你想要的流程。

二、自定义Cognito认证插件（可选） #

如果标准流程无法满足特殊业务需求，也可以通过Swagger UI的自定义能力实现：

• 编写自定义授权逻辑
  可借助AWS Amplify SDK或直接调用Cognito API处理登录与令牌获取，示例代码如下：

  const customCognitoAuth = async () => {
    // 初始化Amplify
    Amplify.configure({
      Auth: {
        userPoolId: '<你的用户池ID>',
        userPoolWebClientId: '<你的客户端ID>',
        region: '<你的AWS区域>'
      }
    });
  
    // 触发Cognito托管UI登录
    const user = await Auth.federatedSignIn();
    // 获取令牌（此处用ID Token，可按需替换为Access Token）
    const token = user.signInUserSession.idToken.jwtToken;
    // 将令牌设置到Swagger授权头中
    ui.preauthorizeApiKey('cognitoOAuth2', `Bearer ${token}`);
  };
  

• 绑定到Swagger UI交互事件
  你可以自定义「Authorize」按钮的点击事件，或添加新的自定义按钮触发上述函数，实现完全定制化的认证流程。

总结 #

优先选择标准OAuth2授权码流，它符合行业规范，无需额外维护大量自定义代码，还能无缝对接Cognito托管UI；自定义插件适合有特殊业务逻辑的场景，但需要自行维护代码。

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