Loading TOC...
Security Guide (PDF)

Security Guide — Chapter 4

Authenticating Users

MarkLogic Server authenticates users when they access an application. This chapter describes users and the available authentication schemes, and includes the following sections:


A user in MarkLogic Server is the basis for authenticating requests to a MarkLogic application server. Users are assigned to roles. Roles carry security attributes, such as privileges and default permissions. Permissions assigned to documents pair a role with a capability, therefore roles are central to document permissions. Users derive authorization to perform actions from their roles.

You configure users in the Admin Interface, where you assign a user a name, a password, a set of roles, and a set of default permissions. To see the security attributes associated with a given user, click on the User:username link in the Admin Interface screen for the given user. For details on configuring users in the Admin Interface, see the Security Administration chapter in the Administrator's Guide.

During the initial installation of MarkLogic Server, two users are created. One of the users is an authorized administrator who has the admin role. During the installation, you are prompted to specify the username and password for this user. The other user is a user named nobody, which is created with no roles assigned and is given a password which is randomly generated. For details about installing MarkLogic Server, see the Installation Guide.

Types of Authentication

You can control the authentication scheme for HTTP, WebDAV, ODBC, and XDBC App Servers. This section describes the authentication schemes and includes the following parts:


Basic authentication is the typical authentication scheme for web applications. When a user accesses an application page, she is prompted for a username and password. In basic mode, the password is obfuscated but not encrypted.


Digest authentication works the same way as basic, but offers encryption of passwords sent over the network. When a user accesses an application page, she is prompted for a username and password.

If you change an App Server from basic to digest authentication, it invalidates all passwords in the security database. You must then reenter the passwords in the Admin Interface. Alternatively, you can migrate to digest-basic mode initially, then switch to digest-only mode once all users have accessed the server at least once. The first time the user accesses the server after changing from basic to digest-basic scheme, the server computes the digest password by extracting the relevant information from the credentials supplied in basic mode.


The digest-basic authentication scheme uses the more secure digest scheme whenever possible, but reverts to basic authentication when needed. Some older browsers, for example, do not support digest authentication. The digest-basic scheme is also useful if you previously used basic authentication, but want to migrate to digest. The first time a user accesses the server after changing from basic to digest-basic authentication scheme, the server computes the digest password by extracting the relevant information from the credentials supplied in basic mode.

Limitations of Digest and Basic Authentication

Since the browser does not provide a way to clear a user's authentication information in basic or digest mode, the user remains logged in until the browser is shut down. In addition, there is no way to create a custom login page using these schemes. For certain deployments, application-level authentication may be more appropriate.


Certificate-based authentication requires internal and external users and HTTPS clients to authenticate themselves to MarkLogic Server via a client certificate, either in addition to, or rather than a password.

Certificate-based authentication can take the following forms:

  • MarkLogic Server authenticates an internal user via the common name in a certificate.
  • MarkLogic Server authenticates an internal user via the distinguished name in a certificate, by matching the distinguished name to an external name configured for an internal user.
  • MarkLogic Server authenticates an external LDAP user via a certificate subject name, with internal authorization.
  • MarkLogic Server authenticates an external user via a certificate subject name, with external authorization. User is entirely defined external to MarkLogic.
  • MarkLogic Server authenticates via both a client certificate and a username/password. This provides a greater level of security by requiring that user provide a client certificate that matches the specified user.

For details on Certificate-based authentication, see Certificate-based Authentication.

Application Level

Application-level authentication bypasses all authentication and automatically logs all users in as a specified default user. You specify the default user in the Admin Interface, and any users accessing the server automatically inherit the security attributes (roles, privileges, default permissions) of the default user. Application-level authentication is available on HTTP, ODBC, and WebDAV servers.

The default user should have the required privileges to at least read the initial page of the application. In many application scenarios, the user is then given the opportunity to explicitly log in to the rest of the application from that page. How much of the application and what data a user can access before explicitly logging in depends on the application and the roles that the default user is part of. For an example of this type of configuration, see Using Custom Login Pages.

Kerberos Ticket

The user is authenticated by Kerberos and a Kerberos session ticket is used to authenticate the user to access MarkLogic Server. For details, see Overview of External Authentication.


When SAML authentication is used, a client requests a resource from MarkLogic Server with no security context; MarkLogic redirects the authentication request to an Identity Provider. The Identity Provider prompts the user to login, if necessary, and sends the authentication request back to MarkLogic Server (the Service Provider) for validation.

There are two major components in SAML:

  • Identity Provider (IDP) authenticates a subject and provides security assertion to service provider.
  • Service Provider (SP) provides access to the resource for a client. MarkLogic Server is a Service Provider.

MarkLogic Server sends a redirect to the resource. The client requests the resource again with a security context. MarkLogic Server then authenticates the user using the information from the authentication request to grant the user access to the requested resource.

See SAML Authentication for more information.

« Previous chapter
Next chapter »