Logo / Docs

LDAP Connector

Overview

LDAP Connectors allow you to authenticate users against or migrate them from an LDAP server accessible to FusionAuth.

Configuration

The LDAP Connector creation screen.

Form Fields

Id

An optional UUID. When this value is omitted a unique Id will be generated automatically.

Namerequired

A unique name to identify the Connector. This name is for display purposes only and it can be modified later if desired.

LDAP URLrequired

The URL used to connect to the LDAP service.

Security method

The desired security method used to connect to LDAP. The default value of None is unencrypted which is not recommended unless you use an alternative method of securing your connection, such as a VPN.

Connect timeoutrequired

The connect timeout in milliseconds used when making the request to LDAP.

Read timeoutrequired

The read timeout in milliseconds used when making the request to LDAP.

Reconcile lambdarequired

The lambda used to reconcile the user from LDAP to FusionAuth.

Navigate to Customizations -> Lambdas to create this lambda.

Debug enabled

Enable debug to create an event log to assist you in debugging integration errors.

The LDAP Connector creation screen.

Directory

Base structurerequired

The base structure is the directory to use in order to search for users.

For example, to search the entire directory, you’d use a base structure of DC=piedpiper,DC=com. If you want to search against only engineering, add the organization: OU=engineering,DC=piedpiper,DC=com.

System account DNrequired

The distinguished name of an entry which has read access to the directory.

For example: CN=ReadOnlyFusionAuthUser,OU=engineering,DC=piedpiper,DC=com.

System account passwordrequired

The password of the System Account DN .

Login identifier attributerequired

The value that the user would enter for their username on a login screen.

For example: uid or userPrincipalName

Identifying attributerequired

The entry attribute name which is the first component of the distinguished name of entries in the directory.

For example: cn

Requested attributesrequired

The list of requested directory attributes to be returned. These will be passed to the lambda to be converted into FusionAuth user attributes. These must be added one at a time.

For example: cn givenName sn userPrincipalName mail

Using the LDAP Connector

Once you have completed configuration of the LDAP connector, you will need to instruct a tenant to use this connector.

  • Ensure your LDAP server is accessible to the FusionAuth instance. This may entail setting up a VPN, locating FusionAuth in the correct network, or configuring a firewall to allow access.
  • Determine which LDAP user FusionAuth will connect as.
  • Create an LDAP reconcile Lambda to map the directory attributes to FusionAuth user attributes.
  • Configure the Connector in Settings -> Connectors . At a minimum, configure ** The LDAP URL and connection security ** The previously created lambda ** LDAP directory settings
  • Add the Connector Policy in Tenants -> Your Tenant -> Connectors to configure to which domains the connector applies.

Using the LDAP Connector as the System of Record

You can use this Connector as either a source of authentication or to migrate your users. In the former case, the backing LDAP directory remains the system of record (where the canonical user data exists). In the latter, the user is moved over once they have authenticated successfully one time, and FusionAuth becomes the system of record.

As documented, there are a number of differences between these two choices. However, one difference is worth emphasizing.

When you are not migrating the user and therefore using the backing LDAP directory as the system of record, the following user attributes will reset every time the user authenticates:

  • Group memberships
  • Application registrations

If, for instance, you were to register such a user for an application using the FusionAuth API or the administrative user interface, the next time they authenticated, they would not be registered for that application.

Since FusionAuth is not the system of record, the backing LDAP directory is the authoritative data source.

The correct way to maintain these attributes is:

  • store them in the LDAP directory
  • request them by configure the appropriate Requested attributes
  • use the reconcile lambda to set the user’s attributes appropriately

FusionAuth does not support pushing user profile data into LDAP. Data always flows through a Connector into FusionAuth.

If you use the Connector as a source of authentication, the source of truth remains the LDAP server. If you migrate your users (by toggling on Migrate user on the Tenant Connector policy), FusionAuth becomes the source of truth after the first login of each user. You can review the connectorId associated with the User object to confirm which Connector is authoritative for a user.

Connecting to Active Directory

User data stored in Microsoft Active Directory is accessible via LDAP. If you’d like to federate and allow some of your users to authenticate against Active Directory, use the LDAP Connector.

Here’s a video walking through such a configuration of FusionAuth and Microsoft Active Directory:

Play