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. If none is specified the This default, 389, is used.
  • Base DN This refers to the Base Distinguished Name used by the AD server to look for users.

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

  • OKERA_LDAP_HOST e.g. example.com or 127.0.0.4.
  • OKERA_LDAP_PORT This has a default value of 389 if not set.
  • OKERA_LDAP_BASE_DN Please note: 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 example.com
  • OKERA_LDAP_USE_SSL 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.
  • OKERA_LDAP_DOMAIN 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/env.sh file, the following variables need to be uncommented 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_BASE_DN=your_ad_base_dn

For example, for an LDAP Host at example.com:324, and Base DN of dc=example,dc=com, the LDAP related variables will look like:

# set to enable ldap basic auth
export OKERA_LDAP_HOST=example.com
export OKERA_LDAP_PORT=324
export OKERA_LDAP_BASE_DN=example.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: <LDAP_HOST>:<LDAP_PORT>
LDAP Server Base DN: <base DN in 'dc=x' format>

# assuming your ldap server is at 127.0.0.4:389 and base dn is "example.com"
LDAP configurations initialized
LDAP Server: 127.0.0.4:389
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.