Loading TOC...
Security Guide (PDF)

Security Guide — Chapter 10

External Security

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), Kerberos, or certificate. These external agents serve as centralized points of authentication or repositories for user information from which authorization decisions can be made.

You can configure MarkLogic Server with multiple external security providers. A user only needs to authenticate with one of them to gain access.

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.
  • 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.

  • Certificate Authentication enables HTTPS clients to authenticate themselves to MarkLogic server via a client certificate, either in addition to, or rather than a password.
  • SAML (Security Assertion Markup Language) is an authorization scheme that defines a Principal (such as a user), an Identity Provider (IdP), and a Service Provider (SP). In this scheme, the Principal requests a service from the Service Provider, which accesses the Identity Provider to authorize the Principal. MarkLogic supports SAML, version 2.0.
  • A SAML Entity is an XML document located in the MarkLogic Security database that serves as the SAML Identity Provider.

Overview of External Authentication

MarkLogic Server supports external authentication by means of LDAP, Kerberos or certificate. 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, SAML, or Kerberos for authentication. Once authenticated, the LDAP, Kerberos, or certificate 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 or SAML server, or both internally and externally.

If the App Server is configured for internal authorization, 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, Kerberos or certificate, 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 SAML authorization, the server issues a standard SAML attribute query to the identity provider to retrieve authorization information. The identity provider is uniquely identified by its ID, which is combined with an attribute name and value to form an external name with the necessary privileges.

If the App Server is configured for both internal and external 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 or SAML 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.

Authentication ProtocolAuthentication SchemeAuthorization SchemeDescription
certificate
certificate |
application-level
| basic
ldap | saml
The user is authenticated by a certificate and the user's groups are mapped to the MarkLogic roles. The user does not need to exist on MarkLogic. Instead, the LDAP server or SAML identity provider creates a temporary user with the correct roles to access MarkLogic.
certificate
certificate |
application-level
| basic
internal
The user is authenticated by a certificate. User must exist in MarkLogic.
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
certificate |
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
certificate |
application-level
| basic
ldap | saml
The user is authenticated by LDAP or SAML and the user's groups are mapped to the MarkLogic roles. The user does not need to exist on MarkLogic. Instead, the LDAP server or SAML identity provider 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 Security in the left tree menu.
  2. Click External Security.
  3. Click the Create tab at the top of the External Security Summary window:

FieldDescription
external security nameThe name used to identify this External Security Configuration Object.
descriptionThe description of this External Authentication Configuration Object.
authenticationThe authentication protocol to use: ldap, kerberos or certificate.
cache timeoutThe login cache timeout, in seconds. When the timeout period is exceeded, the LDAP server reauthenticates the user with MarkLogic Server.
authorizationThe authorization scheme: internal for authorization by MarkLogic Server, ldap for authorization by an LDAP server, or saml for authorization by an SAML server.
ldap server uriIf authorization is set to ldap, then enter the URI for the LDAP server. Required if authentication or authorization is ldap.
ldap baseIf authorization is set to ldap, then enter the base DN for user lookup. Required if authentication or authorization is ldap.
ldap attributeIf authorization is set to ldap, then enter the name of the attribute used to identify the user on the LDAP server. Required if authentication or authorization is ldap.
ldap default user

The LDAP default user. Required if authentication is kerberos and authorization is ldap or bind method is simple.

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

ldap password confirm ldap passwordThe password and confirmation password for the LDAP default user. Required if authentication is kerberos and authorization is ldap or bind method is simple.
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).

FieldDescription
saml entity idSAML entity id. Required if authorization is SAML. For details on creating and inserting a SAML entity, see Defining and Inserting a SAML Entity
saml attribute nameOne or more SAML attribute names. Optional when authorization is SAML. These names will be requested as part of the attribute query and mapped as appropriate to internal MarkLogic roles.
saml privilege attribute nameSAML privilege attribute name. Optional when authorization is SAML. If specified, the name will also be requested as part of the attribute query and mapped to MarkLogic privileges.
ssl client certificate authoritiesIf you set SSL Require Client Certificate to true, then select Show and chose with certificate authority is to be used to sign client certificates.
ssl require client certificateSpecifies whether or not a client certificate is required. If you want SSL to require clients to provide a certificate, select true for SSL Require Client Certificate then select Show under SSL Client Certificate Authorities and select which certificate authority is to be used to sign client certificates for the server:
  1. Click Ok.

Defining and Inserting a SAML Entity

SAML authorization is done by means of a SAML entity stored in the MarkLogic Security database.

The SAML 2.0 specification provides a standard format for describing a SAML entity. The SAML specification provides for a variety of elements that can be defined in an entity, but only the AttributeAuthorityDescriptor element is used by MarkLogic. The SAML spec is located at the URL:

http://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf

The SAML entity defines an entityID in the form of a URL. To make use of a SAML entity, specify its entity ID URL in the 'saml entity id' field in the external security configuration, as described in Creating an External Authentication Configuration Object.

MarkLogic only supports the SAML 2.0 SOAP binding over HTTP. If multiple AttributeService elements are specified in the entity, one will be chosen at random. This allows support for multiple hosts in a cluster to be specified when no load balancer is used.

Use the sec:saml-entity-insert function to insert the SAML entity into the MarkLogic Security database. For example, to insert a SAML entity, identified as http://example.com/example, that uses an encoded certificate for authorization, enter:

xquery version "1.0-ml"; 
import module namespace sec = "http://marklogic.com/xdmp/security" 
      at "/MarkLogic/security.xqy";

declare namespace md="urn:oasis:names:tc:SAML:2.0:metadata";
declare namespace ds="http://www.w3.org/2000/09/xmldsig#";

