Integrating MarkLogic with Okta identity management and Microsoft Windows Active Directory using the Okta AD Agent
25 April 2018 08:51 AM


Okta provides secure identity management and single sign-on to any application, whether in the cloud, on-premises or on a mobile device.

The following procedure describes the procedure required to integrate MarkLogic with Okta identity management and Microsoft Windows Active Directory using the Okta AD Agent.

This document assumes that the users accessing MarkLogic are defined in the Windows Active Directory only and do not currently have Okta User Profiles defined.

Authentication Flow

 The authentication flow in this scenario will be as follows:

  1. The user opens a Browser connection to the Site Single Sign-On Portal page.
  2. The user enters their Active Directory credentials
  3. Okta verifies the user credentials using the Okta LDAP Agent
  4. If successful, the user is presented with a selection of applications they can sign-on to.
  5. The user selects the required application and Okta completes the sign-on using the stored user credentials.


• MarkLogic Server version 8 or 9
• Okta Admin account access
• Okta AD Agent
• Active Directory Server

For the purpose of this document the following Active Directory user entry will be used as an example:

# LDAPv3
# base <dc=MarkLogic,dc=Local> with scope subtree
# filter: (sAMAccountName=martin.warnes)
# requesting: *

# Martin Warnes, Users, marklogic.local
dn: CN=Martin Warnes,CN=Users,DC=marklogic,DC=local
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: user
cn: Martin Warnes
sn: Warnes
givenName: Martin
distinguishedName: CN=Martin Warnes,CN=Users,DC=marklogic,DC=local
sAMAccountName: martin.warnes
memberOf: CN=mladmins,CN=Users,DC=marklogic,DC=local
sAMAccountType: 805306368
userPrincipalName: martin.warnes@marklogic.local


  1. By default, Okta uses the email address as the username, however, MarkLogic usernames cannot contain certain special characters such as the @ symbol so the sAMAccountName will be used to sign-on on to MarkLogic. This will be configured later during the Okta Application definition.
  2. One or more memberOf attributes should be assigned to the Active Directory user entry and these will be used to assign MarkLogic Roles without requiring the need to configure duplicate user entries in the MarkLogic security database.

Step 1. Create a MarkLogic External Security definition

 An External Security definition is required to authenticate and authorize Okta users against a Microsoft Windows Active Directory server.

 Full details on configuring an external security definition can be found at:

 You should ensure that both “authentication” and “authorization” are set to “ldap”, for details on the remaining settings you should consult your Active Directory administrator.

Step 2. Assign Active Directory group membership to MarkLogic Roles

In order to assign the correct Roles and Permission to Okta users, you will need to map Active Directory memberOf attributes to MarkLogic rolls.

In my example Active Directory user entry martin.warnes belongs to the following Group:

 memberOf: CN=mladmins,CN=Users,DC=marklogic,DC=local

To ensure that all members of this Group are assigned MarkLogic Admin roles you simply need to add the memberOf attribute value as an external name in the admin role as below:

Step 3. Configure the MarkLogic AppServer

For each App Server that you wish to integrate with Okta, you will need to set the “authentication” to “basic” and select the “external security” definition.

As HTTP Basic Authentication is considered insecure it is highly recommended that you secure the AppServer connection using HTTPS by configuring and selecting a “SSL certificate template”.

 Further details on configuring SSL for AppServers can be found at:

Step 4. Install and Configure Okta AD Integration

In order for Okta to authenticate your Active Directory users, you will first need to download and install the Okta AD Agent using the following instructions supplied by Okta

 Once installed your Okta Administrator will be able to complete the AD Agent configuration to select which AD users to import into Okta.

Step 5. Create Okta MarkLogic application

From the Okta Administrator select “Add Application”, search for the Basic Authentication template and click “Add

On the “General Settings” tab, enter the MarkLogic AppServer URL, ensure to use HTTP or HTTPS depending on whether you have chosen to secure the listening port using TLS.

 Check the “Browser plugin auto-submit” option.

On the Sign-On options panel select “Administrator sets username, password is the same as user’s Okta password

 For “Application username format” select “AD SAM Account name” from the drop-down selection.

Once the Okta application is created you should assign the users permitted to access the application

When assigning a user, you will be prompted to check the AD Credentials, at this point you should just check that Okta has selected the correct "sAMAccountName" value, the password will not be modifiable.

Repeat Step 5. for each AppServer you wish to access via the Okta SSO portal.

Step 6. Sign-on to Okta SSO Portal

All assigned MarkLogic applications should be shown:

Selecting one of the MarkLogic applications should automatically log you in using your AD Credentials stored within Okta.

Additional Reading

(0 vote(s))
Not helpful

Comments (0)