Nav

Basic Authentication: LDAP (Mule 4)

The Lightweight Directory Access Protocol (LDAP) authentication policy establishes the configuration details for an Open LDAP or Active Directory LDAP that you set up for your enterprise. This policy is available only to an API you are managing in Mule 4 or later.

You can follow the general instructions for applying a policy, including those for applying the policy to resources and methods.

The following properties configure the LDAP policy for connecting to your LDAP or Active Directory.

  • LDAP Server URL

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

  • 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.

  • 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 below.

All fields are required. These literal string values support property placeholders. Enter the password as a secure value, which is a value that, once specified, is not visible or retrievable.

Example Configuration for an Active Directory

Field Example Literal String Value Example Secure Property Placeholder

LDAP Server URL

ldap://174.19.33.17:389/

${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}

The search filter string given above is specific to Active Directory applications.

Example Configuration for a OpenLDAP

Field Example Literal String Value Example Secure Property Placeholder

LDAP Server URL

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}

Note: The search filter string given above is specific to OpenLDAP applications.

If you use secure property placeholders when you configure an LDAP policy, specify the values for the placeholders as system variables, either in the command line or in your Mule Runtime wrapper.conf file.

For example:

# OpenLDAP properties definitions
wrapper.java.additional.7=-Dldap.password=<password here>
wrapper.java.additional.8=-Dldap.user.dn=cn=Manager,dc=my-company,dc=com
wrapper.java.additional.9=-Dldap.search.base=ou=people,dc=my-company,dc=com
wrapper.java.additional.10=-Dldap.search.filter=(uid={0})
wrapper.java.additional.11=-Dldap.server.url=ldaps://my-company-ldap.cloudhub.io:1010/

Search scope

The search scope options differ depending on the policy version:

  • 1.0.0 only has the one level search scope available.

  • 1.1.0 provides two search scopes. You can choose between ‘one level’ and ‘subtree’ search scopes by using the ‘LDAP Search in subtree’ checkbox.

One Level search scope

By using this option, the filter affects only the objects immediately subordinate to the base object, but does not include the base object itself. The 1.0.0 version of this policy has only this search scope.

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

search scope

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

Subtree search scope

By using this option, the policy examines the subtree below the base DN and also includes the base DN level. Notice that performance will be affected by this behavior.

Continuing with the previous example, we can see that the analyzed area covers the entire organization. The group and user entries are considered at any level of the organization.

search scope2

Request Requirements

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

Authorization: Basic <username:password>

where username:password is a base64-encoded string. In Mac OS X or Linux, for example:

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

Mule Runtime separates the credentials of the header and sends the request to the LDAP server with the search filter.

From the username and search filter, LDAP finds the registered user, and verifies credentials. Finally, the valid result is sent to Mule Runtime, as shown in the following diagram.

ldap verification

The following diagram shows the course of invalid requests:

ldap verification invalid

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