Contact Us 1-800-596-4880

LDAP Connector

Support Category: Select

Included here are an example of a simple LDAP connector configuration and basic instructions for installing and connecting to an LDAP server using the LDAP connector.

The Lightweight Directory Access Protocol (LDAP) is a public standard that facilitates maintenance and access to distributed directories such as network user privilege information over an Internet Protocol (IP) network.

Many LDAP servers are included as free-use open source projects and packages. The particulars of installing, running, and configuring LDAP servers are outside the scope of this document.

Before You Begin

This document assumes that you are familiar with LDAP, Mule, Anypoint Connectors, Anypoint Studio essentials, elements in a Mule flow, and global elements.

To use the LDAP connector, you must have the following:

  • Access to either an OpenLDAP, Apache Directory, or MicroSoft Active Directory Instance.

  • Anypoint Studio - Enterprise Edition.

To use the LDAP connector in a production environment, you must have either:

  • An Enterprise license to use Mule.

  • An Anypoint Platform Starter, Professional, or Enterprise account.

For compatibility information, see the LDAP Connector Release Notes.

Install this Connector

  1. In Anypoint Studio, click the Exchange icon in the Studio task bar.

  2. Click Login in Anypoint Exchange.

  3. Search for the connector and click Install.

  4. Follow the prompts to install the connector.

Configure the Global Element with the Studio Visual Editor

To use the LDAP connector in a Mule app, configure a global LDAP configuration element that can be used by as many LDAP connectors as you require for your app. Note that this connector supports connection caching, which can be configured in the Cache Configuration tab of the global element.

  1. Click the Global Elements tab at the base of the canvas.

  2. In the Global Mule Configuration Elements screen, click Create.

  3. In the Choose Global Type wizard, expand Connector Configuration, select LDAP: Configuration, and click OK.

    Global Element Configuration Wizard
  4. Configure the parameters using the information in the next table.

    Global Element Configuration
    Parameter Description

    Name

    Enter a name for the configuration to reference it.

    Principal DN

    The DN (distinguished name) of the user.

    Password

    The password of the user.

    URL

    The connection URL to the LDAP server. The URL must always begin with ldap:// irrespective if it’s for TLS or normal connections.

    Authentication

    Specifies the authentication mechanism to use. Valid values are:

    • simple: (Default) Simple authentication. The LDAP server authenticates the user by using the user’s fully qualified DN (Principal DN parameter) and password (Password parameter).

    • none: Anonymous authentication. The LDAP server allows the client to read and update data configured to be accessible by an unauthenticated client. For more information, see https://docs.oracle.com/javase/jndi/tutorial/ldap/security/ldap.html.

    In the previous image, the placeholder values refer to a configuration file placed in the src folder of your project.

  5. You can either enter your credentials into the global configuration properties, or reference a configuration file that contains these values. For simpler maintenance and better reuse of your project, Mule recommends that you use a configuration file. Keeping these values in a separate file is useful if you need to deploy to different environments, such as production, development, and QA, where your access credentials differ.

  6. Keep the Pooling Profile and the Reconnection tabs with their default entries.

  7. Click Test Connection to confirm that the parameters of your global configuration are accurate, and that Mule is able to successfully connect to your instance of LDAP.

Configure the Global Element with the Studio XML Editor

  1. Include the LDAP name spaces in your configuration file.

    <mule xmlns:http="http://www.mulesoft.org/schema/mule/http"
    xmlns="http://www.mulesoft.org/schema/mule/core"
    xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
    xmlns:spring="http://www.springframework.org/schema/beans"
    xmlns:ldap="http://www.mulesoft.org/schema/mule/ldap"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans-current.xsd
    http://www.mulesoft.org/schema/mule/core
    http://www.mulesoft.org/schema/mule/core/current/mule.xsd
    http://www.mulesoft.org/schema/mule/http
    http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
    http://www.mulesoft.org/schema/mule/ldap
    http://www.mulesoft.org/schema/mule/ldap/current/mule-ldap.xsd">
    
    <!-- Put your flows and configuration elements here -->
    </mule>
  2. Create a global element for LDAP configuration using the following global configuration code:

    <ldap:config name="LDAP_Configuration" doc:name="LDAP: Configuration"
        authDn="${config.principal.dn}"
        authPassword="${config.password}"
        url="${config.url}" >
        <ldap:extended-configuration>
            <ldap:extended-configuration key="key.name" value="key.value" </ldap:extended-configuration>
        </ldap:extended-configuration>
    </ldap:config>
  3. Save the changes made to the XML file.

