Secure Okera REST API Access Using LDAP

Okera now supports LDAP Basic Authentication. This document explains how to allow Okera users to authenticate using their Active Directory credentials using Basic authentication.

LDAP Basic Authentication

In this section we will cover:

Prerequisites to enable LDAP Basic authentication on Okera

You will need the following pieces of information for ODAS to support LDAP:

  • Hostname - This must be the IP address or the hostname of the Active Directory server instance you are using.

  • Port Number - This is the port number on which the Active Directory instance is listening. This defaults to the SSL enabled LDAP port which is 636.

  • Base DN/Bind Template - One of these need to be specified to construct the bind string against the LDAP server. See below for details.

To enable LDAP Basic authentication for ODAS access, set the following environment variables in your /etc/okera/ file:


    For example, or


    This has a default value of 636 if not set.


    By default, Okera assumes the LDAP server has SSL enabled. We recommend this for all production configurations in which case this config does not need to be specified. For test deployments, this can be set to false if the LDAP server does not have SSL enabled.


    Template of the bind string when authenticating a user. Each bind template should contain a single ā€˜%sā€™, which is substituted with the user name trying to authenticate. For example, a bind template of cn=%s,ou=ca,dc=domain,dc=com with the user Alice trying to authenticate, the resulting binding string for the LDAP server would be: cn=Alice,ou=ca,dc=domain,dc=com.

    Multiple bind strings can be specified separated by ;. In this case, ODAS will try each bind string in order, authenticating the user on the first successful bind. For example, if this config was set to: cn=%s,ou=ca,dc=domain,dc=com;cn=%s,ou=wa,dc=domain,dc=com, again with the user being Alice, ODAS will try binding with: cn=Alice,ou=ca,dc=domain,dc=com and if unsuccessful, try with cn=Alice,ou=wa,dc=domain,dc=com. The user can authenticate if any of the binds succeeded and ODAS will not try the subsequent templates.

    Note: This value cannot be set if either OKERA_LDAP_BASE_DN or OKERA_LDAP_DOMAIN is set.


    Okera accepts the base DN in a particular notation as described here: If your base DN is of the format dc=example,dc=com, the value to be passed in should be


    This is the default domain for users. For example, if set to ALL USERS and a user tries to log in with their username, userid, Okera will authenticate (i.e. bind) with the LDAP server using ALL USERS\\userid. If a domain is explicitly specified when logging in, Okera will ignore this value. For example, in the same identical configuration, if the user explicitly logged in as TEST DOMAIN\\userid, then we will authenticate with LDAP using exactly that login. By default, this is not set and there is no default domain. If this is set, OKERA_LDAP_BASE_DN should not be set.

For clarity, in your /etc/okera/ file, the following variables need to be commented out and set:

# set to enable ldap basic auth
# export OKERA_LDAP_HOST=your_ad_hostname
# export OKERA_LDAP_PORT_ldap_port=your_ad_port
# export OKERA_LDAP_BIND_TEMPLATE=your_bind_template

For example, for an LDAP Host at, and a bind template DN of cn=%s,ou=ca,dc=example,dc=com, the LDAP related variables will look like:

# set to enable ldap basic auth
export OKERA_LDAP_PORT=324
export OKERA_LDAP_BIND_TEMPLATE=cn=%s,ou=ca,dc=example,dc=com

Verify LDAP Basic authentication using curl

Before we begin this section, make sure you have a set of LDAP credentials that you intend to use for authentication:

  • Check the LDAP connection using CURL:

    The following curl command should return the authenticated client name

      $ curl <ODAS_REST_SERVER>/api/health-authenticated -u <AD_USERNAME>
      Enter host password for user '<AD_USERNAME>':
        "health": "ok",
        "token": null,
        "user": "<AD_USERNAME>"
      # An example for REST server running at localhost:5000, and AD username
      # "testuser" is as follows
      $ curl localhost:5000/api/health-authenticated -u testuser
      Enter host password for user 'testuser':
        "health": "ok",
        "token": null,
        "user": "testuser"
  • Authenticate user and get token using CURL:

    The following curl command should return an Okera token on successful authentication

      $ curl -X POST <ODAS_REST_SERVER>/api/get-token -u <AD_USERNAME>
      Enter host password for user '<AD_USERNAME>':
        "token": "<Token>"
      # An example for REST server running at localhost:5000, and AD username
      # "testuser" is as follows
      $ curl -X POST localhost:5000/api/get-token -u testuser
      Enter host password for user 'testuser':
        "token": "AAdzYXVyYWJoAAdzYXVyYWJoigFcIb5C_IoBXEXKxvwBAg$$.xvm3yXp3_CZX377y0BqFVBmjKIY$"

Use Okera Portal to authenticate and get an Okera token

It is now possible to get an Okera token using the Okera Web UI. Point your browser to the login page in the Web UI and enter your credentials.

To verify if the LDAP related values are set as intended, and for LDAP related debugging, look for the following logs in your REST service. You should see the following lines in your REST server logs:

# the general format of expected logs
LDAP configurations initialized
LDAP Server Base DN: <base DN in 'dc=x' format>

# assuming your ldap server is at and base dn is ""
LDAP configurations initialized
LDAP Server:
LDAP Server Base DN: dc=example,dc=com

If the above lines are not present, your REST service did not start with LDAP Basic authentication enabled.