Delegated Administration: Settings Query Hook

The Settings Query Hook allows you to customize the look and feel of the Delegated Administration extension.

• ctx: Context object.

  • request.user: User currently logged in.

  • locale: Locale (as inferred from the URL) -- https://{yourTenant}.us.webtask.io/auth0-delegated-admin/en/users will set locale to en.

• callback(error, settings): Callback to which you can return an error and a settings object.

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

  return callback(null, {
    // Only these connections should be visible in the connections picker. If only one connection is available, the connections picker will not be shown in the UI.
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // The dictionary allows you to overwrite the title of the dashboard and the "Memberships" label in the Create User dialog.
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments',
      menuName: ctx.request.user.name
    },
    // The CSS option allows you to inject a custom CSS file depending on the context of the current user (eg: a different CSS for every customer)
    css: (department && department !== 'IT') && 'https://rawgit.com/auth0-extensions/auth0-delegated-administration-extension/master/docs/theme/fabrikam.css',
    // This option allows you to restrict creating new users
    canCreateUser: (department === 'IT')
  });
}

• connections: List of the connections this admin is allowed to create and edit users within.

• dict: Dictionary that allows you to overwrite the title of the dashboard and the Memberships label in the Create User dialog.

  • dict.title: Title to display at the top of the UI.

  • dict.memberships: Label to set for memberships fields.

  • dict.menuName: Name to set for the upper right-hand dropdown menu.

  • dict.logoutUrl: Alternate URL for the logout menu option.

• userFields: Array of user fields (see "Custom fields" below).

• css: String URL to import CSS.

• altcss: String URL to import a second set of CSS. You can use this to specify things like accessibility CSS for larger fonts. The user will be presented with a menu item allowing them to toggle this set of CSS on/off.

• languageDictionary: String URL or Dictionary Object (see "Localization"below).

• suppressRawData: Set to true to skip pages that show raw JSON

• errorTranslator: Function that translates error messages based on localization. Example: (function (error, languageDictionary) { return languageDictionary.customErrors[error] || error; }).toString()

• canCreateUser: Boolean flag. If set to false, removes Create User button and forbids creating new users, true by default.

Beginning with version 3.0 of the Delegated Admin Extension, you can define custom fields and specify their values. Custom fields can be stored in the user metadata and app metadata fields accessible during the user creation or update processes.

You may also customize existing fields defined by Auth0, such as email, username, name, and connection.

To use custom fields, you must:

• Add your list of userFields to the Settings Query Hook

• Implement a Write Hook. Custom fields require the use of the Write Hook to properly update user_metadata and app_metadata. You must update the user object passed to the callback function with the user_metadata and app_metadata from the context (ctx object) provided to the Hook.

To learn more about Write Hooks, read Delegated Administration: Write Hook.

Sample schema for userFields:

