Comment gérer les métadonnées du profil utilisateur

Vous pouvez accéder aux champs user_metadata et app_metadata des profils utilisateur et les définir à l’aide de diverses méthodes, selon votre cas d’utilisation.

Management API
Action post-login
Verrouiller
Règles

Lorsque vous créez un nouvel utilisateur à l’aide du terminal Create a User de Management API (POST /users), vous pouvez définir ses métadonnées en précisant les paramètres de corps user_metadata et app_metadata.

Exemple : créer un nouvel utilisateur avec des métadonnées

Pour créer un utilisateur avec les renseignements de profil suivants :

{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}

Effectuez l’appel POST suivant au terminal /post_users de pour créer l’utilisateur et définir les valeurs des propriétés :

Vous utilisez l’interface de ligne de commande (CLI) Auth0? Si ce n’est pas déjà fait, configurez et authentifiez votre session CLI avant d’exécuter cette commande.

Vous pouvez définir ou mettre à jour les métadonnées d’un utilisateur existant à l’aide du terminal Mettre à jour un utilisateur (PATCH /users/{id}) en précisant, de la même manière, les paramètres de corps user_metadata et app_metadta.

Exemple : mettre à jour les métadonnées d’un utilisateur existant

Supposons que vous ayez créé un utilisateur avec les valeurs de métadonnées suivantes :

{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}

Pour mettre à jour user_metadata et y ajouter l’adresse domiciliaire de l’utilisateur comme propriété de deuxième niveau :

{
    "addresses": {
        "home": "123 Main Street, Anytown, ST 12345"
    }
}

Vous devriez effectuer l’appel PATCH suivant :Le profil de l’utilisateur s’affichera désormais comme suit :

{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing",
        "addresses": {
            "home": "123 Main Street, Anytown, ST 12345"
        }
    },
    "app_metadata": {
        "plan": "full"
    }
}

Lorsque vous mettez à jour les métadonnées d’un utilisateur existant, seules les propriétés de premier niveau sont fusionnées dans l’objet. Toutes les propriétés des niveaux inférieurs sont remplacées.

Exemple : mettre à jour les sous-propriétés des métadonnées

Par exemple, pour ajouter l’adresse professionnelle d’un utilisateur comme propriété interne supplémentaire, vous devriez inclure tout le contenu de la propriété addresses. Comme l’objet addresses est une propriété de niveau racine, il sera fusionné dans l’objet JSON final qui représente l’utilisateur, mais ce ne sera pas le cas de ses sous-propriétés.

{
  "user_metadata": {
    "addresses": {
      "home": "123 Main Street, Anytown, ST 12345",
      "work": "100 Industrial Way, Anytown, ST 12345"
    }
  }
}

L’appel PATCH correspondant à l’API serait donc le suivant :

Pour supprimer une clé de métadonnées, effectuez un appel PATCH en définissant la valeur de cette clé à null (par exemple, { "user_metadata": {"color": null}}).Pour supprimer entièrement les métadonnées d’utilisateur ou d’application, effectuez un appel PATCH et attribuez un objet vide aux métadonnées elles-mêmes (par exemple, { "user_metadata": {} }).

Vous pouvez configurer un déclencheur post-login pour modifier user_metadata et app_metadata dans le cadre du flux de connexion d’un utilisateur.Les déclencheurs post-connexion sont utiles pour des tâches comme le stockage de données propres à l’application dans le profil utilisateur, la capture des journaux d’opérations de l’utilisateur, le mappage des attributs vers le champ de métadonnées, ou encore la mise en cache, dans le profil utilisateur, des valeurs d’opérations coûteuses afin de les réutiliser lors des connexions ultérieures.L’objet api de post-login fournit des opérations courantes que vous pouvez effectuer dans ce déclencheur. Pour gérer les métadonnées d’utilisateur, nous utiliserons les méthodes api.user.setAppMetadata et api.user.setUserMetadata. Par exemple, pour éviter qu’un comportement ne s’exécute plus d’une fois pour un utilisateur donné, vous pourriez utiliser une Action comme celle-ci :

