The Okta LDAP Deployment Guide

This guide provides the information you need to plan, install, and configure your Okta LDAPLightweight Directory Access Protocol (LDAP) is a lightweight client-server protocol for accessing directory services, specifically X.500-based directory services. LDAP runs over TCP/IP or other connection oriented transfer services. integration. LDAP integration allows end usersIn Okta literature, we generally refer to "end users" as the people who have their own Okta home page (My Applications), using apps to authenticate into all of their apps. End users do not have any administrative control. When we refer to "users" we are generally referring to the individual(s) who have administrative control. 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.

Depending on the size and complexity of your Okta LDAP integration, you will work your way through select topics based on whether or not they apply to your environment and how familiar you already are with Okta.

Install the Okta Java LDAP agent

Supported directories

Okta integrates with most LDAPv3 directories. To learn about the specific requirements for your directory, select one of these links:


To integrate Okta with your LDAP instance:

Known issues

  • Oracle Internet Directory — Oracle Internet Directory (OID) has been tested and is supported with the Okta LDAP Agent v5.04.01 and later. When Okta searches an LDAP Directory, it leverages a paged search control to optimize how results are returned to the agent. Due to an issue with pagination in the current version of OID (Oracle Bug 25287786), we are aware of a problem where the Okta LDAP Agent will be unable to query for more objects than the default LDAP page size. While awaiting resolution from Oracle on this issue, customers should evaluate the configuration of the orclsizelimit attribute within their directory to balance scalability, performance and interoperability. Further details are available within the Oracle Internet Directory Administrators Guide.
  • Incremental Import — Each user, group, and OU/container entry in the LDAP server must have accurate modifyTimestamp value for incremental import to work. If your LDAP server cannot guarantee that, do not use incremental import.

Install the LDAP agent in a Linux environment

  1. On the host server, sign in to Okta using an Okta adminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. account with Super admin permissions, to access the Admin Console.
  2. Download the LDAP agent:
    1. Click Directory > Directory Integrations.
    2. Click Add Directory > Add LDAP Directory.
    3. Review the installation requirements, and then click Set Up LDAP.
    4. Click Download Agent and select Download RPM Installer or Download DEB Installer.
  3. Install the LDAP agent on your Linux server:
    1. Sign in to your Linux server as the root user.
    2. Copy the agent .rpm or .deb file to a scratch directory.
    3. Open a command prompt and cd to the scratch directory.
    4. Run one of the following commands to install the agent:


yum localinstall OktaLDAPAgent_xx.xx.xx.x86_64.rpm


dpkg -i OktaLDAPAgent_xx.xx.xx_amd64.deb

The installation process reports the total size of the installation and prompts you to continue.

Install the LDAP agent in a Windows environment

  1. On the host server, sign in to Okta using an Okta admin account with Super admin permissions, to access the Admin Console.
  2. Download the LDAP agent:
    1. Click Directory > Directory Integrations.
    2. Click Add Directory > Add LDAP Directory.
    3. Review the installation requirements, and then click Set Up LDAP.
    4. Click Download Agent, select Download EXE Installer and download it to your Windows server.
  3. On the host server, double click the file and then click Run.
    1. If the message displays Do you want to allow the following program to make changes to this computer?, click Yes.
    2. Click Next.
    3. Accept the license agreement and click Next.
    4. Accept the default installation folder location, or click Browse to select another location, and click Install.
    5. Optional. If you want to enable LDAP over SSL (LDAPS), complete Enable LDAP over SSL, and then continue with this procedure.
    6. At the LDAP configuration screen, enter the following information:
      • LDAP Server —  Enter the LDAP host and port in the form of host:port. For example:

      • Root DN —  The root distinguished name of the DIT from which users and groups are searched.
      • Bind DN —  The distinguished name of the bind LDAP user that is used to connect to the LDAP directory by the agent.
      • Bind Password — The password of the bind distinguished name that is used to connect to the LDAP directory by the agent.
      • Optional. Use SSL connection —  Select if you have enabled LDAP over SSL (LDAPS). (Note: If you select this without performing the steps in Enable LDAP over SSL, the error Failed to connect to the specified LDAP server displays.)
  4. Click Next.
  5. Optional. Enter a proxy server for your LDAP agent on the Okta LDAP Agent Proxy Configuration page, and then click Next.
  6. To register the LDAP Agent with the Okta service, enter your Okta subdomain name, and then click Next. A browser window launches.
  7. On the Okta Sign In page, enter the username and password for your Okta admin account, and then click Sign In.
  8. Click Allow Access to access the Okta API. Note: If an error message appears, see Okta LDAP agent log location.
  9. Click Finish.

