MarkLogic 9 Product Documentation

Security Guide — Chapter 12

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.

certificate |
application-level
| basic

ldap | saml

certificate |
application-level
| basic

internal

kerberos-ticket

internal

application-level

internal

basic

internal

kerberos-ticket |
application-level
| basic

ldap

certificate |
application-level
| basic

internal

certificate |
application-level
| basic

ldap | saml

saml

saml

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:

   

   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.

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.

   

   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.

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
• Creating a keytab File on Linux

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.

$ 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

$ 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

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>)
)

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.

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:

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:

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.