LDAP Agent Deployment Guide Skip to main content
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
LDAP Agent Deployment Guide
Published: Jan 13, 2015   -   Updated: Jun 22, 2018

This guide describes how to integrate Okta with your LDAP directory service by deploying the Okta LDAP Agent. LDAP integration allows end users to authenticate to Okta using their LDAP credentials without replicating those credentials into the cloud. In addition, Okta can import user accounts and attributes into the cloud service to improve performance and support complex scenarios. Okta’s LDAP integration helps organizations leverage current identity directory investments when controlling access to Okta-protected resources.

This guide includes the following topics:

Okta Overview

Okta is an enterprise-grade, identity management service built for the cloud but compatible with many on-premises applications. With Okta, IT can manage any employee's access to any application or device. Okta runs in the cloud on a secure, reliable, and extensively audited platform that integrates deeply with on-premises applications, directories, and identity management systems.

LDAP Overview

LDAP stands for Lightweight Directory Access Protocol (version v3 at the time of this writing). LDAP is a standard protocol for managing objects in a hierarchical directory and commonly used for user management. LDAP is prevalent; in fact, Microsoft Active Directory is an LDAP-based solution. Okta can integrate with an organization’s LDAP directory or directories by delegating authentication and/or importing users and groups.



Okta can integrate with most LDAPv3 directories. The configuration wizard provides templates for the following distributions:

  • OpenDJ
  • OpenLDAP
  • Oracle Internet Directory
  • IBM
  • Sun One LDAP 5.2+, 6.x and 7.x
  • Active Directory Lightweight Directory Services (AD LDS) (Windows Agent Only)

To integrate Okta with your LDAP instance, you need the following:

  • For Windows Agents – Windows Server 2003 R2 or later is required for the Windows-based agent. The Windows server must be able to reach the LDAP host and port.
  • For Linux Agents – The Linux-based agent must be installed on an RPM-enabled Linux distribution such as CentOS or Red Hat.
  • An Okta administrator account to connect the agent with your Okta org.
  • An LDAP user to perform binds and queries from the agent to your LDAP directory. This user must have the ability to look up users and groups/roles in the Directory Information Tree (DIT).


Installation Overview

The installation procedure you perform depends on which platform you are using. Separate procedures for Linux and Windows platforms are provided in Installing and Configuring the LDAP Agent.

The Okta LDAP Agent officially supports the following Operating Systems:

  • CentOS 6 or newer
  • Debian 7 or newer
  • Ubuntu 14 or newer
  • Windows Server 2008 R2 SP1 
  • Windows Server 2012 

The LDAP Agent is compatible with any LDAPv3-compliant directory, but is tested only on the following:

  • RadiantOne Directory 7.1
  • OpenDJ 2.6.0
  • OpenLDAP 2.4.23
  • Oracle Internet Directory
  • Sun One Directory Server 5.2
  • IBM Directory Server 6.3.1
  • Active Directory Lightweight Directory Services (2k8r2 + 2k12)


Architecture Overview

The Okta LDAP agent is a java-based service that runs locally on any server. The LDAP agent integrates with an organization’s directory using the LDAP protocol over port 389 by default. The agent communicates with Okta via a technique called long-polling. A TLS channel is established every 60 seconds, upon which the agent waits for instructions from Okta. Once an instruction is received, the agent processes it and returns the result over the same secure channel. If no instruction is received before the channel times out, the agent disconnects and immediately establishes a new TLS channel.

The diagram below shows the LDAP agent’s interaction with Okta and an organization’s on-premises infrastructure.  

User-added image


Functional Event Sequences

The LDAP Agent facilitates three major workflows for Okta users:

Delegated Authentication Flow

Okta’s LDAP Agent can authenticate users against an organization’s LDAP directory in real-time. This prevents Okta from being forced to store user credentials in the cloud and minimizes the passwords a user must memorize. The diagram below shows the LDAP delegated authentication flow via the Okta LDAP Agent.

User-added image


Password Reset Flow

Okta’s LDAP Agent also facilitates password change requests from an end user. If a user's password needs to change, whether because it expired or the policy dictates a change for any reason, Okta’s password reset flow works for LDAP passwords, too. This feature helps to reduce help desk calls by empowering users to perform self-service password reset.  

The diagram below shows the password reset flow in an LDAP-integration scenario.

User-added image

Just-In-Time Import Flow

The Okta LDAP Agent imports user information each time the user successfully authenticates. The flow is very similar to delegated authentication, but there is an extra step: after the user successfully authenticates, Okta either creates or updates the user’s account.

User-added image


Planning for High Availability and Performance

Okta agents are selected randomly from the pool of registered agents to fulfill authentication requests. To ensure that there is always one agent available to facilitate commands in case one server or connection goes down, a minimum of two LDAP Agents are recommended. If the directory contains more than 30K users, entailing a much higher authentication frequency, four or more LDAP agents are recommended. In general, capacity scales linearly with the number of agents. Adding additional agents will provide automatic failover and improve authentication throughput.