Flux de travail du mécanisme d'autorisation Lambda Étapes à suivre pour créer un mécanisme d'autorisation Lambda Création d'une fonction de mécanismes d'autorisation Lambda dans la console Lambda

Utilisation des mécanismes d'autorisation Lambda API Gateway

Un mécanisme d'autorisation Lambda (anciennement appelé mécanisme d'autorisation personnalisée) est une fonction API Gateway qui utilise une fonction Lambda pour contrôler l'accès à votre API.

Un mécanisme d'autorisation Lambda s'avère utile pour mettre en œuvre un schéma d'autorisation personnalisée qui utilise une stratégie d'authentification par jeton de porteur, telle qu'OAuth ou SAML, ou qui utilise les paramètres de demande afin de déterminer l'identité de l'appelant.

Lorsqu'un client envoie une demande à l'une de vos méthodes d'API, API Gateway appelle votre mécanisme d'autorisation Lambda, qui accepte l'identité de l'appelant comme entrée et renvoie une stratégie IAM comme sortie.

Il existe deux types d'autorisations Lambda :

Un mécanisme d'autorisation Lambda par jeton (également appelé mécanisme d'autorisation TOKEN) reçoit l'identité de l'appelant dans un jeton de porteur, par exemple un jeton web JSON ou un jeton OAuth.
Un mécanisme d'autorisation Lambda basé sur les paramètres de demande (également appelé mécanisme d'autorisation REQUEST) reçoit l'identité de l'appelant dans une combinaison d'en-têtes, de paramètres de chaîne de requête et de variables stageVariables et $context.

Pour les API WebSocket, seuls les mécanismes d'autorisation basés sur des paramètres de demande sont pris en charge.

Il est possible d'utiliser une fonction AWS Lambda d'un compte AWS différent de celui dans lequel vous avez créé votre fonction de mécanisme d'autorisation Lambda. Pour plus d'informations, consultez Configuration d'un mécanisme d'autorisation Lambda entre comptes.

Pour accéder à des exemples de fonction Lambda, veuillez consulter aws-apigateway-lambda-authorizer-blueprints sur GitHub.

Rubriques

Flux de travail du mécanisme d'autorisation Lambda

Le schéma suivant illustre le flux de travail d'autorisation des mécanismes d'autorisation de Lambda.

Flux de travail d'autorisation Lambda API Gateway

Le client appelle une méthode sur une méthode d'API API Gateway, en transmettant un jeton de porteur ou des paramètres de demande.
API Gateway vérifie si un mécanisme d'autorisation Lambda est configuré pour la méthode. Si c'est le cas, API Gateway appelle la fonction Lambda.
La fonction Lambda authentifie l'appelant des façons suivantes :
- En appelant un fournisseur OAuth pour obtenir un jeton d'accès OAuth
- En appelant un fournisseur SAML pour obtenir une déclaration SAML
- En générant une stratégie IAM basée sur les valeurs des paramètres de demande
- En extrayant les informations d'identification d'une base de données
Si l'appel aboutit, la fonction Lambda accorde l'accès en renvoyant un objet de sortie contenant au moins une stratégie IAM et un identifiant principal.
API Gateway évalue la stratégie.
- Si l'accès est refusé, API Gateway renvoie un code de statut HTTP adapté, par exemple 403 ACCESS_DENIED.
- Si l'accès est autorisé, API Gateway exécute la méthode. Si la mise en cache est activée dans les paramètres du mécanisme d'autorisation, API Gateway met également en cache la stratégie afin qu'il ne soit pas nécessaire de rappeler la fonction du mécanisme d'autorisation Lambda.

Étapes à suivre pour créer un mécanisme d'autorisation Lambda API Gateway

Pour créer un mécanisme d'autorisation Lambda, procédez comme suit :

Créez la fonction du mécanisme d'autorisation Lambda dans la console Lambda comme décrit dans Création d'une fonction de mécanisme d'autorisation Lambda API Gateway dans la console Lambda. Vous pouvez commencer par utiliser l'un des exemples de plan, dans lequel vous personnaliserez l'entrée et la sortie à votre gré.
Configurez la fonction Lambda en tant que mécanisme d'autorisation API Gateway et configurez une méthode d'API pour l'exiger, comme décrit dans Configuration d'un mécanisme d'autorisation Lambda à l'aide de la console API Gateway. Sinon, si vous avez besoin d'un mécanisme d'autorisation Lambda entre comptes, veuillez consulter Configuration d'un mécanisme d'autorisation Lambda entre comptes.

Note

Vous pouvez également configurer un mécanisme d'autorisation à l'aide de l'interface de ligne de commande AWS ou d'un kit SDK AWS.
Testez votre mécanisme d'autorisation avec Postman, comme décrit dans Appel d'une API avec des mécanismes d'autorisation Lambda API Gateway.

Création d'une fonction de mécanisme d'autorisation Lambda API Gateway dans la console Lambda

Avant de configurer un mécanisme d'autorisation Lambda, vous devez créer la fonction Lambda qui implémente la logique permettant d'autoriser et, si nécessaire, d'authentifier l'appelant. La console Lambda fournit un plan Python, que vous pouvez utiliser en choisissant Use a blueprint (Utiliser un plan), puis en choisissant le plan api-gateway-authorizer-python. Sinon, utilisez l'un des plans du référentiel GitHub awslabs comme point de départ.

