MarkLogic Certificate based Authentication with LDAP Authorization
20 July 2017 09:57 AM


MarkLogic 9 introduces Certificate based User Authentication, which allows users to Log into MarkLogic Server without being required to enter user name/password. In previous versions, Certificates were only utilized to restrict client access to MarkLogic Server with the Digest/Basic User Authentication Scheme. In addition to Certificate based User Authentication using Internal user and External name verification MarkLogic 9 also permits authenticating and authorizing user certificates against an LDAP or Active Directory database to permit access based on MarkLogic Roles and LDAP Group membership. By using this method of authentication and authorization a site is able to maintain all users access externally without the need to manage a separate set of users within the MarkLogic security database.

This document will expand on the concepts and configuration examples described in the associated "MarkLogic Certificate based User Authentication" knowledge base article and will show the additional steps required to configure MarkLogic to authorize a User certificate against an LDAP or Active Directory. It is highly recommended that you make yourself familiar with the previous article as it covers in more detail the steps required to setup the MarkLogic App Server to ensure that TLS Client Authentication is configured correctly to request and verify the certificates that may be presented by the user.

Creating the External Security definition

To authorize users presenting a certificate you should first create a new External Security definition selecting “Certificate” for authentication and LDAP for authorization.


Next, configure the LDAP server entry.



  • Unlike standard user authorization when MarkLogic searches for the user certificate, MarkLogic uses a base Object search using the full certificate distinguished name rather than a sub-tree search off the “ldap base”. MarkLogic UI currently requires an entry for the “ldap base”; Even though it is not used, as such you will need to code a dummy value to satisfy UI verification.
  • When performing the LDAP search, MarkLogic will request the “ldap attribute” value to use when creating the temporary userid. Care should be taken when selecting this value to ensure that the value is unique for all possible Certificate DN’s that may be presented.
  • Ensure that the “ldap default user” has the required permissions to search for the Certificate within the LDAP or Active Directory server and return the required attributes.
  • MarkLogic uses the “memberOf” and “member” attributes to return Group and Group of Group membership, if your LDAP or Active Directory server using different attributes such as “isMemberOf” you can override them in the “memberOf” and “member” attribute fields. 

Configuring the App Server

Configure the App Server to use “certificate” authentication, set “Internal Security” to false and select the external security definition created above.


Enable TLS Client Authentication and configure the SSL Client Certificate authorities that you will accept to sign the user certificates. Any certificates presented that is not signed by one of the specified CA’s will be rejected.



For more details on configuring the CA certificates required for certificate based authentication please from to the knowledge base article "MarkLogic Certificate based User Authentication". 

Configure MarkLogic Security Roles

For each role specify one or more external names that match the “memberOf” attribute returned for the Certificate DN.

To confirm that users are being authorized to the MarkLogic AppServer correctly, connect using your browser or command line tool such as “cUrl”.

MacPro-4505:~ $ curl -k --cert ./mluser1.p12:password https://localhost:8013
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">
<html xml:lang="en" xmlns="">
<title>Welcome to the MarkLogic Test page.</title>
<body><p>This application is running on MarkLogic Server version 9.0-1.1</p></body>

Within the AppServer AccessLog, you should see a mapping for a new temporary userid to the expected role.

External User(mluser1) is Mapped to Temp User(mluser1) with Role(s): mladmin
::1 - mluser1 [18/Jul/2017:16:07:05 +0100] "GET / HTTP/1.1" 200 347 - "curl/7.51.0"


If a user is not able to connect using their certificate, the first thing to check is if the Certificate Distinguished Name (DN) can be found in the LDAP or Active Directory database and if it contains the required userid and memberOf attributes.

Using a tool such as OpenSSL determine the correct Subject Certificate DN, e.g.

MacPro-4505:~ $ openssl x509 -in mluser1.pem -text
Version: 3 (0x2)
Serial Number: 1497030421 (0x593adf15)
Signature Algorithm: sha256WithRSAEncryption
Issuer: CN=User Signing Authority, O=MarkLogic, OU=Support
Not Before: Jun 9 17:47:13 2017 GMT
Not After : Jun 9 17:47:13 2018 GMT
Subject: CN=mluser1, OU=Users, DC=MarkLogic, DC=Local
Next using an LDAP lookup tool such as “ldapsearch” or "ldp.exe" on Microsoft Windows, perform a base Object search for the Certificate DN requesting the LDAP user and memberOf attribute (with the entries matching your LDAP External Security settings).

If either the userid or memberOf attributes are missing access will be denied.

MacPro-4505:~ $ ldapsearch -H ldap:// -x -D "cn=manager,dc=marklogic,dc=local" -W -s base -b "cn=mluser1,ou=Users,dc=MarkLogic,dc=Local" "memberOf" "cn"
# extended LDIF
# LDAPv3
# base <cn=mluser1,ou=Users,dc=MarkLogic,dc=Local> with scope baseObject
# filter: (objectclass=*)
# requesting: memberOf uid
# mluser1, Users, MarkLogic.Local
dn: cn=mluser1,ou=Users,dc=MarkLogic,dc=Local
uid: mluser1
memberOf: cn=AppAdmin,ou=Groups,dc=MarkLogic,dc=Local
# search result
search: 2
result: 0 Success
If MarkLogic is able successfully to locate the certificate and return the required attributes, then check if the external names in the security role matches (case-sensitive) the “memberOf” attribute returned by the LDAP search.

The following XQuery can be used to show all the external names assigned to a specific role. 

(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace sec = ""
    at "/MarkLogic/security.xqy";



If MarkLogic is still not able to authenticate users, it is very useful to use a packet capture tool such as Wireshark to check - if MarkLogic is able to contact the LDAP or Active Directory server and is receiving the expected successful Admin bind and Search for the Certificate DN.

The following example trace shows a successful BIND using the LDAP Default user followed by a successful search for the Certificate DN.


Further Reading

(0 vote(s))
Not helpful

Comments (0)