Users and Roles

MarkLogic uses a role-based security model, where users are assigned roles with the minimum privileges they need to access data and product features.

MarkLogic Data Hub provides predefined roles for use in different components:

  • General roles are used by Data Hub in any platform, whether on-premises 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-premises installation to DHS. To use these roles, you need MarkLogic Server 10.0-3 or later.

  • Hub Central roles allow access to various features of Hub Central, the GUI interface for Data Hub in DHS.

    These roles are used only by Hub Central and are not required by other tools to access the same Data Hub functionality.

  • MarkLogic Server also provides roles that can be inherited by custom roles for use in Data Hub: Other Inheritable Roles

  • Legacy roles are still available for backward compatibility: Legacy Roles

Learn how to create custom roles and privileges.

Important: You must create custom roles with the appropriate privileges to access your data in MarkLogic Server. Learn more: Custom Roles and Privileges

The security role definitions are stored as JSON files in your local project directory under your-project-root/src/main/hub-internal-config/security/roles. Learn more: Project Structure

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. Learn more: Set Security Credentials Using Gradle

Tip: You can determine what each role inherits by using the Gradle task hubDescribeRole. Learn more: Other Gradle Tasks

Please refer to Data Hub Properties for more information on Authentication Support.

Default General Roles

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.
Note: Assign the pii-reader role to a user to view data that contains personally identifiable information (PII). For example, if you assign a user the hub-central-operator role that needs to view PII, the user must be assigned the following roles: hub-central-operator, pii-reader
Role Name Directly Inherits Role Description
  • Data Hub Admin
  • (data-hub-admin)
  • data-hub-developer
 Permits an assigned user:
  • To do everything that the data-hub-developer role can.
  • To clear the STAGING, FINAL, and JOBS databases.

Can be inherited by a custom role.
  • Data Hub Security Admin
  • (data-hub-security-admin)
  • manage
 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 http://datahub.marklogic.com/custom/.
  • To assign roles to users.
  • Data Hub Developer
  • (data-hub-developer)
  • data-hub-custom-writer
  • data-hub-entity-model-writer
  • data-hub-flow-writer
  • data-hub-ingestion-writer
  • data-hub-mapping-writer
  • data-hub-match-merge-writer
  • data-hub-module-writer
  • data-hub-operator
  • data-hub-saved-query-user
  • data-hub-step-definition-writer
  • data-hub-user-reader
  • manage-user
  • ps-user
  • tde-admin
 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.

Can be inherited by a custom role.
  • Data Hub Operator
  • (data-hub-operator)
  • data-hub-common
  • data-hub-common-writer
  • data-hub-custom-reader
  • data-hub-entity-model-reader
  • data-hub-flow-reader
  • data-hub-ingestion-reader
  • data-hub-job-reader
  • data-hub-mapping-reader
  • data-hub-match-merge-reader
  • data-hub-module-reader
  • data-hub-saved-query-user
  • data-hub-step-definition-reader
  • data-hub-temporal-user
  • redaction-user
  • rest-extension-user
  • rest-reader
  • tde-view
 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.

Can be inherited by a custom role.
  • Data Hub Monitor
  • (data-hub-monitor)
  • data-hub-job-reader
  • manage-user
 Permits an assigned user:

Can be inherited by a custom role.
  • PII Reader
  • (pii-reader)
Permits an assigned user to view personally identifiable information (PII). Learn more: Managing Personally Identifiable Information

Can be inherited by a custom role.

