Envoyez des attributs personnalisés à Amazon Cognito et injectez-les dans des jetons

Carlos Alessandro Ribeiro et Mauricio Mendoza, Amazon Web Services

Récapitulatif

L'envoi d'attributs personnalisés à un processus d'authentification Amazon Cognito peut fournir un contexte supplémentaire à une application, permettre des contrôles d'accès plus précis et faciliter la gestion des profils utilisateurs et des exigences d'authentification. Ces fonctionnalités sont utiles dans un large éventail d'applications et de scénarios, et elles peuvent vous aider à améliorer la sécurité globale et les fonctionnalités d'une application.

Ce modèle montre comment envoyer des attributs personnalisés à un processus d'authentification Amazon Cognito lorsqu'une application doit fournir un contexte supplémentaire au jeton d'accès ou au jeton d'identité (ID). Vous utilisez le fichier Node.js comme application principale. L'application authentifie un utilisateur à partir d'un groupe d'utilisateurs Amazon Cognito et transmet les attributs personnalisés nécessaires à la génération de jetons. Vous pouvez utiliser des AWS Lambda déclencheurs pour Amazon Cognito afin de personnaliser votre processus d'authentification sans avoir à personnaliser le code ou à déployer des efforts importants.

Important

Le code et les exemples de ce modèle ne sont pas recommandés pour les charges de travail de production car ils sont uniquement destinés à des fins de démonstration. Pour les charges de travail de production, une configuration supplémentaire est requise côté client. Utilisez ce modèle comme référence à des fins pilotes ou proof-of-concept à des fins uniquement.

Conditions préalables et limitations

Prérequis

• Un actif Compte AWS

• Autorisations pour créer et gérer des groupes d'utilisateurs et des fonctions Amazon Cognito AWS Lambda

• AWS Command Line Interface (AWS CLI), installé et configuré

• Un environnement de développement intégré (IDE) qui prend en charge Node.js

• Node.js version 18 ou ultérieure, installé

• npm version 8 ou ultérieure, installé

• TypeScript, installé

Limites

• Ce modèle n'est pas applicable à l'intégration d'applications via le flux d'authentification des informations d'identification du client.

• Le déclencheur de génération préalable au jeton peut ajouter ou modifier uniquement certains attributs du jeton d'accès et du jeton d'identité. Pour plus d'informations, consultez la section Déclencheur Lambda avant la génération de jetons dans la documentation Amazon Cognito.

Architecture

Architecture cible

Le schéma suivant montre l'architecture cible pour ce modèle. Il montre également comment l'application Node.js peut fonctionner avec un backend pour mettre à jour les bases de données. Cependant, les mises à jour de la base de données principale n'entrent pas dans le cadre de ce modèle.

Le schéma suivant illustre le flux de travail suivant :

1. L'application Node.js émet un jeton d'accès avec des attributs personnalisés pour le groupe d'utilisateurs Amazon Cognito.

2. Le groupe d'utilisateurs Amazon Cognito lance la fonction Lambda préalable à la génération des jetons, qui personnalise les jetons d'accès et d'identification.

3. L'application Node.js effectue un appel d'API via Amazon API Gateway.

Note

Les autres composants architecturaux présentés dans cette architecture ne le sont que par exemple et ne sont pas concernés par ce modèle.

Automatisation et mise à l'échelle

Vous pouvez automatiser le provisionnement des groupes d'utilisateurs, des fonctions AWS Lambda , des instances de base de données et d'autres ressources Amazon Cognito AWS CloudFormationen utilisant Terraform ou tout autre AWS Cloud Development Kit (AWS CDK)outil HashiCorp d'infrastructure sous forme de code (IaC) pris en charge. Si vous souhaitez étendre vos déploiements, utilisez des pipelines d'intégration continue et de livraison continue (CI/CD), qui permettent d'éviter les erreurs associées aux déploiements manuels.

Outils

Services AWS

• Amazon API Gateway vous aide à créer, publier, gérer, surveiller et sécuriser REST, HTTP, et ce, WebSocket APIs à n'importe quelle échelle.

• Amazon Cognito fournit des fonctionnalités d'authentification, d'autorisation et de gestion des utilisateurs pour les applications Web et mobiles.