userFields: [
    {
        "property": string, // required
        "label": string,
        "sortProperty": string,
        "display": true || function.toString(),
        "search": false || {
            "display": true || function.toString()
            "listOrder": 1,
            "listSize": string(###%), // e.g. 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 (required): Property name of the ctx.payload object for the Write Hook. In the Write Hook, "property": "app_metadata.dbId" sets ctx.payload.app_metadata.dbId.

• label: Label that will be used when adding a label to the field on the user info page, create page, edit profile page, or search page.

• sortProperty: If sorting by a different field than this for the search table, use this field. Dot notation is allowed.

• display: true || false || stringified => This is the default display value. If not overridden in search, edit, or create, it will use this value.

  • if true, will just return user.<property>.

  • Default: if false this value will not be displayed on any page (unless overridden in search, edit, or create).

  • if stringified function: Executes function to get the value to display. Example: (function display(user, value, languageDictionary) { return moment(value).fromNow(); }).toString()

• search: false || object => Describes how this field will behave on the search page.

  • Default: if false, will not show up in the search table.

  • search.display: Overrides the default display value.

  • search.listOrder: Specifies the column order for the search display table.

  • search.listSize: Specifies the default width of the column.

  • search.filter: Specifies whether to allow this field to be searched in the search dropdown. Default is false.

  • search.sort: Specifies whether this column is sortable. Use sortProperty if you want to sort by a field other than property. Default is false.

• edit: false || object => Describes whether the field shows up on the edit dialogs. If not a default field and set to an object, this will show up in the Change Profile page on the User Actions dropdown on the user page.

  • Default: if false, will not show up on any edit/update page.

  • edit.display: Overrides the default display value.

  • edit.required: Set to true to fail if it does not have a value. Default is false.

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

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

    • InputText (default): Simple text box.

    • InputCombo: Searchable dropdown, single value only.

    • InputMultiCombo: Searchable dropdown with multiple values allowed.

    • InputSelectCombo: Select dropdown of options.

  • edit.options: If component is one of InputCombo, InputMultiCombo, InputSelectCombo, the option values need to be specified.

    • Array(string): Array of values (the label and value fields will be set to the same value).

    • Array({ "value": string, "label": string }): Allows you to set separate values for the value and label. This will result in the value in the Write Hook having the same value, but it can be trimmed down to just the value in the Write Hook.

    • Server-side validation will ensure that any value specified for this field appears in the options array.

  • edit.disabled: true if the component should be read only; default is false.

  • edit.validateFunction: Stringified function for validation. Note that this validation function will run on both the server- and client-side. Example: (function validate(value, values, context, languageDictionary) { if (value...) return 'something went wrong'; return false; }).toString().

• create: false || object => Describes whether the field shows up on the create dialog.

  • Default: if false, will not show up on the create page.

  • create.placeholder: Provide placeholder text to show when input is empty.

  • create.required: Set to true to fail if it does not have a value. Default is false.

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

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

    • InputText (default): Text box. Default for type text and password.

    • InputCombo: Searchable dropdown, single value only.

    • InputMultiCombo: Searchable dropdown with multiple values allowed.

    • InputSelectCombo: Select dropdown of options.

  • create.options: If component is one of InputCombo, InputMultiCombo, InputSelectCombo, the option values need to be specified.

    • Array(string): Simple array of values, label, and value will be set to the same.

    • Array({ "value": string, "label": string }): Allows you to set separate values for both the value and label. This will result in the value in the Write Hook having the same value, but it can be trimmed down to just the value in the Write Hook.

    • Server-side validation will ensure that any value specified for this field is in the options array.

  • create.disabled: true if component should be read only, default is false.

  • create.validateFunction: Stringified function for checking the validation.

    • Example: (function validate(value, values, context, languageDictionary) { if (value...) return 'something went wrong'; return false; }).toString()

    • This validation function will run on both the server- and client-side.

There are a set of pre-defined, searchable fields for default behavior.

You can override the default behavior by adding the field as a userField and then overriding the behavior you would like to change. This would often be done to suppress a field by setting the display to false.

• name: Constructed field from other fields: default display function: (function(user, value) { return (value || user.nickname || user.email || user.user_id); }).toString()

• email: Email address or N/A

• last_login_relative: Last login time

• logins_count: Number of logins

• connection: Database connection

• user_id: User ID

• name: User's name

• username: User's username

• email: User's email

• identity.connection: Connection value

• isBlocked: Whether or not the user is blocked

• blocked_for: Whether or not the user has attack protection blocks

• last_ip: Last IP the user used to log in

• logins_count: Number of times the user has logged in

• currentMemberships: List of memberships for this user

• created_at: Date/time at which the user was created

• updated_at: Date/time at which the user was updated

• last_login: Date/time at which the user last logged in

• connection: User's database

• password: New password

• repeatPassword: Repeat of the user's password

• email: User's email

• username: User's username

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

  return callback(null, {
    // Only these connections should be visible in the connections picker.
    // If only one connection is available, the connections picker will not be shown in the UI.
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // The dictionary allows you to overwrite the title of the dashboard and the "Memberships" label in the Create User dialog.
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // User Fields are the custom fields that can be displayed in create and edit, and can also be used for searching, and can be used to customize the view user page
    userFields: [
        {
            "label": "Conexión",
            "property": "connection",
        },
        {
            "label": "Correo Electrónico",
            "property": "email",
        },
        ...
    ],
    // The CSS option allows you to inject a custom CSS file depending on the context of the current user (eg: a different CSS for every customer)
    css: (department && department !== 'IT') && 'https://rawgit.com/auth0-extensions/auth0-delegated-administration-extension/master/docs/theme/fabrikam.css',
    languageDictionary: 'https://your-cdn.com/locale/es.json'
  });
}

Beginning with version 3.0 of the Delegated Admin Extension, you can provide a language dictionary for use with localization. The language dictionary is used only for static page content; for field level content, you must use userFields labels.

To specify the locale, you can use the path. For example: https://{yourTenant}.us.webtask.io/auth0-delegated-admin/en/users will set context.locale to en in the settings query.

The languageDictionary is set as part of the settings query, which allows you to:

• Explicitly define a languageDictionary

• Provide a URL to fetch the contents for the languageDictionary parameter

For more information, you can review the Delegated Administration Extension Language Dictionary file.

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

  return callback(null, {
    // Only these connections should be visible in the connections picker.
    // If only one connection is available, the connections picker will not be shown in the UI.
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // The dictionary allows you to overwrite the title of the dashboard and the "Memberships" label in the Create User dialog.
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // User Fields are the custom fields that can be displayed in create and edit, and can also be used for searching, and can be used to customize the view user page
    userFields: [
        {
            "label": "Conexión",
            "property": "connection",
        },
        {
            "label": "Correo Electrónico",
            "property": "email",
        },
        ...
    ],
    // The CSS option allows you to inject a custom CSS file depending on the context of the current user (eg: a different CSS for every customer)
    css: (department && department !== 'IT') && 'https://rawgit.com/auth0-extensions/auth0-delegated-administration-extension/master/docs/theme/fabrikam.css',
    languageDictionary: 'https://your-cdn.com/locale/es.json'
  });
}

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

  return callback(null, {
    // Only these connections should be visible in the connections picker.
    // If only one connection is available, the connections picker will not be shown in the UI.
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // The dictionary allows you to overwrite the title of the dashboard and the "Memberships" label in the Create User dialog.
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // User Fields are the custom fields that can be displayed in create and edit, and can also be used for searching, and can be used to customize the view user page
    userFields: [
        {
            "label": "Conexión",
            "property": "connection",
        },
        {
            "label": "Correo Electrónico",
            "property": "email",
        },
        ...
    ],
    // The CSS option allows you to inject a custom CSS file depending on the context of the current user (eg: a different CSS for every customer)
    css: (department && department !== 'IT') && 'https://rawgit.com/auth0-extensions/auth0-delegated-administration-extension/master/docs/theme/fabrikam.css',
    languageDictionary: {
        loginsCountLabel: 'Cantidad de Logins:',
        searchBarPlaceholder: 'Busqueda de usuarios usando la sintaxis de Lucene',
        deviceNameColumnHeader: 'Dispositivo',
        ...
    }
  });
}

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