Utiliser les API autorisateurs Gateway Lambda - APIPasserelle Amazon

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Utiliser les API autorisateurs Gateway Lambda

Utilisez un autorisateur Lambda (anciennement connu sous le nom d'autorisateur personnalisé) pour contrôler l'accès à votre. API Lorsqu'un client soumet une requête à votre API méthode, API Gateway appelle votre autorisateur Lambda. L'autorisateur Lambda prend l'identité de l'appelant en entrée et renvoie une IAM politique en sortie.

Utilisez un autorisateur Lambda pour implémenter un schéma d'autorisation personnalisé. Votre schéma peut utiliser des paramètres de demande pour déterminer l'identité de l'appelant ou utiliser une stratégie d'authentification par jeton porteur telle que OAuth ou. SAML Créez un autorisateur Lambda dans la REST API console API Gateway à l'aide de, ou d' AWS CLI un. AWS SDK

Flux de travail d'autorisation Lambda Authorizer

Le schéma suivant montre le flux de travail d'autorisation pour un autorisateur Lambda.

APIFlux de travail d'autorisation Gateway Lambda
APIFlux de travail d'autorisation Gateway Lambda
  1. Le client appelle une méthode sur une API passerelleAPI, en transmettant un jeton porteur ou des paramètres de demande.

  2. APIGateway vérifie si la demande de méthode est configurée avec un autorisateur Lambda. Si tel est le cas, API Gateway appelle la fonction Lambda.

  3. La fonction Lambda authentifie l'appelant. La fonction peut s'authentifier de différentes manières :

    • En appelant un OAuth fournisseur pour obtenir un jeton OAuth d'accès.

    • En appelant un SAML fournisseur pour obtenir une SAML assertion.

    • En générant une IAM politique basée sur les valeurs des paramètres de demande.

    • En récupérant les informations d'identification d'une base de données.

  4. La fonction Lambda renvoie une IAM politique et un identifiant principal. Si la fonction Lambda ne renvoie pas ces informations, l'appel échoue.

  5. APIGateway évalue la IAM politique.

    • Si l'accès est refusé, API Gateway renvoie un code d'HTTPétat approprié, tel que403 ACCESS_DENIED.

    • Si l'accès est autorisé, API Gateway invoque la méthode.

      Si vous activez la mise en cache des autorisations, API Gateway met en cache la politique afin que la fonction d'autorisation Lambda ne soit pas invoquée à nouveau.

Vous pouvez personnaliser les réponses 403 ACCESS_DENIED ou les réponses de la 401 UNAUTHORIZED passerelle. Pour en savoir plus, consultez Réponses de Gateway pour REST APIs in API Gateway.

Choisir un type d'autorisateur Lambda

Il existe deux types d'autorisations Lambda :

Autorisateur Lambda basé sur les paramètres de demande (autorisateur) REQUEST

Un REQUEST autorisateur reçoit l'identité de l'appelant sous forme d'une combinaison d'en-têtes, de paramètres de chaîne de requête et de variables stageVariables. $context Vous pouvez utiliser un REQUEST autorisateur pour créer des politiques précises basées sur les informations provenant de plusieurs sources d'identité, telles que les variables de contexte $context.path et$context.httpMethod.

Si vous activez la mise en cache des autorisations pour un REQUEST autorisateur, API Gateway vérifie que toutes les sources d'identité spécifiées sont présentes dans la demande. Si une source d'identification spécifiée est manquante, nulle ou vide, API Gateway renvoie une 401 Unauthorized HTTP réponse sans appeler la fonction d'autorisation Lambda. Lorsque plusieurs sources d'identité sont définies, elles sont toutes utilisées pour dériver la clé de cache de l'autorisateur, l'ordre étant préservé. Vous pouvez définir une clé de cache précise en utilisant plusieurs sources d'identité.

Si vous modifiez l'un des éléments clés du cache et que vous redéployez le vôtreAPI, l'autorisateur supprime le document de politique mis en cache et en génère un nouveau.

Si vous désactivez la mise en cache des autorisations pour un REQUEST autorisateur, API Gateway transmet directement la demande à la fonction Lambda.

Autorisateur Lambda basé sur des jetons (autorisateur) TOKEN

Un TOKEN autorisateur reçoit l'identité de l'appelant dans un jeton porteur, tel qu'un jeton JSON Web (JWT) ou un jeton. OAuth

Si vous activez la mise en cache des autorisations pour un TOKEN autorisateur, le nom d'en-tête spécifié dans la source du jeton devient la clé du cache.

En outre, vous pouvez utiliser la validation par jeton pour saisir une RegEx déclaration. APIGateway effectue la validation initiale du jeton d'entrée par rapport à cette expression et invoque la fonction d'autorisation Lambda une fois la validation réussie. Cela permet de réduire le nombre d'appels vers votreAPI.

La IdentityValidationExpression propriété est prise en charge uniquement pour les TOKEN personnes autorisées. Pour de plus amples informations, veuillez consulter x-amazon-apigateway-authorizer objet.

Note

Nous vous recommandons d'utiliser un REQUEST autorisateur pour contrôler l'accès à votreAPI. Vous pouvez contrôler l'accès à votre compte API en fonction de plusieurs sources d'identité lorsque vous utilisez un REQUEST autorisateur, par rapport à une seule source d'identité lorsque vous utilisez un TOKEN autorisateur. En outre, vous pouvez séparer les clés de cache à l'aide de plusieurs sources d'identité pour un REQUEST autorisateur.

Exemple de fonction REQUEST Lambda d'autorisation

L'exemple de code suivant crée une fonction d'autorisation Lambda qui autorise une demande si l'HeaderAuth1en-tête, le paramètre de QueryString1 requête et la variable d'étape fournis par le client correspondent aux valeurs spécifiées deStageVar1, etheaderValue1, queryValue1 respectivement. stageValue1

Node.js
// A simple request-based authorizer example to demonstrate how to use request // parameters to allow or deny a request. In this example, a request is // authorized if the client-supplied HeaderAuth1 header, QueryString1 // query parameter, and stage variable of StageVar1 all match // specified values of 'headerValue1', 'queryValue1', and 'stageValue1', // respectively. export const handler = function(event, context, callback) { console.log('Received event:', JSON.stringify(event, null, 2)); // Retrieve request parameters from the Lambda function input: var headers = event.headers; var queryStringParameters = event.queryStringParameters; var pathParameters = event.pathParameters; var stageVariables = event.stageVariables; // Parse the input for the parameter values var tmp = event.methodArn.split(':'); var apiGatewayArnTmp = tmp[5].split('/'); var awsAccountId = tmp[4]; var region = tmp[3]; var restApiId = apiGatewayArnTmp[0]; var stage = apiGatewayArnTmp[1]; var method = apiGatewayArnTmp[2]; var resource = '/'; // root resource if (apiGatewayArnTmp[3]) { resource += apiGatewayArnTmp[3]; } // Perform authorization to return the Allow policy for correct parameters and // the 'Unauthorized' error, otherwise. if (headers.HeaderAuth1 === "headerValue1" && queryStringParameters.QueryString1 === "queryValue1" && stageVariables.StageVar1 === "stageValue1") { callback(null, generateAllow('me', event.methodArn)); } else { callback("Unauthorized"); } } // Help function to generate an IAM policy var generatePolicy = function(principalId, effect, resource) { // Required output: var authResponse = {}; authResponse.principalId = principalId; if (effect && resource) { var policyDocument = {}; policyDocument.Version = '2012-10-17'; // default version policyDocument.Statement = []; var statementOne = {}; statementOne.Action = 'execute-api:Invoke'; // default action statementOne.Effect = effect; statementOne.Resource = resource; policyDocument.Statement[0] = statementOne; authResponse.policyDocument = policyDocument; } // Optional output with custom properties of the String, Number or Boolean type. authResponse.context = { "stringKey": "stringval", "numberKey": 123, "booleanKey": true }; return authResponse; } var generateAllow = function(principalId, resource) { return generatePolicy(principalId, 'Allow', resource); } var generateDeny = function(principalId, resource) { return generatePolicy(principalId, 'Deny', resource); }
Python
# A simple request-based authorizer example to demonstrate how to use request # parameters to allow or deny a request. In this example, a request is # authorized if the client-supplied headerauth1 header, QueryString1 # query parameter, and stage variable of StageVar1 all match # specified values of 'headerValue1', 'queryValue1', and 'stageValue1', # respectively. import json def lambda_handler(event, context): print(event) # Retrieve request parameters from the Lambda function input: headers = event['headers'] queryStringParameters = event['queryStringParameters'] pathParameters = event['pathParameters'] stageVariables = event['stageVariables'] # Parse the input for the parameter values tmp = event['methodArn'].split(':') apiGatewayArnTmp = tmp[5].split('/') awsAccountId = tmp[4] region = tmp[3] restApiId = apiGatewayArnTmp[0] stage = apiGatewayArnTmp[1] method = apiGatewayArnTmp[2] resource = '/' if (apiGatewayArnTmp[3]): resource += apiGatewayArnTmp[3] # Perform authorization to return the Allow policy for correct parameters # and the 'Unauthorized' error, otherwise. if (headers['HeaderAuth1'] == "headerValue1" and queryStringParameters['QueryString1'] == "queryValue1" and stageVariables['StageVar1'] == "stageValue1"): response = generateAllow('me', event['methodArn']) print('authorized') return response else: print('unauthorized') raise Exception('Unauthorized') # Return a 401 Unauthorized response # Help function to generate IAM policy def generatePolicy(principalId, effect, resource): authResponse = {} authResponse['principalId'] = principalId if (effect and resource): policyDocument = {} policyDocument['Version'] = '2012-10-17' policyDocument['Statement'] = [] statementOne = {} statementOne['Action'] = 'execute-api:Invoke' statementOne['Effect'] = effect statementOne['Resource'] = resource policyDocument['Statement'] = [statementOne] authResponse['policyDocument'] = policyDocument authResponse['context'] = { "stringKey": "stringval", "numberKey": 123, "booleanKey": True } return authResponse def generateAllow(principalId, resource): return generatePolicy(principalId, 'Allow', resource) def generateDeny(principalId, resource): return generatePolicy(principalId, 'Deny', resource)

Dans cet exemple, la fonction du mécanisme d'autorisation Lambda vérifie les paramètres d'entrée et agit comme suit :

  • Si toutes les valeurs de paramètres requises correspondent aux valeurs attendues, la fonction d'autorisation renvoie une 200 OK HTTP réponse et une IAM politique semblables à ce qui suit, et la demande de méthode aboutit :

    { "Version": "2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] }
  • Dans le cas contraire, la fonction d'autorisation renvoie une 401 Unauthorized HTTP réponse et la demande de méthode échoue.

En plus de renvoyer une IAM politique, la fonction d'autorisation Lambda doit également renvoyer l'identifiant principal de l'appelant. Facultativement, il peut renvoyer un context objet contenant des informations supplémentaires qui peuvent être transmises au backend d'intégration. Pour de plus amples informations, veuillez consulter Sortie d'un autorisateur API Gateway Lambda.

Dans le code de production, vous devrez peut-être authentifier l'utilisateur avant d'accorder l'autorisation. Vous pouvez ajouter une logique d'authentification dans la fonction Lambda en appelant un fournisseur d'authentification comme indiqué dans la documentation de ce fournisseur.

Exemple de fonction TOKEN Lambda d'autorisation

L'exemple de code suivant crée une fonction d'autorisation TOKEN Lambda qui permet à un appelant d'invoquer une méthode si la valeur du jeton fournie par le client est. allow L'appelant n'est pas autorisé à invoquer la demande si la valeur du jeton estdeny. Si la valeur du jeton est unauthorized ou une chaîne vide, la fonction d'autorisation renvoie une 401 UNAUTHORIZED réponse.

Node.js
// A simple token-based authorizer example to demonstrate how to use an authorization token // to allow or deny a request. In this example, the caller named 'user' is allowed to invoke // a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke // the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty // string, the authorizer function returns an HTTP 401 status code. For any other token value, // the authorizer returns an HTTP 500 status code. // Note that token values are case-sensitive. export const handler = function(event, context, callback) { var token = event.authorizationToken; switch (token) { case 'allow': callback(null, generatePolicy('user', 'Allow', event.methodArn)); break; case 'deny': callback(null, generatePolicy('user', 'Deny', event.methodArn)); break; case 'unauthorized': callback("Unauthorized"); // Return a 401 Unauthorized response break; default: callback("Error: Invalid token"); // Return a 500 Invalid token response } }; // Help function to generate an IAM policy var generatePolicy = function(principalId, effect, resource) { var authResponse = {}; authResponse.principalId = principalId; if (effect && resource) { var policyDocument = {}; policyDocument.Version = '2012-10-17'; policyDocument.Statement = []; var statementOne = {}; statementOne.Action = 'execute-api:Invoke'; statementOne.Effect = effect; statementOne.Resource = resource; policyDocument.Statement[0] = statementOne; authResponse.policyDocument = policyDocument; } // Optional output with custom properties of the String, Number or Boolean type. authResponse.context = { "stringKey": "stringval", "numberKey": 123, "booleanKey": true }; return authResponse; }
Python
# A simple token-based authorizer example to demonstrate how to use an authorization token # to allow or deny a request. In this example, the caller named 'user' is allowed to invoke # a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke # the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty # string, the authorizer function returns an HTTP 401 status code. For any other token value, # the authorizer returns an HTTP 500 status code. # Note that token values are case-sensitive. import json def lambda_handler(event, context): token = event['authorizationToken'] if token == 'allow': print('authorized') response = generatePolicy('user', 'Allow', event['methodArn']) elif token == 'deny': print('unauthorized') response = generatePolicy('user', 'Deny', event['methodArn']) elif token == 'unauthorized': print('unauthorized') raise Exception('Unauthorized') # Return a 401 Unauthorized response return 'unauthorized' try: return json.loads(response) except BaseException: print('unauthorized') return 'unauthorized' # Return a 500 error def generatePolicy(principalId, effect, resource): authResponse = {} authResponse['principalId'] = principalId if (effect and resource): policyDocument = {} policyDocument['Version'] = '2012-10-17' policyDocument['Statement'] = [] statementOne = {} statementOne['Action'] = 'execute-api:Invoke' statementOne['Effect'] = effect statementOne['Resource'] = resource policyDocument['Statement'] = [statementOne] authResponse['policyDocument'] = policyDocument authResponse['context'] = { "stringKey": "stringval", "numberKey": 123, "booleanKey": True } authResponse_JSON = json.dumps(authResponse) return authResponse_JSON

Dans cet exemple, lorsque Gateway API reçoit une demande de méthode, API Gateway transmet le jeton source à cette fonction d'autorisation Lambda dans l'attribut. event.authorizationToken La fonction du mécanisme d'autorisation Lambda lit le jeton et agit comme suit :

  • Si la valeur du jeton est allow égale à cette valeur, la fonction d'autorisation renvoie une 200 OK HTTP réponse et une IAM politique semblables à ce qui suit, et la demande de méthode aboutit :

    { "Version": "2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] }
  • Si la valeur du jeton est deny égale à cette valeur, la fonction d'autorisation renvoie une 200 OK HTTP réponse et une Deny IAM politique semblables à ce qui suit, et la demande de méthode échoue :

    { "Version": "2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Deny", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] }
    Note

    En dehors de l'environnement de test, API Gateway renvoie une 403 Forbidden HTTP réponse et la demande de méthode échoue.

  • Si la valeur du jeton est unauthorized ou une chaîne vide, la fonction d'autorisation renvoie une 401 Unauthorized HTTP réponse et l'appel de méthode échoue.

  • Si le jeton a n'importe quelle autre valeur, le client reçoit une réponse 500 Invalid token et l'appel de la méthode échoue.

En plus de renvoyer une IAM politique, la fonction d'autorisation Lambda doit également renvoyer l'identifiant principal de l'appelant. Facultativement, il peut renvoyer un context objet contenant des informations supplémentaires qui peuvent être transmises au backend d'intégration. Pour de plus amples informations, veuillez consulter Sortie d'un autorisateur API Gateway Lambda.

Dans le code de production, vous devrez peut-être authentifier l'utilisateur avant d'accorder l'autorisation. Vous pouvez ajouter une logique d'authentification dans la fonction Lambda en appelant un fournisseur d'authentification comme indiqué dans la documentation de ce fournisseur.

Exemples supplémentaires de fonctions d'autorisation Lambda

La liste suivante présente d'autres exemples de fonctions d'autorisation Lambda. Vous pouvez créer une fonction Lambda dans le même compte, ou sur un compte différent, à partir duquel vous avez créé votre. API

Dans l'exemple précédent, vous pouvez utiliser les fonctions Lambda intégrées AWSLambdaBasicExecutionRole, car ces fonctions n'appellent aucun autre AWS service. Si votre fonction Lambda appelle d'autres AWS services, vous devez attribuer un rôle d'IAMexécution à la fonction Lambda. Pour créer le rôle, suivez les instructions dans Rôle d'exécution AWS Lambda.

Exemples supplémentaires de fonctions d'autorisation Lambda