x-amazon-apigateway-authorizer REST API 的示例 x-amazon-apigateway-authorizer HTTP API 的示例

x-amazon-apigateway-authorizer 对象

定义 Lambda 授权方、Amazon Cognito 用户群体或 JWT 授权方，用于对 API Gateway 中的方法调用进行授权。此扩展适用于 OpenAPI 2 和 OpenAPI 3 中的安全定义。

属性
属性名称	类型	说明
`type`	`string`	授权方的类型。这是一个必需属性。对于 REST API，为具有已嵌入授权令牌中的调用方身份的授权方指定 `token`。为具有请求参数中包含的调用方身份的授权方指定 `request`。为使用 Amazon Cognito 用户群体控制对 API 的访问权限的授权方指定 `cognito_user_pools`。对于 HTTP API，为具有请求参数中包含的调用方身份的 Lambda 授权方指定 `request`。为 JWT 授权方指定 `jwt`。
`authorizerUri`	`string`	授权方 Lambda 函数的统一资源标识符 (URI)。语法如下： `"arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:auth_function_name/invocations"`
`authorizerCredentials`	`string`	调用授权方所需的凭证（如果有），该凭证采用 IAM 执行角色的 ARN 形式。例如，“arn:aws:iam::`account-id`:`IAM_role`”。
`authorizerPayloadFormatVersion`	`string`	对于 HTTP API，指定 API Gateway 发送到 Lambda 授权方的数据格式，以及 API Gateway 如何解释来自 Lambda 的响应。要了解更多信息，请参阅“负载格式版本”。
`enableSimpleResponses`	`Boolean`	对于 HTTP API，指定 `request` 授权方是返回布尔值还是 IAM 策略。仅支持用于 `authorizerPayloadFormatVersion` 为 `2.0` 的授权方。如果启用，Lambda 授权方函数将返回一个布尔值。要了解更多信息，请参阅“格式 2.0 的 Lambda 函数响应”。
`identitySource`	`string`	请求参数（作为身份来源）的映射表达式的逗号分隔列表。仅适用于 `request` 和 `jwt` 类型的授权方。
`jwtConfiguration`	`Object`	指定 JWT 授权方的发布者和受众。要了解更多信息，请参阅 API Gateway 版本 2 API 参考中的 JWTConfiguration。仅 HTTP API 支持。
`identityValidationExpression`	`string`	一个正则表达式，用于验证作为传入身份的令牌。例如，“^x-[a-z]+”。仅支持用于 REST API 。
`authorizerResultTtlInSeconds`	`string`	对授权方结果进行缓存的秒数。
`providerARNs`	`string` 数组	`COGNITO_USER_POOLS` 的 Amazon Cognito 用户群体 ARN 列表。

x-amazon-apigateway-authorizer REST API 的示例

以下 OpenAPI 安全定义示例指定了一个名为 test-authorizer 的“token”类型的 Lambda 授权方。



  "securityDefinitions" : {
    "test-authorizer" : {
      "type" : "apiKey",                         // Required and the value must be "apiKey" for an API Gateway API.
      "name" : "Authorization",                  // The name of the header containing the authorization token.
      "in" : "header",                           // Required and the value must be "header" for an API Gateway API.
      "x-amazon-apigateway-authtype" : "oauth2", // Specifies the authorization mechanism for the client.
      "x-amazon-apigateway-authorizer" : {       // An API Gateway Lambda authorizer definition
        "type" : "token",                        // Required property and the value must "token"
        "authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:function-name/invocations",
        "authorizerCredentials" : "arn:aws:iam::account-id:role",
        "identityValidationExpression" : "^x-[a-z]+",
        "authorizerResultTtlInSeconds" : 60
      }
    }
  }

以下 OpenAPI 操作对象代码段设置 GET /http 来使用上述 Lambda 授权方。



   "/http" : {
      "get" : {
        "responses" : { },
        "security" : [ {
          "test-authorizer" : [ ]
        } ],
        "x-amazon-apigateway-integration" : {
          "type" : "http",
          "responses" : {
            "default" : {
              "statusCode" : "200"
            }
          },
          "httpMethod" : "GET",
          "uri" : "http://api.example.com"
        }
      }
    }

以下 OpenAPI 安全定义示例指定“request”类型的 Lambda 授权方作为身份来源，带单个标头参数 (auth)。securityDefinitions 名为 request_authorizer_single_header。


"securityDefinitions": {
    "request_authorizer_single_header" : {
      "type" : "apiKey",
      "name" : "auth",               // The name of a single header or query parameter as the identity source.
      "in" : "header",               // The location of the single identity source request parameter. The valid value is "header" or "query"
      "x-amazon-apigateway-authtype" : "custom",
      "x-amazon-apigateway-authorizer" : {
        "type" : "request",
        "identitySource" : "method.request.header.auth",   // Request parameter mapping expression of the identity source. In this example, it is the 'auth' header.
        "authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
        "authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
        "authorizerResultTtlInSeconds" : 300
      }
    }
}

