Understanding and Using Security Guide (PDF)

Understanding and Using Security Guide — Chapter 7

« Previous chapter
Next chapter »

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.

This chapter describes how to configure MarkLogic Server for external authentication using LDAP and/or Kerberos. The topics in this chapter are:

Terms Used in this Chapter

The following terms are used in this chapter:

  • Authentication is the process of verifying user credentials for a named user, usually based on a username and password. Authentication generally verifies user credentials and associates a session with the authenticated user. It does not grant any access or authority to perform any actions on the system. Authentication can be done internally inside MarkLogic Server, or externally by means of a Kerberos or LDAP server. This chapter describes how do configure MarkLogic Server for external authentication using either the Kerberos or LDAP protocol.
  • Authorization is the process of allowing a user to perform some action, such as create, read, update, or delete a document or execute a program, based on the user's identity. Authorization defines what an authenticated user is allowed to do on the server. When an App Server is configured for external authentication, authorization can be done either by MarkLogic Server or by LDAP.
  • Lightweight Directory Access Protocol (LDAP) is an authentication protocol for accessing server resources over an internet or intranet network. An LDAP server provides a centralized user database where one password can be used to authenticate a user for access to multiple servers in the network. LDAP is supported on Active Directory on Windows Server 2008 and OpenLDAP 2.4 on Linux and other Unix platforms.
  • Kerberos is a ticket-based authentication protocol for trusted hosts on untrusted networks. Kerberos provides users with encrypted tickets that can be used to request access to particular servers. Because Kerberos uses tickets, both the user and the server can verify each other's identity and user passwords do not have to pass through the network.

    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.

  • An External Authentication Configuration Object specifies which authentication protocol and authorization scheme to use, along with any other parameters necessary for LDAP authentication. After an external authentication configuration object is created, multiple App Servers can use the same configuration object.
  • A Distinguished Name (DN) is a sequence of Relative Distinguished Names (RDNs), which are attributes with associated values expressed by the form attribute=value. Each RDN is separated by a comma in a DN. For example, to identify the user, 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 Principal is a unique identity to which Kerberos can assign tickets. For example, in Kerberos, a user is a principal that consists of a user name and a server resource, described as a realm. Each user or service that participates in a Kerberos authentication realm must have a principal defined in the Kerberos database.

    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.

Overview of External Authentication

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.

AuthenticationProtocol AuthenticationScheme AuthorizationScheme Description
kerberos
kerberos-ticket
internal

The user is authenticated by Kerberos and a Kerberos session ticket is used to authenticate the user to access MarkLogic Server.

The user must exist in MarkLogic, where the user's 'external name' matches the Kerberos User Principal.

kerberos
application-level
internal

The user is authenticated by Kerberos and a Kerberos session ticket is used at a time determined by the App Server to authenticate the user to access MarkLogic Server.

The user must exist in MarkLogic, where the user's 'external name' matches the Kerberos User Principal.

kerberos
basic
internal

The user is authenticated by Kerberos. No ticket is exchanged between the client and the App Server. Instead, the username and password are passed. This configuration is used when the client is not capable of ticket exchange and should only be used over SSL connections because the password is communicated as clear text.

The user must exist in MarkLogic, where the user's 'external name' matches the Kerberos User Principal.

kerberos
kerberos-ticket |
application-level | basic
ldap

The user is authenticated by Kerberos and a Kerberos session ticket is used to identify the user to MarkLogic Server. MarkLogic extracts the user ID from the ticket and sends it to the LDAP directory.

MarkLogic uses the information returned by the LDAP directory to create a temporary user with the correct roles to access MarkLogic. The user does not need to exist on MarkLogic.

ldap
application-level | basic
internal
The user is authenticated by LDAP. User must exist in MarkLogic, where the user's 'external name' matches the LDAP Distinguished Name (DN).
ldap
application-level | basic
ldap
The user is authenticated by LDAP and the user's groups are mapped to the MarkLogic roles. The user does not need to exist on MarkLogic. Instead, the LDAP server creates a temporary user with the correct roles to access MarkLogic.

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.

Creating an External Authentication Configuration Object

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.

  1. In the Admin Interface, click the Security icon in the left tree menu.
  2. Click the External Authentication icon.
  3. Click the Create tab at the top of the External Authentication Summary window:

Field Description
external security name
The name used to identify this External Authentication Configuration Object.
description
The description of this External Authentication Configuration Object.
authentication
The authentication protocol to use: ldap or kerberos.
cache timeout
The login cache timeout, in seconds. When the timeout period is exceeded, the LDAP server reauthenticates the user with MarkLogic Server.
authorization
The authorization scheme: internal for authorization by MarkLogic Server or ldap for authorization by an LDAP server.
ldap server uri
If authorization is set to ldap, then enter the URI for the LDAP server.
ldap base
If authorization is set to ldap, then enter the base DN for user lookup.
ldap attribute
If authorization is set to ldap, then enter the name of the attribute used to identify the user on the LDAP server.
ldap default user
The LDAP default user. If you specify an ldap-bind-method of simple, this must be a Distinguished Name (DN). If you specify an ldap-bind-method of MD5, this must be the name of a user registered with the LDAP server.
ldap password
confirm ldap password
The password and confirmation password for the LDAP default user.
ldap bind method

The LDAP bind method to use. This can be either MD5 or simple. MD5 makes use of the DIGEST-MD5 authentication method. If the bind method is simple, then the ldap default user must be a Distinguished Name (DN). If MD5, then the ldap default user must be the name of a valid LDAP user.

When using a bind method of simple, the password is not encrypted, so it is recommended you use secure ldaps (LDAP with SSL).

  1. Click Ok.

Assigning an External Name to a User

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.

  1. Click the Security icon in the left tree menu.
  2. Click the Users icon.
  3. Select a user or create a new one by clicking the Create tab at the top of the User Summary window.
  4. In the User Configuration window, enter the external name for the user in the field in the External Name section. You can associate multiple external names with the user by clicking More External Name.
  5. Click OK.

Assigning an External Name to a Role

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.

  1. Click the Security icon in the left tree menu.
  2. Click the Roles icon.
  3. Select a role or create a new one by clicking the Create tab at the top of the Role Summary window.
  4. In the Role Configuration window, enter the name of the LDAP group to be associated with the role in the field in the External Name section. You can associate multiple LDAP groups with the role by clicking More External Name.
  5. Click OK.

Configuring an App Server for External Authentication

This section describes how to configure an App Server for external authentication.

  1. Click the Groups icon in the left frame.
  2. Click the group in which you want to create or configure the App Server (for example, Default).
  3. Click the App Servers icon on the left tree menu.
  4. Select the Create HTTP tab to create a new App Server, or select an existing App Server from the Summary page.
  5. In the App Server Configuration page, scroll down to the au ten tic at ion section and set the fields, as described in the table below.

    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.

Creating a Kerberos keytab File

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:

Creating a keytab File on Windows

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:

  1. Using Active Directory Domain Services on the Windows server, create a 'user' with the same name as the MarkLogic Server hostname. For example, if the MarkLogic Server is named mysrvr.marklogic.com, create a user with the name mysrvr.marklogic.com.
  2. Create a keytab file with the principal 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
  3. Copy the services.keytab from the Windows server to the MarkLogic data directory on your MarkLogic Server.

Creating a keytab File on Linux

On Linux platforms, the services.keytab file is created as follows:

  1. In a shell window, use kadmin.local to start the Kerberos administration command-line tool.
  2. Use the addprinc command to add the principal to Kerberos.
  3. Use the 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

Example External Authorization Configurations

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:

  • Kerberos Principal: jsmith@MLTEST1.LOCAL
  • LDAP DN: CN=John Smith,CN=Users,DC=MLTEST1,DC=LOCAL
  • LDAP memberOf: 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.

Kerberos User:

  • User name: krbuser1
  • External names: jsmith@MLTEST1.LOCAL

LDAP User:

  • User name: ldapuser1
  • External names: CN=John Smith,CN=Users,DC=MLTEST1,DC=LOCAL

Role:

  • Role name: ldaprole1
  • External names: CN=TestGroup Admin,CN=Users,DC=MLTEST1,DC=LOCAL

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.

AuthenticationProtocol AuthorizationScheme Name Returned
kerberos internal krbuser1
kerberos ldap jsmith@MLTEST1.LOCAL (TEMP user with role ldaprole1)
ldap internal ldapuser1
ldap ldap jsmith (TEMP user with role ldaprole1)

« Previous chapter
Next chapter »
Powered by MarkLogic Server | Terms of Use | Privacy Policy