MarkLogic 9 Product DocumentationConcepts Guide — Chapter 6
MarkLogic Server Security Model
MarkLogic Server includes a powerful and flexible role-based security model to protect your data according to your application security requirements. This chapter introduces the MarkLogic Server security model and includes the following sections:
- Role-Based Security Model (Authorization)
- The Security Database
- Security Administration
- SSL and TLS Support
- External Authentication (LDAP and Kerberos)
- Secure Credentials
- Encryption at Rest
- Element Level Security
- Other Security Tools
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 diagram illustrates the relationships between the different entities in the MarkLogic Server security model. Note how each of these entities point to one or more roles.
Privileges are the primitives used to grant users the authority to access assets in MarkLogic Server. There are two types of privileges: execute privileges and URI privileges. Execute privileges provide the authority to perform protected actions. 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. URI privileges provide the authority to create documents within particular base URIs. 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.
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. The keys to the doors are distributed to users through roles.
Amps provide users with the additional privileges to execute specific protected actions by temporarily giving users additional roles for the duration of the protected action.
Permissions are used to protect documents. Permissions are assigned to documents either at load time or when a document is updated. Each permission is a combination of a role and a capability (read, insert, 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:
Users inherit the sum of the privileges and permissions from their roles.
For more details on how roles, privileges and permissions work in MarkLogic Server, see the Security Guide.
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, XDBC, ODBC, or WebDAV 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. There is always a single security database associated with each HTTP, XDBC, ODBC, or WebDAV server.
The configuration that associates the security database with the database and servers is at the database level. App servers each access a single content database, and each content database in turn accesses a single security database. Multiple content databases can access the same security database. The following figure shows many servers accessing some shared and some different content databases, all of which access 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.
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.
The security database also contains the configuration data for collections, as well as the certificate authorities and templates used to enable SSL-based security on App Servers. For details on collections, see Protected Collections. For details on SSL, see SSL and TLS Support.
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 two ways to administer security:
For details on administering security using the Admin Interface, see the Administrator's Guide. For details on administering security using the admin and sec APIs, see the Scripting Administrative Tasks Guide.
SSL and TLS Support
SSL (Secure Sockets Layer) is a transaction security standard that provides encrypted protection between browsers and App Servers. When SSL is enabled for an App Server, browsers communicate with the App Server by means of an HTTPS connection, which is HTTP over an encrypted Secure Sockets Layer. HTTPS connections are widely used by banks and web vendors for secure transactions over the web.
A browser and App Server create a secure HTTPS connection by using a handshaking procedure. When browser connects to an SSL-enabled App Server, the App Server sends back its identification in the form of a digital certificate that contains the server name, the trusted certificate authority, and the server's public encryption key. The browser uses the server's public encryption key from the digital certificate to encrypt a random number and sends the result to the server. From the random number, both the browser and App Server generate a session key. The session key is used for the rest of the session to encrypt/decrypt all transmissions between the browser and App Server, enabling them to verify that the data didn't change in route.
The end result of the handshaking procedure described above is that only the server is authenticated. The client can trust the server, but the client remains unauthenticated. MarkLogic Server supports mutual authentication, in which the client also holds a digital certificate that it sends to the server. When mutual authentication is enabled, both the client and the server are authenticated and mutually trusted.
MarkLogic Server uses OpenSSL to implement the Secure Sockets Layer (SSL v3) and Transport Layer Security (TLS v1) protocols.
External Authentication (LDAP and Kerberos)
MarkLogic Server allows you to configure MarkLogic Server so that users are authenticated using an external authentication protocol, such as Lightweight Directory Access Protocol (LDAP) or Kerberos. These external agents serve as centralized points of authentication or repositories for user information from which authorization decisions can be made.
When a user attempts to access a MarkLogic App Server that is configured for external authentication, the requested App Server sends the username and password to the LDAP server or Kerberos for authentication. Once authenticated, the LDAP or Kerberos protocol is used to identify the user on MarkLogic Server.
Users can be authorized either internally by MarkLogic Server, externally by an LDAP server, or both. If internal authorization is used, the user needs to exist in the MarkLogic Security database where his or her external name matches the external user identity registered with either LDAP or Kerberos, depending on the selected authentication protocol.
If the App Server is configured for LDAP authorization, the user does not need to exist in MarkLogic Server. Instead, the external user is identified by a username with the LDAP server and the LDAP groups associated with the DN are mapped to MarkLogic roles. MarkLogic Server then creates a temporary user with a unique and deterministic id and those roles.
If the App Server is configured for both internal and LDAP authorization, users that exist in the MarkLogic Security database are authorized internally by MarkLogic Server. If a user is not a registered MarkLogic user, then the user must be registered on the LDAP server.
For details on compartment security see External Security in the Security Guide.
Secure Credentials
Secure credentials enable a security administrator to manage credentials, making them available to less privileged users for authentication to other systems without giving them access to the credentials themselves.
Secure credentials consist of a PEM encoded x509 certificate and private key and/or a username and password. Secure credentials are stored as secure documents in the Security database on MarkLogic Server, with passwords and private keys encrypted. A user references a credential by name and access is granted if the permissions stored within the credential document permit the access to the user. There is no way for a user to get access to the unencrypted credentials.
Secure credentials allow you to control which users have access to specific resources. A secure credential controls what URIs it may be used for, the type of authentication (e.g. digest), whether the credential can be used to sign other certificates, and the user role(s) needed to access the resource.
The security on a credential can be configured three different ways:
- Credentials that secure a resource by username and password.
- Credentials that secure a resource by a PEM encoded X509 certificate and a PEM encoded private key.
- Credentials that secure a resource by username and password, as well as a PEM encoded X509 certificate and a PEM encoded private key.
For details on compartment security see Secure Credentialsin the Security Guide.
Encryption at Rest
Increasing security risks and compliance requirements sometimes mandate the use of encryption at rest to prevent unauthorized access to data on disk. Encryption at rest protects your data on disk - at rest as opposed to when that data is being used in a process or in motion. Encryption at rest allows data, configuration, and logs to be encrypted in a transparent mode; encrypted while at rest, decrypted (with the proper permissions) when in use. The administrator can choose which databases to encrypt, if configuration should be encrypted, and/or if logs should be encrypted.
Encryption works with keys generated by the internal MarkLogic Key Management System (KMS) or keys generated by an external third party KMS. The MarkLogic KMS (a PKCS #11 secured wallet) can function as an internal keystore for encryption, or you can employ a third party KMIP 1.2 compliant server as a keystore. For details about encryption at rest, see Encryption at Rest in the Security Guide.
Element Level Security
Element-level Security provides secure access control to protect XML elements or JSON properties within documents, in addition to the existing document-level security and compartment security provided by MarkLogic. This means that specific information inside a document may be hidden from a particular user based on his or her role, while still providing access to other information in the document the user is allowed to see.
Element level security allows you to specify more complex security rules on specific elements within documents. Permissions on an element or property are similar to permissions defined on a document. Elements or properties may contain all supported datatypes. Search results and update built-ins will honor the permissions defined at the element level. For more about element level security, see Element Level Security in the Security Guide.
Other Security Tools
This section describes two additional MarkLogic security tools:
Protected Collections
As described in Collections, collections group documents that are related and enables queries to target subsets of documents within a database. A document can belong to any number of collections simultaneously. A collection exists in the system when a document in the system states that it is part of that collection. However, an associated collection object is not created and stored in the security database unless it is protected. A collection created through the Admin Interface is a protected collection and is stored in the security database.
Read, Insert, Update, and Execute capabilities apply for permissions on a collection. A user requires insert or update permissions on the collection to add documents to a protected collection. Collection permissions have no effect on document permissions, so a user with sufficient document permissions can read, update, or delete a document in a protected collection, whether or not the user has any collection permissions.
Compartments
MarkLogic Server includes an extension to the security model called compartment security. Compartment security allows you to specify more complex security rules on documents.
A compartment is a name associated with a role. You specify that a role is part of a compartment by adding the compartment name to each role in the compartment. When a role is compartmented, the compartment name is used as an additional check when determining a user's authority to access or create documents in a database. Compartments have no effect on execute privileges. Without compartment security, permissions are checked using OR semantics.
For example, if a document has read permission for role1 and read permission for role2, a user who possesses either role1 or role2 can read that document. If those roles have different compartments associated with them (for example, compartment1 and compartment2, respectively), then the permissions are checked using AND semantics for each compartment, as well as OR semantics for each non-compartmented role. To access the document if role1 and role2 are in different compartments, a user must possess both role1 and role2 to access the document, as well as a non-compartmented role that has a corresponding permission on the document.
If any permission on a document has a compartment, then the user must have that compartment in order to access any of the capabilities, even if the capability is not the one with the compartment.
Access to a document requires a permission in each compartment for which there is a permission on the document, regardless of the capability of the permission. So if there is a read permission for a role in compartment1, there must also be an update permission for some role in compartment1 (but not necessarily the same role). If you try to add read, insert, or execute permissions that reference a compartmented role to a document for which there is no update permission with the corresponding compartment, an exception is thrown.
For details on compartment security see Compartment Security in the Security Guide.