Objet x-amazon-apigateway-authorizer

Définit un mécanisme d’autorisation Lambda, un groupe d’utilisateurs Amazon Cognito ou un mécanisme d’autorisation JWT à appliquer pour l’autorisation des appels de méthode dans API Gateway. Cette extension s’applique à la définition de sécurité dans OpenAPI 2 et OpenAPI 3.

Nom de la propriété	Type	Description
type	string	Type du mécanisme d’autorisation. Cette propriété est requise. Pour les API REST, spécifiez token pour un mécanisme d’autorisation avec l’identité de l’appelant incorporée dans un jeton d’autorisation. Spécifiez request pour un mécanisme d’autorisation avec l’identité de l’appelant contenue dans les paramètres de la demande. Spécifiez cognito_user_pools pour un mécanisme d’autorisation qui utilise un groupe d’utilisateurs Amazon Cognito pour contrôler l’accès à votre API. Pour les API HTTP, spécifiez request pour un mécanisme d’autorisation Lambda avec l’identité de l’appelant contenue dans les paramètres de la demande. Spécifiez jwt pour un mécanisme d’autorisation JWT.
authorizerUri	string	Identificateur de ressource uniforme (URI) de la fonction Lambda du mécanisme d’autorisation. La syntaxe est la suivante : "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	Informations d’identification requises pour appeler le mécanisme d’autorisation, le cas échéant, sous la forme de l’ARN d’un rôle d’exécution IAM. Par exemple, « arn:aws:iam::account-id:IAM_role ».
authorizerPayloadFormatVersion	string	Pour les API HTTP, spécifie le format des données envoyées par API Gateway à un mécanisme d’autorisation Lambda et comment API Gateway interprète la réponse de Lambda. Pour en savoir plus, consultez la section Version du format de charge utile.
enableSimpleResponses	Boolean	Pour les API HTTP, spécifie si un mécanisme d’autorisation request renvoie une valeur booléenne ou une politique IAM. Prise en charge uniquement pour les mécanismes d’autorisation avec un authorizerPayloadFormatVersion de 2.0. Si cette option est activée, la fonction du mécanisme d’autorisation Lambda renvoie une valeur booléenne. Pour en savoir plus, consultez la section Réponse de la fonction Lambda pour le format 2.0.
identitySource	string	Liste (séparée par des virgules) des expressions de mappage des paramètres de la demande en tant que source d’identité. Applicable pour le mécanisme d’autorisation de types request et jwt uniquement.
jwtConfiguration	Object	Spécifie l’émetteur et les audiences d’un mécanisme d’autorisation JWT. Pour plus d’informations, consultez JWTConfiguration dans la Référence d’API API Gateway version 2. Prise en charge uniquement pour les API HTTP.
identityValidationExpression	string	Expression régulière permettant de valider le jeton en tant qu’identité entrante. Par exemple, « ^x-[a-z]+ ». Prise en charge uniquement pour les mécanismes d’autorisation TOKEN pour les API REST.
authorizerResultTtlInSeconds	string	Nombre de secondes pendant lesquelles le résultat du mécanisme d’autorisation est mis en cache.
providerARNs	Tableau d’éléments string	Liste des ARN des groupes d’utilisateurs Amazon Cognito pour COGNITO_USER_POOLS.

Exemples x-amazon-apigateway-authorizer pour les API REST

L’exemple de définitions de sécurité OpenAPI suivant spécifie un mécanisme d’autorisation Lambda de type « token » nommé 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
      }
    }
  }

L’extrait d’objet Opération OpenAPI suivant configure la méthode GET /http afin d’utiliser le mécanisme d’autorisation Lambda précédent.

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

L’exemple de définitions de sécurité OpenAPI suivant spécifie un mécanisme d’autorisation Lambda de type « request », avec un seul paramètre d’en-tête (auth) comme source d’identité. L’exemple securityDefinitions est nommé 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
      }
    }
}

L’exemple de définitions de sécurité OpenAPI suivant spécifie un mécanisme d’autorisation Lambda de type « request », avec un seul en-tête (HeaderAuth1) et un seul paramètre de chaîne de requête QueryString1 comme sources d’identité.

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

L’exemple de définitions de sécurité OpenAPI suivant spécifie un mécanisme d’autorisation Lambda API Gateway de type « request », avec une seule variable d’étape (stage) comme source d’identité.

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

L’exemple de définition de sécurité OpenAPI suivant spécifie un groupe d’utilisateurs Amazon Cognito en tant que mécanisme d’autorisation.

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

L’extrait d’objet d’opération OpenAPI suivant définit GET /http pour utiliser le groupe d’utilisateurs Amazon Cognito précédent en tant que mécanisme d’autorisation, sans portées personnalisées.

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

Exemples x-amazon-apigateway-authorizer pour les API HTTP

L’exemple OpenAPI 3.0 suivant crée un mécanisme d’autorisation JWT pour une API HTTP qui utilise Amazon Cognito comme fournisseur d’identité, avec l’en-tête Authorization comme source d’identité.

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

L’exemple OpenAPI 3.0 suivant produit le même mécanisme d’autorisation JWT que l’exemple précédent. Toutefois, cet exemple utilise la propriété openIdConnectUrl d’OpenAPI pour détecter automatiquement l’émetteur. Le openIdConnectUrl doit être entièrement formé.

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

L’exemple suivant crée un mécanisme d’autorisation Lambda pour une API HTTP. Cet exemple de mécanisme d’autorisation utilise l’en-tête Authorization comme source d’identité. Le mécanisme d’autorisation utilise la version de format de charge utile 2.0 et renvoie une valeur booléenne, car enableSimpleResponses est défini sur 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
    }
  }
}