Loading TOC...
Security Guide (PDF)

MarkLogic Server 11.0 Product Documentation
Security Guide
— Chapter 9

Granular Privileges

Granular privileges extend MarkLogic Server security model by allowing finer granularity access control over configuration and various administration abilities. Granular privileges is a subtype of execute privileges type. The purposes of granular privileges are:

  • Allow different applications to coexist in a single cluster, with some users having authority over some parts of the cluster and other users having authority over other parts of the cluster.
  • Support separation of concerns between different administrative users, constraining control to just the layers they are concerned with.

This chapter describes granular privileges and includes the following sections:

Understanding Granular Privileges

The MarkLogic security model includes execute privileges. Execute privileges are identified with URIs and can be assigned to roles. For detail on execute privileges, see Protecting XQuery and JavaScript Functions With Privileges.

For example, the following privilege allows a user to restart any forest:

http://marklogic.com/xdmp/privileges/xdmp-forest-restart

Granular privileges allow more fine-grained approach to execute privileges. When assigning privileges to roles, you may not only specify a privilege to perform a specific action but also identify a specific resource to which this privilege applies.

For example, you may allow a user to restart a specific forest by assigning one of the following privileges to this user's role:

http://marklogic.com/xdmp/privileges/xdmp-forest-restart/forest/forest-ID
http://marklogic.com/xdmp/privileges/xdmp-forest-restart/database/database-ID

where forest-ID is the forest identifier and database-ID is the identifier of the database using the forest.

You can create an appropriate fine-grained privilege, assign it to some role, and assign that role to a user. Then the user will be able to restart the specified forest, or forests in the specified database.

Categories of Granularity

You can use various categories of granular privileges to limit access to privileged operations. These categories are elaborated in this section:

Privileges to Read, Write, or Delete Any Configuration File

A privilege in this category grants a user the ability to read, write, or delete any configuration file as specified (for example, call to xdmp:write-cluster-config-file()). This privilege is specific to the operation (for example, "write") and the scope (for example, "cluster"). The combination of the two values is a specific privilege (for example, http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file).

The following granular privileges belong to this category:

http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file
http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file
http://marklogic.com/xdmp/privileges/xdmp-delete-cluster-config-file

Privileges to Read, Write, or Delete a Specific Configuration File

A privilege in this category grants a user the ability to read, write, or delete a specific configuration file (for example, databases.xml). This privilege is specific to the operation (for example, "write"), scope (for example, "cluster"), and the configuration file (for example, "databases.xml"). The combination of the three values is a specific privilege (for example, http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file/databases.xml).

The following privileges belong to this category:

http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file/assignments.xml
http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file/calendars.xml
http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file/clusters.xml
http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file/countries.xml
http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file/databases.xml
http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file/groups.xml
http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file/hosts.xml
http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file/languages.xml
http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file/mimetypes.xml
http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file/security.xml
http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file/server.xml
http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file/tokenizer.xml
http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file/user-languages.xml
http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file/assignments.xml
http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file/calendars.xml
http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file/clusters.xml
http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file/countries.xml
http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file/databases.xml
http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file/groups.xml
http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file/hosts.xml
http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file/languages.xml
http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file/mimetypes.xml
http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file/security.xml
http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file/server.xml
http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file/tokenizer.xml
http://marklogic.com/xdmp/privileges/xdmp-write-cluster-config-file/user-languages.xml
http://marklogic.com/xdmp/privileges/xdmp-delete-cluster-config-file/assignments.xml
http://marklogic.com/xdmp/privileges/xdmp-delete-cluster-config-file/calendars.xml
http://marklogic.com/xdmp/privileges/xdmp-delete-cluster-config-file/clusters.xml
http://marklogic.com/xdmp/privileges/xdmp-delete-cluster-config-file/countries.xml
http://marklogic.com/xdmp/privileges/xdmp-delete-cluster-config-file/databases.xml
http://marklogic.com/xdmp/privileges/xdmp-delete-cluster-config-file/groups.xml
http://marklogic.com/xdmp/privileges/xdmp-delete-cluster-config-file/hosts.xml
http://marklogic.com/xdmp/privileges/xdmp-delete-cluster-config-file/languages.xml
http://marklogic.com/xdmp/privileges/xdmp-delete-cluster-config-file/mimetypes.xml
http://marklogic.com/xdmp/privileges/xdmp-delete-cluster-config-file/security.xml
http://marklogic.com/xdmp/privileges/xdmp-delete-cluster-config-file/server.xml
http://marklogic.com/xdmp/privileges/xdmp-delete-cluster-config-file/tokenizer.xml
http://marklogic.com/xdmp/privileges/xdmp-delete-cluster-config-file/user-languages.xml

