Basic Authentication: LDAP Policy

Policy Name

Basic Authentication: LDAP

Summary

Allows access based on the basic authorization mechanism, with user-password defined on LDAP

Category

Security

First Omni Gateway version available

v1.1.0

Release Notes

Basic Authentication: LDAP

Returned Status Codes

401 - Unauthorized or invalid client application credentials

Summary

The Lightweight Directory Access Protocol (LDAP) authentication policy specifies how to restrict access to an API using LDAP authentication mechanism.

When an error is encountered, the Basic Authentication - LDAP policy returns an "WWW-Authenticate" HTTP header field using the format:`WWW-Authenticate: Basic realm="mule-realm"`.

LDAP is an inverted tree, and each leaf has a username-password pair and associated metadata. Each level is like a tree branch. For more information about LDAP, see About LDAP.

Configuring Policy Parameters

Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

- policyRef:
    name: ldap-authentication-flex
  config:
    ldapServerURL: <string> // OPTIONAL, default: "ldap://127.0.0.1:389"
    authorizationOrigin: <string> // OPTIONAL, default: "httpBasicAuthenticationHeader"
    authorizationExpression: <string> // REQUIRED when authorizationOrigin is "customExpression"
    ldapServerUserDn: <string> // REQUIRED
    ldapServerUserPassword: <string> // REQUIRED
    ldapSearchBase: <string> // REQUIRED
    ldapSearchFilter: <string> // OPTIONAL, default: "(uid={0})"
    ldapSearchInSubtree: <bool> // OPTIONAL, default: false

Parameter Required or Optional Default Value Description

Parameter	Required or Optional	Default Value	Description
`ldapServerURL`	Optional	`ldap://127.0.0.1:389`	Address and port of the location to the LDAP server
`authorizationOrigin`	Optional	`httpBasicAuthenticationHeader`	Origin of the Authorization token. Use `httpBasicAuthenticationHeader` to read credentials from the HTTP Basic Authentication header, or `customExpression` to extract the token using a DataWeave expression.
`authorizationExpression`	Required when `authorizationOrigin` is `customExpression`	`#[attributes.headers['token']]`	DataWeave expression to extract the Authorization token from API requests. Only applicable when `authorizationOrigin` is `customExpression`.
`ldapServerUserDn`	Required		The name of the user or user group with access to traverse and list users of LDAP
`ldapServerUserPassword`	Required		The password for the user or usergroup
`ldapSearchBase`	Required		The place where the LDAP search begins
`ldapSearchFilter`	Required		The criteria for the filter for the Active Directory or the OpenLDAP model
`ldapSearchInSubtree`	Optional	`false`	Whether to examine the subtree below the base DN and include the base DN level. Performance will be affected by this. Otherwise, the one-level scope will be used, examining only the level immediately below the base DN

ldapServerURL

Optional

ldap://127.0.0.1:389

Address and port of the location to the LDAP server

authorizationOrigin

Optional

httpBasicAuthenticationHeader

Origin of the Authorization token. Use httpBasicAuthenticationHeader to read credentials from the HTTP Basic Authentication header, or customExpression to extract the token using a DataWeave expression.

authorizationExpression

Required when authorizationOrigin is customExpression

#[attributes.headers['token']]

DataWeave expression to extract the Authorization token from API requests. Only applicable when authorizationOrigin is customExpression.

ldapServerUserDn

Required

The name of the user or user group with access to traverse and list users of LDAP

ldapServerUserPassword

Required

The password for the user or usergroup

ldapSearchBase

Required

The place where the LDAP search begins

ldapSearchFilter

Required

The criteria for the filter for the Active Directory or the OpenLDAP model

ldapSearchInSubtree

Optional

false

Whether to examine the subtree below the base DN and include the base DN level. Performance will be affected by this. Otherwise, the one-level scope will be used, examining only the level immediately below the base DN

Resource Configuration Example

- policyRef:
    name: ldap-authentication-flex
  config:
    ldapServerURL: "ldap://localhost:389"
    authorizationOrigin: "httpBasicAuthenticationHeader"
    authorizationExpression: "#[attributes.headers['Authorization']]"
    ldapServerUserDn: "cn=admin,dc=example,dc=org"
    ldapServerUserPassword: "admin"
    ldapSearchBase: "dc=example,dc=org"
    ldapSearchFilter: "(uid={0})"
    ldapSearchInSubtree: true

Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

Parameter	Description
LDAP Server URL	The URL of your LDAP OR LDAPS server, including the port number.
Authorization token origin	Origin of the Authorization token: HTTP Basic Authentication Header or Custom Expression.
Token Expression	DataWeave expression used to extract the Authorization from API requests. Shown when Authorization token origin is Custom Expression.
LDAP User DN	The name of the user or user group with access to traverse and list users of LDAP.
LDAP User Password	The password for the user or user group. The password must be a secure value that, once specified, is not visible or retrievable.
LDAP Search Base	The starting point for the search in the directory tree.
LDAP Search Filter	The criteria for the filter for the Active Directory or the OpenLDAP model, as shown in the examples.

Parameter

Description

LDAP Server URL

The URL of your LDAP OR LDAPS server, including the port number.

Authorization token origin

Origin of the Authorization token: HTTP Basic Authentication Header or Custom Expression.

Token Expression

DataWeave expression used to extract the Authorization from API requests. Shown when Authorization token origin is Custom Expression.

