Loading TOC...
Security Guide (PDF)

MarkLogic Server 11.0 Product Documentation
Security Guide
— Chapter 13

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, SAML, or Certificates.
  • 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 instead of, 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.

    MarkLogic currently only supports SOAP binding only HTTPS.

  • 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, SAML, 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 an LDAP or SAML server for authentication. (For Kerberos, only the username is sent.) Once authenticated, the LDAP, SAML, 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 Protocol Authentication Scheme Authorization Scheme Description
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 MarkLogic server 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 MarkLogic server creates a temporary user with the correct roles to access MarkLogic.
saml
saml
saml
A SAML Identity Provider prompts the user to login, if necessary, and sends the authentication request back to MarkLogic Server.

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.

If the authentication used in an appserver is Kerberos or SAML, only the first external security configuration will be used.

  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:

    Field Description
    external security name The name used to identify this External Security Configuration Object.
    description The description of this External Authentication Configuration Object.
    authentication The authentication protocol to use: certificate, kerberos, ldap, or saml. The configuration details for LDAP and SAML are described below in LDAP Authentication and SAML Authentication.
    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, ldap for authorization by an LDAP server, or saml for authorization by a SAML server.

LDAP Authentication

If you use LDAP authentication, set the fields described in this section.

The MarkLogic SSL App Server can work with SAN or Wild Card certificates. However, the MarkLogic LDAP client will not accept or work with a SAN or Wildcard-based certificate.

Field Description
ldap server uri If authorization is set to ldap, then enter the URI for the LDAP server. Required if authentication or authorization is ldap.
ldap base If authorization is set to ldap, then enter the base DN for user lookup. Required if authentication or authorization is ldap.
ldap attribute If 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 password The 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, simple, or external. 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).

A bind method of external makes use of a certificate to authenticate with the LDAP server. If the bind method is external, ldap-start-tls should be set to true.

ldap memberof attribute The optional ldap attribute for group lookup. If not specified, memberOf is used for search for the groups of a user.
ldap member attribute The optional ldap attribute for group lookup. If not specified, member is used for search for the group of a group.
ldap start tls Whether or not to use start TLS request to the LDAP server. Set to true to use start TLS request. If set to true, the LDAP server URI should start with ldap:// instead of ldaps://.
ldap certificate The PEM encoded X509 certificate for MarkLogic server to connect the LDAP server using mutual authentication. Required if bind method is external. Optional if bind method is MD5 or simple.
ldap private key The PEM encoded private key corresponding to the certificate. Required if bind method is external. Optional if bind method is MD5 or simple.
ldap nested lookup Whether or not to perform nested group lookup.
ldap remove domain Whether or not to remove domain before matching with ldap-attribute.

SAML Authentication

If you use SAML authentication, set the fields described in this section.

Field Description
saml entity id SAML entity id (as a URL). Required if authorization is SAML. For details on creating and inserting a SAML entity, see Defining and Inserting a SAML Entity
saml destination The URL that identifies the Identity Provider to accept the authentication request.
saml issuer The URL that identifies the Service Provider (MarkLogic Server).
saml assertion host The URL that identifies the host making the assertion
saml idp certificate authority The certificate used to validate the signature in the authentication request.
saml sp certificate The certificate used to sign the authentication request.
saml sp private key The private key used to sign the authentication request.
saml attribute name One 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 name SAML 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.

When you have finished configuring MarkLogic Server for external security, 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.

The saml-entity-insert is only needed for SAML authorization without SAML authentication (for example LDAP authentication and SAML authorization). This is not a common use case. The common use case would be SAML authentication and SAML authorization. There is no Admin UI mapping for saml-entity-insert.

You do not need to use saml-entity-insert. To use SAML, you only need create-external-security or to use the Admin UI to configure it.

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.

    Field Description
    authentication
    The authentication scheme: basic or application-level for LDAP authentication, kerberos-ticket for Kerberos authentication, certificate for certificate authentication, or saml for SAML 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. To set additional external authentication configuration objects, click on More External Securities and select an additional configuration object from the pull-down menu.

    If you have configured an App Server with multiple external configuration objects that use LDAP, the LDAP server specified by the first configuration object (the object at the top of the list) is always used first. If this first LDAP server is unresponsive, the second LDAP server will not be tried until the first LDAP server exceeds the time-out period established by cache timeout setting.

    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.