sec:saml-entity-insert(
<md:EntityDescriptor entityID="http://example.com/example"> 
  <md:AttributeAuthorityDescriptor 
    protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor> 
      <ds:KeyInfo> 
        <ds:X509Data> 
          <ds:X509Certificate>
MIID+TCCAeGgAwIBAgIJAImAkE0o79czMA0GCSqGSIb3DQEBCwUAMDwxEjAQBgNV
BAoMCUFjbWUgSW5jLjEmMCQGA1UEAwwdQWNtZSBJbmMuIE9wZXJhdGlvbnMgRGly
ZWN0b3IwHhcNMTcwMTA5MjE0MDE0WhcNMjcwMTA3MjE0MDE0WjA8MRIwEAYDVQQK
DAlBY21lIEluYy4xJjAkBgNVBAMMHU9wc0RpciBNYW5hZ2VkIENsdXN0ZXIgQWNj
ZXNzMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwu4iOujPFrkltDel
XgNl1BO/Xbcu6SEWnGCh3yGMwETqx1PnYDlueRuXIrZAHj8FFoKICJIwsARhcixM
ia2vDH0EkZPFGhb0shf0NEt7glDf1uaUava2x2jNXo5YUuiGDUhES50H3A0HS0Nz
WO0TIMaCu1vCTh5IHnKUnQB2MWrNGeb0I3RxOpqhRp6HarTb1u0mQN1iyiQox+pi
67Wh+eZ1313RTQBv8oavJFKHPT6JQK0rOVDXGDez/VajiUJswFNGZ2MgpVxqCDu3
iA+fdTV3TFp8XGYTPYCQgri5OKC9cGmFXzDgIiXqJLR8iAGbQT8YWsCzTzpYtTVN
JnqN/QIDAQABMA0GCSqGSIb3DQEBCwUAA4ICAQDPgcmLCl4kQFp15cfEKuI0QguC
vlCMjaZDDAr86IUDVJkVfm3Ytkw/QswI4ghZkbPuEhRf4SCo37OSR3++sPmMu5MR
gFtsU/UWGm6xXmIrBl/bkK+wmUwrW3DCcZQLZGOTG4o0tXSX+gGlvip5swpBTf5T
BsxJ3Hu479R48fTMIjoJ2gnVvZQ7aqnDqcZkifEskY6E7v431W1GEgccf0EJggnz
eRcTWfReYNy/foKKFuPW5MFYLd6RHOyWxgqJ3Nvroqu6xegVSQYJloJprZhhHx2H
NLZcBNYcgu2RgWNq9Pdjswxn3P1rRjch9YjgzZyjWywQpX+aASpPT2m0ONDYbkWK
V6YZmZbTmDDmwVfR4SK5GB93oxdZ647SfJwVsqN2qyKEDl/P2qwSY1iN851PhXAh
WMEyHfMgPTP22LHyYfQa+ExN5hpD95az+ZBdx+1CTO/9fJmQXvrmD1bNdbpfeKBD
YIv+yyL3UDtKQcMhp8zumt2XYJNAzSMhLkAMe2P7/i+47f5lXiGtrRuDVPyNzddB
VD2cQvB3JvQ7YRmt6BJPFmtuGSlx65d0fN7D3M8I5xtDa3XkmrrivcgOKi7DRSzE
bUu4cwfg7mWFJFDkWNWtIzqeni8658yLuEEgyFBUeW9OVjR2caTUZcSIObD2yvq7
o1oZlzTJxNplg99CCA==
          </ds:X509Certificate
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:AttributeService
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" 
        Location="https://ML1:8005/SAML2/SOAP/AttributeQuery"/>
  </md:AttributeAuthorityDescriptor>
</md:EntityDescriptor>
)

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 Security in the left tree menu.
  2. Click Users.
  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 Security in the left tree menu.
  2. Click the Roles.
  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 Groups in the left tree menu.
  2. Click the group in which you want to create or configure the App Server (for example, Default).
  3. Click App Servers 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 authentication section and set the fields, as described in the table below.

    FieldDescription
    authentication
    The authentication scheme: basic or application-level for LDAP authentication, kerberos-ticket for Kerberos authentication, or certificate for certificate 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 for 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.

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 ktadd 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
  4. Copy the services.keytab from the Linux Kerberos server to the MarkLogic data directory on your MarkLogic Server.

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.

AuthenticationProtocolAuthorizationSchemeName Returned
kerberosinternal krbuser1
kerberosldapjsmith@MLTEST1.LOCAL (TEMP user with role ldaprole1)
ldapinternalldapuser1
ldapldapjsmith (TEMP user with role ldaprole1)

Kerberos Authentication in xdmp:http-* Functions

Kerberos authentication is supported in xdmp:http-get, xdmp:http-post, xdmp:http-put, and xdmp:http-delete operations be means of the negotiate authentication method option. When negotiate is specified, the username and password are not used. Instead, the server authenticates with the keytab file identified by an environment variable. This effectively does a kinit operation with the keytab file and then starts the MarkLogic server.

To use this feature, you must set the following environment variables:

Environment VariableValue
MARKLOGIC_KEYTABPath to the services.keytab file.
MARKLOGIC_PRINCIPALKerberos Principal.

For example, to authenticate xdmp:http:get for Kerberos, your function would look like the following.

XQuery:

xdmp:http-get("http://atsoi-z620.marklogic.com:8008/ticket.xqy",
<options xmlns="xdmp:http">
    <authentication method="negotiate">
    </authentication>
</options>)

JavaScript:

xdmp.httpGet("http://atsoi-z620.marklogic.com:8008/ticket.xqy",
{ "authentication": { "method" : "negotiate" } })

« Previous chapter
Next chapter »
Powered by MarkLogic Server 7.0-4.1 and rundmc | Terms of Use | Privacy Policy