LDAP User DN

The name of the user or user group with access to traverse and list users of LDAP.

LDAP User Password

The password for the user or user group. The password must be a secure value that, once specified, is not visible or retrievable.

LDAP Search Base

The starting point for the search in the directory tree.

LDAP Search Filter

The criteria for the filter for the Active Directory or the OpenLDAP model, as shown in the examples.

All parameters are required to successfully configure LDAP or Active Directory.

Example Configuration for an Active Directory

You can configure Active Directory for your LDAP authentication by providing the following values:

Field	Example Literal String Value	Example Secure Property Placeholder
LDAP Server URL	ldap://174.19.33.17:389/	${ldap.server.url}
LDAP Secure Server URL (SSL)	ldaps://my-company-ldap.cloudhub.io:1010/	${ldap.server.url}
LDAP Server User DN	CN=Administrator,CN=Users,DC=my-company,DC=com	${ldap.user.dn}
LDAP User Password	somePassword	${ldap.password}
LDAP Search Base	CN=Users,DC=my-company,DC=com	${ldap.search.base}
LDAP Search Filter	(sAMAccountName={0})	${ldap.search.filter}

Field

Example Literal String Value

Example Secure Property Placeholder

LDAP Server URL

ldap://174.19.33.17:389/

${ldap.server.url}

LDAP Secure Server URL (SSL)

ldaps://my-company-ldap.cloudhub.io:1010/

${ldap.server.url}

LDAP Server User DN

CN=Administrator,CN=Users,DC=my-company,DC=com

${ldap.user.dn}

LDAP User Password

somePassword

${ldap.password}

LDAP Search Base

CN=Users,DC=my-company,DC=com

${ldap.search.base}

LDAP Search Filter

(sAMAccountName={0})

${ldap.search.filter}

The search filter string in the example is specific to Active Directory applications.

Example Configuration for OpenLDAP

You can configure OpenLDAP for your LDAP authentication by providing the following values:

Field	Example Literal String Value	Example Secure Property Placeholder
LDAP Server URL	ldap://174.19.33.17:389/	${ldap.server.url}
LDAP Secure Server URL (SSL)	ldaps://my-company-ldap.cloudhub.io:1010/	${ldap.server.url}
LDAP Server User DN	cn=Manager,dc=my-company,dc=com	${ldap.user.dn}
LDAP User Password	somePassword	${ldap.password}
LDAP Search Base	ou=people,dc=my-company,dc=com	${ldap.search.base}
LDAP Search Filter	(uid={0})	${ldap.search.filter}

Field

Example Literal String Value

Example Secure Property Placeholder

LDAP Server URL

ldap://174.19.33.17:389/

${ldap.server.url}

LDAP Secure Server URL (SSL)

ldaps://my-company-ldap.cloudhub.io:1010/

${ldap.server.url}

LDAP Server User DN

cn=Manager,dc=my-company,dc=com

${ldap.user.dn}

LDAP User Password

somePassword

${ldap.password}

LDAP Search Base

ou=people,dc=my-company,dc=com

${ldap.search.base}

LDAP Search Filter

(uid={0})

${ldap.search.filter}

The search filter string in the example is specific to OpenLDAP applications.

How This Policy Works

The Basic Authentication - LDAP policy intercepts the request to the protected resource and looks for the Authorization HTTP header.

The policy then extracts the username and password encoded in Base64 and then requests the configured LDAP instance to determine if the user credentials are correct in the provided LDAP context.

You can configure the Basic Authentication: LDAP policy to credentials using the following methods:

Search for the valid username and password pair in the level specified.
Search for the valid username and password pair in the level specified, including lower levels. This search option is comprehensive, however, can result in slow performance.

Search Scope

Your search scope options differ depending on your policy version. The search scope options are one level for LDAP 1.0.0 and two levels (subtree) for LDAP 1.1.0.

You can choose between one level and subtree search scopes by using the LDAP Search in subtree option.

The LDAP search base is the starting point for the search in the directory.

One-Level Search Scope

With this option, the filter affects only the objects immediately subordinate to the LDAP search base, and not the LDAP search base itself.

In the following example, the first level has four entries: two users and two groups. These are the only entries that are a part of any search:

Diagram of a hierarchical organizational structure

If you set the search filter to (uid={0}), only Jane and Paul are found. The group entries are not considered.

Subtree Search Scope

With this option, the Basic Authentication - LDAP policy examines the subtree below the LDAP search base and also includes the LDAP search base level. Notice that performance is affected by this behavior.

In the previous example, the analyzed area covers the entire organization. The group and user entries are considered at any level of the organization:

A flowchart that shows an example organizational structure

Creating Requests for APIs with Basic Authentication Policies Applied

After applying the Basic Authentication - LDAP policy to the API, a request to that API must contain the following header:

Authorization: Basic <username:password>

The username:password value must be a Base64-encoded string. For example on a Mac OS X or Linux system, the username and password requirement is implemented as:

echo -n '<Client Id>:<Client Secret>' | base64

From the username and search filter, LDAP finds the registered user and then verifies credentials. The valid result is returned:

Here’s a sequence diagram that illustrates the message flow for client authentication through an LDAP Server

The following diagram illustrates an invalid request:

A sequence diagram that illustrates the message flow for authorization

The Basic Authentication: LDAP policy throws an HTTP 401 status code to indicate that the authorization header is malformed, not provided, or invalid.