• Amazon Elastic Container Service (Amazon ECS) est un service de gestion de conteneurs évolutif et rapide, qui facilite l'exécution, l'arrêt et la gestion de conteneurs Docker sur un cluster.

• AWS Lambda est un service de calcul qui vous aide à exécuter du code sans avoir à allouer ni à gérer des serveurs. Il exécute votre code uniquement lorsque cela est nécessaire et évolue automatiquement, de sorte que vous ne payez que pour le temps de calcul que vous utilisez.

• AWS SDK pour JavaScriptfournit une JavaScript API pour Services AWS. Vous pouvez l'utiliser pour créer des bibliothèques ou des applications pour Node.js ou le navigateur.

Autres outils

• Node.js est un environnement d' JavaScript exécution piloté par les événements conçu pour créer des applications réseau évolutives.

• npm est un registre de logiciels qui s'exécute dans un environnement Node.js et est utilisé pour partager ou emprunter des packages et gérer le déploiement de packages privés.

Bonnes pratiques

Nous vous recommandons de mettre en œuvre les meilleures pratiques suivantes :

• Secrets et données sensibles — Ne stockez pas de secrets ou de données sensibles dans l'application. Utilisez un système externe à partir duquel l'application peut extraire les données, tel que AWS AppConfigAWS Secrets Manager, ou AWS Systems Manager Parameter Store.

• Déploiement standardisé : utilisez des CI/CD pipelines pour déployer vos applications. Vous pouvez utiliser des services tels que AWS CodeBuildet AWS CodePipeline.

• Expiration du jeton : définissez une courte date d'expiration pour le jeton d'accès.

• Utiliser une connexion sécurisée — Toutes les communications entre l'application cliente et le backend doivent être cryptées à l'aide du protocole SSL/TLS. Utilisez AWS Certificate Manager (ACM) pour générer et gérer les SSL/TLS certificats, et utilisez Amazon CloudFront ou Elastic Load Balancing pour gérer la SSL/TLS résiliation.

• Valider les entrées utilisateur — Assurez-vous que toutes les entrées utilisateur sont validées pour éviter les attaques par injection et autres failles de sécurité. Utilisez des bibliothèques et des services de validation des entrées tels qu'Amazon API Gateway AWS WAFpour empêcher les vecteurs d'attaque courants.

• Utiliser des rôles IAM : utilisez des rôles AWS Identity and Access Management (IAM) pour contrôler l'accès aux AWS ressources et vous assurer que seuls les utilisateurs autorisés y ont accès. Respectez le principe du moindre privilège et assurez-vous que chaque utilisateur dispose uniquement des autorisations nécessaires pour remplir son rôle.

• Utiliser une politique de mot de passe : configurez une politique de mot de passe qui répond à vos exigences de sécurité, telles que la longueur, la complexité et l'expiration minimales. Utilisez Secrets Manager ou AWS Systems Manager Parameter Store pour stocker et gérer les mots de passe en toute sécurité.

• Activer l'authentification multifactorielle (MFA) : activez l'authentification multifactorielle pour tous les utilisateurs afin de fournir un niveau de sécurité supplémentaire et de réduire le risque d'accès non autorisé. Utilisez AWS IAM Identity CenterAmazon Cognito pour activer le MFA et d'autres méthodes d'authentification.

• Stockez les informations sensibles en toute sécurité : stockez les informations sensibles, telles que les mots de passe et les jetons d'accès, en toute sécurité à l'aide de AWS Key Management Service (AWS KMS) ou d'autres services de cryptage.

• Utiliser des méthodes d'authentification fortes — Pour renforcer la sécurité du processus d'authentification, utilisez des méthodes d'authentification fortes, telles que l'authentification biométrique ou l'authentification multifactorielle.

• Surveillance des activités suspectes : utilisez AWS CloudTraild'autres outils de surveillance pour détecter les activités suspectes et les menaces de sécurité potentielles. Configurez des alertes automatisées en cas d'activité inhabituelle et utilisez Amazon GuardDuty ou AWS Security Hubpour détecter des menaces potentielles.

