MarkLogic 9 Product Documentation
Security Guide — Chapter 10

Certificate-based Authentication

Certificate-based user authentication allows users to log into MarkLogic Server without being required to enter user name/password. Certificate-based user authentication configuration can be achieved using either internal user or external name based user configurations.

The main topics are as follows.

User Certificate Example
CA Certificate (User Cert Signer) Import from Admin Interface
CA Certificate Import into MarkLogic from Query Console
Certificate Template & Template CA import into Client (Browser/SSL Client)
Creating a MarkLogic User to use Certificate-based Authentication

User Certificate Example

There are few common steps/examples listed to add to clarity. In this example setup, the certificate presented by the App Server user (demoUser1) will be as follows.

Certificate:
        Data:
            Version: 1 (0x0)
            Serial Number: 7 (0x7)
        Signature Algorithm: sha1WithRSAEncryption
            Issuer: C=US, ST=CA, L=San Carlos, O=MarkLogic Corp., 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=CA, L=San Carlos, O=MarkLogic Corp., 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 Interface

In order 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.

Install a CA certificate used to sign the demoUser1 certificate in the Admin Interface, as follows.

Click the Security icon in the left tree menu.
Click the Certificate Authorities icon on the left tree menu.

Click the Import tab and import a certificate, such as the one shown in the example below.

Example CA certificate:

Certificate:
        Data:
            Version: 3 (0x2)
            Serial Number: 9774683164744115905 (0x87a6a68cc29066c1)
        Signature Algorithm: sha256WithRSAEncryption
            Issuer: C=US, ST=CA, L=San Carlos, O=MarkLogic Corp., 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=CA, L=San Carlos, O=MarkLogic Corp., 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 by using the pki:insert-trusted-certificates function to load the Trusted CA into the Security database in MarkLogic, as shown below.

If using Query Console, make sure this query is executed against the Security database.

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

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

To enable SSL on the App Server, do either of the following.

Create certificate template, as described in Creating a Certificate Template, to utilize Self Signed Certificate.
or.....
Import a signed certificate into MarkLogic, as described in Importing a Signed Certificate into MarkLogic Server.

In both of the above cases, you must import the CA used to sign the certificate used by the MarkLogic SSL App Server into Client Browser/SSL Client, as described in Procedures for Obtaining a Signed Certificate or Importing a Self-Signed Certificate Authority into Windows.

After creating a certificate template, link the template with the App Server and enable SSL on the App Server.

Creating a MarkLogic User to use Certificate-based Authentication

When creating a internal MarkLogic user to use certificate-based authentication, specify the user name as it appears in the CN value of the certificate Subject field (demoUser1 in the example shown in User Certificate Example). When creating an external MarkLogic user to use certificate-based authentication, specify the external name as it appears in the whole certificate Subject field (C=US,ST=CA,L=San Carlos,O=MarkLogic Corp.,OU=Engineering,CN=demoUser1 in the example shown in User Certificate Example).

Creating a MarkLogic User with an Internal Name

To configure certificate-based user authentication for user, demoUser1, as a MarkLogic internal user, do the following in the Admin Interface.

Click the Security icon in the left tree menu.
Click the Users icon.
Click the Create tab. The User Configuration page appears
In the user name field, enter the user name as it appears in the CN value of the certificate Subject field (demoUser1 in the example shown in User Certificate Example)
In the App Server configuration page, set Authentication to Certificate and set Internal Security to true. Unless you want to have the user authenticated as an external user as well, set External Securities to none.
In the App Server configuration page, scroll down to the bottom and select show in the SSL Client Certificate Authorities section.
Select the CA created in CA Certificate (User Cert Signer) Import from Admin Interface to sign the client/user certificate.

Once configured, demoUser1 is now able to access the App Server with a browser that has the user certificate installed, as described in Certificate Template & Template CA import into Client (Browser/SSL Client).

You will also need to assign the necessary roles to demoUser1 to access the needed MarkLogic resources.

Creating a MarkLogic User with an External Name

To configure certificate-based user authentication for user, newUser1, as a MarkLogic user with an external name, do the following in the Admin Interface.

Click the Security icon in the left tree menu.
Click the Users icon.
Click the Create tab. The User Configuration page appears
In the User Name field, enter newUser1.
In the External Name field, enter the entire Subject field from the example shown in User Certificate Example.
Click Security in the left tree menu.
Click External Security.
Click the Create tab at the top of the External Security Summary window:
In the New External Security object window, name the External Security object and select Certificate for Authentication.
Scroll down to the bottom of the External Security object configuration page and select show in the SSL Client Certificate Authorities section.
Select the CA certificate you configured in CA Certificate (User Cert Signer) Import from Admin Interface.
Return to the App Server configuration page and select the External Security object you just created from the External Securities pull-down menu.

MarkLogic 9 Product DocumentationSecurity Guide — Chapter 10

MarkLogic 9 Product Documentation
Security Guide — Chapter 10