Sécuriser les points de terminaison d’AWS API Gateway à l’aide d’autorisateurs personnalisés

Comment sécuriser AWS API Gateway à l’aide d’autorisateurs personnalisés qui acceptent des jetons d’accès émis par Auth0.

Sécurisez les endpoints d’AWS API Gateway à l’aide d’autorisateurs personnalisés qui acceptent les jetons d’accès émis par Auth0. Pour ce faire, vous configurez votre API dans API Gateway, créez et configurez vos fonctions AWS Lambda (y compris les autorisateurs personnalisés) pour sécuriser vos endpoints d’API, et implémentez le flux d’autorisation afin que vos utilisateurs puissent récupérer auprès d’Auth0 les jetons d’accès nécessaires pour accéder à votre API.

Pour en savoir plus, consultez AWS Lambda Overview une fois connecté à votre AWS API Gateway.

API Gateway étend les capacités de Lambda en ajoutant une couche de service devant vos fonctions Lambda afin de renforcer la sécurité, de gérer les transformations des messages d’entrée et de sortie, et d’offrir des fonctionnalités comme la limitation du débit et l’audit. Une approche sans serveur simplifie vos besoins opérationnels, puisque des aspects comme la mise à l’échelle et la tolérance aux pannes relèvent désormais du service de calcul qui exécute votre code.

Les autorisateurs personnalisés vont :

• Vérifier que le jeton d’accès a été transmis dans l’en-tête authorization de la requête permettant d’accéder à l’API.
• Vérifier la signature RS256 du jeton d’accès à l’aide d’une clé publique obtenue au moyen d’un endpoint JWKS.
• S’assurer que le jeton d’accès contient les claims iss de l’émetteur et aud de l’audience requis.

Suivez les étapes ci-dessous pour utiliser des autorisateurs personnalisés :

1. Créer une API Auth0
2. Importer et déployer l’API AWS API Gateway
3. Créer les autorisateurs personnalisés
4. Sécuriser l’API à l’aide d’autorisateurs personnalisés
5. Tester votre déploiement

Pour en savoir plus sur les algorithmes de signature, consultez Signing Algorithms. Pour plus de détails sur l’utilisation de JWKS, consultez JSON Web Key Sets.

​

Fonctionnement des custom authorizers d’API Gateway

Selon Amazon, un custom authorizer d’API Gateway est une « fonction Lambda que vous fournissez pour contrôler l’accès à votre API à l’aide de stratégies d’authentification par jeton Bearer, comme OAuth ou SAML. »

Chaque fois qu’une personne (ou un programme) tente d’appeler votre API, API Gateway vérifie si un custom authorizer est configuré pour cette API.

Si un custom authorizer est configuré pour l’API, API Gateway appelle le custom authorizer et lui transmet le jeton d’autorisation extrait de l’en-tête de la requête reçue.

Vous pouvez utiliser le custom authorizer pour mettre en œuvre différents types de stratégies d’autorisation, y compris la vérification des JWT, afin de renvoyer des politiques IAM autorisant la requête. Si la politique renvoyée n’est pas valide ou si les permissions sont refusées, l’appel d’API échoue.

Si la politique est valide, l’API la met en cache, l’associe au jeton entrant et l’utilise pour la requête en cours ainsi que pour les requêtes suivantes. Vous pouvez configurer la durée de mise en cache de la politique. La valeur par défaut est de 300 secondes et la durée maximale de mise en cache est de 3600 secondes (vous pouvez aussi définir la valeur à 0 pour désactiver la mise en cache).

Pour en savoir plus, consultez What is Amazon API Gateway? dans le guide du développeur d’Amazon. Pour plus d’information sur la vérification des JWT, consultez notre article sur les JSON Web Token.

​

Prérequis

Vous devez créer un compte AWS. Cela vous donne accès aux fonctionnalités d’AWS, notamment API Gateway et Lambda. Tous les nouveaux utilisateurs bénéficient de douze mois d’accès à l’offre gratuite d’AWS.

​

Créer une API Auth0

Configurez les API utilisées par les applications qui obtiennent une autorisation avec succès.

1. Accédez à Auth0 Dashboard > Applications > APIs, puis sélectionnez Create API.