• Révision et mise à jour régulières des politiques de sécurité — Passez régulièrement en revue et mettez à jour vos politiques et procédures de sécurité pour vous assurer qu'elles répondent à vos exigences de sécurité changeantes et aux meilleures pratiques. AWS Config À utiliser pour suivre et auditer les modifications apportées à vos politiques et procédures de sécurité.

• Inscription automatique : n'activez pas l'inscription automatique à un groupe d'utilisateurs Amazon Cognito. Pour plus d'informations, consultez Réduisez les risques de fraude lors de l'inscription des utilisateurs et d'envoi de SMS avec les groupes d'utilisateurs Amazon CognitoAWS (article de blog).

Pour connaître les meilleures pratiques supplémentaires, consultez les meilleures pratiques de sécurité pour les groupes d'utilisateurs Amazon Cognito dans la documentation Amazon Cognito.

Épopées

Configurez les AWS ressources

Tâche	Description	Compétences requises
Créez un groupe d'utilisateurs.	Dans un terminal CLI, entrez la commande suivante pour créer un groupe d'utilisateurs Amazon Cognito : aws cognito-idp create-user-pool \ --pool-name <MyUserPool> Entrez la commande suivante pour créer un identifiant client et un code secret qui seront utilisés avec le SDK pour JavaScript : aws cognito-idp create-user-pool-client \ --user-pool-id <UserPoolID> \ --client-name <MyNewClient> \ --no-generate-secret \ --explicit-auth-flows "USER_PASSWORD_AUTH" "ADMIN_NO_SRP_AUTH" Pour plus d'informations et des instructions sur la façon de configurer un groupe d'utilisateurs dans le AWS Management Console, voir Commencer avec les groupes d'utilisateurs et Ajouter des fonctionnalités et des options de sécurité supplémentaires à votre groupe d'utilisateurs. Astuce Pour réduire les coûts, utilisez le plan Essentials ou le plan Lite pour tester ce modèle. Pour plus d'informations, consultez la tarification d'Amazon Cognito.	Développeur d'applications, AWS DevOps
Ajoutez un utilisateur au groupe d'utilisateurs.	Entrez la commande suivante pour créer un utilisateur dans le groupe d'utilisateurs Amazon Cognito : aws cognito-idp sign-up \ --client-id <ClientID> \ --username <[e-mail]> \ --password <PASSWORD> \ --user-attributes Name="email",Value="<[e-mail]>" Name="name",Value="<Jane>"	Développeur d'applications, AWS DevOps
Ajoutez le client de l'application au groupe d'utilisateurs.	Accédez à la console Amazon Cognito. Choisissez Groupes d’utilisateurs. Choisissez le groupe d'utilisateurs que vous avez créé précédemment. Sous Définissez votre application, choisissez le type d'application qui correspond le mieux au scénario d'application pour lequel vous souhaitez créer des services d'authentification et d'autorisation. Dans Nommez votre application, entrez un nom descriptif ou utilisez le nom par défaut. Sous Ajouter une URL de retour, entrez un chemin de redirection vers votre application pour une fois l'authentification des utilisateurs terminée. Choisissez Créer votre application. Vous pouvez configurer les options avancées après avoir créé votre client d'application.	Administrateur système AWS, administrateur AWS, AWS DevOps, développeur d'applications
Créez un déclencheur Lambda pour la génération préalable au jeton.	Ouvrez la page Functions (Fonctions) de la console Lambda. Choisissez Créer une fonction. Sélectionnez Créer à partir de zéro. Dans le volet Informations de base, pour Nom de la fonction, entrezmyPreTokenGenerationLambdaFunction. Pour Runtime, choisissez Node.js 22. Laissez l'architecture définie sur x86_64. Choisissez Créer une fonction. Dans l'onglet Code, sous Source de code, entrez l'exemple de fonction Lambda dans la section Ressources supplémentaires de ce modèle. Cette fonction Lambda injecte les attributs personnalisés dans le jeton d'identification et le jeton d'accès.	AWS DevOps, développeur d'applications
Personnalisez le flux de travail du groupe d'utilisateurs.	Accédez à la console Amazon Cognito. Choisissez Groupes d’utilisateurs. Choisissez le groupe d'utilisateurs que vous avez créé précédemment. Dans le volet de navigation de gauche, sous Authentification, sélectionnez Extensions. Choisissez Ajouter un déclencheur Lambda. Ajoutez ou modifiez un déclencheur de prégénération de jetons. Pour Type de déclencheur, choisissez Authentification. Sous Authentification, sélectionnez Déclencheur de génération de jetons préalable. Pour la fonction Assign Lambda, sélectionnez. myPreTokenGenerationLambdaFunction Choisissez Ajouter un déclencheur Lambda. Choisissez une version Trigger Event des fonctionnalités de base + personnalisation des jetons d'accès pour les identités des utilisateurs ou des fonctionnalités de base + personnalisation des jetons d'accès pour les identités des utilisateurs et des machines. Ce paramètre met à jour les paramètres de demande qu’Amazon Cognito envoie à votre fonction afin d’inclure des champs pour la personnalisation des jetons d’accès. Pour plus d'informations, consultez la section Personnalisation des flux de travail des groupes d'utilisateurs à l'aide de déclencheurs Lambda dans la documentation Amazon Cognito.	AWS DevOps, développeur d'applications