exports.onExecutePostLogin = async (event, api) => {
  if (event.user.app_metadata.didAnExpensiveTask) {
    console.log(`Skipping the expensive task because it already occurred for ${event.user.email}.`);

    return;
  }
  // effectuer une tâche coûteuse
  api.user.setAppMetadata("didAnExpensiveTask", true);
};

Ici, nous avons ajouté une vérification au début de l’Action afin de déterminer si la tâche coûteuse a déjà été effectuée pour cet utilisateur. Si le champ de métadonnées existe, nous quittons la fonction.À la fin de l’Action, nous appelons api.user.setAppMetadata pour indiquer que nous souhaitons stocker des métadonnées dans l’objet utilisateur. À la fin de l’exécution de chaque déclencheur, les Actions mettent à jour le profil utilisateur en une seule opération. Si plusieurs appels à setUserMetadata sont effectués, même s’ils proviennent d’actions différentes au sein du même flux, les Actions ne mettront à jour le profil utilisateur qu’une seule fois, soit à la fin de l’exécution du déclencheur.

Plusieurs appels à setUserMetadata ou à setAppMetadata seront regroupés en une seule mise à jour du profil utilisateur à la fin de l’exécution du déclencheur, même s’ils sont effectués par des Actions différentes.

Dans le cas d’une redirection déclenchée avec api.redirect.sendUserTo(), toutes les mises à jour en attente des métadonnées d’utilisateur ou d’application seront appliquées au profil utilisateur avant que l’utilisateur ne soit redirigé vers le site externe.

Vous pouvez utiliser la bibliothèque Lock pour définir, ajouter, lire et mettre à jour les user_metadata. Vous pouvez lire les propriétés user_metadata de l’utilisateur de la même façon que vous liriez n’importe quelle autre propriété du profil utilisateur. Par exemple, l’extrait de code suivant récupère la valeur associée à user_metadata.hobby et l’attribue à un élément de la page :

// Utiliser l'accessToken obtenu lors de l'authentification pour appeler getUserInfo
lock.getUserInfo(accessToken, function(error, profile) {
  if (!error) {
    document.getElementById('hobby').textContent = profile.user_metadata.hobby;
  }
});

Vous pouvez utiliser additionalSignUpFields pour ajouter des champs personnalisés aux formulaires d’inscription des utilisateurs. Lorsqu’un utilisateur saisit des données dans un champ personnalisé, Auth0 enregistre les valeurs saisies dans le user_metadata de cet utilisateur. Pour en savoir plus sur l’ajout de user_metadata lors de l’inscription, consultez Champs d’inscription supplémentaires.

La date de fin de vie (EOL) des Rules et des Hooks est fixée au 18 novembre 2026, et ceux-ci ne sont plus offerts aux nouveaux locataires créés depuis le 16 octobre 2023. Les locataires existants qui ont des Hooks actifs conserveront l’accès au produit Hooks jusqu’à la fin de vie.Nous vous recommandons fortement d’utiliser Actions pour étendre Auth0. Actions vous donne accès à des informations de typage détaillées, à de la documentation intégrée et à des paquets npm publics, en plus de vous permettre de connecter des intégrations externes qui enrichissent votre expérience globale d’extensibilité. Pour en savoir plus sur ce qu’offre Actions, consultez Comprendre le fonctionnement d’Auth0 Actions.Pour faciliter votre migration, nous proposons des guides qui vous aideront à migrer des Rules vers Actions et à migrer des Hooks vers Actions. Nous avons également une page dédiée, Move to Actions, qui présente 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 des Rules et des Hooks, consultez notre article de blogue : Preparing for Rules and Hooks End of Life.

Vous pouvez lire, mettre à jour et supprimer des métadonnées au moyen des Rules Auth0. Les sections suivantes s’appuient 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": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

