FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    LDAP Connector

    Overview

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

    • Configuration

    • Using the LDAP Connector

      • Using the LDAP Connector as the System of Record

    • Connecting to Active Directory

    Configuration

    The LDAP Connector creation screen.

    Form Fields

    Id Optional

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

    Name Required

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

    LDAP URL Required

    The URL used to connect to the LDAP service.

    Security method Optional default is None

    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 timeout Required default is 1000

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

    Read timeout Required default is 2000

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

    Reconcile lambda Required

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

    Navigate to Customizations → Lambdas to create this lambda.

    Debug enabled Optional default is false

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

    The LDAP Connector creation screen.

    Directory

    Base structure Required

    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 DN Required

    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 password Required

    The password of the System Account DN.

    Login identifier attribute Required

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

    For example: uid or userPrincipalName

    Identifying attribute Required

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

    For example: cn

    Requested attributes Required

    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 to store them in the LDAP directory, request them using the Requested attributes, and use the reconcile lambda to set the user’s attributes appropriately.

    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:

    Related Posts

    • How to migrate your legacy user data to a centralized auth system

    • Authenticating with AWS Managed Microsoft Active Directory and LDAP

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    Subscribe for developer updates