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.
This chapter describes how to configure MarkLogic Server for external authentication using LDAP and/or Kerberos. The topics in this chapter are:
The following terms are used in this chapter:
Kerberos is not supported when running MarkLogic Server on Windows. However, you can run Kerberos on an external Windows server to access a remote instance of MarkLogic.
joe
, as having access to the server MARKLOGIC1.COM
, the DN for joe
would look like:UID=joe,CN=Users,DC=MARKLOGIC1,DC=COM
The attributes after UID
make up what is known as the Base DN.
For details on LDAP DNs, see http://www.rfc-editor.org/rfc/rfc4514.txt.
A user principal is defined by the format: username@REALM.NAME
. For example, to identify the user, joe
, as having access to the server MARKLOGIC1.COM
, the principal might look like:
joe@MARKLOGIC1.COM
For details on Kerberos principals, see http://www.kerberos.org/software/tutorial.html#1.3.2.
MarkLogic Server supports external authentication by means of LDAP and Kerberos. 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. For details on how to configure an App Server for external authentication, see Creating an External Authentication Configuration Object and Configuring an App Server for External Authentication.
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. For details on how to map a MarkLogic user to an LDAP Distinguished Name (DN) or a Kerberos User Principal, see Assigning an External Name to a User.
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. For details on how to map a MarkLogic role to an LDAP group, see Assigning an External Name to a Role.
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.
MarkLogic Server caches negative lookups to avoid overloading the external Kerberos or LDAP server. Successful logins are also cached. The cache can be cleared by calling the sec:external-security-clear-cache function.
The following flowchart illustrates the logic used to determine how a MarkLogic user is authenticated and authorized.
The possible external authorization configurations for accessing MarkLogic Server are shown in the following table.
When application-level authentication is enabled with Kerberos authentication, an application can use the xdmp:gss-server-negotiate function to obtain a username that can be passed to the xdmp:login function to log into MarkLogic Server.
If running MarkLogic Server on Windows and using LDAP authentication to authenticate users, the user name must include the domain name of the form: userName@domainName
.
This section describes how to create an external authentication configuration object in the Admin Interface. You can also use the sec:create-external-security function to create an external authentication configuration object. Once created, multiple App Servers can use the same external authentication configuration object.
This section describes how to assign one or more external names to a user in the Admin Interface. You can also use the sec:create-user or sec:user-set-external-names function to assign one or more external names to a user. The external names are used to match the user with one or more Distinguished Names in an LDAP server or User Principals in a Kerberos server.
When LDAP authorization is used, the LDAP groups associated with the user are mapped to MarkLogic roles. One or more groups can be associated with a single role. These LDAP groups are defined as External Names in the Role Configuration Page.
This section describes how to assign one or more external names to a role in the Admin Interface. You can also use the sec:create-role or sec:role-set-external-names function to assign one or more external names to a role.
This section describes how to configure an App Server for external authentication.
Field | Description |
---|---|
authentication |
The authentication scheme: basic or application-level for LDAP authentication, or kerberos-ticket for Kerberos authentication. |
internal security |
Determines whether or not authentication for the App Server is to be done internally by MarkLogic Server. |
external security |
The name of the external authentication configuration object to use. For details on how to create an external authentication configuration object, see Creating an External Authentication Configuration Object. |
default user |
If you select application-level authentication, you will also need to specify a Default User. Anyone accessing the HTTP server is automatically logged in as the Default User until the user logs in explicitly. A Default User must be an internal user stored in the Security database. |
If you are configured to Kerberos authentication, then you must create a services.keytab
file and place it in the MarkLogic data directory.
The name of the generated keytab file must be services.keytab
.
This section contains the following topics:
On Windows platforms, the services.keytab
file is created using Active Directory Domain Services (AD DS) on a Windows server.
Kerberos is not supported when running MarkLogic Server on Windows. However, you can run Kerberos on an external Windows server to access a remote instance of MarkLogic.
If you are using the MD5 bind method and Active Directory Domain Services (AD DS) on a computer that is running Windows Server 2008 or Windows Server 2008 R2, be sure that you have installed the hot fix described in http://support.microsoft.com/kb/975697.
To create a services.keytab
file, do the following:
mysrvr.marklogic.com
, create a user with the name mysrvr.marklogic.com
.HTTP/
hostname using ktpass
command of the form: ktpass princ HTTP/
<hostname> mapuser <user-account> pass <password>
out <filename>
For example, to create a keytab file for the host named mysrvr.marklogic.com
, do the following:
ktpass princ HTTP/mysrvr.marklogic.com@MLTEST1.LOCAL mapuser mysrvr.marklogic.com@MLTEST1.LOCAL pass mysecret out services.keytab
services.keytab
from the Windows server to the MarkLogic data directory on your MarkLogic Server.On Linux platforms, the services.keytab
file is created as follows:
kadmin.local
to start the Kerberos administration command-line tool.addprinc
command to add the principal to Kerberos. addprinc
command to generate the services.keytab
file for the principal.For example, to create a services.keytab
file for the host named mysrvr.marklogic.com
, do the following:
$ kadmin.local > addprinc -randkey HTTP/mysrvr
.marklogic.com > ktadd -k services.keytab HTTP/mysrvr
.marklogic.com
This section provides an example of how Kerberos and LDAP users and groups might be mapped to MarkLogic users and roles.
On Active Directory, there is a Kerberos user and an LDAP user assigned to an LDAP group:
jsmith@MLTEST1.LOCAL
CN=John Smith,CN=Users,DC=MLTEST1,DC=LOCAL
CN=TestGroup Admin,CN=Users,DC=MLTEST1,DC=LOCAL
On MarkLogic Server, the two users and the ldaprole1
role are assigned external names that map them to the above users and LDAP group.
After authentication, the xdmp:get-current-user function returns a different user name, depending on the external authorization configuration. The possible configurations and returned name is shown in the following table.