Default Hub Central Roles

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.
Note: Assign the pii-reader role to a user to view data that contains personally identifiable information (PII). For example, if you assign a user the hub-central-operator role that needs to view PII, the user must be assigned the following roles: hub-central-operator, pii-reader
Role Name Directly Inherits Role Description
  • Hub Central Explorer
  • (hub-central-explorer)
  • hub-central-entity-exporter
  • hub-central-saved-query-user
 Permits an assigned user:
  • To view project information.
  • To view entity models.
  • To save and manage their own queries within Hub Central.
  • To export the CSV-formatted results of a query on the curated data.
  • Hub Central Modeler
  • (hub-central-modeler)
  • hub-central-entity-model-writer
 Permits an assigned user:
  • To view project information.
  • To view, create, edit, and delete entity models.
  • To view the properties and settings of Custom steps.
  • To create and edit concept classes and entity to class relationships.
  • Hub Central Developer
  • (hub-central-developer)
  • hub-central-clear-user-data
  • hub-central-downloader
  • hub-central-entity-model-writer
  • hub-central-flow-writer
  • hub-central-load-writer
  • hub-central-mapping-writer
  • hub-central-match-merge-writer
  • hub-central-operator
 Permits an assigned user:
  • To view project information.
  • To view, create, edit, and delete entity models.
  • To view, create, edit, and delete Loading steps.
  • To view, create, edit, and delete Mapping steps.
  • To view, create, edit, and delete Matching and Merging steps.
  • To view the properties and settings of Custom steps.
  • To view, create, edit, and delete flows.
  • To run steps of any type.
  • To download project files.
  • To clear user data (not user-created project artifacts) from the STAGING, FINAL, and JOBS databases.
  • To create and edit concept classes and entity to class relationships.

Can be inherited by a custom role.
  • Hub Central Operator
  • (hub-central-operator)
  • hub-central-custom-reader
  • hub-central-entity-exporter
  • hub-central-entity-model-reader
  • hub-central-load-reader
  • hub-central-mapping-reader
  • hub-central-match-merge-reader
  • hub-central-saved-query-user
  • hub-central-step-runner
  • hub-central-user
  • redaction-user
 Permits an assigned user:
  • To view project information.
  • To view entity models.
  • To view Loading steps.
  • To view Mapping steps.
  • To view Matching and Merging steps.
  • To view the properties and settings of Custom steps.
  • To run steps of any type.
  • To save and manage their own queries within Hub Central.
  • To export the CSV-formatted results of a query on the curated data.

Can be inherited by a custom role.
  • Hub Central Curator
  • (hub-central-curator)
  • hub-central-custom-reader
  • hub-central-entity-model-reader
  • hub-central-flow-writer
  • hub-central-load-writer
  • hub-central-mapping-writer
  • hub-central-match-merge-writer
 Permits an assigned user:
  • To view project information.
  • To view, create, edit, and delete Loading steps.
  • To view, create, edit, and delete Mapping steps.
  • To view, create, edit, and delete Matching and Merging steps.
  • To view the properties and settings of Custom steps.
  • To run steps of any type.

Other General Roles

In addition to the default general roles marked as inheritable above, a custom role can also inherit any of the following roles for use in all areas of Data Hub.

Role Name Directly Inherits Role Description
data-hub-common
  • data-hub-module-reader
  • rest-extension-user
  • rest-reader
The role with the least privilege. Provides a common set of privileges and roles needed to perform Data Hub 5.x read operations. Inherited by all other roles; not intended to be directly assigned to users.

Can be inherited by a custom role.
data-hub-common-writer
  • data-hub-common
Provides a common set of privileges and roles needed to perform Data Hub 5.x read and write operations. Inherited by other roles; not intended to be directly assigned to users.

Can be inherited by a custom role.
data-hub-custom-reader
Permits an assigned user to view the properties and settings of Custom steps.

Can be inherited by a custom role.
data-hub-custom-writer
  • data-hub-custom-reader
Permits an assigned user to edit Custom steps. For the ability to add, remove, or rearrange steps within the flow, see data-hub-flow-writer. For the ability to create and delete Custom steps, see data-hub-developer.

Can be inherited by a custom role.
data-hub-entity-model-reader
Permits an assigned user to view the properties and settings of the entity models used for mapping.

Can be inherited by a custom role.
data-hub-entity-model-writer
  • data-hub-common-writer
Permits an assigned user to create, edit, and delete entity models.

Can be inherited by a custom role.
data-hub-flow-reader
Permits an assigned user to view the properties and settings of flows.

Can be inherited by a custom role.
data-hub-flow-writer
  • data-hub-common-writer
  • data-hub-flow-reader
Permits an assigned user to create, edit, and delete flows.
Note: Step writer roles (data-hub-ingestion-writer, data-hub-mapping-writer, and data-hub-match-merge-writer) can only create, edit, and delete steps. The data-hub-flow-writer is needed to add, remove, or rearrange steps within the flow.

Can be inherited by a custom role.
data-hub-ingestion-reader
Permits an assigned user to view the properties and settings of Ingestion/Loading steps.

