Gérer les métadonnées avec des règles

Apprenez à gérer les métadonnées des applications, des utilisateurs et des clients à l’aide de règles.

La date de fin de vie (EOL) des Règles et des Appels sera le 18 novembre 2026. Ils ne sont plus disponibles pour les nouveaux locataires créés à partir du 16 octobre 2023. Les locataires actuels ayant des hooks actifs conserveront l’accès aux produit Hooks jusqu’à la fin de leur durée de vie.

Nous vous conseillons vivement d’utiliser les Actions pour étendre Auth0. Avec les Actions, vous avez accès à des informations de type enrichies, à une documentation intégrée et à des packages npm publics, et vous pouvez connecter des intégrations externes qui optimisent votre expérience d’extensibilité globale. Pour en savoir plus sur ce que les Actions proposent, consultez Comprendre comment fonctionnent Auth0 Actions.

Pour vous aider dans votre migration, nous proposons des guides qui vous aideront à migrer des Règles vers les Actions et à migrer des Hooks vers les Actions. Nous avons également une page dédiée à la Migration vers les Actions qui met en évidence les comparaisons de fonctionnalités, une démo des Actions et d’autres ressources pour vous aider dans votre parcours de migration.

Pour en savoir plus sur l’obsolescence des Règles et des Appels, consultez notre article de blog : Preparing for Rules and Hooks End of Life (Préparation à la fin de vie des règles et des crochets).

Vous pouvez lire, mettre à jour et supprimer les métadonnées à l’aide des Règles d’Auth0. Dans les sections suivantes, nous nous référerons à cet exemple où l’utilisateur et ses informations sont représentés par l’extrait de code 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 avec Management API. Vous pouvez également rechercher des informations relatives au profil dans user_metadata, telles que :

• name
• nickname
• given_name
• family_name

Par défaut, les attributs du profil utilisateur fournis par des fournisseurs d’identité autres qu’Auth0 (tels que Google, Facebook ou X) ne sont pas directement modifiables, car ils sont mis à jour par le fournisseur d’identité à chaque fois que l’utilisateur se connecte.

Pour pouvoir modifier les attributs name, nickname, given_name, family_name ou les attributs racine de l’image sur le profil utilisateur normalisé, vous devez configurer votre synchronisation de connexion avec Auth0 de manière à ce que les attributs de l’utilisateur soient mis à jour à partir du fournisseur d’identité uniquement lors de la création du profil utilisateur. Ces attributs racine seront alors disponibles à l’édition individuelle ou par importation en grande quantité.

À titre d’exemple, supposons que les métadonnées suivantes soient stockées pour un utilisateur dont l’adresse courriel est [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 vous référer à des éléments précis de l’ensemble de données dans des règles d’Auth0 ou via un appel à 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 extrait JSON valide peut être utilisé comme métadonnées, mais notez que user.app_metadata est Undefined par défaut.

Pour lire les métadonnées disponibles, vous devez accéder à la propriété utilisateur adéquate.

​

Lire les métadonnées de l’application

Vous pouvez prendre une décision en fonction des rôles utilisateur.

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  if (user.app_metadata.roles.indexOf('writer')){
    // code to be executed
  }
  ...
}

​

Lire les métadonnées utilisateur

Vous pouvez baser vos décisions sur des 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 to be executed
  }
  ...
}

​

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’ont pas de valeur pour cette propriété.

function(user, context, callback){
  context.clientMetadata = context.clientMetadata || {};
  if (context.clientMetadata.usersuppliedkey1 === 'black'){
    // this code would not be executed for the user
  }
  ...
}

​

Mettre à jour les métadonnées

Utilisez des règles pour mapper les attributs SAML qu’Auth0 reçoit de l’IdP dans 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 || {};
  // update the app_metadata that will be part of the response
  user.app_metadata.roles = user.app_metadata.roles || [];
  user.app_metadata.roles.push('administrator');

  // persist the app_metadata update
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

Il en résulte la représentation JSON suivante des informations 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 d’un utilisateur

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

function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  // update the user_metadata that will be part of the response
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

  // persist the user_metadata update
  auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

Il en résulte la représentation JSON suivante des informations 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 les app_metadata et les 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 || {};
  // update the user_metadata that will be part of the response
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

  // update the app_metadata that will be part of the response
  user.app_metadata.roles = user.app_metadata.roles || [];
  user.app_metadata.roles.push('admin');

  // persist the app_metadata update
  var appMetadataPromise  = auth0.users.updateAppMetadata(user.user_id, user.app_metadata);

  // persist the user_metadata update
  var userMetadataPromise = auth0.users.updateUserMetadata(user.user_id, user.user_metadata);

  // using q library to wait for all promises to complete
  q.all([userMetadataPromise, appMetadataPromise])
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

Il en résulte la représentation JSON suivante des informations 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 de l’application

Pour supprimer une propriété, il suffit de définir sa valeur sur null.

​

Exemple de suppression des rôles d’un utilisateur

Pour supprimer les rôles de l’utilisateur, utilisez l’exemple de règle suivant :

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  // update the app_metadata that will be part of the response
  user.app_metadata.roles = null;

  // persist the app_metadata update
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

Il en résulte 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 spécifique. 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){
    // update the app_metadata that will be part of the response
    user.app_metadata.roles.splice(index, 1);
  }

  // persist the app_metadata update
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

Il en résulte 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 || {};
  // update the user_metadata that will be part of the response
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  delete user.user_metadata.preferences.color;

  // persist the user_metadata update
  auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
  });
}

Il en résulte la représentation JSON suivante des informations du profil utilisateur :

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

​

En savoir plus

• Utiliser Management API à partir des règles
• Propriétés de l’objet contexte dans les règles
• Règles d’Auth0