Use the Connector

The LDAP connector is an operation-based connector, which means that when you add the connector to your flow, you need to configure a specific operation for the connector to execute. The connector currently supports the following operations:

Operation Description

Add multi-valued attribute

Adds a specific multi-valued attribute to an existing LDAP entry.

Add single-valued attribute

Adds a specific single-valued attribute to an existing LDAP entry.

Add

Creates a new LDAP entry.

Bind

Authenticates against the LDAP server. This occurs automatically before each operation but can also be performed on request.

Delete multi-valued attribute

Deletes specific multi-valued attribute to an existing LDAP entry.

Delete single-valued attribute

Deletes specific single-valued attribute to an existing LDAP entry.

Delete

Deletes an existing LDAP entry.

Exists

Checks whether an LDAP entry exists in the LDAP server or not.

Lookup

Retrieves a unique LDAP entry.

Modify multi-valued attribute

Updates specific multi-valued attribute of an existing LDAP entry.

Modify single-valued attribute

Updates specific single-valued attribute of an existing LDAP entry.

Modify

Updates an existing LDAP entry.

Paged result search

Performs an LDAP search and streams result to the rest of the flow.

Search one

Performs an LDAP search that is supposed to return a unique result.

Search

Performs an LDAP search in a base DN with a given filter.

Connector Name Space and Schema

When designing your app in Studio, the act of dragging the connector from the palette onto the Anypoint Studio canvas should automatically populate the XML code with the connector name space and schema location.

Name Space: http://www.mulesoft.org/schema/mule/ldap
Schema Location: http://www.mulesoft.org/schema/mule/ldap/current/mule-ldap.xsd
http://www.mulesoft.org/schema/mule/ldap/current/mule-ldap.xsd

If you are manually coding the Mule app in Studio’s XML editor or other text editor, paste these into the header of your configuration XML inside the <mule> tag.

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:sns="http://www.mulesoft.org/schema/mule/ldap"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/sns
               http://www.mulesoft.org/schema/mule/ldap/current/mule-ldap.xsd">

      <!-- put your global configuration elements and flows here -->

</mule>

Use the Connector in a Mavenized Mule App

If you are coding a Mavenized Mule app, this XML snippet must be included in your pom.xml file.

<dependency>
  <groupId>org.mule.modules</groupId>
  <artifactId>mule-module-ldap</artifactId>
  <version>x.x.x</version>
</dependency>

Replace x.x.x with the version that corresponds to the connector you are using.

To obtain the most up-to-date pom.xml file information, access the connector in Anypoint Exchange and click Dependency Snippets.

Use Cases and Demos

The following are the most common use cases for the LDAP connector, and some demo app walkthroughs.

Use Case Description

Adding User Accounts to Active Directory

Business user accounts can be added to Active Directory groups defined on the base DN.

Retrieve User attributes

Basic attributes of the business user can be retrieved for one or more purposes, like email or phone.

Add to a Flow

  1. Create a new Mule Project in Anypoint Studio.

  2. Add a suitable Mule inbound endpoint, such as the HTTP Listener or File connector at the beginning of the flow.

  3. Drag and drop the LDAP connector onto the canvas.

  4. Click the connector to open the Properties Editor.

    Flow Settings
  5. Configure the following parameters:

    Field Description

    Basic Settings:

    Display Name

    Enter a unique label for the connector in your app.

    Connector Configuration

    Connect to a global element linked to this connector. Global elements encapsulate reusable data about the connection to the target resource or service. Select the global LDAP connector element that you just created.

    Operation

    Select Add entry from the drop-down menu.

    General:

    Topic Name

    Enter a unique name for the topic.

  6. Click the blank space on the canvas for the connector to fetch the metadata based on the Structural Object Class, which traverses the directory information tree to retrieve the hierarchy and all the properties it inherits.

Example Use Case 1 with LDAP Connector

Add and delete an organizational person from an organizational unit.

