# x-amazon-apigateway-authorizer オブジェクト
<a name="api-gateway-swagger-extensions-authorizer"></a>

 API Gateway でのメソッド呼び出しの認可に適用される Lambda オーソライザー、Amazon Cognito ユーザープール、または JWT オーソライザーを定義します。この拡張機能は、[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 |  認証のタイプ。これは必須のプロパティです。 REST API で、発信者 ID が認可トークンに埋め込まれるオーソライザーの場合は、`token` を指定します。呼び出し元 ID がリクエストパラメータに含まれるオーソライザーの場合は、`request` を指定します。Amazon Cognito ユーザープールを使用して API へのアクセスを制御するオーソライザーには、`cognito_user_pools` を指定します。 HTTP API で、発信者 ID がリクエストパラメータに含まれる Lambda オーソライザーの場合は、`request` を指定します。JWT オーソライザーの場合は、`jwt` を指定します。  | 
| authorizerUri | string |   オーソライザー Lambda 関数の Uniform Resource Identifier (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\$1role*"。  | 
| 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 ポリシーを返すかを指定します。`authorizerPayloadFormatVersion` が `2.0` のオーソライザーでのみサポートされます。有効にすると、Lambda オーソライザー関数はブール値を返します。詳細については、「[Lambda 関数レスポンス形式 2.0](http-api-lambda-authorizer.md#http-api-lambda-authorizer.v2)」を参照してください。  | 
| identitySource | string |  ID ソースとして、リクエストパラメータの式をマッピングするカンマ区切りのリスト。`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]\$1" などです。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` という名前で「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" : "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 オペレーションオブジェクトのスニペットでは、上記の Lambda オーソライザーを使用するよう `GET /http` を設定します。

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

次の OpenAPI セキュリティ定義の例では、単一のヘッダーパラメータ (`auth`) を ID ソースとして使用して、「request」タイプの Lambda オーソライザーを指定します。`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 セキュリティ定義の例では、1 つのヘッダー (`HeaderAuth1`) とクエリ文字列パラメータ (`QueryString1`) を ID ソースとして使用して、「request」タイプの Lambda オーソライザーを指定します。

```
"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 セキュリティ定義の例では、単一のステージ変数 (`stage`) を ID ソースとして使用して、「request」タイプの API Gateway Lambda オーソライザーを指定します。

```
"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 オペレーションオブジェクトスニペットでは、カスタムスコープなしで、上記の Amazon Cognito ユーザープールをオーソライザーとして使用するよう `GET /http` を設定しています。

```
   "/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 の例では、Amazon Cognito を ID プロバイダーとして使用し、`Authorization` ヘッダーを ID ソースとして使用する HTTP API の JWT オーソライザーを作成します。

```
"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 オーソライザーを作成します。この例のオーソライザーは、ID ソースとして `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
    }
  }
}
```