Gérer les métadonnées avec Rules

Découvrez comment gérer les métadonnées de l’application, les métadonnées utilisateur et les client metadata à l’aide de Rules.

La date de fin de vie (EOL) de Rules et Hooks sera le 18 novembre 2026, et ils ne sont plus disponibles pour les nouveaux tenants créés à compter du 16 octobre 2023. Les tenants existants ayant des Hooks actifs conserveront l’accès à la fonctionnalité Hooks jusqu’à la fin de vie.

Nous vous recommandons fortement d’utiliser Actions pour étendre Auth0. Avec Actions, vous avez accès à des informations de typage détaillées, à une documentation intégrée et à des packages npm publics, et vous pouvez connecter des intégrations externes qui améliorent votre expérience globale en matière d’extensibilité. Pour en savoir plus sur ce qu’offre Actions, consultez Understand How Auth0 Actions Work.

Pour vous aider dans votre migration, nous proposons des guides pour vous aider à passer de Rules à Actions et à passer de Hooks à Actions. Nous avons aussi une page dédiée Move to Actions qui met en évidence des comparaisons de fonctionnalités, une démo d’Actions et d’autres ressources pour vous accompagner tout au long de votre migration.

Pour en savoir plus sur la dépréciation de Rules et Hooks, consultez notre billet de blogue : Preparing for Rules and Hooks End of Life.

Vous pouvez lire, mettre à jour et supprimer des métadonnées à l’aide de Auth0 Rules. Dans les sections suivantes, nous ferons référence à cet exemple, dans lequel l’utilisateur et ses renseignements sont représentés par l’extrait JSON suivant :

{
  "user_id": "jdoe",
  "email": "[e-mail]",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

​

Lire les métadonnées

Vous pouvez lire les métadonnées à l’aide de règles et de la Management API. Vous pouvez aussi rechercher des renseignements liés au profil dans user_metadata, comme :

• name
• nickname
• given_name
• family_name

Par défaut, les attributs du profil utilisateur fournis par des fournisseurs d’identité autres qu’Auth0 (comme Google, Facebook ou X) ne peuvent pas être modifiés directement, car ils sont mis à jour à partir du fournisseur d’identité chaque fois que l’utilisateur se connecte. Pour en savoir plus sur les attributs provenant des fournisseurs d’identité, consultez Configurer la connexion du fournisseur d’identité pour les mises à jour du profil utilisateur.

Pour pouvoir modifier les attributs racine name, nickname, given_name, family_name ou picture dans le profil utilisateur normalisé, vous devez configurer la synchronisation de votre connexion avec Auth0 afin que les attributs utilisateur soient mis à jour à partir du fournisseur d’identité uniquement lors de la création du profil utilisateur. Ces attributs racine pourront ensuite être modifiés individuellement ou au moyen d’importations en bloc

À titre d’exemple, supposons que les métadonnées suivantes soient stockées pour un utilisateur ayant l’adresse courriel [e-mail] :

{
    "email": "[e-mail]",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}

À partir des métadonnées d’exemple ci-dessus, vous pouvez vous référer à des éléments précis de l’ensemble de données dans Auth0 Rules ou au moyen d’une requête à la Management API, comme suit :

console.log(user.email); // "[e-mail]"
console.log(user.user_metadata.hobby); // "surfing"
console.log(user.app_metadata.plan); // "full"

Tout fragment JSON valide peut être utilisé comme métadonnées, mais notez que user.app_metadata vaut Undefined par défaut.

Pour lire les métadonnées disponibles, vous devrez accéder à la propriété utilisateur appropriée.

​

Lire les métadonnées de l’application

Vous pouvez prendre une décision en fonction des rôles de l’utilisateur :

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  if (user.app_metadata.roles.indexOf('writer')){
    // code à exécuter
  }
  ...
}

​

Lire les métadonnées utilisateur

Vous pouvez prendre des décisions en fonction de préférences précises, comme une préférence de couleur :

function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  if (user.user_metadata.preferences.color === 'black'){
    // code à exécuter
  }
  ...
}

​

Lire les métadonnées de l’application (clientMetadata)

Les métadonnées de l’application (clientMetadata) constituent une propriété facultative de premier niveau de l’objet context. Les applications existantes n’auront aucune valeur associée à cette propriété.

function(user, context, callback){
  context.clientMetadata = context.clientMetadata || {};
  if (context.clientMetadata.usersuppliedkey1 === 'black'){
    // ce code ne serait pas exécuté pour l'utilisateur
  }
  ...
}

​

Mettre à jour les métadonnées