2. Entrez des valeurs dans les champs suivants, puis sélectionnez Create.

   Champ	Description
   Nom	Un nom convivial pour votre API. C’est le nom que vous verrez dans votre liste d’API Auth0.
   Identifiant	Un identifiant logique pour votre API. Nous vous recommandons de formater cet identifiant comme une URL https://your-api-gateway.
   Algorithme de signature	L’algorithme qu’Auth0 doit utiliser pour signer le jeton d’accès émis. Pour en savoir plus, consultez Signing Algorithms.

Pour voir les détails de votre API nouvellement créée, consultez la vue Settings.

La création d’une API crée également une Machine to Machine Application à utiliser avec l’API. Vous pouvez voir cette application affichée comme Authorized dans la vue Machine to Machine Application. Prenez note du Client ID; vous en aurez besoin dans la partie 3 de ce tutoriel.

​

Importer et déployer l’API AWS API Gateway

Cette partie du tutoriel est adaptée de l’exemple officiel d’AWS. Consultez cet exemple pour des notes et des explications détaillées.

Dans cette étape, vous allez :

• Importer une API dans API Gateway
• Tester l’importation d’une API
• Déployer une API pour l’utiliser avec n’importe quelle application frontale
• Tester le déploiement d’une API

​

Importer et configurer l’API Pets

1. Connectez-vous à votre compte AWS et, à partir de la liste déroulante Services située dans la barre de navigation supérieure, accédez à API Gateway Console.

2. Si vous avez déjà créé une API, accédez simplement à API Gateway Console et cliquez sur Create API. Vous aurez l’option de créer l’Example API dans le formulaire Create new API. Si vous n’avez jamais créé d’API avec API Gateway, l’écran suivant s’affichera. Cliquez sur Get Started pour continuer.

   

   Un message contextuel vous souhaitera la bienvenue dans API Gateway. Cliquez sur OK pour continuer.

3. Dans le formulaire Create new API, vous verrez que l’Example API est sélectionnée par défaut et qu’un exemple d’API est déjà défini dans l’éditeur. Nous utiliserons cette API pour le reste du tutoriel; commencez donc le processus de création de l’API en cliquant sur Import.

   

   Une fois l’opération terminée, AWS affiche un message indiquant que votre API a été créée et remplie avec les données fournies. Notez que l’API comporte déjà des méthodes qui lui sont associées (notamment GET et POST). Vous pouvez afficher les détails d’une méthode, modifier sa configuration ou tester son invocation en cliquant sur son nom dans l’arborescence des ressources.

   

​

Testez votre API

Pour tester votre API, cliquez sur POST sous /pets. La fenêtre Method Execution s’ouvre alors et présente un aperçu de la structure et du comportement de la méthode POST :

• Method Request et Method Response : l’interface de l’API avec le front-end
• Integration Request et Integration Response : l’interface de l’API avec le back-end

Vous pouvez utiliser cette zone pour tester l’API.

1. Cliquez sur Test (affiché dans le volet Client situé au milieu de la page). Vous serez redirigé vers la page /pets - POST - Method Test. Faites défiler jusqu’au bas de la page, puis entrez l’extrait suivant dans Request Body :

   {"type": "dog", "price": 249.99}
   

   Le corps de la requête indique les attributs de l’animal que nous voulons ajouter à la base de données, ainsi que son prix.

2. Cliquez sur Test pour continuer. Les résultats du test s’afficheront à droite de la page.

   

​

Déployer l’API

Le test que nous venons d’effectuer a été réalisé à l’aide de la console API Gateway. Pour utiliser l’API avec une autre application, vous devrez la déployer dans une étape.

1. Dans le menu Actions, sélectionnez Deploy API.

2. Entrez les valeurs suivantes, puis cliquez sur Déployer.

   Paramètre	Valeur
   Étape de déploiement	Choisissez [New Stage]
   Nom de l’étape	Entrez un nom pour votre étape
   Description de l’étape	Entrez une description pour votre étape
   Deployment description	Entrez une description pour le déploiement de votre API

​

Tester le déploiement

Une fois l’API déployée avec succès, vous serez redirigé vers le Test Stage Editor. Vous pourrez alors tester l’API pour vérifier qu’elle a bien été déployée.