Privileges to Administer a Set of Resources

A privilege of this category grants a user the ability to administer a specific set of resources (for example, databases). This privilege is specific to the resource set (for example, "databases"), which defines the specific privilege (for example, http://marklogic.com/xdmp/privileges/admin/database). This privilege may imply the privilege to read and write a specific configuration file.

The following privileges belong to this category:

http://marklogic.com/xdmp/privileges/admin/database
http://marklogic.com/xdmp/privileges/admin/forest
http://marklogic.com/xdmp/privileges/admin/host
http://marklogic.com/xdmp/privileges/admin/app-server
http://marklogic.com/xdmp/privileges/admin/app-server-security
http://marklogic.com/xdmp/privileges/admin/group
http://marklogic.com/xdmp/privileges/admin/group-security
http://marklogic.com/xdmp/privileges/admin/cluster
http://marklogic.com/xdmp/privileges/admin/mimetypes

Privileges of this category are pre-defined and included with every installation of MarkLogic Server. You can view them in the Execute Privileges Summary page of the Admin Interface (see instructions in Viewing an Execute Privilege section of the Administrator's Guide).

Privileges to Administer a Specific Resource

A privilege of this category grants a user an ability to administer a specific resource (for example, a database with the specified identifier). This privilege is granted by suffixing the administrator privilege for that kind of resource (for example, "database") with the specific identifier (for example, database-ID), which results in the specific privilege (for example, http://marklogic.com/xdmp/privileges/admin/database/database-ID). This privilege may imply the privilege to read and write a portion of a configuration file. It also grants the ability to call various built-in functions for specific resources (for example, http://marklogic.com/xdmp/privileges/xdmp-forest-clear/forest/forest-ID privilege allows calls to xdmp:forest-clear() for that forest identifier).

The following privileges belong to this category:

http://marklogic.com/xdmp/privileges/admin/database/database-ID
http://marklogic.com/xdmp/privileges/admin/forest/forest-ID
http://marklogic.com/xdmp/privileges/admin/host/host-ID
http://marklogic.com/xdmp/privileges/admin/app-server/server-ID
http://marklogic.com/xdmp/privileges/admin/app-server-security/server-ID
http://marklogic.com/xdmp/privileges/admin/group/group-ID
http://marklogic.com/xdmp/privileges/admin/group-security/group-ID
http://marklogic.com/xdmp/privileges/admin/cluster/cluster-ID

Privileges to Administer a Specific Aspect of a Set of Resources

A privilege of this category grants a user an ability to administer a specific aspect (for example, backup) of a set of resources (for example, databases). This privilege is granted by suffixing the administrator privilege for that kind of resource (for example, "database") with the specific aspect (for example, "backup"), which results in the specific privilege (for example, http://marklogic.com/xdmp/privileges/admin/database/backup). This privilege may imply the privilege to read and write a portion of a configuration file.

The following privileges belong to this category:

http://marklogic.com/xdmp/privileges/admin/database/forests
http://marklogic.com/xdmp/privileges/admin/database/backup
http://marklogic.com/xdmp/privileges/admin/database/index
http://marklogic.com/xdmp/privileges/admin/database/replication
http://marklogic.com/xdmp/privileges/admin/database/forest-backup
http://marklogic.com/xdmp/privileges/admin/forest/backup
http://marklogic.com/xdmp/privileges/admin/group/scheduled-task

Privileges to Administer a Specific Aspect of a Specific Resource

A privilege of this category grants a user an ability to administer a specific aspect (for example, backup) of a specific resource (for example, the database with identifier database-ID). This privilege is granted by suffixing the privilege for the specific aspect (for example, "backup") of that kind of resource (for example, "database") with the specific identifier (for example, "database-ID"), which results in the specific privilege (for example, http://marklogic.com/xdmp/privileges/admin/database/backup/database-ID). This privilege may imply the privilege to read and write a portion of a configuration file.

The following privileges belong to this category:

http://marklogic.com/xdmp/privileges/admin/database/forests/database-ID
http://marklogic.com/xdmp/privileges/admin/database/backup/database-ID
http://marklogic.com/xdmp/privileges/admin/database/index/database-ID
http://marklogic.com/xdmp/privileges/admin/database/index/database-name
http://marklogic.com/xdmp/privileges/admin/database/replication/database-ID
http://marklogic.com/xdmp/privileges/admin/database/forest-backup/database-ID
http://marklogic.com/xdmp/privileges/admin/forest/backup/forest-ID
http://marklogic.com/xdmp/privileges/admin/group/scheduled-task/group-ID

A user with any of the following privileges:

http://marklogic.com/xdmp/privileges/admin/database/index
http://marklogic.com/xdmp/privileges/admin/database/index/database-ID
http://marklogic.com/xdmp/privileges/admin/database/index/database-name

can alter the following properties:

Property Description
attribute-value-positions Index attribute value positions for faster near searches involving element-attribute-value-query (slower document loads and larger database files).
collection-lexicon Maintain a lexicon of collection URIs (slower document loads and larger database files).
default-rulesets The default rulesets configuration.
element-attribute-word-lexicons Maintain lexicons of words in elements.
element-value-positions Index element value positions for faster near searches involving element-value-query (slower document loads and larger database files).
element-word-lexicons Maintain lexicons of words in XML elements or JSON properties.
element-word-positions Index element word positions for faster element-based phrase and near searches (slower document loads and larger database files).
element-word-query-throughs The element-word-query-through specifications.
fast-case-sensitive-searches Enable faster case sensitive searches (slower document loads and larger database files).
fast-diacritic-sensitive-searches Enable faster diacritic sensitive searches (slower document loads and larger database files).
fast-element-character-searches Enable element wildcard searches and element-character-based XQuery predicates (slower document loads and larger database files).
fast-element-phrase-searches Enable faster element phrase searches (slower document loads and larger database files).
fast-element-trailing-wildcard-searches Enable element trailing wildcard searches (slower document loads and larger database files).
fast-element-word-searches Enable faster element-word searches (slower document loads and larger database files).
fast-phrase-searches Enable faster phrase searches (slower document loads and larger database files).
fast-reverse-searches Enable faster reverse searches (slower document loads and larger database files).
field-value-positions Index field value positions for faster near searches involving field-value-query (slower document loads and larger database files).
field-value-searches Index field values for faster searches involving field-value-query (slower document loads and larger database files).
fields The fields specifications.
geospatial-element-attribute-pair-indexes Indexes for fast geospatial element comparisons.
geospatial-element-child-indexes Indexes for fast geospatial element comparisons.
geospatial-element-indexes Indexes for fast geospatial element comparisons.
geospatial-element-pair-indexes Indexes for fast geospatial element comparisons.
geospatial-path-indexes Indexes for fast geospatial path-based comparisons.
geospatial-region-path-indexes Indexes for fast geospatial region comparisons.
language The default language assumed for content (if xml:lang encoding is absent)
path-namespaces The namespace binding specifications for Path indexes.
phrase-arounds The phrase-around specifications.
phrase-throughs The phrase-through specifications.
range-element-attribute-indexes Indexes for fast element-attribute inequality comparisons.
range-element-indexes Indexes for fast inequality comparisons.
range-index-optimize Specifies how to optimize range indexes.
range-path-indexes Indexes for fast inequality comparisons.
stemmed-searches Enable stemmed word searches (slower document loads and larger database files).
tf-normalization What kind of TF normalization to apply.
three-character-searches Enable wildcard searches and faster character-based XQuery predicates using three or more characters (slower document loads and larger database files).
three-character-word-positions Index word positions for three-character searches only when three-character-searches are enabled (slower document loads and larger database files).
trailing-wildcard-searches Enable trailing wildcard searches (slower document loads and larger database files).
trailing-wildcard-word-positions Index word positions for trailing-wildcard searches only when trailing-wildcard-searches are enabled (slower document loads and larger database files).
triple-index Enable the RDF triple index (slower document loads and larger database files).
triple-positions Index triple positions for faster near searches involving cts:triple-range-query (slower document loads and larger database files).
uri-lexicon Maintain a lexicon of document URIs (slower document loads and larger database files).
word-lexicons A list of word lexicons. Each lexicon is defined by its collation URI.
word-positions Index word positions for faster phrase and near searches (slower document loads and larger database files).
word-searches Enable unstemmed word searches (slower document loads and larger database files).

Configuring Granular Privileges

You can configure granular privileges either via the MarkLogic Server Admin Interface or via the functions of XQuery API security module.

This section describes both mechanisms in the corresponding subsections:

Configure Granular Privileges via the Admin Interface

To create a new granular privilege via the Admin Interface, follow steps for creating an execute privilege described at Creating an Execute Privilege section of the Administrator's Guide.

For example, to create a granular privilege that grants a user an ability to administer a specific aspect (for example, backup) of a set of resources (for example, forests), perform the following steps:

  1. Use the Admin Interface to create an execute privilege named admin-forest-backup.
  2. Assign the action URI http://marklogic.com/xdmp/privileges/admin/forest/backup to the privilege.
  3. Assign the privilege to the desired role or roles. You may want to create a specific role for this privilege depending on your security requirements.

The following screenshot depicts the New Execute Privilege page with these parameters:

You cannot create a granular privilege that grants a user the ability to administer a specific resource (such as a forest with the specified identifier) in the manner described here because resource identifiers are not exposed in the Admin Interface. To create a granular privilege of this type (for example, http://marklogic.com/xdmp/privileges/admin/forest/forest-ID), you need to use the functions of the XQuery API security module, as described in the following section Configure Granular Privileges via the XQuery API Security Module.

Configure Granular Privileges via the XQuery API Security Module

You can use the XQuery API security module to create and assign granular privileges. The following sections describe this in detail:

Creating and Assigning Granular Privileges

To create a new granular privilege programmatically, use the following function of the XQuery API security module:

sec:create-privilege(
   $privilege-name as xs:string,
   $action as xs:string,
   $kind as xs:string,
   $role-names as xs:string*
) as xs:unsignedLong

To assign an existing granular privilege to an additional role, use the following function of the XQuery API security module:

sec:privilege-set-roles(
   $action as xs:string,
   $kind as xs:string,
   $role-names as xs:string*
) as empty-sequence()

For detailed descriptions of sec:create-privilege and sec:privilege-set-roles functions of security.xqy library module, see the MarkLogic XQuery and XSLT Function Reference.

Using Pseudo-Functions with Granular Privileges

When you have a payload that creates a database and a granular privilege for that database, you need to substitute a variable of some sort for the ID of the database because the database has yet to be created. MarkLogic has the following pseudo-functions that can be used when creating and assigning granular privileges:

Pseudo-Function and Parameters Replaced By...
$$group-id(group-name) The group ID of the named group.
$$database-id(database-name) The database ID of the named database.
$$host-id() The host ID of the host running the query.
$$host-id(host-name) The host ID of the named host.
$$forest-id(forest-name) The forest ID of the named forest.
$$cluster-id() The cluster ID of the cluster to which the host running the query belongs.
$$cluster-id(cluster-name) The cluster ID of the named cluster.
$$role-id(role-name) The role ID of the named role.
$$user-id(user-name) The user ID of the named user.
$$server-id(server-name) The server ID of the named server in the group to which the host running the query belongs.
$$server-id("server-name", group-id)

The server ID of the named server in the specified group. Note that group-id is an unsigned long. To refer to the group by name as well, nest the calls:

$$server-id(server-name, $$group-id(group-name))

$$privilege-id("privilege-name") The privilege ID of the named /execute/ privilege.
$$privilege-id("privilege-name", "execute") The privilege ID of the named execute privilege.
$$privilege-id("privilege-name", "uri") The privilege ID of the named URI privilege.

For example, to create the privilege finalDbName-index-editor for a not-yet-created database represented by the variable FinalDbName, execute the following code:

{
    "privilege-name": "finalDbName-index-editor",
    "action": "http://marklogic.com/xdmp/privileges/admin/database/index/$$database-id(FinalDbName)",
    "role": ["firstEditorRole","secondEditorRole"],
    "kind": "execute"
  }
Examples of Creating and Assigning Granular Privileges

The following are examples of creating and assigning granular privileges via the XQuery API.

Example 1: Assign a privilege to perform index operations on any database to role1

Suppose you previously created http://marklogic.com/xdmp/privileges/admin/database/index privilege via the Admin Interface, as described in the previous section Configure Granular Privileges via the Admin Interface. Assign this privilege to role1 as follows:

xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at "/MarkLogic/security.xqy";

sec:privilege-set-roles(
   "http://marklogic.com/xdmp/privileges/admin/database/index",
   "execute",
   ("admin","role1")
)

Example 2: Create a privilege to perform any operations on database db1 for role2

Create a privilege to perform any operations on database db1 for role2 as follows (note the use of function xdmp:database("db1") to convert from the database name to the database identifier):

xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at "/MarkLogic/security.xqy";

sec:create-privilege(
   "admin-database-db1",
   fn:concat("http://marklogic.com/xdmp/privileges/admin/database/", xdmp:database("db1")),
   "execute",
   "role2"
)

Example 3: Create a privilege to perform index operations on database db1 for role3

Create a privilege to perform index operations on database db1 for role3 as follows (note the use of function xdmp:database("db1") to convert from the database name to the database identifier):

xquery version "1.0-ml";
import module namespace sec="http://marklogic.com/xdmp/security" at "/MarkLogic/security.xqy";

sec:create-privilege(
   "admin-database-db1",
   fn:concat("http://marklogic.com/xdmp/privileges/admin/database/index/", xdmp:database("db1")),
   "execute",
   "role3"
)

Examples of Granular Privileges Usage

This section describes several scenarios that use granular privileges.

Prerequisites - Create Databases, Roles, Users, and Privileges

To execute the scenarios discussed in this section, you need to perform the following preparation steps:

  1. Using the Admin Interface, create databases db1 and db2. For details on creating databases, see Creating a New Database section of the Administrator's Guide.
  2. Using the Admin Interface, create roles role1, role2, and role3. For details on creating roles, see Creating a Role section of the Administrator's Guide.
  3. Using the Admin Interface, create users user1, user2, and user3 with roles role1, role2, and role3 correspondingly. For details on creating users and assigning roles to them, see Creating a User section of the Administrator's Guide.
  4. Create and assign granular privileges to roles role1, role2, and role3 as described in Example 1, Example 2, and Example 3 correspondingly of the previous section Configure Granular Privileges via the XQuery API Security Module.

As the result, you will have the users with roles and privileges as described in the following table:

User Role Privilege
user1 role1 http://marklogic.com/xdmp/privileges/admin/database/index
user2 role2 http://marklogic.com/xdmp/privileges/admin/database/db1_identifier
user3 role3 http://marklogic.com/xdmp/privileges/admin/database/index/db1_identifier

Scenarios that Use Granular Privileges

This section includes examples in XQuery that you may run for user1, user2, and user3 from the Query Console and observe different results depending on the user's privileges. The results are discussed in detail in the next section, Test It Out.

Scenario 1: Add range index to database db1

Execute the following XQuery code to add a range index to database db1:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" at "/MarkLogic/admin.xqy";

let $config := admin:get-configuration()
let $dbid := xdmp:database("db1")
let $rangespec := admin:database-range-element-index("int", "http://marklogic.com/qa", "column1", (), fn:false())
let $config := admin:database-add-range-element-index($config, $dbid, $rangespec)
return admin:save-configuration($config)

Scenario 2: Add range index to database db2

Execute the following XQuery code to add a range index to database db2:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" at "/MarkLogic/admin.xqy";

let $config := admin:get-configuration()
let $dbid := xdmp:database("db2")
let $rangespec := admin:database-range-element-index("int", "http://marklogic.com/qa", "column1", (), fn:false())
let $config := admin:database-add-range-element-index($config, $dbid, $rangespec)
return admin:save-configuration($config)

Scenario 3: Add backup for database db1

Execute the following XQuery code to add a backup for database db1:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" at "/MarkLogic/admin.xqy";
let $config := admin:get-configuration()
let $backup := admin:database-monthly-backup("/space/backup", 2, 1, xs:time("09:45:00"), 2, true(), true(), true())
return admin:save-configuration(admin:database-add-backup($config, xdmp:database("db1"), $backup))

Test It Out

Using the Query Console, you can execute Scenario 1, Scenario 2, and Scenario 3 for each one of the users user1, user2, and user3. The results of the execution are presented in the following table:

User Role Scenario Result
user1 role1 Add range index to database db1 Success
user1 role1 Add range index to database db2 Success
user1 role1 Add backup for database db1 Failure
user2 role2 Add range index to database db1 Success
user2 role2 Add range index to database db2 Failure
user2 role2 Add backup for database db1 Success
user3 role3 Add range index to database db1 Success
user3 role3 Add range index to database db2 Failure
user3 role3 Add backup for database db1 Failure

The following analysis explains these results:

  • The user user1 successfully adds indexes to both databases db1 and db2, but fails to add backup to database db1, because the user's role1 has granular privilege http://marklogic.com/xdmp/privileges/admin/database/index that allows to add indexes to any database but does not allow other operations on databases.
  • The user user2 successfully adds both the index and backup to database db1, but fails to add index to database db2, because the user's role2 has granular privilege http://marklogic.com/xdmp/privileges/admin/database/db1_identifier that allows this user to perform any operation on database db1 but does not allow operations on other databases.
  • The user user3 successfully adds index to database db1, but fails to add index to database db2 and to add backup to database db1, because the user's role3 has granular privilege http://marklogic.com/xdmp/privileges/admin/database/index/db1_identifier that allows to add indexes to database db1 but does not allow any other operation on database db1 and does not allow any operation on other databases.

Enabling Non-Privileged Users to Create Privileges, Roles, and Users

Non-privileged users can use granular privileges to create and manage user privileges, create and manage roles, and create users.

This section includes:

Enabling Non- Privileged Users to Assign Roles

The create-user-privilege privilege enables otherwise non-privileged users to create and manage user-defined privileges.

If a user has a role with this privilege set, they do not need the grant-my-privileges privilege to assign specific privileges.

The general form of this granular privilege is:

http://marklogic.com/xdmp/privileges/admin/create-user-privilege/DOMAIN/PRIVILEGE-PATH/

Note that the PRIVILEGE-PATH can contain more than one slash (/) and must end with a slash.

For example, given a user with a role that has the following privilege:

http://marklogic.com/xdmp/privileges/admin/create-user-privilege/acme.com/publishing/

This user can manage the following execute or URI privileges:

  • http://acme.com/publishing/
  • http://acme.com/publishing/updates/
  • http://acme.com/publishing/updates/weekly/

This user can also create roles that use these privileges, as long as the role name is unique to the entire system, including someone else's set of roles.

As another example, if you only want this user to be able to publish weekly updates, you would assign them a role with the following privilege:

http://marklogic.com/xdmp/privileges/admin/create-user-privilege/acme.com/publishing/updates/weekly

Enabling Non-Privileged Users to Create and Manage Roles (Data Roles)

The http://marklogic.com/xdmp/privileges/create-data-role allows non-admin users (with the manage role) to create and manage roles.

  • data role: created by a data manage (non-admin) user
  • data manage user for data roles:
    • non-admin to create and manage roles
    • can only manage (edit, delete and grant) roles own created or granted
    • requires one role to include create-data-role privilege and manage role (or privilege)
    • user self can be created by admin or another data manage user
    • optional grant-my-role privilege to grant roles or create another data manage user
    • can grant own created or granted data roles to other data roles
  • created data roles are attached to the roles (with create-data-role privilege) data manage user owned
    • tracked by internal data-role-edit-<ROLEID> and data-role-inherit-<ROLEID> privileges created for every data role
  • every data manage user granted (new or existed) with above roles can also manage these data roles
    • to share responsibility for managing data roles through a common data role
  • An optional privilege - http://marklogic.com/xdmp/privileges/role-set-queries - is required to create data roles with query-based access control (QBAC) queries. The http://marklogic.com/xdmp/privileges/role-get-queries privilege is needed for reading the QBAC queries on the data roles. For more information on QBAC, please see Query-Based Access Control.

For example:

Create role (demo-data-role), grant that role the create-data-role privilege.

curl -s --anyauth -u admin:admin -H "content-type:application/json" \
     -X POST -d "{\"role-name\": \"demo-data-role\",
                  \"description\": \"A role for demonstrating the create-data-role privilege\", \
                   \"privilege\": [ { \
                      \"privilege-name\": \"create-data-role\", \
                       \"action\": \"http://marklogic.com/xdmp/privileges/create-data-role\", \
                         \"kind\": \"execute\"}]}" \
     http://localhost:8002/manage/v2/roles

Create a user and grant that user (demo-user) the demo-data-role and the manage role.

curl -s --anyauth -u admin:admin -H "content-type:application/json" \
     -X POST -d "{\"user-name\": \"demo-user\", \"password\": \"password\", \
               \"description\": \"A demo user\", \
                \"role\": [ \"demo-data-role\", \"manage\" ] }" \
     http://localhost:8002/manage/v2/users

Now that user can create new roles, demo-role-one:

curl -s --anyauth -u "demo-user:password" -H "content-type:application/json" \
     -X POST -d "{\"role-name\": \"demo-role-one\",
                  \"description\": \"First demo role\" }" \
     http://localhost:8002/manage/v2/roles

And demo-role-two:

curl -s --anyauth -u "demo-user:password" -H "content-type:application/json" \
     -X POST -d "{\"role-name\": \"demo-role-two\",
                   \"description\": \"Second demo role\" }" \
     http://localhost:8002/manage/v2/roles

The users can assign roles they have created to each other:

curl -s --anyauth -u "demo-user:password" -H "content-type:application/json" \
     -X PUT -d "{\"role\": [\"demo-role-two\"]}" \
     http://localhost:8002/manage/v2/roles/demo-role-one/properties

But they cannot assign roles that they did not create. To allow a user to assign existing roles, you can grant this demo-data-role to another user or role, so that user can manage both demo-role-one and demo-role-two.

A user with the ability to edit a role may also delete it. When the role is deleted, the extra data-role-edit and data-role-inherit privileges associated with it are also removed.

Enabling Non-Privileged Users to Create and Manage Users (Data Users)

The http://marklogic.com/xdmp/privileges/create-data-user allows non-admin users (with the manage role) to create and manage users.

  • data user: created by a data manage (non-admin) user
  • data role: created by a data manage (non-admin) user
  • data manage user for data users:
    • non-admin to create and manage users
    • can only manage (edit and delete) users own created or granted
    • might be the same data manage user to create data roles and data users
    • requires one role to include create-data-user privilege and manage role (or privilege)
    • user self can be created by admin or another data manage user
    • optional grant-my-role privilege to grant roles or create another data manage user
    • can grant data users own created or granted to other data roles
  • created data users are attached to the roles (with create-data-user privilege) data manage user owned
    • tracked by an internal data-user-edit-<USERID> privilege created for every data user
  • every data manage user granted (new or existed) with above roles can also manage these data users
    • to share responsibility for managing data users through a common data role
  • An optional privilege - http://marklogic.com/xdmp/privileges/user-set-queries - is required to create data users with query-based access control (QBAC) queries. The http://marklogic.com/xdmp/privileges/user-get-queries privilege is needed for reading the QBAC queries on the data users. For more information on QBAC, please see Query-Based Access Control.

For example:

Create a role (demo-data-user-role-one) and grant that role the create-data-user privilege.

curl -s --anyauth -u admin:admin -H "content-type:application/json" \
     -X POST -d "{\"role-name\": \"demo-data-user-role-one\",
                  \"description\": \"A role for demonstrating the create-data-user privilege\", \
                  \"privilege\": [ { \
                     \"privilege-name\": \"create-data-user\", \
                     \"action\": \"http://marklogic.com/xdmp/privileges/create-data-user\", \
                     \"kind\": \"execute\"}]}" \
     http://localhost:8002/manage/v2/roles

Create another role (demo-data-user-role-two) and grant that role the create-data-user privilege.

curl -s --anyauth -u admin:admin -H "content-type:application/json" \
     -X POST -d "{\"role-name\": \"demo-data-user-role-two\",
                  \"description\": \"Second role for demonstrating the create-data-user privilege\", \
                  \"privilege\": [ { \
                     \"privilege-name\": \"create-data-user\", \
                     \"action\": \"http://marklogic.com/xdmp/privileges/create-data-user\", \
                      \"kind\": \"execute\"}]}" \
     http://localhost:8002/manage/v2/roles

Create user demo-user-one, and grant two roles: the manage role, the new created demo-data-user-role-one role.

curl -s --anyauth -u admin:admin -H "content-type:application/json" \
     -X POST -d "{\"user-name\": \"demo-user-one\", \"password\":                   \"password\", \
                  \"description\": \"A demo user one\", \
                  \"role\": [ \"demo-data-user-role-one\", \"manage\" ] }" \
     http://localhost:8002/manage/v2/users

Also create another user demo-user-two and grant demo-data-user-role-two and manage role.

curl -s --anyauth -u admin:admin -H "content-type:application/json" \
     -X POST -d "{\"user-name\": \"demo-user-two\", \"password\": \"password\", \
                  \"description\": \"A demo user two\", \
                  \"role\": [ \"demo-data-user-role-two\", \"manage\" ] }" \
     http://localhost:8002/manage/v2/users

Now that user demo-user-one can create new users, demo-one-created-user:

curl -s --anyauth -u "demo-user-one:password" -H "content-type:application/json" \
     -X POST -d "{\"user-name\": \" demo-one-created-user\",
                  \"description\": \"user created by demo-user-one\" }" \
     http://localhost:8002/manage/v2/users

And user demo-user-two can create new users, demo-two-created-user:

curl -s --anyauth -u "demo-user-two:password" -H "content-type:application/json" \
     -X POST -d "{\"user-name\": \" demo-two-created-user\",
                   \"description\": \"user created by demo-user-two\" }" \
     http://localhost:8002/manage/v2/users

The user demo-one-created-user can be updated (and also deleted) by user demo-user-one who created this user:

curl -s --anyauth -u "demo-user-one:password" -H "content-type:application/json" \
     -X PUT -d "{\"description\": \"demo-user-one updated this\"}" \
     http://localhost:8002/manage/v2/users/demo-one-created-user/properties

And user demo-user-two can update demo-two-created-user:

curl -s --anyauth -u "demo-user-two:password" -H "content-type:application/json" \
     -X PUT -d "{\"description\": \"demo-user-two updated this\"}" \
     http://localhost:8002/manage/v2/users/demo-two-created-user/properties

But these users cannot update users they did not create.

curl -s --anyauth -u "demo-user-two:password" -H "content-type:application/json" \
     -X PUT -d "{\"description\": \"demo-user-two updating demo-one-created-user\"}" \
     http://localhost:8002/manage/v2/users/demo-one-created-user/properties

This request fails.

All users created by demo-user-two are attached to demo-data-user-role-two role, and can be added to demo-user-one directly, so demo-user-one can edit them.

curl -s --anyauth -u "admin:admin" -H "content-type:application/json" \
     -X PUT -d "{\"role\": [ \"demo-data-user-role-one\", \"demo-data-user-role-two\", \"manage\" ] }" \
     http://localhost:8002/manage/v2/users/demo-user-one/properties

Now user demo-user-two with role demo-data-user-role-two has the appropriate privilege to edit demo-one-created-user directly. So demo-user-two can edit them, and the previous request will succeed.

Using Granular Privileges with MarkLogic Data Hub Service

MarkLogic Data Hub Service (DHS) provides a managed instance in which to deploy an operational data hub created using MarkLogic Data Hub.

The following roles are built into DHS:

Amazon Web Services (AWS)

Microsoft Azure

The following rules apply to granular privileges on a data hub:

  • A user assigned the Security Admin service role cannot delete or modify privileges for these or any other pre-built roles, and these pre-built roles cannot inherit privileges.
  • When a user assigned the Security Admin service role creates a DHS custom role, that role initially has no pre-built roles associated with it.
  • Custom roles in DHS can inherit functionality from the pre-built DHS roles, from other DHS custom roles, or they can be created to have no inheritance, but you cannot assign any privileges to DHS custom roles.
  • DHS custom roles cannot inherit privileges from any other (non-DHS) pre-built MarkLogic roles.
  • You can change the external name for a DHS custom role, but the internal name stays constant.
« Previous chapter
Next chapter »