Can be inherited by a custom role.
data-hub-ingestion-writer
  • data-hub-common-writer
  • data-hub-ingestion-reader
  • data-hub-step-definition-reader
Permits an assigned user to create, edit, and delete Ingestion/Loading steps. For the ability to add, remove, or rearrange steps within the flow, see data-hub-flow-writer.

Can be inherited by a custom role.
data-hub-job-reader
Permits an assigned user to view details about completed jobs.

Can be inherited by a custom role.
data-hub-mapping-reader
Permits an assigned user to view the properties and settings of Mapping steps, as well as the mapping details.

Can be inherited by a custom role.
data-hub-mapping-writer
  • data-hub-common-writer
  • data-hub-mapping-reader
  • data-hub-step-definition-reader
Permits an assigned user to create, edit, and delete Mapping steps. For the ability to add, remove, or rearrange steps within the flow, see data-hub-flow-writer.

Can be inherited by a custom role.
data-hub-match-merge-reader
  • data-hub-common
Permits an assigned user to view the properties and settings of Matching and Merging steps, as well as the matching and merging details.

Can be inherited by a custom role.
data-hub-match-merge-writer
  • data-hub-common-writer
  • data-hub-match-merge-reader
  • data-hub-step-definition-reader
Permits an assigned user to create, edit, and delete Matching and Merging steps. For the ability to add, remove, or rearrange steps within the flow, see data-hub-flow-writer.

Can be inherited by a custom role.
data-hub-module-reader
Permits an assigned user to view custom modules.

Can be inherited by a custom role.
data-hub-module-writer
Permits an assigned user to create, edit, and delete custom modules.

Can be inherited by a custom role.
data-hub-odbc-user
Permits an assigned user to perform operations on the databases using ODBC.

Can be inherited by a custom role.
data-hub-saved-query-user
  • data-hub-common-writer
Permits an assigned user to save and manage their own queries.

To save and manage queries using Hub Central, use hub-central-saved-query-user.

Can be inherited by a custom role.
data-hub-spawn-user
Permits an assigned user to create spawn functions on the task server.

Can be inherited by a custom role.
data-hub-step-definition-reader
Permits an assigned user to view the properties and settings of step definitions.

Can be inherited by a custom role.
data-hub-step-definition-writer
Permits an assigned user to create, edit, and delete step definitions.

Can be inherited by a custom role.
data-hub-temporal-user
Permits an assigned user to create temporal collections and to load and manage temporal documents.

Can be inherited by a custom role.
data-hub-user-reader
Permits an assigned user to read information about a user's assigned roles or about a role's inherited roles and privileges.

Can be inherited by a custom role.

Other Hub Central Roles

In addition to the default Hub Central roles marked as inheritable above, a custom role can also inherit any of the following roles for use in Hub Central.

Role Name Directly Inherits Role Description
hub-central-clear-user-data
  • data-hub-custom-writer
  • data-hub-entity-model-writer
  • data-hub-flow-writer
  • data-hub-ingestion-writer
  • data-hub-mapping-writer
  • data-hub-match-merge-writer
  • data-hub-operator
  • data-hub-step-definition-writer
  • hub-central-user
  • manage-user
  • tde-admin
Permits an assigned user to clear user data (not user-created project artifacts) from the STAGING, FINAL, and JOBS databases.

Can be inherited by a custom role.
hub-central-custom-reader
  • data-hub-custom-reader
  • data-hub-step-definition-reader
  • hub-central-user
Permits an assigned user to view the properties and settings of Custom steps.

Can be inherited by a custom role.
hub-central-downloader
  • data-hub-entity-model-reader
  • data-hub-flow-reader
  • data-hub-ingestion-reader
  • data-hub-mapping-reader
  • data-hub-match-merge-reader
  • data-hub-step-definition-reader
  • hub-central-user
Permits an assigned user to download project files.

Can be inherited by a custom role.
hub-central-entity-exporter
  • data-hub-entity-model-reader
  • hub-central-user
  • tde-view
Permits an assigned user to export the CSV-formatted results of a query on the curated data.

Can be inherited by a custom role.
hub-central-entity-model-reader
  • data-hub-entity-model-reader
  • hub-central-user
Permits an assigned user to view the properties and settings of the entity models used for mapping.