1. En haut de la fenêtre Test Stage Editor se trouve une bannière bleue affichant votre Invoke URL. Il s’agit de l’URL utilisée pour appeler l’endpoint GET de votre API. Cliquez sur le lien pour envoyer la requête de méthode GET / dans un navigateur. Vous devriez obtenir la réponse de réussite suivante :

   

2. Dans la page Stages, développez l’arborescence sous Test. Cliquez sur GET sous /pets/{petId}.

   

3. Vous verrez un Invoke URL affiché dans la bannière bleue en haut de la fenêtre. La dernière partie, {petID}, correspond à une variable de chemin. Remplacez cette variable par 1, puis accédez à la nouvelle URL dans votre navigateur. Vous devriez recevoir une réponse HTTP 200 avec la charge utile JSON suivante :

   {
     "id": 1,
     "type": "dog",
     "price": 249.99
   }
   

​

Créer les authorizers personnalisés

Maintenant que nous avons une API entièrement fonctionnelle gérée par API Gateway, sécurisez-la afin que seules les personnes disposant de l’autorisation appropriée puissent accéder au back-end de l’API.

Utilisez les request authorizers personnalisés d’API Gateway pour autoriser vos API au moyen de stratégies d’autorisation par bearer token, comme OAuth 2.0 ou SAML. Pour chaque requête entrante, voici ce qui se passe :

1. API Gateway vérifie qu’un authorizer personnalisé est correctement configuré.
2. API Gateway appelle l’authorizer personnalisé (qui est une fonction Lambda) avec le jeton d’autorisation.
3. Si le jeton d’autorisation est valide, l’authorizer personnalisé renvoie les politiques AWS Identity and Access Management (IAM) appropriées.
4. API Gateway utilise les politiques renvoyées à l’étape 3 pour autoriser la requête.

​

Préparez le custom authorizer

Vous pouvez télécharger un exemple de custom authorizer compatible avec les jetons émis par Auth0. Ensuite, vous devrez personnaliser les fichiers afin que le custom authorizer fonctionne dans votre environnement.

1. Décompressez le dossier contenant les fichiers d’exemple téléchargés ci-dessus à l’emplacement de votre choix, puis accédez-y à l’aide de la ligne de commande.

2. Dans le dossier d’exemple, exécutez npm install pour installer les packages Node.js requis pour le déploiement; AWS exige que ces fichiers soient inclus dans l’archive que vous téléverserez vers AWS à une étape ultérieure.

3. Configurez votre environnement local à l’aide d’un fichier .env. Vous pouvez copier le fichier .env.sample (en le renommant du même coup en .env) avec cp .env.sample .env. Apportez les modifications suivantes :

   Parameter	Valeur
   TOKEN_ISSUER	L’issuer du jeton. Si Auth0 est l’issuer du jeton, utilisez https://{yourDomain}/. Assurez-vous d’inclure la barre oblique à la fin.
   JWKS_URI	L’URL du JWKS endpoint. Si Auth0 est l’issuer du jeton, utilisez https://{yourDomain}/.well-known/jwks.json
   AUDIENCE	La valeur identifier de l’API que vous avez créée dans la section Créer une API Auth0 ci-dessus.

   Par exemple, une fois rempli, votre fichier .env devrait ressembler à ceci :

​

Tester l’authorizer personnalisé localement

Obtenez un jeton d’accès JWT valide. Il existe plusieurs façons d’en obtenir un, et la méthode choisie dépend du type de votre application, de son niveau de confiance ou de l’expérience globale de l’utilisateur final. Pour en savoir plus, consultez Obtenir des jetons d’accès.

1. Vous pouvez obtenir un jeton de test pour votre API en allant dans Auth0 Dashboard > Applications > APIs, en sélectionnant votre API, puis Test.
2. Créez un fichier local event.json contenant le jeton. Vous pouvez copier le fichier d’exemple (exécutez cp event.json.sample event.json). Remplacez ACCESS_TOKEN par votre jeton JWT et methodArn par la valeur ARN appropriée pour la méthode GET de votre API.

Pour obtenir le methodArn :

1. Dans la console API Gateway, ouvrez l’API PetStore.
2. Dans le menu de navigation de gauche, sélectionnez Resources.
3. Dans le panneau central Resources, développez l’arborescence des ressources. Sous /pets, sélectionnez GET.
4. Dans la zone Method Request, vous verrez l’ARN.
5. Exécutez le test avec npm test.

