如何在Lambda授权器验证Cognito JWT时启用API Gateway使用计划？

问题场景 #

我通过Lambda授权器验证Cognito JWT令牌实现用户身份认证，当前流程不依赖API密钥，但希望启用API Gateway的使用计划管控功能。已按AWS官方文档生成包含usageIdentifierKey字段的授权策略，将API密钥源设置为Authorizer，但无论该字段留空、填入API密钥ID/值/名称，均无法触发使用计划的管控规则。

核心排查与解决步骤 #

1. 明确usageIdentifierKey的正确取值 #

这个字段必须填写API密钥的ID（不是密钥值或名称）。API密钥ID可在API Gateway控制台的「API密钥」页面获取，格式为类似abcdef123456的短字符串。

2. 检查API密钥与使用计划的绑定关系 #

• 确认目标API密钥已绑定到对应的使用计划
• 确保使用计划已关联需要管控的API阶段（Stage）
• 检查使用计划的配额、限流规则配置正确，且未过期

3. 验证Lambda授权器与API阶段配置 #

• 确认API阶段的「API密钥源」已设置为Authorizer，且该阶段启用了「使用计划」管控
• 检查Lambda授权器的返回格式：
  • usageIdentifierKey必须是顶层字段，不能嵌套在context中
  • 策略文档的Resource需包含当前请求的完整API ARN，避免权限范围不匹配
  • 确保Lambda执行角色具备基础权限，无额外策略限制返回内容

4. 日志与测试验证 #

• 开启API Gateway访问日志，查看请求中usageIdentifierKey是否被正确传递
• 在Lambda授权器中添加日志输出，确认返回的策略里usageIdentifierKey字段携带了正确的API密钥ID
• 用curl或Postman发起测试请求，通过CloudWatch日志或X-Ray追踪确认使用计划规则是否被触发

5. 特殊场景注意事项 #

• 若通过Cognito用户池组绑定使用计划，需从JWT令牌的cognito:groups字段获取组关联的API密钥ID，再填入usageIdentifierKey
• 不要在API阶段同时启用「API密钥必填」和「授权器作为密钥源」，二者会产生冲突，仅需设置密钥源为Authorizer即可

正确的授权策略示例 #

{
  "principalId": "testuser",
  "policyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Action": "execute-api:Invoke",
        "Effect": "Allow",
        "Resource": [
          "arn:aws:execute-api:eu-central-1:<accountnr>:<sth>/test/GET/*"
        ]
      }
    ]
  },
  "context": {
    "attribute1": "value1",
    "attribute2": "value2"
  },
  "usageIdentifierKey": "abcdef123456" // 此处填写API密钥ID
}

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