Setting Response Headers for HTTPS-enabled App Servers

App Servers that use HTTPS do not set strict-transport-security in the response header by default. MarkLogic has options to control HSTS (HTTP Strict-Transport-Security) headers.

These options are only effective when the app server is configured with HTTPS.

The max age value can be set for the HSTS response headers. If the max age value for the HSTS is set to 0 (over an HTTPS connection) it immediately expires the Strict-Transport-Security header, allowing access via HTTP. The typical value used for HSTS is one year, expressed as 31536000.

These options can be set in three different ways.

Using the MarkLogic Admin UI

In the Admin UI, click App Servers in the left nav bar. Then click App-Services to open the configuration options. Scroll to the bottom of the screen to the enable hsts header option specify whether to include HSTS header in response if the app server is configured to use HTTPS.

Select true to enable the option. Set the maximum age for the HSTS in the next field. Click ok to enable the HSTS header when you are done.

Using Admin Functions

The Admin functions appserver-get-enable-hsts-header, appserver-get-hsts-header-max-age, appserver-set-enable-hsts-header, and appserver-set-hsts-header-max-age can be used to enable and configure HSTS headers.

Use appserver-get-enable-hsts-header to get information about the HSTS header.

xquery version "1.0-ml";

import module namespace admin = "http://marklogic.com/xdmp/admin"
    at "/MarkLogic/admin.xqy";

let $config := admin:get-configuration()
let $groupid := admin:group-get-id($config, "Default")
return
admin:appserver-get-enable-hsts-header($config,
    admin:appserver-get-id($config, $groupid, "test"))

Use appserver-get-hsts-header-max-age to get information about the current HSTS header max age amount.

xquery version "1.0-ml";

import module namespace admin = "http://marklogic.com/xdmp/admin"
  at "/MarkLogic/admin.xqy";

let $config := admin:get-configuration()
let $groupid := admin:group-get-id($config, "Default")
return
admin:appserver-get-hsts-header-max-age($config,
  admin:appserver-get-id($config, $groupid, "test"))

Use appserver-set-enable-hsts-header to enable HSTS header.

xquery version "1.0-ml";

import module namespace admin = "http://marklogic.com/xdmp/admin"
  at "/MarkLogic/admin.xqy";

let $config := admin:get-configuration()
let $groupid := admin:group-get-id($config, "Default")
return
admin:appserver-set-enable-hsts-header($config,
  admin:appserver-get-id($config, $groupid, "test"),true())

Use appserver-set-hsts-header-max-age to set the HSTS max age amount.

xquery version "1.0-ml";

import module namespace admin = "http://marklogic.com/xdmp/admin"
  at "/MarkLogic/admin.xqy";

let $config := admin:get-configuration()
let $groupid := admin:group-get-id($config, "Default")
return
admin:appserver-set-hsts-header-max-age($config,
  admin:appserver-get-id($config, $groupid, "test"),31536000)

The max age amount is being set to 31536000 or one year.

Using REST APIs

These REST APIs can be used to set HSTS headers.

This REST call will get the current properties.

curl -X GET --digest -u admin:admin \
"http://localhost:8002/manage/v2/servers/test/properties?group-id=Default"

This REST call enables the HSTS header and sets the HSTS max age.

curl -X PUT --digest -u admin:admin -H "Content-type: application/json"\
-d '{"enable-hsts-header":true, "hsts-header-max-age":31536000}'\
"http://localhost:8002/manage/v2/servers/test/properties?group-id=Default"

The max age amount is being set to 31536000 or one year.

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.

External Certificate User Authentication

MarkLogic 9 includes certificate-based user authentication, which allows users to log into MarkLogic Server without being required to enter a user name/password. Previously certificates were only utilized to restrict client access to MarkLogic Server with the Digest/Basic User Authentication Scheme. Certificate-based user authentication configuration can be achieved based user configurations using either an internal user or external name.

Certificate Authentication Based on Internal User vs External Name

The difference between authentication based on an internal user or external name lies in the existence of the Certificate CN field-based user (demoUser1 in the following example) in the MarkLogic Security Database (internal user) versus if the user retrieved from Certificate Subject field (the whole Subject field as DN) is mapped as external name value in any existing user.

User Certificate Examples