Le test utilise le package lambda-local pour tester l’authorizer personnalisé à l’aide de votre jeton. Si le test réussit, vous verrez une sortie semblable à celle-ci :

Message
------
{
    "principalId": "C8npTEMVnBrILsBTI91MOh6dfuZbPVAU@clients",
    "policyDocument": {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Action": "execute-api:Invoke",
                "Effect": "Allow",
                "Resource": "arn:aws:execute-api:us-east-1:1234567890:apiId/stage/method/resourcePath"
            }
        ]
    },
    "context": {
        "scope": "FULL_LIST_OF_SCOPES"
    }
}

Si la valeur de Effect est Allow, votre authorizer aurait autorisé la requête vers API Gateway.

Pour en savoir plus, consultez Lambda-local sur NPM.

​

Créer le rôle IAM

Le rôle IAM dispose des autorisations requises pour appeler des fonctions Lambda; avant de poursuivre avec notre authorizer personnalisé, nous devons créer un rôle IAM capable d’appeler cet authorizer personnalisé chaque fois qu’API Gateway reçoit une requête d’accès.

1. Connectez-vous à AWS, puis accédez à la console IAM. Dans le menu de navigation de gauche, sélectionnez Roles.

2. Sélectionnez Create new role.

3. Sous AWS service, sélectionnez la ligne AWS Lambda, puis Next: Permissions.

4. À l’écran Attach permissions policy, sélectionnez AWSLambdaRole. Vous pouvez utiliser le filtre fourni pour restreindre la liste des options. Sélectionnez Next: Tags, puis Next: Review pour continuer.

5. À l’écran Review, entrez un Role name, par exemple Auth0Integration. Laissez les autres champs tels quels. Sélectionnez Create role.

6. Une fois le rôle créé par AWS, vous serez redirigé vers la page Roles d’IAM. Sélectionnez votre nouveau rôle.

7. Sur la page Summary du rôle que vous venez de créer, sélectionnez la vue Trust relationships.

8. Sélectionnez Edit trust relationship, puis remplissez le champ Policy Document avec l’extrait JSON suivant :

   {
      "Version": "2012-10-17",
      "Statement": [
         {
            "Effect": "Allow",
            "Principal": {
               "Service": [
                  "apigateway.amazonaws.com",
                  "lambda.amazonaws.com"
               ]
            },
            "Action": "sts:AssumeRole"
         }
      ]
   }
   

9. Cliquez sur Update Trust Policy.

10. Vous serez redirigé vers la page Summary. Copiez la valeur Role ARN pour l’utiliser plus tard.

    

​

Créez la fonction Lambda et déployez l’authorizer personnalisé

Maintenant que vous avez configuré votre authorizer personnalisé pour votre environnement et l’avez testé pour vous assurer qu’il fonctionne, déployez-le sur AWS.

1. Créez un bundle que vous pouvez téléverser sur AWS en exécutant npm run bundle. Cette commande génère un bundle custom-authorizer.zip contenant le code source, la configuration et les modules Node.js requis par AWS Lambda.

2. Accédez à la console Lambda, puis cliquez sur Create function.

3. Sur la page Select blueprint, cliquez sur Author from scratch pour créer une fonction vide. Sous Basic information, indiquez des valeurs pour les paramètres suivants :

   Paramètre	Valeur
   Name	Un nom pour votre fonction Lambda, par exemple jwtRsaCustomAuthorizer
   Description	Une description de votre fonction Lambda (facultatif)
   Runtime	Sélectionnez Node.js 10.x

4. Cliquez sur Create Function pour continuer.

5. Sur la page Configuration de votre fonction, faites défiler la page jusqu’à la section Function Code.

6. Sélectionnez Upload a .ZIP file comme Code entry type.

7. Cliquez sur Upload et sélectionnez le bundle custom-authorizer.zip que vous avez créé précédemment.

8. Créez ensuite les trois variables d’environnement suivantes. Notez que ces informations sont identiques à celles du fichier .env.

   Paramètre	Valeur
   TOKEN_ISSUER	L’émetteur du jeton. Si Auth0 est l’émetteur du jeton, utilisez https://{yourDomain}/
   JWKS_URI	L’URL du point de terminaison JWKS. Si Auth0 est l’émetteur du jeton, utilisez https://{yourDomain}/.well-known/jwks.json
   AUDIENCE	La valeur identifier de l’API que vous avez créée à l’étape 1.

