Delegated Administration : Settings Query Hook

Découvrez comment utiliser le Settings Query Hook avec l’extension Delegated Administration.

Le Settings Query Hook vous permet de personnaliser l’apparence et la convivialité de l’extension Delegated Administration.

​

Contrat du Hook

• ctx : Objet de contexte.

  • request.user : Utilisateur connecté.
  • locale : Paramètre régional (déduit de l’URL) — https://{yourTenant}.us.webtask.io/auth0-delegated-admin/en/users définira locale sur en.

• callback(error, settings) : Fonction de rappel à laquelle vous pouvez renvoyer une erreur et un objet de paramètres.

​

Exemple d’utilisation

function(ctx, callback) {
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;

  return callback(null, {
    // Seules ces connexions doivent être visibles dans le sélecteur de connexions. Si une seule connexion est disponible, le sélecteur de connexions ne s'affichera pas dans l'interface utilisateur.
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // Le dictionnaire vous permet de remplacer le titre du tableau de bord et l'étiquette « Memberships » dans la boîte de dialogue Create User.
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments',
      menuName: ctx.request.user.name
    },
    // L'option CSS vous permet d'injecter un fichier CSS personnalisé selon le contexte de l'utilisateur actuel (p. ex. : un CSS différent pour chaque client)
    css: (department && department !== 'IT') && 'https://cdn.jsdelivr.net/gh/auth0-extensions/auth0-delegated-administration-extension/docs/theme/fabrikam.css',
    // Cette option vous permet de restreindre la création de nouveaux utilisateurs
    canCreateUser: (department === 'IT')
  });
}

​

Propriétés

• connections : Liste des connexions dans lesquelles cet administrateur est autorisé à créer et à modifier des utilisateurs.

• dict : Dictionnaire qui vous permet de remplacer le titre du dashboard et le libellé Memberships dans la boîte de dialogue Create User.

  • dict.title : Titre à afficher en haut de l’UI.
  • dict.memberships : Libellé à définir pour les champs Memberships.
  • dict.menuName : Nom à définir pour le menu déroulant situé en haut à droite.
  • dict.logoutUrl : URL de remplacement pour l’option de menu de déconnexion.

• userFields : Tableau de champs utilisateur (voir « champs personnalisés » ci-dessous).

• css : URL de type String pour l’importation de CSS.

• altcss : URL de type String pour l’importation d’un deuxième ensemble de CSS. Vous pouvez l’utiliser pour préciser, par exemple, une feuille de style d’accessibilité avec des polices plus grandes. L’utilisateur verra un élément de menu lui permettant d’activer ou de désactiver cet ensemble de CSS.

• languageDictionary : URL de type String ou objet Dictionary (voir « localisation » ci-dessous).

• suppressRawData : Définissez cette valeur sur true pour ignorer les pages qui affichent du JSON brut

• errorTranslator : Fonction qui traduit les messages d’erreur selon la localisation. Exemple : (function (error, languageDictionary) { return languageDictionary.customErrors[error] || error; }).toString()

• canCreateUser : Indicateur booléen. S’il est défini sur false, supprime le bouton Create User et interdit la création de nouveaux utilisateurs; true par défaut.

​

Champs personnalisés

À partir de la version 3.0 de la Delegated Admin Extension, vous pouvez définir des champs personnalisés et préciser leurs valeurs. Les champs personnalisés peuvent être stockés dans les champs métadonnées utilisateur et métadonnées d’application, accessibles lors des processus de création ou de mise à jour de l’utilisateur.

Vous pouvez aussi personnaliser les champs existants définis par Auth0, comme email, username, name et connection.

Pour utiliser des champs personnalisés, vous devez :

• Ajouter votre liste de userFields au Settings Query Hook
• Implémenter un Write Hook. Les champs personnalisés nécessitent l’utilisation du Write Hook pour mettre correctement à jour user_metadata et app_metadata. Vous devez mettre à jour l’objet user transmis à la fonction de rappel avec les user_metadata et app_metadata du contexte (objet ctx) fourni au Hook.

Pour en savoir plus sur les Write Hooks, consultez Delegated Administration : Write Hook.

Exemple de schéma pour userFields:

