x-amazon-apigateway-authorizer オブジェクト - Amazon API Gateway

x-amazon-apigateway-authorizer オブジェクト

API Gateway でのメソッド呼び出しの認証に適用される Lambda オーソライザーまたは JWT オーソライザーを定義します。この拡張機能は、 OpenAPI 2 および OpenAPI 3 のセキュリティ定義に適用されます。

プロパティ
プロパティ名 タイプ 説明
type string

認証のタイプ。これは必須のプロパティです。

REST API で、発信者 ID が認証トークンに埋め込まれるオーソライザーの場合は、token を指定します。呼び出し元 ID がリクエストパラメータに含まれるオーソライザーの場合は、request を指定します。

HTTP API で、発信者 ID がリクエストパラメータに含まれる Lambda オーソライザーの場合は、request を指定します。JWT オーソライザーの場合は、jwt を指定します。

authorizerUri string

オーソライザー Lambda 関数の Uniform Resource Identifier (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 ポリシーを返すかを指定します。authorizerPayloadFormatVersion2.0 のオーソライザーでのみサポートされます。有効にすると、Lambda オーソライザー関数はブール値を返します。詳細については、「Lambda 関数レスポンス形式 2.0」を参照してください。

identitySource string

ID ソースとして、リクエストパラメータの式をマッピングするカンマ区切りのリスト。request および jwt タイプのオーソライザーにのみ適用されます。

jwtConfiguration Object

JWT オーソライザーの発行者と対象者を指定します。詳細については、API Gateway バージョン 2 API リファレンスの「JWTConfiguration」を参照してください。HTTP API に対してのみサポートされます。

identityValidationExpression string

入力のアイデンティティとしてトークンを検証するための正規表現。たとえば、"^x-[a-z]+" などです。REST API でのみサポートされます。

authorizerResultTtlInSeconds string

オーソライザーの結果がキャッシュされる秒数。

REST API の x-amazon-apigateway-authorizer の例

次の 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 オペレーションオブジェクトのスニペットでは、上記の 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 } } }

HTTP API の x-amazon-apigateway-authorizer の例

次の 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.0enableSimpleResponses に設定されているため、オーソライザーは 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 } } }