Utilisez Rules pour mapper les attributs SAML qu’Auth0 reçoit de l’IdP vers user_metadata ou app_metadata.

​

Mettre à jour les métadonnées de l’application

Pour ajouter un rôle administratif à l’utilisateur :

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  // mettre à jour l'app_metadata qui fera partie de la réponse
  user.app_metadata.roles = user.app_metadata.roles || [];
  user.app_metadata.roles.push('administrator');

  // enregistrer la mise à jour de l'app_metadata
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

Voici la représentation JSON suivante du détail du profil utilisateur :

{
  "user_id": "jdoe",
  "email": "[e-mail]",
  "app_metadata": {
    "roles": [ "writer", "administrator" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

​

Mettre à jour les métadonnées de l’utilisateur

Pour ajouter la préférence fontSize de l’utilisateur à son profil :

function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  // mettre à jour le user_metadata qui fera partie de la réponse
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

  // enregistrer la mise à jour du user_metadata
  auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

On obtient la représentation JSON suivante du détail du profil utilisateur :

{
  "user_id": "jdoe",
  "email": "[e-mail]",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue",
      "fontSize": 12
    }
  }
}

​

Mettre à jour simultanément les métadonnées de l’application et de l’utilisateur

Pour réduire le temps de traitement de la règle, vous pouvez mettre à jour app_metadata et user_metadata dans la même règle :

function(user, context, callback){

  var q = require('q');

  user.app_metadata = user.app_metadata || {};
  user.user_metadata = user.user_metadata || {};
  // mettre à jour le user_metadata qui fera partie de la réponse
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

  // mettre à jour le app_metadata qui fera partie de la réponse
  user.app_metadata.roles = user.app_metadata.roles || [];
  user.app_metadata.roles.push('admin');

  // enregistrer la mise à jour du app_metadata
  var appMetadataPromise  = auth0.users.updateAppMetadata(user.user_id, user.app_metadata);

  // enregistrer la mise à jour du user_metadata
  var userMetadataPromise = auth0.users.updateUserMetadata(user.user_id, user.user_metadata);

  // utiliser la bibliothèque q pour attendre que toutes les promesses soient terminées
  q.all([userMetadataPromise, appMetadataPromise])
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

On obtient la représentation JSON suivante des détails du profil utilisateur :

{
  "user_id": "jdoe",
  "email": "[e-mail]",
  "app_metadata": {
    "roles": [ "writer", "admin" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue",
      "fontSize": 12
    }
  }
}

​

Supprimer les métadonnées

​

Supprimer les propriétés et les valeurs des métadonnées d’application

Pour supprimer une propriété, définissez sa valeur sur null.

​

Exemple de suppression des rôles d’un utilisateur

Pour supprimer les rôles d’un utilisateur, utilisez la règle suivante :

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  // mettre à jour l'app_metadata qui fera partie de la réponse
  user.app_metadata.roles = null;

  // enregistrer la mise à jour de l'app_metadata
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

On obtient la représentation JSON suivante du profil de l’utilisateur :

{
  "user_id": "jdoe",
  "email": "[e-mail]",
  "app_metadata": { },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

​

Exemple de suppression d’une seule valeur de propriété

Pour supprimer une seule valeur d’une propriété, retirez simplement cette valeur. Par exemple, pour retirer le rôle writer du profil de l’utilisateur :

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  user.app_metadata.roles = user.app_metadata.roles || [];

  var index = user.app_metadata.roles.indexOf('writer');

  if (index !== -1){
    // mettre à jour l'app_metadata qui fera partie de la réponse
    user.app_metadata.roles.splice(index, 1);
  }

  // enregistrer la mise à jour de l'app_metadata
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

Cela donne la représentation JSON suivante du profil utilisateur :

{
  "user_id": "google-oauth2|1234",
  "email": "[e-mail]",
  "app_metadata": {
    "roles": [ ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

Notez que la propriété roles existe toujours, mais ne contient aucune valeur.

​

Supprimer les propriétés et les valeurs des métadonnées utilisateur

Pour supprimer la préférence de couleur de l’utilisateur :

function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  // mettre à jour les user_metadata qui feront partie de la réponse
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  delete user.user_metadata.preferences.color;

  // enregistrer la mise à jour des user_metadata
  auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
  });
}

On obtient la représentation JSON suivante du détail du profil utilisateur :

{
  "user_id": "jdoe",
  "email": "[e-mail]",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": { }
  }
}

​

En savoir plus

• Utiliser la Management API à partir des Rules
• Propriétés de l’objet context dans les Rules
• Auth0 Rules