If you are installing the Okta Java LDAP agent for the first time, the Install Wizard takes you to Step 2 of the agent configuration.

Configure LDAP

  1. On the Okta Admin Console, click Directory > Directory Integrations.
  2. Click the LDAP agent from the list of directories. It should be marked Not yet configured.
  3. In Set Up LDAP > Configure Directory Mappings, configure the following settings:
    • LDAP Version — Select your vendor. Vendor-specific configuration templates are provided and pre-populate configuration settings for you. If your LDAP vendor is not on the list, complete the configuration fields manually. Because each LDAP environment is unique, you must confirm the default values using an LDAP browser like Apache Directory Studio. Note that not all configuration settings must have values.
    • Unique Identifier Attribute — Specifies the unique immutable attribute of all LDAP objects that will be imported (users and groups). Only objects possessing this attribute can be imported into your Okta org. Okta populates this field automatically based on your chosen LDAP version. You can change the auto-populated value during initial setup. Note: if your LDAP server implements RFC 4530, make sure to enter entryuuid in this field. For AD LDS, use objectguid.
    • DN Attribute — The attribute on all LDAP objects containing the Distinguished Name value.
  1. In the User section, configure the following settings:
    • User Search Base — The DN of the container for user searches (that is, root of the user subtree). This is the base DN of the container that holds all users that will be imported into your Okta org. For example: cn=Users, dc=example, dc=com.
    • Object Class — The objectClass of a user that Okta uses in its query when importing users. For example, inetorgperson, posixaccount, posixuser.
    • Auxiliary Object Class — You can input a comma-separated list of auxiliary objectClasses. Okta will use these in its query when importing users. For example, auxClass1,auxClass2.
    • User Object Filter — By default, Okta auto-populates this field with the objectClass (objectClass=<entered objectClass name>). This must be a valid LDAP filter.

      Use standard LDAP search filter notation (RFC 2254). For example:

      (&(givenName=Bab*)(|(sn=Jensen)(cn=Babs J*)))

      The same filter capability is also in place for Group Objects.

    • Account Disabled Attribute — The user attribute that indicates whether or not the account is disabled for the user in Okta. If this attribute equals the value specified in the Account Disabled Value field, we deactivate the user account.
    • Account Disabled Value — The value that indicates that the account is locked (for example, TRUE).
    • Password Attribute — The user password attribute.
    • Password Expiration Attribute — Different LDAP directories have different attribute names for password and password expiration. If you select one of the pre-populated directories, Okta will auto-fill the correct default value. If your directory is not in the supported list, refer to your LDAP server documentation or configuration and use that value for password expiry. This attribute is usually a Boolean value, but may vary depending on your LDAP server.
    • Extra Attributes — You can specify up to four additional attributes to be imported from LDAP.
  1. Complete the Group or Role section. Typically, only one of these is used.
  1. Validate your configuration settings.
    1. Select an Okta username format.

      When you import users from LDAP, these settings are used to generate the Okta username that your users use to sign in to Okta.

      Note: Okta requires that valid user names be in an email format. Configuring these options correctly make sure that your user names satisfy this requirement.

    1. Enter a Username.

      Enter the username of a user in the specified username format. Since the username that you enter uniquely identifies a single user in your LDAP directory, the query that Okta executes will retrieve only your specified user and the following details about the user. Validate that all returned details are correct.

      • Status
      • UID
      • Unique ID
      • Distinguished Name
      • Full Name
      • Email
      • Groups – All the groups of the specified Group Object Class within the Group Search Base of which this user is a member. If the expected groups are not listed here, group imports might fail later.
    1. Click Test Configuration.

      If your configuration settings are valid, the message Validation successful! displays along with information about the returned user object. If there is a problem with your configuration, or if the user is not found, you are prompted to review your settings.

  1. When your settings are successfully validated, click Next and then Done to complete LDAP configuration.

After validating your settings, in the background Okta begins the LDAP schema discoveryAbility to import additional attributes to Okta process.

Note: You can change any of these settings by navigating to the LDAP agent and selecting Provisioning > Integration.

What's next?

Configure the LDAP agent. See Configure the Okta LDAP Agent.