为自定义AWS Lambda设置PrincipalID时API Gateway调用报500错误排查

核心排查方向 #

1. 授权器返回格式不符合要求 #

Lambda授权器执行成功但返回格式错误是触发该异常的常见原因，必须严格遵循API Gateway的格式规范：

• 必须包含principalId字符串字段
• policyDocument必须是符合IAM规范的JSON对象，Version固定为2012-10-17，Statement数组需包含Effect（Allow/Deny）、Action（固定为execute-api:Invoke）、Resource（对应API Gateway目标资源的ARN）
• 可选的context字段值只能是字符串、数字或布尔类型，不能嵌套复杂结构

正确返回示例：

{
  "principalId": "user_123",
  "policyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": "execute-api:Invoke",
        "Resource": "arn:aws:execute-api:us-east-1:123456789012:xyz789/prod/GET/users"
      }
    ]
  },
  "context": {
    "userRole": "editor",
    "userId": "12345"
  }
}

2. API Gateway与Lambda授权器的权限配置缺失 #

确认API Gateway拥有调用Lambda授权器的权限：

• 检查Lambda函数的资源策略，是否允许apigateway.amazonaws.com作为调用主体
• 确认API Gateway控制台中配置的授权器Lambda ARN无拼写错误，且指向已部署的函数版本/别名

3. API Gateway资源策略与授权器策略冲突 #

如果API Gateway资源策略设置了全局拒绝规则，或与授权器返回的允许策略存在逻辑矛盾，会触发配置异常。需确保资源策略与授权器策略的权限逻辑一致。

4. 授权器部署状态异常 #

确认Lambda授权器已完成部署，API Gateway引用的是已发布的Lambda版本或别名，而非未部署的草稿版本。

授权器返回字段官方说明 #

以下是API Gateway要求的授权器返回字段定义：

• principalId（必填）：字符串类型，标识请求的用户或实体唯一ID
• policyDocument（必填）：IAM策略文档对象，核心参数：
  • Version：固定为2012-10-17
  • Statement：数组类型，每个元素需包含Effect（Allow/Deny）、Action（必须为execute-api:Invoke）、Resource（目标API资源的完整ARN）
• context（可选）：键值对集合，用于向后端集成传递自定义上下文信息，值仅支持字符串、数字、布尔类型
• usageIdentifierKey（可选）：字符串类型，用于关联API用量计划的自定义标识

请对照上述检查点，核对你提供的curl请求参数、Lambda授权器代码返回格式、API Gateway资源策略逻辑。

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