Créez l'application Node.js

Tâche	Description	Compétences requises
Créez l'application Node.js.	Dans un terminal, entrez les commandes suivantes : mkdir my-app cd my-app npm init -y npm install --save-dev typescript npm i --save-dev @types/node npm i amazon-cognito-identity-js npx tsc --init mkdir src touch src/index.ts Modifiez le package.json fichier pour inclure les scripts de TypeScript compilation : "scripts": { "start": "node src/index.js", "build": "tsc" },	Développeur d’applications
Implémentez la logique d'authentification.	Ouvrez le fichier index.ts. Collez l'exemple de texte dactylographié fourni dans la section Ressources supplémentaires de ce modèle. Enregistrez et fermez le fichier index.ts. Note Vous pouvez créer votre propre TypeScript fichier ou modifier l'exemple fourni en fonction de votre cas d'utilisation.	Développeur d’applications
Configurez les variables d'environnement et le fichier de configuration.	Dans un terminal, entrez les commandes suivantes pour créer les variables d'environnement : export USERNAME="<COGNITO_USER_NAME>" export PASSWORD="<COGNITO_USER_PASSWORD>" export USER_POOL_ID="<COGNITO_USER_ID>" export CLIENT_ID="<COGNITO_CLIENT_ID>" Important Ne codez pas vos secrets en dur et ne divulguez pas vos informations d'identification.	Développeur d’applications
Exécutez l'application.	Entrez les commandes suivantes pour exécuter l'application et vérifier qu'elle fonctionne : npm run build npm start	Développeur d’applications
Vérifiez que les attributs personnalisés sont injectés dans les jetons.	Utilisez les fonctionnalités de débogage de votre IDE pour afficher les jetons d'accès et d'identification. Vérifiez que les attributs personnalisés ont été ajoutés. Pour les exemples de jetons, consultez la section Informations supplémentaires de ce modèle.	Développeur d’applications

Résolution des problèmes

Problème	Solution
ID client non valide lors de la tentative d'authentification de l'utilisateur	Cette erreur se produit généralement lorsque vous utilisez un ID client avec un secret client généré. Vous devez créer un ID client auquel aucun secret n'est attaché. Pour plus d'informations, consultez la section Paramètres spécifiques à l'application avec les clients d'applications.

Ressources connexes

• Personnalisation des flux de travail des groupes d'utilisateurs à l'aide de déclencheurs Lambda (documentation Amazon Cognito)

• Déclencheur Lambda avant la génération de jetons (documentation Amazon Cognito)

• CognitoIdentityProviderClient(AWS SDK pour JavaScript documentation)

• cognito-idp (documentation)AWS CLI

Informations supplémentaires

TypeScript Fichier d'exemple

L'exemple de code suivant est un TypeScript fichier qui appelle le processus d'authentification à l'aide d'un AWS SDK pour envoyer des attributs personnalisés à Amazon Cognito :

import * as AmazonCognitoIdentity from "amazon-cognito-identity-js";

