本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# x-amazon-apigateway-authorizer 物件
<a name="api-gateway-swagger-extensions-authorizer"></a>

 定義要套用的 Lambda 授權方、Amazon Cognito 使用者集區或 JWT 授權方，以授權在 API Gateway 中的方法調用。此延伸適用於 [OpenAPI 2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#security-definitions-object) 中的安全性定義和 [OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#security-scheme-object) 中的安全性結構描述。


| 屬性名稱 | 類型 | 描述 | 
| --- | --- | --- | 
| type | string | 授權方的類型。這是必要屬性。<br />對於 REST API，指定 `token` 為授權方，並在授權權杖中嵌入發起人身分。為發起人身分包含在請求參數的授權方指定 `request`。針對使用 Amazon Cognito 使用者集區進行 API 存取控制的授權方指定 `cognito_user_pools`。<br />對於 HTTP API，指定 `request` 為 Lambda 授權方，並在授權參數中包含發起人身分。為 JWT 授權方指定 `jwt`。 | 
| authorizerUri | string |  授權方 Lambda 函數的統一資源識別符 (URI)。語法如下：<pre>"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"</pre> | 
| authorizerCredentials | string | 呼叫授權方的必要登入資料 (如果有)，格式為 IAM 執行角色的 ARN。例如，"arn:aws:iam::{{account-id}}:{{IAM\_role}}"。 | 
| authorizerPayloadFormatVersion | string | 對於 HTTP API，指定 API Gateway 傳送到 Lambda 授權方的資料格式，以及 API Gateway 如何解釋 Lambda 的回應。如需進一步了解，請參閱[裝載格式版本](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format)。 | 
| enableSimpleResponses | Boolean | 對於 HTTP API，指定 `request` 授權方是否傳回布林值或 IAM 政策。僅支援具有 `2.0` 的 `authorizerPayloadFormatVersion` 的授權者。如果啟用，Lambda 授權方函數會傳回一個布林值。如需進一步了解，請參閱[格式 2.0 的 Lambda 函數回應](http-api-lambda-authorizer.md#http-api-lambda-authorizer.v2)。 | 
| identitySource | string | 做為身分來源之請求參數的對應表達式逗號分隔清單。僅適用於 `request` 和 `jwt` 類型的授權方。 | 
| jwtConfiguration | Object | 指定 JWT 授權方的發行者和對象。若要進一步了解，請參閱《API Gateway 第 2 版 API 參考》中的 [JWTConfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration)。僅支援 HTTP API。 | 
| identityValidationExpression | string |  驗證做為傳入身分之字符的一般表達式。例如，"^x-[a-z]\+"。僅支援 REST API 的 `TOKEN` 授權方。 | 
| authorizerResultTtlInSeconds | string |  快取授權方結果的秒數。 | 
| providerARNs | string 陣列 | `COGNITO_USER_POOLS` 的 Amazon Cognito 使用者集區 ARN 清單。 | 

## REST API 的 x-amazon-apigateway-authorizer 範例
<a name="api-gateway-swagger-extensions-authorizer-example"></a>

下列 OpenAPI 安全定義範例會指定類型為「權杖」且名為 `test-authorizer` 的 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" : "custom", // 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"
        }
      }
    }
```

## HTTP API 的 x-amazon-apigateway-authorizer 範例
<a name="api-gateway-openapi-extensions-authorizer-examples-http"></a>

以下 OpenAPI 3.0 範例為 HTTP API 建立 JWT 授權方，它會使用 Amazon Cognito 做為身分提供者，並以 `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
    }
  }
}
```