Can be inherited by a custom role.
hub-central-entity-model-writer
  • data-hub-custom-reader
  • data-hub-entity-model-writer
  • data-hub-flow-reader
  • data-hub-mapping-reader
  • data-hub-match-merge-reader
  • hub-central-entity-model-reader
  • tde-admin
Permits an assigned user to create, edit, and delete entity models.

Can be inherited by a custom role.
hub-central-flow-writer
  • data-hub-flow-writer
  • hub-central-step-runner
Permits an assigned user to create, edit, and delete flows.
Note: Step writer roles (hub-central-load-writer, hub-central-mapping-writer, and hub-central-match-merge-writer) can only create, edit, and delete steps. The hub-central-flow-writer is needed to add, remove, or rearrange steps within the flow.

Can be inherited by a custom role.
hub-central-load-reader
  • data-hub-ingestion-reader
  • hub-central-user
Permits an assigned user to view the properties and settings of Loading steps.

Can be inherited by a custom role.
hub-central-load-writer
  • data-hub-ingestion-writer
  • hub-central-load-reader
Permits an assigned user to create, edit, and delete Loading steps. For the ability to add, remove, or rearrange steps within the flow, see hub-central-flow-writer.

Can be inherited by a custom role.
hub-central-mapping-reader
  • data-hub-entity-model-reader
  • data-hub-mapping-reader
  • hub-central-user
Permits an assigned user to view the properties and settings of Mapping steps, as well as the mapping details.

Can be inherited by a custom role.
hub-central-mapping-writer
  • data-hub-common-writer
  • data-hub-mapping-writer
  • hub-central-mapping-reader
Permits an assigned user to create, edit, and delete Mapping steps. For the ability to add, remove, or rearrange steps within the flow, see hub-central-flow-writer.

Can be inherited by a custom role.
hub-central-match-merge-reader
  • data-hub-entity-model-reader
  • data-hub-match-merge-reader
  • hub-central-user
Permits an assigned user to view the properties and settings of Matching and Merging steps, as well as the matching and merging details.

Can be inherited by a custom role.
hub-central-match-merge-writer
  • data-hub-match-merge-writer
  • hub-central-match-merge-reader
Permits an assigned user to create, edit, and delete Matching and Merging steps. For the ability to add, remove, or rearrange steps within the flow, see hub-central-flow-writer.

Can be inherited by a custom role.
hub-central-saved-query-user
  • data-hub-saved-query-user
  • hub-central-user
Permits an assigned user to save and manage their own queries within Hub Central.

Can be inherited by a custom role.
hub-central-step-runner
  • data-hub-common-writer
  • data-hub-custom-reader
  • data-hub-flow-reader
  • data-hub-ingestion-reader
  • data-hub-job-reader
  • data-hub-mapping-reader
  • data-hub-match-merge-reader
  • data-hub-step-definition-reader
  • hub-central-user
Permits an assigned user to run flows and steps.

Can be inherited by a custom role.
hub-central-user
  • data-hub-common
  • data-hub-entity-model-reader
Permits an assigned user to view project information.

Can be inherited by a custom role.

Other Inheritable Roles

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.

These roles are provided by ML Server and can be inherited by custom roles used in Data Hub.

Role Name Role Description
dls-admin Permits an assigned user to perform operations that use the Library Services API, such as inserting retention policies and breaking checkouts. Learn more: Security Considerations of Library Services Applications

Can be inherited by a custom role.
dls-user Permits an assigned user to execute code that manage, check out, and check in managed documents that the user is allowed to update. Learn more: Security Considerations of Library Services Applications

Can be inherited by a custom role.
redaction-user Permits an assigned user to redact documents to hide sensitive information within them. Learn more: Redacting Document Content - Security Considerations

Can be inherited by a custom role.
rest-reader Permits an assigned user to perform read operations through the REST Client API, such as retrieving documents and metadata. Additional privileges might be required. Learn more: MarkLogic REST API - Security Requirements

Can be inherited by a custom role.
rest-writer Permits an assigned user to perform write operations through the REST Client API, such as creating documents, metadata, or configuration information. Additional privileges might be required. Learn more: MarkLogic REST API - Security Requirements

Can be inherited by a custom role.

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
data-hub-admin-role
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
flow-developer-role
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
flow-operator-role
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