x-amazon-apigateway-authorizer object - Amazon API Gateway
Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

x-amazon-apigateway-authorizer object

Defines a Lambda authorizer, Amazon Cognito user pool, or JWT authorizer to be applied for authorization of method invocations in API Gateway. This extension applies to the security definition in OpenAPI 2 and the security scheme in OpenAPI 3.

Property name Type Description
type string

The type of the authorizer. This is a required property.

For REST APIs, specify token for an authorizer with the caller identity embedded in an authorization token. Specify request for an authorizer with the caller identity contained in request parameters. Specify cognito_user_pools for an authorizer that uses an Amazon Cognito user pool to control access to your API. Specify jwt for a JWT authorizer that validates JSON Web Tokens from an OpenID Connect (OIDC) identity provider.

For HTTP APIs, specify request for a Lambda authorizer with the caller identity contained in request parameters. Specify jwt for a JWT authorizer.

authorizerUri string

The Uniform Resource Identifier (URI) of the authorizer Lambda function. The syntax is as follows:

"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

The credentials required for invoking the authorizer, if any, in the form of an ARN of an IAM execution role. For example, "arn:aws:iam::account-id:IAM_role".

authorizerPayloadFormatVersion string

For HTTP APIs, specifies the format of the data that API Gateway sends to a Lambda authorizer, and how API Gateway interprets the response from Lambda. To learn more, see .

enableSimpleResponses Boolean

For HTTP APIs, specifies whether a request authorizer returns a Boolean value or an IAM policy. Supported only for authorizers with an authorizerPayloadFormatVersion of 2.0. If enabled, the Lambda authorizer function returns a Boolean value. To learn more, see .

identitySource string

A comma-separated list of mapping expressions of the request parameters as the identity source. For HTTP APIs, applicable for request and jwt authorizers. For REST APIs, applicable for request authorizers only. A REST jwt authorizer takes its identity source from the security scheme's name, and the scheme's in value must be header.

jwtConfiguration Object

Specifies the configuration of a JWT authorizer. The shape of this object differs between HTTP APIs and REST APIs.

For HTTP APIs, this object specifies the issuer (a string) and audience (an array of string) for the authorizer. To learn more, see JWTConfiguration in the API Gateway Version 2 API Reference.

For REST APIs, this object contains the following properties:

  • issuers – An array of issuer objects. Each object contains an issuer (a string that must match the token's iss claim exactly, including any trailing slash), an audiences array (string values matched against the token's aud claim), and an additionalClaims array of custom claim rules. Each claim rule contains a claimName (the name of the claim to validate), a format (the claim value type, such as SINGLE_STRING), a required (Boolean) flag that indicates whether the claim must be present, and an expectedValues array of accepted values.

  • defaultAlgorithms – An array of string signing algorithms accepted when validating a token's signature.

When you import an API definition, API Gateway ignores the jwksUri property. When you export an API definition, API Gateway omits it.

identityValidationExpression string

A regular expression for validating the token as the incoming identity. For example, "^x-[a-z]+". Supported only for TOKEN authorizers for REST APIs.

authorizerResultTtlInSeconds string

The number of seconds during which authorizer result is cached.

providerARNs An array of string

A list of the Amazon Cognito user pool ARNs for the COGNITO_USER_POOLS.

x-amazon-apigateway-authorizer examples for REST APIs

The following OpenAPI security definitions example specifies a Lambda authorizer of the "token" type and named test-authorizer.

"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 } } }

The following OpenAPI operation object snippet sets the GET /http to use the preceding Lambda authorizer.

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

The following OpenAPI security definitions example specifies a Lambda authorizer of the "request" type, with a single header parameter (auth) as the identity source. The securityDefinitions is named 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 } } }

The following OpenAPI security definitions example specifies a Lambda authorizer of the "request" type, with one header (HeaderAuth1) and one query string parameter QueryString1 as the identity sources.

"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 } } }

The following OpenAPI security definitions example specifies an API Gateway Lambda authorizer of the "request" type, with a single stage variable (stage) as the identity source.

"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 } } }

The following OpenAPI security definition example specifies an Amazon Cognito user pool as an authorizer.

"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" ] } }

The following OpenAPI operation object snippet sets the GET /http to use the preceding Amazon Cognito user pool as an authorizer, with no custom scopes.

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

The following OpenAPI 3.0 example specifies a JWT authorizer for a REST API. The authorizer validates tokens from one issuer, requires a custom claim, and uses the Authorization header to carry the token.

"securitySchemes" : { "orders-jwt" : { "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" : "jwt", // Specifies the authorization mechanism for the client. "x-amazon-apigateway-authorizer" : { // An API Gateway JWT authorizer definition "type" : "jwt", // Required property and the value must be "jwt". "jwtConfiguration" : { "issuers" : [ { "issuer" : "https://identity.example.com", "audiences" : [ "api://orders" ], "additionalClaims" : [ { "claimName" : "department", "format" : "SINGLE_STRING", "required" : true, "expectedValues" : [ "eng" ] } ] } ], "defaultAlgorithms" : [ "RS256", "ES256" ] } } } }

The following OpenAPI operation object snippet sets GET /orders to use the preceding JWT authorizer and requires the orders:read scope. The scopes that you list in an operation's security entry become the method's authorizationScopes.

"/orders" : { "get" : { "responses" : { }, "security" : [ { "orders-jwt" : [ "orders:read" ] } ], "x-amazon-apigateway-integration" : { "type" : "mock", "requestTemplates" : { "application/json" : "{\"statusCode\": 200}" }, "responses" : { "default" : { "statusCode" : "200" } } } } }

x-amazon-apigateway-authorizer examples for HTTP APIs

The following OpenAPI 3.0 example creates a JWT authorizer for an HTTP API that uses Amazon Cognito as an identity provider, with the Authorization header as an identity source.

The following OpenAPI 3.0 example produces the same JWT authorizer as the previous example. However, this example uses the OpenAPI openIdConnectUrl property to automatically detect the issuer. The openIdConnectUrl must be fully formed.

The following example creates a Lambda authorizer for an HTTP API. This example authorizer uses the Authorization header as its identity source. The authorizer uses the 2.0 payload format version, and returns Boolean value, because enableSimpleResponses is set to 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 } } }