Knowledgebase:
MarkLogic Certificate based User Authentication
16 February 2021 03:13 PM

Summary

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. Certificate based User Authentication configuration can be achieved using Internal User or External Name based user configurations.

Certificate Authentication: Internal User vs External Name based Authentication:

The difference between Internal User or External Name based authentication lies in the existence of the Certificate CN field based User (demoUser1 in our example) in the MarkLogic Security Database (Internal User) vs if the user retrieved from Certificate Subject field (whole Subject field as DN) is mapped as External Name value in any Existing User.

User Certificate Example:

There are few common steps/examples listed to add to clarity. For our example setup, the certificate presented by the App Server User (demoUser1) will be as 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

In order to allow MarkLogic Server to accept the Certificate presented by a user, MarkLogic Server needs Certificate Authority (CA) to sign the User Certificate installed into MarkLogic. We can install CA Certificate (below) used to sign demoUser1 Cert using Admin GUI->Configure->Security->Certificate Authority Import tab.

$ 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

We can also import above Certificate Authority with xquery call pki:insert-trusted-certificates to load the Trusted CA into MarkLogic.  The sample Query Console code below demonstrates this process. 

(Please ensure this query is executed against the Security database)

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

To enable SSL App Server, we will either

1) Create Certificate Template to utilize Self Signed Certificate.

or, 2) Import pre-signed Certificate Certificate into MarkLogic

In both of the above cases, we will need to import CA used to sign Certificate used by MarkLogic SSL AppServer ro Client Browser/SSL Client.

Importing a Self Signed Certificate Authority into Windows

Once template is created, we will link our Template with our App Server to enable SSL based App Server.

Certificate Authentication: CN as Internal User vs External Name based Internal User

Difference between above two lies in if Certificate CN field User (demoUser1 in our example) exist in MarkLogic Security Database as Internal User -vs- if User retrieved from Certificate Subject field is mapped as External Name to any Existing User.

1.) Certificate Authentication: Certificate CN field value as MarkLogic Security Database Internal User

Steps to configure Certificate based User Authentication for our User demoUser1 as MarkLogic Internal User.

a.) Create User "demoUser1" with necessary roles in MarkLogic Security (Internal User).

DemoUser1_Internal_User.png

b.) On the AppServer page, we will set Authentication schema to "Certificate" with Internal Security to "true". Also, unless you want to have some Users Authenticated as External User as well, you should leave External Security object to "none".

AppServer_Authentication_Certificate.png

c.) AppServer would also select CA that will be used to sign Client/User Certificate as accepted Certificate Authorities (please see section: CA Certificate earlier for our example).

ClientCert_CA.png

Once Configured, accessing above App Server with Browser with User Certificate (demoUser1) installed will be able to log into MarkLogic with internal demoUser1 (Note- We will also need to assign necessary Roles to Internal User to access resource as needed). 

2.) Certificate Authentication: User Certificate Subject field value as External Name for Internal User

Steps to configure Certificate based User Authentication for our User demoUser1 as MarkLogic External Name for Internal User "newUser1".

a.) Create User "newUser1" with necessary roles in MarkLogic Security (Internal User), and Configure User Certificate Subject field as External Name to User.

NewUser1_External_Name.png

b.) Create an External Security object with Certificate based Authentication.

External_Sec_Object.png

c.) On External Security Object Configuration itself, select CA that will be used to sign Client/User Certificate as accepted Certificate Authorities (please see section: CA Certificate earlier for our example).

Please Note - below Configuration is different then configuring Client CA on App Server (required for Internal User).

External_Sec_ClientCert_CA.png

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

AppServer_ExternalSec_Link.png

(2 vote(s))
Helpful
Not helpful

Comments (0)