const userPoolId: string = process.env.USER_POOL_ID ?? '';
const clientId: string = process.env.CLIENT_ID ?? '';

const poolData = {
  UserPoolId: userPoolId,
  ClientId: clientId
};
const userPool = new AmazonCognitoIdentity.CognitoUserPool(poolData);

export const loginWithCognitoSDK = function (userName: string, password: string) {
  const authenticationDetails = new AmazonCognitoIdentity.AuthenticationDetails({
    Username: userName,
    Password: password,
    ClientMetadata: {
        customGroup: "MyCustomGroup",
        customApplicationData: "Custom data from a custom application"
    }
  });
  const userData = {
    Username: userName,
    Pool: userPool
  };

  const cognitoUser = new AmazonCognitoIdentity.CognitoUser(userData);

  // Authenticate the user using the authenticationDetails object
  cognitoUser.authenticateUser(authenticationDetails, {
    onSuccess: function (result: any) {},
    onFailure: function (err: any) {},
  });
}
loginWithCognitoSDK(process.env.USERNAME ?? '', process.env.PASSWORD ?? '');

L'exemple utilise le AuthenticationDetails modèle du SDK pour fournir le nom JavaScript d'utilisateur, le mot de passe et leClientMetadada. Après l'authentification dans Amazon Cognito, les métadonnées du client peuvent être récupérées à partir des jetons d'accès et d'identification.

Exemple de fonction Lambda

L'exemple de code suivant est une fonction Lambda liée au jeton de pré-génération d'Amazon Cognito. Il vous permet de personnaliser le jeton d'accès et le jeton d'identification utilisés par Amazon Cognito. Les jetons sont transmis par le biais des intégrations entre votre architecture. Cet exemple inclut un attribut de réclamation personnalisé appelé customApplicationData et un nom de groupe personnalisé appelé MyCustomGroup :

export const handler = async(event, context, callback) => {
    event.response = {
        claimsOverrideDetails: {
            claimsToAddOrOverride: { customApplicationData: event.request.clientMetadata.customApplicationData },
            groupOverrideDetails: { groupsToOverride: [event.request.clientMetadata.customGroup] }
        }
    };
    callback(null, event);
};

Exemple de jeton d'accès

Vous pouvez décoder le jeton d'accès pour visualiser les attributs personnalisés qui ont été ajoutés. Voici un exemple de jeton d'accès :

{
  "sub": "6daf331f-4451-48b4-abde-774579299204",
  "cognito:groups": [
    "MyCustomGroup"
  ],
  "iss": "https://cognito-idp.<REGION>.amazonaws.com/<USERPOOL_ID>",
  "client_id": "<YOUR_CLIENT_ID>",
  "origin_jti": "acff7e91-09f9-4fde-8eec-38b0f8c47cdc",
  "event_id": "c5113a9c-1f01-435b-9b73-a5cd3e88514e",
  "token_use": "access",
  "scope": "aws.cognito.signin.user.admin",
  "auth_time": 1677979246,
  "exp": 1677982846,
  "iat": 1677979246,
  "jti": "5c9c2708-a871-4428-bd9b-18ad261bea90",
  "username": "<USER_NAME>"
}

Exemple de jeton d'identification

Vous pouvez décoder le jeton d'accès pour visualiser les attributs personnalisés qui ont été ajoutés. Voici un exemple de jeton d'accès :

{
  "sub": "6daf331f-4451-48b4-abde-774579299204",
  "cognito:groups": [
    "MyCustomGroup"
  ],
  "iss": "https://cognito-idp.<REGION>.amazonaws.com/<USERPOOL_ID>",
  "cognito:username": "<USER_NAME>",
  "origin_jti": "acff7e91-09f9-4fde-8eec-38b0f8c47cdc",
  "customApplicationData": "Custom data from a custom application",
  "aud": "<YOUR_CLIENT_ID>",
  "event_id": "c5113a9c-1f01-435b-9b73-a5cd3e88514e",
  "token_use": "id",
  "auth_time": 1677979246,
  "exp": 1677982846,
  "iat": 1677979246,
  "jti": "f7ca006b-f25b-44d2-a7a4-6e6423f4201f",
  "email": "<USER_EMAIL>"
}