Gérer les métadonnées avec Rules

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

La date de fin de vie (EOL) de Rules et Hooks est fixée au 18 novembre 2026, et ils ne sont plus offerts aux nouveaux locataires créés à compter du 16 octobre 2023. Les locataires existants qui ont des Hooks actifs conserveront l’accès au produit Hooks jusqu’à sa fin de vie.

Nous vous recommandons fortement d’utiliser Actions pour étendre Auth0. Avec Actions, vous avez accès à des informations de type plus riches, à de la 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’Actions offre, consultez Comprendre le fonctionnement d’Auth0 Actions.

Pour vous aider dans votre migration, nous proposons des guides pour migrer de Rules vers Actions et migrer de Hooks vers Actions. Nous avons également une page dédiée, Passer à Actions, qui présente des comparaisons de fonctionnalités, une démonstration 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 des Auth0 Rules. Dans les sections suivantes, nous nous appuierons sur l’exemple ci-dessous, 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 Rules avec la Management API. Vous pouvez aussi rechercher des informations liées au profil dans user_metadata, par exemple :

• 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 alors être modifiés individuellement ou par importation en masse

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

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

En utilisant l’exemple de métadonnées ci-dessus, vous pouvez accéder à des éléments précis de l’ensemble de données dans les Auth0 Rules ou au moyen d’un appel à 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"

N’importe quel extrait JSON valide peut servir de 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 bonne propriété de l’utilisateur.

​

Lire les métadonnées de l’application

Vous pouvez prendre une décision selon les 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 de l’utilisateur

Vous pouvez prendre des décisions en fonction de préférences précises, par exemple 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) correspondent à une propriété facultative de premier niveau de l’objet context. Les applications existantes n’ont aucune valeur définie pour 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 faire correspondre les attributs SAML qu’Auth0 reçoit de l’IdP à user_metadata ou à app_metadata.

​

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

Pour ajouter un rôle d’administrateur à 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);
    });
}

Cela donne la représentation JSON suivante des renseignements 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 utilisateur :

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;

  // sauvegarder 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 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 celles de l’utilisateur

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

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');

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

  // sauvegarder 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 résolues
  q.all([userMetadataPromise, appMetadataPromise])
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

Cela donne 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 à null.

​

Exemple de suppression des rôles de l’utilisateur

Pour supprimer les rôles de l’utilisateur, utilisez la Rule d’exemple 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);
    });
}

Vous obtenez ainsi la représentation JSON suivante du profil 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é, supprimez cette valeur précise. Par exemple, pour supprimer le rôle writer du profil 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);
    });
}

On obtient 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 qu’elle ne contient aucune valeur.

​

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

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

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 || {};
  delete user.user_metadata.preferences.color;

  // sauvegarder 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);
  });
}

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

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

​

En savoir plus

• Utiliser le Management API dans les Rules
• Propriétés de l’objet de contexte dans les Rules
• Auth0 Rules