Here are a few common examples, shown for clarity.

For the examples, the certificate presented by the App Server User (demoUser1) is the following.

$ openssl x509 -in UserCert.pem -text -noout
    Certificate:
        Data:
            Version: 1 (0x0)
            Serial Number: 7 (0x7)
        Signature Algorithm: sha1WithRSAEncryption
            Issuer: C=US, ST=NY, L=New York, O=MarkLogic Corporation, OU=Engineering, CN=MarkLogic DemoCA
            Validity
                Not Before: Jul 11 02:58:24 2017 GMT
                Not After : Aug 27 02:58:24 2019 GMT
            Subject: C=US, ST=NJ, L=Princeton, O=MarkLogic Corporation, OU=Engineering, CN=demoUser1
            Subject Public Key Info:
                Public Key Algorithm: rsaEncryption
                    Public-Key: (1024 bit)
                    Modulus:
                        .....................
                    Exponent: 65537 (0x10001)
        Signature Algorithm: sha1WithRSAEncryption

CA Certificate (User Cert Signer) Import from Admin GUI

To allow MarkLogic Server to accept the certificate presented by a user, MarkLogic Server needs a Certificate Authority (CA) to sign the user certificate installed into MarkLogic. You can install a CA Certificate (below) to be used to sign demoUser1 Cert through the Admin UI.

Click Configure in the left tree menu of the Admin UI, then click Security to expand the options. Click Certificate Authorities, and then click the Import tab.

Paste this text for the trusted certificate into the field:

$ openssl x509 -in CACert.pem -text -noout
    Certificate:
        Data:
            Version: 3 (0x2)
            Serial Number: 9774683164744115905 (0x87a6a68cc29066c1)
        Signature Algorithm: sha256WithRSAEncryption
            Issuer: C=US, ST=NY, L=New York, O=MarkLogic Corporation, OU=Engineering, CN=MarkLogic DemoCA
            Validity
                Not Before: Jul 11 02:53:18 2017 GMT
                Not After : Jul  6 02:53:18 2037 GMT
            Subject: C=US, ST=NY, L=New York, O=MarkLogic Corporation, OU=Engineering, CN=MarkLogic DemoCA
            Subject Public Key Info:
                Public Key Algorithm: rsaEncryption
                    Public-Key: (4096 bit)
                    Modulus:
                       ......................
                    Exponent: 65537 (0x10001)
            X509v3 extensions:
                X509v3 Subject Key Identifier:
                    D9:45:B9:9A:DC:93:7B:DB:47:07:C6:96:63:57:13:A7:A8:F1:D0:C8
                X509v3 Authority Key Identifier:
                    keyid:D9:45:B9:9A:DC:93:7B:DB:47:07:C6:96:63:57:13:A7:A8:F1:D0:C8
                X509v3 Basic Constraints: critical
                    CA:TRUE
                X509v3 Key Usage: critical
                    Digital Signature, Certificate Sign, CRL Sign
        Signature Algorithm: sha256WithRSAEncryption

CA Certificate Import into MarkLogic from Query Console

You can also import the Certificate Authority using an XQuery call (pki:insert-trusted-certificates) to load the Trusted CA into MarkLogic.

This sample Query Console code demonstrates this process.

xquery version "1.0-ml";
import module namespace pki = "http://marklogic.com/xdmp/pki" 
  at "/MarkLogic/pki.xqy";
 
pki:insert-trusted-certificates(
  xdmp:document-get("/OurCertificateLocation/DemoLabCA.pem",
  <options xmlns="xdmp:document-get">
    <format>text</format>
  </options>)
)

Be sure that this query is executed against the Security database. (The query is Import_Trusted_CA.xqy hosted by GitHub.)

Certificate Template & Template CA import into Client (Browser/SSL Client)

To enable the SSL App Server, you can either:

  • Create a Certificate Template to utilize a Self-Signed Certificate.

or

  • Import a pre-signed Certificate into MarkLogic.

In both of the above cases, you will need to import the Certificate Authority used to sign the certificate used by MarkLogic SSL AppServer into Client Browser/SSL. For example:

  • Importing a Self Signed Certificate Authority into Windows

Once template is created, you can link your Template with your App Server to enable the SSL-based App Server.

Certificate CN as Internal User vs External Name-based Internal User