Lecture des métadonnées

Vous pouvez lire les métadonnées à l’aide de règles avec la . Vous pouvez également rechercher des renseignements liés au profil dans user_metadata, par exemple :

name
nickname
given_name
family_name

Par exemple, supposons que les métadonnées suivantes sont stockées pour un utilisateur dont l’adresse courriel est jane.doe@example.com\u00a0:

{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}

À l’aide de l’exemple de métadonnées ci-dessus, vous pouvez faire référence à des éléments précis de l’ensemble de données dans les Rules Auth0 ou au moyen d’un appel à la Management API, comme suit :

console.log(user.email); // "jane.doe@example.com"
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. Par défaut, user.app_metadata est Undefined.

Exemple : condition fondée sur les métadonnées

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
  }
}

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
  }
  ...
}

Lecture des métadonnées de l’application (clientMetadata)

Les métadonnées d’application (clientMetadata) sont une propriété facultative de premier niveau de l’objet context. Pour les applications existantes, cette propriété n’aura aucune valeur.

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

Vous pouvez utiliser des Rules pour associer 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 attribuer un rôle d’administrateur à l’utilisateur\u00a0:

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

  // rendre persistante la mise à jour des app_metadata
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

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

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer", "administrator" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

Mettre à jour les métadonnées d’utilisateur

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

function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  // mettre à jour les user_metadata qui seront incluses dans la réponse
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

  // 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 ainsi la représentation JSON suivante des détails du profil utilisateur :

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue",
      "fontSize": 12
    }
  }
}

Mettre à jour simultanément les métadonnées d’application et les métadonnées d’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 les user_metadata qui feront partie de la réponse
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

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

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

  // conserver la mise à jour des 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 ainsi la représentation JSON suivante des détails du profil utilisateur :

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "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é, définissez sa valeur à null.

Exemple de suppression des rôles d’un utilisateur

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

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  // mettre à jour les app_metadata qui seront incluses dans la réponse
  user.app_metadata.roles = null;

  // enregistrer de façon persistante la mise à jour des app_metadata
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

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

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "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 cette valeur précise. Par exemple, pour retirer 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 les app_metadata qui seront incluses dans la réponse
    user.app_metadata.roles.splice(index, 1);
  }

  // rendre persistante la mise à jour des app_metadata
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

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

{
  "user_id": "google-oauth2|1234",
  "email": "john.doe@gmail.com",
  "app_metadata": {
    "roles": [ ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

La propriété roles existe toujours, mais ne contient aucune valeur.

Supprimer des propriétés et des valeurs de métadonnées d’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;

  // rendre persistante 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 ainsi la représentation JSON suivante des détails du profil utilisateur :

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": { }
  }
}

Concepts

Procédures

Référence

Cas d’utilisation

Comment gérer les métadonnées du profil utilisateur

Lecture des métadonnées

Lecture des métadonnées de l’application (clientMetadata)

Mettre à jour les métadonnées

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

Mettre à jour les métadonnées d’utilisateur

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

Supprimer les métadonnées

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

Exemple de suppression des rôles d’un utilisateur

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

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

​Lecture des métadonnées

​Lecture des métadonnées de l’application (clientMetadata)

​Mettre à jour les métadonnées

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

​Mettre à jour les métadonnées d’utilisateur

​Mettre à jour simultanément les métadonnées d’application et les métadonnées d’utilisateur

​Supprimer les métadonnées

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

​Exemple de suppression des rôles d’un utilisateur

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

​Supprimer des propriétés et des valeurs de métadonnées d’utilisateur

Lecture des métadonnées

Lecture des métadonnées de l’application (clientMetadata)

Mettre à jour les métadonnées

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

Mettre à jour les métadonnées d’utilisateur

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

Supprimer les métadonnées

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

Exemple de suppression des rôles d’un utilisateur

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

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