Pour les exemples de fonctions de mécanisme d'autorisation Lambda présentés dans cette section, qui n'appellent pas d'autres services, vous pouvez utiliser le plan AWSLambdaBasicExecutionRole intégré. Lors de la création de la fonction Lambda pour votre propre mécanisme d'autorisation Lambda API Gateway, vous devez attribuer un rôle d'exécution IAM à la fonction Lambda si elle appelle d'autres services AWS. Pour créer le rôle, suivez les instructions dans Rôle d'exécution AWS Lambda.

Pour accéder à d'autres exemples de fonction Lambda, veuillez consulter aws-apigateway-lambda-authorizer-blueprints sur GitHub.

EXEMPLE : Création d'une fonction de mécanisme d'autorisation Lambda par jeton

Pour créer une fonction de mécanisme d'autorisation Lambda par jeton, entrez le code Node.js suivant dans la console Lambda et testez-le dans la console API Gateway, comme suit.

Dans la console Lambda, choisissez Create function (Créer une fonction).
Choisissez Créer à partir de zéro.
Entrez un nom pour la fonction.
Sélectionnez Créer une fonction.

Copiez et collez le code suivant dans l'éditeur de code.



// 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.

exports.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;
}

Choisissez Deploy (Déployer).
Dans la console API Gateway, créez une API simple, si vous n'en avez pas déjà une.
Sélectionnez votre API dans la liste des API.
Choisissez Authorizers (Mécanismes d'autorisation).
Choisissez Créer une nouveau mécanisme d'autorisation.
Entrez un nom pour le mécanisme d'autorisation.
Pour Type, choisissez Lambda.
Sous Fonction Lambda, choisissez la région dans laquelle vous avez créé votre fonction de mécanisme d'autorisation Lambda, puis choisissez le nom de la fonction dans la liste déroulante.
Laissez Lambda Invoke Role (Rôle d'appel Lambda) vide.
Pour Lambda Event Payload (Charge utile d'événement Lambda), choisissez Token (Jeton).
Sous Token Source (Source de jeton), entrez authorizationToken.
Choisissez Create (Créer), puis Grant & Create (Accorder et créer).
Sélectionnez Test.
Pour la valeur authorizationToken entrez allow.
Sélectionnez Test.

Dans cet exemple, lorsque l'API reçoit une demande de méthode, API Gateway transmet le jeton source à cette fonction du mécanisme 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', la fonction du mécanisme d'autorisation renvoie une réponse HTTP 200 OK et une stratégie IAM qui ressemble à 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', la fonction du mécanisme d'autorisation renvoie une réponse HTTP 403 Forbidden et une stratégie IAM Deny qui ressemble à 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/"
    }
  ]
}

Si la valeur du jeton est 'unauthorized' ou une chaîne vide, la fonction du mécanisme d'autorisation renvoie une réponse HTTP 401 Unauthorized et l'appel de la 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.

Note

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

En plus de renvoyer une stratégie IAM, la fonction du mécanisme d'autorisation Lambda doit également renvoyer l'identifiant principal de l'appelant. En outre, elle peut éventuellement renvoyer un objet context qui inclut des informations supplémentaires transmissibles au backend d'intégration. Pour de plus amples informations, veuillez consulter Sortie d'un mécanisme d'autorisation Lambda Amazon API Gateway.

EXEMPLE : Création d'une fonction de mécanisme d'autorisation Lambda par demande

Pour créer une fonction de mécanisme d'autorisation Lambda par demande, entrez le code Node.js suivant dans la console Lambda et testez-le dans la console API Gateway, comme suit.

Dans la console Lambda, choisissez Create function (Créer une fonction).
Choisissez Créer à partir de zéro.
Entrez un nom pour la fonction.
Sélectionnez Créer une fonction.

Copiez et collez le code suivant dans l'éditeur de code.


exports.handler = function(event, context, callback) {        
    console.log('Received event:', JSON.stringify(event, null, 2));

    // 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.

    // 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.
    var authResponse = {};
    var condition = {};
    condition.IpAddress = {};
     
    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);
}

Choisissez Deploy (Déployer).
Dans la console API Gateway, créez une API simple, si vous n'en avez pas déjà une.
Sélectionnez votre API dans la liste des API.
Choisissez Authorizers (Mécanismes d'autorisation).
Choisissez Créer une nouveau mécanisme d'autorisation.
Entrez un nom pour le mécanisme d'autorisation.
Pour Type, choisissez Lambda.
Sous Fonction Lambda, choisissez la région dans laquelle vous avez créé votre fonction de mécanisme d'autorisation Lambda, puis choisissez le nom de la fonction dans la liste déroulante.
Laissez Lambda Invoke Role (Rôle d'appel Lambda) vide.
Pour Lambda Event Payload (Charge utile d'événement Lambda), choisissez Request (Demande).
Sous Identity Sources (Sources d'identité), ajoutez un en-tête nommé headerauth1, une chaîne de requête nommée QueryString1 et une variable d'étape nommée StageVar1.
Choisissez Create (Créer), puis Grant & Create (Accorder et créer).
Sélectionnez Test.
Sous HeaderAuth1, entrez headerValue1. Sous QueryString1, entrez queryValue1. Sous StageVar1, entrez stageValue1.
Sélectionnez Test.

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ètre obligatoires correspondent aux valeurs attendues, la fonction du mécanisme d'autorisation renvoie une réponse HTTP 200 OK et une stratégie IAM qui ressemble à ce qui suit, et la demande de la 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/"
    }
  ]
}
```
Sinon, la fonction du mécanisme d'autorisation renvoie une réponse HTTP 401 Unauthorized et l'appel de la méthode échoue.

Note

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Utilisation de balises pour contrôler l'accès à une API REST

Configuration d'un mécanisme d'autorisation Lambda à l'aide de la console