Difference between the two options lies in if the Certificate CN field User (demoUser1 in our example) exists in MarkLogic Security Database as an internal user verses if the user retrieved from the Certificate Subject field is mapped as an external name to any existing user.

1.) Certificate CN Field Value as MarkLogic Security Database Internal User

Follow these steps to configure Certificate-based User Authentication for the user (demoUser1) as a MarkLogic internal user.

  1. Create the user demoUser1 with the necessary roles in the MarkLogic Security database (Internal User).

  2. On the AppServer page, set the authentication schema to Certificate with Internal Security to set to true. Unless you want to have some users authenticated as an External User as well, leave External Security object to none.

  3. The AppServer will also select the CA that will be used to sign Client/User Certificate as accepted Certificate Authorities (See section CA Certificate earlier for example).

Once configured, accessing the App Server with a browser the has the User Certificate (demoUser1) installed will be able to log into MarkLogic with the internal demoUser1.

You will also need to assign the necessary roles to the internal user to be able to access resources as needed.

User Certificate Subject Field Value as External Name for Internal User

Follow these steps to configure certificate-based user authentication for demoUser1 as a MarkLogic external name for the internal user newUser1.

  1. Create a user named newUser1 with the necessary roles in MarkLogic Security database (Internal User), and configure the User Certificate Subject field as External Name to User.

  2. Create an external security object with certificate-based authentication.

  3. For External Name (Cert Subject field) based linkage to Internal User, the App Server needs to point to our External Security Object.

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)

Kerberos Authentication using xdmp:http-* Functions

Kerberos authentication is supported by the xdmp:http-get, xdmp:http-post, xdmp:http-put, and xdmp:http-delete functions with the negotiate authentication 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 Variable Value
MARKLOGIC_KEYTAB Path to the Kerberos client keytab file.
MARKLOGIC_PRINCIPAL Kerberos 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" } })

The xdmp:http-get, xdmp:http-post, xdmp:http-put, and xdmp:http-delete functions include a kerberos-ticket-forwarding option to enable the use of a user credential instead of MARKLOGIC_PRINCIPAL.

For example, to forward the ticket (if the user ticket is forwardable), do the following.

XQuery:

xdmp:http-get(http://myhost.com:8005/index.xqy, 
  <options xmlns="xdmp:http"> 
    <authentication method="negotiate"> 
    </authentication> 
    <kerberos-ticket-forwarding>{optional} 
    </kerberos-ticket-forwarding> 
  </options>) 

JavaScript:

xdmp:httpGet(http://myhost.com:8005/index.xqy, 
  { 
    "authentication": {"method" : "negotiate"}, 
    "kerberosTicketForwarding": optional 
  }) 

The xdmp:http-get, xdmp:http-post, xdmp:http-put, and xdmp:http-delete functions also have a proxy option to support proxy and proxy tunneling. When an HTTP or HTTPS request is sent to proxy server, the proxy server will forward the request to the destination.

For example, to forward requests to a proxy server, named http://proxy.marklogic.com:8080, do the following.

XQuery:

xdmp:http-get("http://targethost.marklogic.com/index.html",
  <options xmlns="xdmp:http">
    <proxy>http://proxy.marklogic.com:8080</proxy>
  </options>)

JavaScript:

xdmp.httpGet("http://targethost.marklogic.com/index.html", 
   {proxy:"http://proxy.marklogic.com:8080"}) 

Kerberos Authentication for Secured HDFS

MarkLogic can use Kerberos Secured HDFS as a file system on Linux platforms. MarkLogic Server acts as a client to Kerberos Secured HDFS and should have its own unique identity, so the credentials provided to MarkLogic Server should be different from the Kerberos credentials of other MarkLogic client applications.

MarkLogic Server accesses Kerberos Secured HDFS using the keytab file and principal. To configure Kerberos authentication to Secured HDFS, set the following environment variables in your /etc/marklogic.conf file:

Environment Variable Value
MARKLOGIC_KEYTAB Path to the Kerberos client keytab file.
MARKLOGIC_PRINCIPAL Kerberos Principal to be authenticated.

When using rolling upgrades, deploy your credential keytab files after the cluster has been fully upgraded to MarkLogic Server 9. Otherwise the behavior of accessing secure HDFS will be undefined.

« Previous chapter
Next chapter »