以下 OpenAPI 安全定义示例指定“request”类型的 Lambda 授权方作为身份来源，带有一个标头 (HeaderAuth1) 和一个查询字符串参数 QueryString1。


"securityDefinitions": {
    "request_authorizer_header_query" : {
      "type" : "apiKey",
      "name" : "Unused",             // Must be "Unused" for multiple identity sources or non header or query type of request parameters.
      "in" : "header",               // Must be "header" for multiple identity sources or non header or query type of request parameters.
      "x-amazon-apigateway-authtype" : "custom",
      "x-amazon-apigateway-authorizer" : {
        "type" : "request",
        "identitySource" : "method.request.header.HeaderAuth1, method.request.querystring.QueryString1",   // Request parameter mapping expressions of the identity sources.
        "authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
        "authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
        "authorizerResultTtlInSeconds" : 300
      }
    }
}

以下 OpenAPI 安全定义示例指定“request”类型的 API Gateway Lambda 授权方作为身份来源，带单个阶段变量 (stage)。


"securityDefinitions": {
    "request_authorizer_single_stagevar" : {
      "type" : "apiKey",
      "name" : "Unused",             // Must be "Unused", for multiple identity sources or non header or query type of request parameters.
      "in" : "header",               // Must be "header", for multiple identity sources or non header or query type of request parameters.
      "x-amazon-apigateway-authtype" : "custom",
      "x-amazon-apigateway-authorizer" : {
        "type" : "request",
        "identitySource" : "stageVariables.stage",   // Request parameter mapping expression of the identity source. In this example, it is the stage variable.
        "authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
        "authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
        "authorizerResultTtlInSeconds" : 300
      }
    }
}

以下 OpenAPI 安全定义示例将 Amazon Cognito 用户群体指定为授权方。


 "securityDefinitions": {
    "cognito-pool": {
      "type": "apiKey",
      "name": "Authorization",
      "in": "header",
      "x-amazon-apigateway-authtype": "cognito_user_pools",
      "x-amazon-apigateway-authorizer": {
        "type": "cognito_user_pools",
        "providerARNs": [
          "arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-east-1_ABC123"
        ]
      }
    }

以下 OpenAPI 操作对象片段将 GET /http 设置为使用前面的 Amazon Cognito 用户群体作为授权方，而没有自定义范围。



   "/http" : {
      "get" : {
        "responses" : { },
        "security" : [ {
          "cognito-pool" : [ ]
        } ],
        "x-amazon-apigateway-integration" : {
          "type" : "http",
          "responses" : {
            "default" : {
              "statusCode" : "200"
            }
          },
          "httpMethod" : "GET",
          "uri" : "http://api.example.com"
        }
      }
    }

x-amazon-apigateway-authorizer HTTP API 的示例

以下 OpenAPI 3.0 示例为使用 Amazon Cognito 作为身份提供商的 HTTP API 创建 JWT 授权方，并将 Authorization 标头作为身份来源。


"securitySchemes": {
  "jwt-authorizer-oauth": {
    "type": "oauth2",
     "x-amazon-apigateway-authorizer": {
       "type": "jwt",
       "jwtConfiguration": {
          "issuer": "https://cognito-idp.region.amazonaws.com/userPoolId",
          "audience": [
            "audience1",
            "audience2"
          ]
        },
        "identitySource": "$request.header.Authorization"
    }
  }
}

以下 OpenAPI 3.0 示例生成的 JWT 授权方与上一个示例相同。但是，此示例使用 OpenAPI 的 openIdConnectUrl 属性来自动检测发布者。openIdConnectUrl 必须完全形成。


"securitySchemes": {
  "jwt-authorizer-autofind": {
    "type": "openIdConnect",
    "openIdConnectUrl": "https://cognito-idp.region.amazonaws.com/userPoolId/.well-known/openid-configuration",
    "x-amazon-apigateway-authorizer": {
      "type": "jwt",
      "jwtConfiguration": {
        "audience": [
          "audience1",
          "audience2"
        ]
      },
      "identitySource": "$request.header.Authorization"
    }
  }
}

以下示例为 HTTP API 创建一个 Lambda 授权方。此示例授权方使用 Authorization 标头作为其身份来源。授权方使用 2.0 负载格式版本，并返回布尔值，因为 enableSimpleResponses 设置为 true。


"securitySchemes" : {
  "lambda-authorizer" : {
    "type" : "apiKey",
    "name" : "Authorization",
    "in" : "header",
    "x-amazon-apigateway-authorizer" : {
      "type" : "request",
      "identitySource" : "$request.header.Authorization",
      "authorizerUri" : "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:function-name/invocations",
      "authorizerPayloadFormatVersion" : "2.0",
      "authorizerResultTtlInSeconds" : 300,
      "enableSimpleResponses" : true
    }
  }
}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

x-amazon-apigateway-auth

x-amazon-apigateway-authtype