Loading TOC...
Security Guide (PDF)

Security Guide — Chapter 1

Introduction to Security

When you create systems that store and retrieve data, it is important to protect the data from unauthorized use, disclosure, modification or destruction. Ensuring that users have the proper authority to see the data, load new data, or update existing data is an important aspect of application development. Do all users need the same level of access to the data and to the functions provided by your applications? Are there subsets of users that need access to privileged functions? Are some documents restricted to certain classes of users? The answers to questions like these help provide the basis for the security requirements for your application.

MarkLogic Server includes a powerful and flexible role-based security model to protect your data according to your application security requirements. There is always a trade-off between security and usability. When a system has no security, then it is open to malicious or unmalicious unauthorized access. When a system is too tightly secured, it might become difficult to use successfully. Before implementing your application security model, it is important to understand the core concepts and features in the MarkLogic Server security model. This chapter introduces the MarkLogic Server security model and includes the following sections:


Some MarkLogic Server security features require an Advanced Security License in addition to the regular license. The Advanced Security License option is required when using:

  • Compartment Security
  • Redaction
  • An external Key Management System (KMS) or keystore with encryption at rest
  • Query-Based Access Control

For more about redaction, see Redacting Document Content in the Application Developer's Guide. See Query-Based Access Control in this guide for more about query-based access control.

Security Overview

This section provides an overview of the three main principles used in MarkLogic Server security:

Authentication and Access Control

Authentication is the process of verifying user credentials for a named user. Authentication makes sure you are who you say you are. Users are typically authenticated with a username and password. Authentication verifies user credentials and associates an application session with the authenticated user. Every request to MarkLogic Server is issued from an authenticated user. Authentication, by itself, does not grant access or authority to perform specific actions. There are several ways to set up server authentication in MarkLogic Server.

Authentication by username and password is only part of the story. You might grant access to users based on something other than identity, something such as the originating IP address for the requests. Restricting access based on something other than the identity of the user is generally referred to as access control.

For details on authentication, see Authenticating Users.


Authorization provides the mechanism to control document access, XQuery and JavaScript code execution, and document creation. For an authenticated user, authorization determines what you are allowed to do. For example, authorization is what allows the user named Melanie to read and update a document, allows the user named Roger to only read the document, and prevents the user named Hal from knowing the document exists at all. In MarkLogic Server, authorization is used to protect documents stored in a database and to protect the execution of XQuery or JavaScript code. For details on authorization in MarkLogic Server, see Protecting Documents and Protecting XQuery and JavaScript Functions With Privileges.


Administration is the process of defining, configuring, and managing the security objects, such as users, roles, privileges, and permissions that implement your security policies. For details on security administration procedures in MarkLogic Server, see Security Administration and the Administrator's Guide.

MarkLogic Security Model

The MarkLogic Server security model is flexible and enables you to set up application security with the level of granularity needed by your security requirements. This section contains the following topics:

Role-Based Security Model (Authorization)

Roles are the central point of authorization in the MarkLogic Server security model. Privileges, users, other roles, and document permissions all relate directly to roles. The following conceptual diagram shows how each of these entities points into one or more roles.

There are two types of privileges: URI privileges and execute privileges. URI privileges are used to control the creation of documents with certain URIs. Execute privileges are used to protect the execution of functions in XQuery or JavaScript code.

For execute privileges' type, you may achieve finer granularity access control over configuration and various administration abilities through defining granular privileges. For information on granular privileges, see Granular Privileges.

Privileges are assigned to zero or more roles, roles are assigned to zero or more other roles, and users are assigned to zero or more roles. A privilege is like a door and, when the door is locked, you need to have the key to the door in order to open it. If the door is unlocked (no privileges), then you can walk right through. The keys to the doors are distributed to users through roles; that is, if a user inherits a privilege through the set of roles to which she is assigned, then she has the keys to unlock those inherited privileges.

Permissions are used to protect documents. Permissions are assigned to documents, either at load time or as a separate administrative action. Each permission is a combination of a role and a capability (read, insert, update, node-update, execute).

Users assigned the role corresponding to the permission have the ability to perform the capability. You can set any number of permissions on a document.

Capabilities represent actions that can be performed. There are four capabilities in MarkLogic Server:

  • read
  • insert
  • update
  • node-update
  • execute

Users inherit the sum of the privileges and permissions from their roles.

For more details on how roles work in MarkLogic Server, see Role-Based Security Model. For more details on privileges and permissions, see Protecting Documents.

Element Level Security

Element level security uses protected paths to conceal certain elements in document from specific users, while leaving other parts of a document available to search and view. You can use element level security to control access to specific JSON properties or XML elements within documents. This means that specific information inside a document may be hidden from a particular user based on the user's role, while still providing access to other information in the document.

Element level security can be used in addition to and along with existing document level security and compartment security. For more information about element level security, see Element Level Security.

Access Control With the Security Database

MarkLogic Server uses a security database to store the user data, privilege data, role data, and other security information. Each database in MarkLogic Server references a security database. A database named Security, which functions as the default security database, is created as part of the installation process.

The following figure shows that many databases can be configured to use the same security database for authentication and authorization.

The security database is accessed to authenticate users and to control access to documents. For details on authentication, the security database, and ways to administer objects in the security database, see Authenticating Users and Administering Security.

There may be circumstances in which a cluster is configured with more than one Security database, such as when using database replication. When multiple Security databases are used, there should be an equal number of Admin servers with different ports, one for each Security database. Each Security database can then be upgraded by its respective Admin Interface.

The name of the Security database used by the Admin Interface is shown in the upper right corner of the Security Configuration page.

Security Administration

MarkLogic Server administrators are privileged users who have the authority to perform tasks such as creating, deleting, modifying users, roles, privileges, and so on. These tasks change or add data in the security database. Users who perform these tasks must have the security role, either explicitly or by inheriting it from another role (for example, from the admin role). Typically, users who perform these tasks have the admin role, which provides the authority to perform any tasks in the database. Use caution when assigning users to the security and/or admin roles; users who are assigned the admin role can perform any task on the system, including deleting data.

MarkLogic Server provides the following ways to administer security:

  • Admin Interface
  • REST Management API
  • XQuery and JavaScript server-side security administration functions

For details on administering security, see Administering Security.


This section defines the following terms, which are used throughout the security documentation:


A user is a named entity used to authenticate a request to an HTTP, WebDAV, ODBC, or XDBC server. For details on users, see Authenticating Users.


A role is a named entity that provides authorization privileges and permissions to other roles or to users. You can assign roles to other roles (which can in turn include assignments to other roles, and so on). Roles are the fundamental building blocks that you use to implement your security policies. For details on roles, see Role-Based Security Model.

Execute Privilege

An execute privilege provides the authority to perform a protected action. Examples of protected actions are the ability to execute a specific user-defined function, the ability to execute a built-in function (for example, xdmp:document-insert), and so on. For details on execute privileges, see Protecting XQuery and JavaScript Functions With Privileges.

URI Privilege

A URI privilege provides the authority to create documents within a base URI. When a URI privilege exists for a base URI, only users assigned to roles that have the URI privilege can create documents with URIs starting with the base string. For details on URI privileges, see Protecting Documents.


A permission provides a role with the capability to perform certain actions (read, insert, update, node-update, execute) on a document or a collection. Permissions consist of a role and a capability. Permissions are assigned to documents and collections. For details on permissions, see Protecting Documents.


An amp provides a user with the additional authorization to execute a specific function by temporarily giving the user additional roles. For details on amps, see Temporarily Increasing Privileges with Amps.

« Table of contents
Next chapter »