Add User Entry Flow
  1. Create a new Mule Project in Anypoint Studio.

  2. Add the properties to mule-app.properties file to hold your LDAP credentials and place it in the project’s src/main/app directory.

    config.principal.dn=<DN>
    config.password=<Password>
    config.url=<URL>
    
    <!-- Configure anonymous authentication -->
    
    config.principal.dn = <DN>
    config.password=<Password>
    config.authentication = none
    config.bindUrl = <URL>
  3. Drag an HTTP connector onto the canvas and configure the following parameters:

    Parameter Value

    Display Name

    HTTP

    Connector Configuration

    If no HTTP element has been created yet, click the plus sign to add a new HTTP Listener Configuration and click OK (leave the values to its defaults).

    Path

    /

  4. Set the flow variable to hold the group distinguished name (dn), for example: DevOpsGroup.

  5. Drag the Variable Transformer next to the HTTP endpoint component.

    Configure according to this table:

    Parameter Description Value

    Operation

    Select the transformer operation.

    Set Variable

    Name

    The variable name.

    dn

    Value

    The variable value.

    ou=DevOpsGroup,#[message.inboundProperties.'http.query.params'.dn]

  6. Create the organizational unit entry using a Groovy component. Drag the Groovy component next to the Variable Transformer and use this script.

    import org.mule.module.ldap.api.LDAPEntry;
    
    LDAPEntry entryToAdd = new LDAPEntry(flowVars.dn);
    entryToAdd.addAttribute("ou", "DevOpsGroup");
    entryToAdd.addAttribute("objectClass", ["top", "organizationalUnit"]);
    
    return entryToAdd
  7. Drag the LDAP connector next to the Groovy component to add the LDAP Entry.

  8. Configure the LDAP connector by adding a new LDAP Global Element. Click the plus sign next to the Connector Configuration field.

  9. Configure the global element according to this table:

    Parameter Description

    Value

    Name

    Enter a name for the configuration to reference it.

    <Configuration_Name>

    Principal DN

    The DN (distinguished name) of the user.

    ${config.principal.dn}

    Password

    The password of the user.

    ${config.password}

    URL

    The connection URL to the LDAP server.

    The corresponding XML configuration should be as follows:

    <ldap:config name="LDAP_Configuration" doc:name="LDAP: Config"
        authDn="${config.principal.dn}"
        authPassword="${config.password}"
        url="${config.url}" />
  10. Click Test Connection to confirm that Mule can connect with the LDAP instance. If the connection is successful, click OK to save the configurations. Otherwise, review or correct any incorrect parameters, then test again.

  11. In the properties editor of the LDAP connector, configure the remaining parameters:

    Parameter Value

    Basic Settings:

    Display Name

    Add Group Entry

    Operation

    Add entry

    General:

    Entry Reference

    #[payload]

  12. Create the organizational person entry using a Groovy component. Drag the Groovy component next to the LDAP connector and add this script to the Script text.

    import org.mule.module.ldap.api.LDAPEntry;
    
    LDAPEntry entryToAdd = new LDAPEntry("cn=Test User,"+ flowVars.dn);
    entryToAdd.addAttribute("uid", "testUser");
    entryToAdd.addAttribute("cn", "Test User");
    entryToAdd.addAttribute("sn", "User");
    entryToAdd.addAttribute("userPassword", "test1234");
    entryToAdd.addAttribute("objectClass", ["top", "person", "organizationalPerson", "inetOrgPerson"]);
    
    return entryToAdd
  13. Drag the LDAP connector next to the Groovy component. The connector adds the LDAP Entry created in the previous step.

  14. In the properties editor of the LDAP connector, configure the parameters:

    Parameter Value

    Basic Settings:

    Display Name

    Add User Entry

    Connector Configuration

    LDAP_Configuration

    Operation

    Add entry

    General:

    Entry Reference

    #[payload]

  15. Now that we have successfully added the entries, let’s try to delete them using the LDAP connector.

  16. Drag the LDAP connector besides the existing flow and configure the parameters:

    Parameter Value

    Basic Settings:

    Display Name

    Delete User Entry

    Connector Configuration

    LDAP_Configuration

    Operation

    Delete entry

    General:

    DN

    cn=Test User,#[flowVars.dn]

  17. Drag another LDAP connector to the right of the first LDAP connector and configure the parameters:

    Parameter Value

    Basic Settings:

    Display Name

    Delete Group Entry

    Connector Configuration

    LDAP_Configuration

    Operation

    Delete entry

    General:

    DN

    #[flowVars.dn]

  18. Finally drag the Set Payload transformer to set the value to Flow Successfully Completed.

Example Use Case 1 Code

