Users and Roles

MarkLogic Data Hub provides default roles and users in your project:

You also need to create custom roles with the privileges to access your data in MarkLogic Server.

You can set the user credentials in the appropriate gradle*.properties file or you can specify them at the command line when running the Gradle task. To learn how, see Set Security Credentials Using Gradle

General Roles

These roles are used by Data Hub in any platform, whether on-premise or in Data Hub Service (DHS). Compared to legacy roles, general roles allow for more granular privilege management and for easier migration from an on-premise installation to DHS. To use these roles, you need MarkLogic Server 10.0-3 or later.

Role Name Role Description
data-hub-admin Permits an assigned user:
  • To do everything that the data-hub-developer role can.
  • To clear the STAGING, FINAL, and JOBS databases.
data-hub-security-admin Permits an assigned user:
  • To create and configure custom Data Hub roles and privileges with the following restrictions:
    • A custom role cannot inherit from any other role.
    • A custom role can only inherit privileges granted to the user creating the role.
    • A custom execute privilege must be assigned an action starting with
  • To assign roles to users.
data-hub-developer Permits an assigned user:
  • To do everything that the data-hub-operator role can.
  • To do everything that the MarkLogic Server manage-user role can, including read access to the MarkLogic Management API and monitoring tools.
  • To deploy the following resources:
    • User modules and artifacts (entities, flows, mappings, and steps)
    • Alert configurations, rules, and actions
    • Database indexes on the STAGING, FINAL, and JOBS databases
    • Scheduled tasks
    • Schemas
    • Temporal axes, collections, and Last Stable Query Time (LSQT)
    • Triggers
    • Protected paths and query rolesets
  • To update Template Driven Extraction (TDE) documents.
data-hub-operator Permits an assigned user:
  • To run a Data Hub application.
  • To run flows.
  • To monitor flows through the JOBS database.
  • To read or query Template Driven Extraction (TDE) documents.
Important: By default, new documents inherit the permissions of the user account that runs the step. For greater security, this role is configured without default privileges to avoid unintended inheritance. However, MarkLogic Server requires each new document to have at least one update permission. Therefore, you must explicitly set the step's Target Permissions to specify at least one update permission to assign to new documents created by the step.
data-hub-monitor Permits an assigned user:
pii-reader Permits an assigned user to view personally identifiable information (PII). See Managing Personally Identifiable Information.
Note: User accounts are not automatically generated for these roles. The MarkLogic Server admin must assign new or existing user accounts to the appropriate roles.

Legacy Roles

The following legacy roles are supported for backward compatibility with Data Hub 5.1 or earlier versions.

Important: These roles cannot be used in DHS.
Role Name Role Description Auto-Generated User When used
Permits an assigned user:
  • To install, uninstall, and upgrade MarkLogic Data Hub.
  • To create Data Hub roles based on existing ones.
  • To assign roles to users.
  • To manage MarkLogic Server resources and perform tasks related to databases, indexes, and configuration of MarkLogic Server.

Must be assigned as part of the first deployment (i.e., bootstrapping role).

Does not have administrative access to the entire MarkLogic server.

Tip: Switch to the data-hub-admin and data-hub-security-admin roles for more granular privileges.
data-hub-admin-user During setup and maintenance
Permits an assigned user:
  • To create and update flows and modules.
  • To deploy flows, modules, and security configurations (including PII).
  • To configure the indexes and Template Driven Extraction (TDE) settings.
Tip: Switch to the data-hub-developer role for more granular privileges.

(Same role as in Data Hub Service.)

flow-developer During development
Permits an assigned user:
  • To run flows.
  • To monitor activity in the job logs.
Tip: Switch to the data-hub-monitor and data-hub-operator roles for more granular privileges.

(Same role as in Data Hub Service.)

flow-operator In a production environment

Custom Roles and Privileges

In addition to the predefined Data Hub roles, you also need to create and deploy custom roles that give you access to your databases in MarkLogic Server. Custom roles can have predefined MarkLogic privileges or your own custom privileges.

Note: You must use an account with the data-hub-security-admin role.

Create Directly in MarkLogic Server

You can create custom privileges directly in MarkLogic Server using the Admin Interface.

You can create custom roles directly in MarkLogic Server:

Create and Deploy Using Gradle

You can manually create your custom roles and privileges in your development environment and later deploy them to your production environment using Gradle.

  1. (Optional) Create your custom privileges.

    The custom privilege definition is a JSON file that contains the privilege name, the kind of privilege (typically execute), and the action URI.

        "privilege-name": "my-custom-privilege-name",
        "kind": "execute",
        "action": "the-URI-of-the-custom-privilege"
    Note: Store your custom privilege JSON files in the your-project-root/src/main/ml-config/security/privileges directory.

    Alternatively, you can define your custom privilege within the privilege array of your custom role definition.

  2. Create your custom roles with the predefined MarkLogic Server privileges or your custom privileges.

    The custom role definition is a JSON file that contains the role name, an optional description, and an array of privileges. See an example.

        "role-name": "my-role-name",
        "privilege": [
            "privilege-name": "a-predefined-MarkLogic-privilege-or-a-custom-privilege",
            "kind": "execute",
            "action": "the-URI-of-the-privilege"

    For a list of MarkLogic Server privileges, see Appendix B: Pre-defined Execute Privileges of MarkLogic Server Administrator's Guide

    Note: Store your custom role JSON files in the your-project-root/src/main/ml-config/security/roles directory.
  3. To deploy the new custom roles and privileges to your production environment (whether on-premise or in DHS), run the Gradle task hubDeployAsSecurityAdmin.
    ./gradlew hubDeployAsSecurityAdmin -PenvironmentName=dhs -igradlew.bat hubDeployAsSecurityAdmin -PenvironmentName=dhs -i

    See an example that shows how to deploy a custom role to DHS.