userFields: [
    {
        "property": string, // obligatoire
        "label": string,
        "sortProperty": string,
        "display": true || function.toString(),
        "search": false || {
            "display": true || function.toString()
            "listOrder": 1,
            "listSize": string(###%), // p. ex. 15%
            "filter": boolean,
            "sort": boolean
        },
        "edit": false || {
            "display": true || function.toString()
            "type": "text || select || password || hidden",
            "component": "InputText || Input Combo || InputMultiCombo || InputSelectCombo",
            "options": Array(string) || Array ({ "value": string, "label": string }),
            "disabled": true || false,
            "validationFunction": function.toString()
        },
        "create": false || {
            "display": true || function.toString()
            "type": "text || select || password || hidden",
            "component": "InputText || Input Combo || InputMultiCombo || InputSelectCombo",
            "options": Array(string) || Array ({ "value": string, "label": string }),
            "disabled": true || false,
            "validationFunction": function.toString()
        }
    },
    ...
]

• property (obligatoire) : Nom de propriété de l’objet ctx.payload pour le Write Hook. Dans le Write Hook, "property": "app_metadata.dbId" définit ctx.payload.app_metadata.dbId.

• label : Libellé utilisé lorsqu’un libellé est ajouté au champ sur la page d’information utilisateur, la page Create, la page de modification du profil ou la page de recherche.

• sortProperty : Si la table de recherche est triée selon un champ différent de celui-ci, utilisez ce champ. La notation par points est permise.

• display: true || false || converti en chaîne => Il s’agit de la valeur d’affichage par défaut. Si elle n’est pas remplacée dans la recherche, la modification ou la création, cette valeur sera utilisée.

  • si true, retournera simplement user.<property>.
  • Par défaut : si false, cette valeur ne sera affichée sur aucune page (à moins d’être redéfinie dans search, edit ou create).
  • si la fonction est convertie en chaîne : exécute la fonction pour obtenir la valeur à afficher. Exemple : (function display(user, value, languageDictionary) { return moment(value).fromNow(); }).toString()

• search: faux || object => Décrit le comportement de ce champ sur la page de recherche.

  • Par défaut : si false, n’apparaîtra pas dans le tableau de recherche.
  • search.display: Remplace la valeur d’affichage par défaut.
  • search.listOrder: Spécifie l’ordre des colonnes dans le tableau d’affichage de la recherche.
  • search.listSize: Spécifie la largeur par défaut de la colonne.
  • search.filter: Indique s’il faut autoriser la recherche de ce champ dans la liste déroulante de recherche. La valeur par défaut est faux.
  • search.sort: Indique si cette colonne peut être triée. Utilisez sortProperty si vous souhaitez trier selon un champ autre que property. La valeur par défaut est faux.

• edit: false || objet => Indique si le champ apparaît dans les boîtes de dialogue de modification. S’il ne s’agit pas d’un champ par défaut et qu’il est défini comme un objet, il apparaîtra sur la page Change Profile, dans le menu déroulant Actions utilisateur de la page de l’utilisateur.

  • Par défaut : si false, ne s’affichera sur aucune page de modification ou de mise à jour.

  • edit.display: Remplace la valeur d’affichage par défaut.

  • edit.required: Définissez à true pour produire une erreur si aucune valeur n’est fournie. La valeur par défaut est false.

  • edit.type required: text || select || password

  • edit.component: InputText || Input Combo || InputMultiCombo || InputSelectCombo

    • InputText (par défaut) : Zone de texte simple.
    • InputCombo: Liste déroulante interrogeable, avec une seule valeur possible.
    • InputMultiCombo: Liste déroulante interrogeable permettant plusieurs valeurs.
    • InputSelectCombo: Liste déroulante de sélection d’options.

  • edit.options: Si le composant est l’un de InputCombo, InputMultiCombo ou InputSelectCombo, les valeurs des options doivent être précisées.

    • Array(string): Tableau de valeurs (les champs label et value auront la même valeur).
    • Array({ “value”: string, “label”: string }): Permet de définir des valeurs distinctes pour value et label. La valeur transmise au Write Hook contiendra la même valeur, mais elle peut être réduite à la seule valeur dans le Write Hook.
    • La validation côté serveur s’assurera que toute valeur précisée pour ce champ figure dans le tableau d’options.

  • edit.disabled: true si le composant doit être en lecture seule; la valeur par défaut est false.

  • edit.validateFunction: Fonction de validation sous forme de chaîne. Notez que cette fonction de validation s’exécutera à la fois côté serveur et côté client. Exemple : (function validate(value, values, context, languageDictionary) { if (value...) return 'something went wrong'; return false; }).toString().

• create: false || object => Indique si le champ apparaît dans la boîte de dialogue de création.

  • Par défaut : si false, ce champ ne s’affichera pas sur la page de création.

  • create.placeholder: Définit le texte d’espace réservé à afficher lorsque le champ est vide.

  • create.required: Définissez cette valeur à true pour provoquer un échec si aucune valeur n’est fournie. Par défaut, la valeur est false.

  • create.type obligatoire: text || select || password

  • create.component: InputText || Input Combo || InputMultiCombo || InputSelectCombo

    • InputText (par défaut) : Zone de texte. Valeur par défaut pour les types text et password.
    • InputCombo: Liste déroulante interrogeable, avec une seule valeur possible.
    • InputMultiCombo: Liste déroulante interrogeable permettant plusieurs valeurs.
    • InputSelectCombo: Liste déroulante de sélection d’options.

  • create.options: Si le composant est l’un des suivants : InputCombo, InputMultiCombo ou InputSelectCombo, les valeurs d’option doivent être précisées.

    • Array(string): Tableau simple de valeurs; label et value auront la même valeur.
    • Array({ “value”: string, “label”: string }): Permet de définir des valeurs distinctes pour value et label. Ainsi, la valeur dans le Write Hook sera la même, mais elle peut être réduite à la seule valeur dans le Write Hook.
    • La validation côté serveur veillera à ce que toute valeur précisée pour ce champ se trouve dans le tableau d’options.

  • create.disabled: true si le composant doit être en lecture seule; par défaut, la valeur est false.

  • create.validateFunction: Fonction convertie en chaîne de caractères servant à effectuer la validation.

    • Exemple : (function validate(value, values, context, languageDictionary) { if (value...) return 'something went wrong'; return false; }).toString()
    • Cette fonction de validation s’exécutera à la fois côté serveur et côté client.

​

Champs prédéfinis

Il existe un ensemble de champs prédéfinis et interrogeables pour le comportement par défaut.

Vous pouvez redéfinir le comportement par défaut en ajoutant le champ comme userField, puis en redéfinissant le comportement que vous souhaitez modifier. On le fait souvent pour masquer un champ en définissant display sur faux.

​

Champs de recherche

• name: Champ généré à partir d’autres champs : fonction d’affichage par défaut : (function(user, value) { return (value || user.nickname || user.email || user.user_id); }).toString()
• email: adresse courriel ou N/A
• last_login_relative: Date et heure de la dernière connexion
• logins_count: Nombre de connexions
• connection: connexion de base de données

​

Champs d’information de l’utilisateur

• user_id: ID de l’utilisateur
• name: Nom de l’utilisateur
• username: Nom d’utilisateur
• email: Adresse courriel de l’utilisateur
• identity.connection: Valeur de la connexion
• isBlocked: Indique si l’utilisateur est bloqué
• blocked_for: Indique si l’utilisateur fait l’objet de blocages liés à la protection contre les attaques
• last_ip: Dernière adresse IP utilisée par l’utilisateur pour se connecter
• logins_count: Nombre de connexions de l’utilisateur
• currentMemberships: Liste des adhésions de cet utilisateur
• created_at: Date et heure de création de l’utilisateur
• updated_at: Date et heure de mise à jour de l’utilisateur
• last_login: Date et heure de la dernière connexion de l’utilisateur

​

Créer et modifier les champs utilisateur

• connection: Base de données de l’utilisateur
• password: Nouveau mot de passe
• repeatPassword: Confirmation du mot de passe de l’utilisateur
• email: Adresse courriel de l’utilisateur
• username: Nom d’utilisateur

​

Exemple d’utilisation

function(ctx, callback) {
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;

  return callback(null, {
    // Seules ces connexions doivent être visibles dans le sélecteur de connexions.
    // Si une seule connexion est disponible, le sélecteur de connexions ne sera pas affiché dans l'interface.
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // Le dictionnaire vous permet de remplacer le titre du Dashboard et l'étiquette « Memberships » dans la boîte de dialogue Create User.
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // Les User Fields sont les champs personnalisés qui peuvent être affichés lors de la création et de la modification, utilisés pour la recherche, et pour personnaliser la page de profil de l'utilisateur.
    userFields: [
        {
            "label": "Conexión",
            "property": "connection",
        },
        {
            "label": "Correo Electrónico",
            "property": "email",
        },
        ...
    ],
    // L'option CSS vous permet d'injecter un fichier CSS personnalisé selon le contexte de l'utilisateur actuel (p. ex. : un CSS différent pour chaque client).
    css: (department && department !== 'IT') && 'https://cdn.jsdelivr.net/gh/auth0-extensions/auth0-delegated-administration-extension/docs/theme/fabrikam.css',
    languageDictionary: 'https://your-cdn.com/locale/es.json'
  });
}

​

Localisation

À partir de la version 3.0 de la Delegated Admin Extension, vous pouvez fournir un dictionnaire de langue à utiliser pour la localisation. Le dictionnaire de langue sert uniquement au contenu statique des pages; pour le contenu au niveau des champs, vous devez utiliser les libellés userFields.

La localisation s’adresse à ceux qui effectuent des tâches non administratives dans le cadre de la gestion des utilisateurs. Auth0 ne prend actuellement pas en charge la localisation dans les pages de Configuration.

Pour préciser le paramètre régional, vous pouvez utiliser le chemin. Par exemple : https://{yourTenant}.us.webtask.io/auth0-delegated-admin/en/users définira context.locale sur en dans la requête de paramètres.

Le languageDictionary est défini dans la requête de paramètres, ce qui vous permet de :

• Définir explicitement un languageDictionary
• Fournir une URL pour récupérer le contenu du paramètre languageDictionary

Pour en savoir plus, vous pouvez consulter le fichier de dictionnaire de langue de la Delegated Administration Extension.

​

Exemple : fournir un lien vers le fichier du dictionnaire de langue

function(ctx, callback) {
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;

  return callback(null, {
    // Seules ces connexions doivent être visibles dans le sélecteur de connexions.
    // Si une seule connexion est disponible, le sélecteur de connexions ne sera pas affiché dans l'interface.
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // Le dictionnaire vous permet de remplacer le titre du Dashboard et l'étiquette « Memberships » dans la boîte de dialogue Create User.
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // Les User Fields sont les champs personnalisés qui peuvent être affichés lors de la création et de la modification, utilisés pour la recherche, et pour personnaliser la page de consultation de l'utilisateur.
    userFields: [
        {
            "label": "Conexión",
            "property": "connection",
        },
        {
            "label": "Correo Electrónico",
            "property": "email",
        },
        ...
    ],
    // L'option CSS vous permet d'injecter un fichier CSS personnalisé selon le contexte de l'utilisateur actuel (p. ex. : un CSS différent pour chaque client).
    css: (department && department !== 'IT') && 'https://cdn.jsdelivr.net/gh/auth0-extensions/auth0-delegated-administration-extension/docs/theme/fabrikam.css',
    languageDictionary: 'https://your-cdn.com/locale/es.json'
  });
}

​

Exemple : fournir un objet de dictionnaire de langue

function(ctx, callback) {
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;

  return callback(null, {
    // Seules ces connexions doivent être visibles dans le sélecteur de connexions.
    // Si une seule connexion est disponible, le sélecteur de connexions ne sera pas affiché dans l'interface.
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // Le dictionnaire vous permet de remplacer le titre du Dashboard et l'étiquette « Memberships » dans la boîte de dialogue Create User.
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // Les User Fields sont les champs personnalisés qui peuvent être affichés lors de la création et de la modification, utilisés pour la recherche, et pour personnaliser la page de visualisation de l'utilisateur.
    userFields: [
        {
            "label": "Conexión",
            "property": "connection",
        },
        {
            "label": "Correo Electrónico",
            "property": "email",
        },
        ...
    ],
    // L'option CSS vous permet d'injecter un fichier CSS personnalisé selon le contexte de l'utilisateur actuel (p. ex. : un CSS différent pour chaque client)
    css: (department && department !== 'IT') && 'https://cdn.jsdelivr.net/gh/auth0-extensions/auth0-delegated-administration-extension/docs/theme/fabrikam.css',
    languageDictionary: {
        loginsCountLabel: 'Cantidad de Logins:',
        searchBarPlaceholder: 'Busqueda de usuarios usando la sintaxis de Lucene',
        deviceNameColumnHeader: 'Dispositivo',
        ...
    }
  });
}

​

En savoir plus

• Delegated Administration : Access Hook
• Delegated Administration : Filter Hook
• Delegated Administration : Write Hook
• Delegated Administration : Memberships Query Hook