在SST项目中配置API Gateway V2的Cognito JWT认证

在AWS云服务中，API Gateway V2是一个强大的服务，用于构建和管理API。当我们需要为API添加认证层时，JWT(JSON Web Token)是一种常见的选择。本文将详细介绍如何在SST(Serverless Stack)项目中正确配置API Gateway V2使用Cognito作为JWT认证提供者。

认证架构概述

API Gateway V2支持多种认证方式，其中JWT认证需要明确指定以下关键信息：

• 令牌颁发者(Issuer)：验证JWT的颁发来源
• 受众(Audiences)：验证JWT的目标接收者
• 授权器(Authorizer)：处理认证逻辑的组件

常见配置误区

许多开发者初次尝试时，会直接在路由配置中添加JWT参数，如下所示：

api.route("POST /generate/embedurl", "packages/functions/src/generate-embed-url.main", {
    auth: {
        jwt: {
            audiences: [userPoolClient.id],
            issuer: `https://cognito-idp.${region}.amazonaws.com/${userPool.id}`
        }
    }
});

这种配置会导致错误，因为缺少了关键的授权器组件。AWS API Gateway V2要求必须显式创建并关联一个JWT授权器。

正确配置方法

完整的配置流程应包含以下步骤：

1. 创建API Gateway V2实例
2. 添加JWT授权器
3. 在路由中引用授权器

// 1. 创建API实例
const api = new sst.aws.ApiGatewayV2("MyAPI", {
    domain: {
        name: "api.example.com"
    }
});

// 2. 添加JWT授权器
const authorizer = api.addAuthorizer({
    name: "cognitoAuthorizer",
    jwt: {
        issuer: `https://cognito-idp.${aws.getRegionOutput().name}.amazonaws.com/${userPool.id}`,
        audiences: [userPoolClient.id]
    }
});

// 3. 配置路由并使用授权器
api.route("POST /secure-endpoint", "path/to/handler.main", {
    auth: {
        jwt: {
            authorizer: authorizer.id
        }
    }
});

关键配置说明

1. 授权器创建：必须通过addAuthorizer方法显式创建授权器，该方法会返回包含授权器ID的对象。

2. Cognito特定参数：

   • issuer：格式固定为https://cognito-idp.{region}.amazonaws.com/{userPoolId}
   • audiences：通常使用Cognito用户池客户端ID

3. 路由配置：在路由的auth配置中，只需引用授权器ID即可，无需重复指定issuer和audiences。

最佳实践建议

1. 对于生产环境，建议将授权器配置提取到单独的文件中，便于多个API共享。

2. 考虑为不同环境(开发/测试/生产)使用不同的Cognito用户池，通过环境变量动态配置issuer和audiences。

3. 在SST项目中，可以利用$app.stage变量实现环境特定的配置。

通过以上配置，开发者可以轻松地为SST项目中的API Gateway V2添加强大的Cognito JWT认证功能，确保API的安全访问。