MarkLogic 9 Product Documentation

Security Guide — Chapter 14

Overview of the Security Database

Authentication in MarkLogic Server occurs via the security database. The security database contains security objects such as privileges, roles, and users. A security database is associated with each HTTP, WebDAV, ODBC, or XDBC server. Typically, a single security database services all of the servers configured in a system. Actions against the server are authorized based on the security database. The security database works the same way for clustered systems as it does for single-node systems; there is always a single security database associated with each HTTP, WebDAV, ODBC, or XDBC server.

The configuration that associates the security database with the database and servers is at the database level. HTTP, WebDAV, ODBC, and XDBC servers each access a single documents database, and each database in turn accesses a single security database. Multiple documents databases can access the same security database. The following figure shows many servers accessing some shared and some different documents databases, but all accessing the same security database.

Sharing the security database across multiple servers provides a common security configuration. You can set up different privileges for different databases if that makes sense, but they are all stored in a common security database. For an example of this type of configuration, see Example: Using the Security Database in Different Servers.

In addition to storing users, roles, and privileges that you create, the security database also stores pre-defined privileges and pre-defined roles. These objects control access to privileged activities in MarkLogic Server. Examples of privileged activities include loading data and accessing URIs. The security database is initialized during the installation process. For a list of all of the pre-defined privileges and roles, see the corresponding appendixes in the Administrator's Guide.

Associating a Security Database With a Documents Database

When you configure a database, you must specify which database is its security database. You can associate the security database to another database in the database configuration screen of the Admin Interface. This configuration specifies which database the server will use to authenticate users and authorize requests. By default, the security database is named Security. The following screen shot shows the server configuration screen drop-list that specifies the security database.

Managing and Using Objects in the Security Database

There are two mechanisms available to add, change, delete, and use objects in the security database: the Admin Interface and the XQuery functions. provided by the security.xqy library module. This section describes what you can do with each of these mechanisms and includes the following topics:

• Using the Admin Interface
• Using the security.xqy Module Functions

Backing Up the Security Database

The security database is the central entry point to all of your MarkLogic Server applications. If the security database becomes unavailable, no users can access any applications. Therefore, it is important to create a backup of the security database. Use the database backup utility in the Admin Interface to back up the security database. For details, see the Backing Up and Restoring a Database chapter of the Administrator's Guide.

Example: Using the Security Database in Different Servers

The security database typically is used for the entire system, including all of the HTTP, WebDAV, ODBC, and XDBC servers configured. You can create distinct privileges to control access to each server. If each server accesses a different document database, these privileges can effectively control access to each database (because the database is associated with the server). Users must have the appropriate login privileges to log into the server, and therefore they have no way of accessing either the applications or the content stored in the database accessed through that server without possessing the appropriate privilege. This example describes such a scenario.

Consider an example with two databases--DocumentsA and DocumentsB. DocumentsA and DocumentsB share a single security database, Security. Security is the default security database managed by the Admin Interface on port 8001. There are two HTTP servers, ApplicationA and ApplicationB, connected to DocumentsA and DocumentsB respectively.

ExecutePrivilegeA controls login access to ApplicationA, and ExecutePrivilegeB to ApplicationB. RoleA is granted ExecutePrivilegeA and RoleB is granted ExecutePrivilegeB.

With this configuration, users who are assigned RoleA can access documents in DocumentsA and users of RoleB can access documents in DocumentsB. Assuming that ExecutePrivilegeA or ExecutePrivilegeB are appropriately configured as login privileges on every HTTP and XDBC server that accesses either DocumentsA or DocumentsB, user access to these databases can conveniently be managed by assigning users the role(s) RoleA and/or RoleB as required.

The Admin Interface at port 8001 is also used to configure all databases, HTTP servers, hosts, and so on. The connection between the Admin Interface and the Security database in the diagram simply indicates that the Admin Interface is storing all security objects--users, roles, and privileges--in Security database.

The steps below outline the process to create the configuration in the above example.

1. Create two document databases: DocumentsA and DocumentsB. Leave the security database for the document databases as Security (the default setting).
2. Create two execute privileges: ExecutePrivilegeA and ExecutePrivilegeB. They represent the privilege to access ApplicationA and ApplicationB respectively. ApplicationA and ApplicationB are two HTTP servers that are created later in this procedure.

   The new execute privileges created using the Admin Interface are stored in the Security database. The new roles and users created below are also stored in the Security database.

3. Create two new roles. These roles are used to organize users into groups and to facilitate granting access to users as a group.
   1. Create a new role. Name it RoleA.
   2. Scroll down to the Execute Privileges section and select ExecutePrivilegeA. This associates ExecutePrivilegeA with RoleA. Any user assigned RoleA is granted ExecutePrivilegeA.
   3. Repeat the steps for RoleB, selecting ExecutePrivilegeB instead.
4. Create two new HTTP servers:
   1. Create a new HTTP server. Name it ApplicationA.
   2. Select DocumentsA as the database. ApplicationA is now attached to DocumentsA which in turn uses Security as its security database.
   3. Select basic, digest or digest-basic authentication scheme.
   4. Select ExecutePrivilegeA in the privilege drop down menu. This indicates that ExecutePrivilegeA is required to access ApplicationA.
   5. Repeat the steps for ApplicationB, selecting ExecutePrivilegeB instead.
5. Create new users.
   1. Create a new user named UserA1.
   2. Scroll down to the Roles section and select RoleA.
   3. Repeat the steps for UserB1, selecting RoleB in the roles section.

      UserA1 is granted ExecutePrivilegeA by virtue of its role (RoleA) and has login access to ApplicationA. Because ApplicationA is connected to DocumentsA, UserA1 is able to access documents in DocumentsA assuming no additional security requirements are implemented in ApplicationA, or added to documents in DocumentsA. The corresponding is true for UserB1.

The configuration process is now complete. Additional users can be created by simply repeating step 5 and selecting the appropriate role. All users assigned RoleA have login access to ApplicationA and all users assigned RoleB have login access to ApplicationB.

This approach can also be easily extended to handle additional discrete databases and user groups by creating additional document databases, roles and execute privileges as necessary.