Loading TOC...
Security Guide (PDF)

Security Guide — Chapter 8

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 to restart a forest:

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

A user who has this privilege via some role is allowed to restart any forest.

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 this privilege is applicable to.

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. The categories are elaborated below.

Privileges to Read or Write Any Configuration File

A privilege of this category grants a user an ability to read/write any configuration file (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-write-cluster-config-file
   http://marklogic.com/xdmp/privileges/xdmp-read-cluster-config-file

Privileges to Write a Particular Configuration File

A privilege of this category grants a user an ability to write a particular 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-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

Privileges to Administer a Set of Resources

A privilege of this category grants a user an ability to administer a 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/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}

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 sub-sections:

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 the above parameters:

You will not be able to create a granular privilege that grants a user an ability to administer a specific resource (for example, a forest with the specified identifier) in the manner described above, 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 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

To create a new granular privilege programmatically, use the following function of 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 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.

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.

Pre-Requisites - Create Databases, Roles, Users, and Privileges

To execute scenarios discussed below, 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 table below:

User RolePrivilege
user1role1http://marklogic.com/xdmp/privileges/admin/database/index
user2role2http://marklogic.com/xdmp/privileges/admin/database/<db1_identifier>
user3role3http://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 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 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 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 table below:

User RoleScenarioResult
user1role1Add range index to database db1Success
user1role1Add range index to database db2Success
user1role1Add backup for database db1Failure
user2role2Add range index to database db1Success
user2role2Add range index to database db2Failure
user2role2Add backup for database db1Success
user3role3Add range index to database db1Success
user3role3Add range index to database db2Failure
user3role3Add backup for database db1Failure

The following analysis explains the above 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 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 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 as well.
« Previous chapter
Next chapter »
Powered by MarkLogic Server 7.0-4.1 and rundmc | Terms of Use | Privacy Policy