9. Dans la section Execution role, sélectionnez Use an existing role, puis le rôle IAM que vous avez créé précédemment comme Existing role.

10. Sous Basic settings, définissez Timeout sur 30 secondes.

11. Cliquez sur Save.

12. Pour tester la fonction Lambda que vous venez de créer, cliquez sur Test dans le coin supérieur droit.

13. Copiez le contenu de votre fichier event.json dans le formulaire Configure test event. Vous pouvez utiliser le modèle d’événement « Hello World » par défaut.

14. Cliquez sur Create.

15. Exécutez votre test en le sélectionnant, puis en cliquant sur Test. Si le test réussit, vous verrez : « Execution result: succeeded ». En développant la fenêtre de sortie, vous devriez voir un message semblable à celui que vous avez reçu après la réussite de votre test local.

    

​

Configurer le custom authorizer d’API Gateway

1. Revenez à API Gateway Console et ouvrez l’API PetStore que nous avons créée précédemment.

2. Dans le panneau de navigation de gauche, ouvrez Authorizers et sélectionnez Create New Authorizer, puis définissez les paramètres suivants et cliquez sur Create.

   Paramètre	Valeur
   Nom	jwt-rsa-custom-authorizer
   Type	Sélectionnez Lambda
   Région Lambda	Utilisez la région de la fonction Lambda que vous avez créée précédemment
   Fonction Lambda	jwtRsaCustomAuthorizer
   Rôle d’invocation Lambda	L’ARN du rôle IAM que vous avez copié ci-dessus
   Payload d’événement Lambda	Sélectionnez Token
   Source du token	Authorization
   Validation du token	^Bearer [-0-9a-zA-z\.]*$
   TTL (secondes)	3600

3. Une fois l’authorizer créé par AWS et la page rechargée, testez votre authorizer en cliquant sur Test et en fournissant le token Auth0 (Bearer ey...) que vous avez utilisé précédemment. Si le test réussit, vous verrez une réponse semblable à la suivante.

   

​

Sécuriser l’API à l’aide d’authorizers personnalisés

Pour savoir comment sécuriser les points de terminaison de votre API, consultez l’article du guide du développeur Amazon API Gateway : Use API Gateway Lambda Authorizers.

​

Configurer les ressources d’API Gateway pour utiliser l’autorisateur personnalisé

1. Connectez-vous à AWS, puis accédez à la API Gateway Console.

   Les autorisateurs personnalisés se configurent pour chaque méthode. Si vous voulez sécuriser plusieurs méthodes à l’aide d’un seul autorisateur, vous devrez répéter les instructions suivantes pour chacune d’elles.

2. Ouvrez l’API PetStore que nous avons créée à l’étape 2 de ce tutoriel. Dans l’arborescence Resource du volet central, sélectionnez la méthode GET sous la ressource /pets.

   

3. Sélectionnez Method Request.

4. Sous Settings, cliquez sur l’icône crayon à droite de Authorization, puis choisissez l’autorisateur personnalisé jwt-rsa-custom-authorizer que vous avez créé à l’étape 3.

5. Cliquez sur l’icône coche pour enregistrer votre choix d’autorisateur personnalisé. Assurez-vous que le champ API Key Required est défini à false.

​

Déployer l’API

Pour rendre vos modifications publiques, déployez votre API.

1. Dans le menu Actions, sélectionnez Deploy API.

2. Entrez les valeurs suivantes, puis cliquez sur Déployer :

   Paramètre	Valeur
   Étape de déploiement	Choisissez [New Stage]
   Nom de l’étape	Entrez un nom pour votre étape
   Description de l’étape	Entrez une description pour votre étape
   Deployment description	Entrez une description pour votre déploiement d’API

Si l’opération réussit, vous serez redirigé vers le Test Stage Editor. Notez l’URL d’invocation indiquée dans le bandeau bleu en haut, car vous en aurez besoin pour tester votre déploiement.

​

Testez votre déploiement

Pour tester votre déploiement, effectuez une requête GET à l’Invoke URL que vous avez notée à l’étape précédente. Si ce test échoue, vérifiez que vous avez bien obtenu le jeton d’accès JWT.

Pour plus de détails, consultez Obtenir des jetons d’accès.