Paste this code into your XML Editor to quickly load the flow for this example use case into your Mule app.

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:scripting="http://www.mulesoft.org/schema/mule/scripting"
xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking"
xmlns:http="http://www.mulesoft.org/schema/mule/http"
xmlns:ldap="http://www.mulesoft.org/schema/mule/ldap"
xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/ldap
http://www.mulesoft.org/schema/mule/ldap/current/mule-ldap.xsd
http://www.mulesoft.org/schema/mule/core
http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/scripting
http://www.mulesoft.org/schema/mule/scripting/current/mule-scripting.xsd
http://www.mulesoft.org/schema/mule/ee/tracking
http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd">
    <http:listener-config name="HTTP_Listener_Configuration" doc:name="HTTP Listener Configuration"
        host="0.0.0.0"
        port="8081" />
    <ldap:config name="LDAP_Configuration" doc:name="LDAP: Config"
        authDn="${config.principal.dn}"
        authPassword="${config.password}"
        url="${config.url}" >
        <ldap:extended-configuration>
            <ldap:extended-configuration key="key.name" value="key.value" </ldap:extended-configuration>
        </ldap:extended-configuration>
    </ldap:config>
    <flow name="ldap-add-entry-flow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
        <set-variable variableName="dn"
        value="ou=DevOpsGroup,#[message.inboundProperties.'http.query.params'.dn]"
        doc:name="Set DN as Flow Variable"/>
        <scripting:component doc:name="Groovy Script to Create DevOps Group Object">
            <scripting:script engine="Groovy"><![CDATA[import org.mule.module.ldap.api.LDAPEntry;

LDAPEntry entryToAdd = new LDAPEntry(flowVars.dn);
entryToAdd.addAttribute("ou", "DevOpsGroup");
entryToAdd.addAttribute("objectclass", ["top", "organizationalUnit"]);

return entryToAdd]]></scripting:script>
        </scripting:component>
        <ldap:add config-ref="LDAP_Configuration" doc:name="Add Group Entry to LDAP Directory"/>
        <scripting:component doc:name="Groovy Script to Create User Object">
            <scripting:script engine="Groovy"><![CDATA[import org.mule.module.ldap.api.LDAPEntry;

LDAPEntry entryToAdd = new LDAPEntry("cn=Test User,"+ flowVars.dn);
entryToAdd.addAttribute("uid", "testUser");
entryToAdd.addAttribute("cn", "Test User");
entryToAdd.addAttribute("sn", "User");
entryToAdd.addAttribute("userPassword", "test1234");
entryToAdd.addAttribute("objectclass", ["top", "person", "organizationalPerson", "inetOrgPerson"]);

return entryToAdd]]></scripting:script>
        </scripting:component>
        <ldap:add config-ref="LDAP_Configuration"
          doc:name="Add User Entry to LDAP Directory"/>
        <ldap:delete config-ref="LDAP_Configuration"
          dn="cn=Test User,#[flowVars.dn]"
          doc:name="Delete User Entry from LDAP Directory"/>
        <ldap:delete config-ref="LDAP_Configuration"
          dn="#[flowVars.dn]"
          doc:name="Delete Group Entry from LDAP Directory"/>
        <set-payload value="Flow Successfully Completed" doc:name="Set Payload: Flow Completed"/>
    </flow>
</mule>

Example Use Case 2 with LDAP Connector

A custom trust store can be setup to tell which servers are allowed to communicate to.

Extended configuration parameters can be used for this to specify a custom trust store.

The previous Use Case 1 can be used to execute this except for the configuration part of LDAP connector which should now use TLS configuration.

The following XML configuration snippet of LDAP connector uses TLS configuration and updates the Use Case 1 XML file with it.

<ldap:tls-config name="LDAP__TLS_Configuration" authDn="xxx" url="ldap:xxxx"
  doc:name="LDAP: TLS Configuration">
  <ldap:extended-configuration>
    <ldap:extended-configuration key="org.mule.module.ldap.trustStorePath">mytruststore.jks</ldap:extended-configuration>
    <ldap:extended-configuration key="org.mule.module.ldap.trustStorePassword" value="xxxx" />
  </ldap:extended-configuration>
</ldap:tls-config>

Run the Demo App

  1. Save and run the project as a Mule Application.

  2. Open a web browser and check the response after entering the http://localhost:8081/?dn=dc=mulesoft,dc=org URL.

View on GitHub