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 Mule version available |
v4.0.0 |
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. This policy is available in Flex and Mule 4 or later.
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
Mule Gateway
When you apply the Basic Authentication - LDAP policy to your API from the UI, you can configure the following parameters to connect to your LDAP or Active Directory:
| Parameter | Description |
|---|---|
LDAP Server URL |
The URL of your LDAP OR LDAPS 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. 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. |
Note that 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} |
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} |
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:
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:
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
Mule runtime engine (Mule) 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 then verifies credentials. The valid result is returned to Mule:
The following diagram illustrates an invalid request:
The Basic Authentication: LDAP policy throws an HTTP 401 status code to indicate that the authorization header is malformed, not provided, or invalid.