Install the Okta Java LDAP Agent

To integrate Okta with your 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. directory, install and configure the Okta Java LDAP agentA software agent is a lightweight program that runs as a service outside of Okta. It is typically installed behind a firewall and allows Okta to tunnel communication between an on-premises service and Okta's cloud service. Okta employs several agent types: Active Directory, LDAP, RADIUS, RSA, Active Directory Password Sync, and IWA. For example, users can install multiple Active Directory agents to ensure that the integration is robust and highly available across geographic locations.. 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.


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, you need the following:

Important: If you are upgrading from a version 4.x agent or earlier to a version 5.x agent, you must first uninstall the old agent before installing the new agent. See the OS-specific installation instructions below.

Known Issues


On Linux

To install the Okta LDAP agent:

  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 dashboard.
  2. Select Directory > Directory Integrations.
    1. Select Add LDAP Directory.
    2. Review the installation requirements, and then click Set Up LDAP.
    3. Click Download Agent.
    1. From the drop-down menu, choose your required installer option (.rpm or .deb).
  3. After downloading the agent, you must install it on your Linux server. Sign in to your Linux server as the root user, copy the agent .rpm or .deb file to a scratch directory, and then cd to that directory.
  4. To install the agent, issue one of the following commands from a command line:
    • RPM: 

      yum localinstall OktaLDAPAgent_xx.xx.xx.x86_64.rpm

    • Debian: 

      dpkg -i OktaLDAPAgent_xx.xx.xx_amd64.deb

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

On Windows

To install the Okta LDAP agent:

  1. On the host server, sign in to Okta using an Okta admin account with Super admin permissions, to access the Admin dashboard.
  2. Go to Directory > Directory Integrations.
    1. From the drop-down menu, select Add LDAP Directory.
    2. Review the installation requirements, and then click Set Up LDAP.
    3. Click Download Agent.
    4. From the drop-down menu, select the .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. At the license agreement, click Next.
    4. At the Installation options dialog box, specify an installation folder, and then click Install.
    5. (Optional) If you want to enable LDAP over SSL (LDAPS), perform the procedure Enable LDAP over SSL, then return to this procedure and complete it.
    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 displays during this step, see Okta LDAP agent log location.
  9. Click Finish when the installation is complete.

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.

LDAP Configuration

  1. Return to 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.


    • Group Search Base — The DN of the container for group searches (that is, root of the group subtree) that holds all groups that will be imported into your Okta org. For example: ou=groups, dc=example, dc=com.
    • Group Object Class — The objectClass of a group that Okta uses in its query when importing groups. For example, groupofnames, groupofuniquenames, posixgroup.
    • Group Object Filter – By default, Okta auto-populates this field with the objectClass of the group (objectClass=<entered objectClass name>).
    • Member Attribute — The attribute containing all the member DNs.
    • User Attribute — Okta uses the member attribute on the group object to determine the user group memberships at runtime. Unless your group object and group filter is explicitly posixGroup and (objectclass=posixGroup), leave the user attribute field empty. If you are using posixGroup, we recommend that you configure the member attribute value to memberUID and the user attribute value to uid.

      Example 1

      ① If the specified group object and group filter is posixGroup  . . . ,

      ② then enter memberUid in the User Attribute field.

      Example 2

      ① If the specified group object and group filter is something other than posixGroup . . . ,

      ② then leave the User Attribute field blank.


    • Object Class – The objectClass of a role.
    • Membership Attribute – The attribute of the user object that indicates role membership (that is, containing the role DNs).
  1. Validate your configuration settings.
    1. Select an Okta username format.

      When you import users from LDAP, Okta uses these settings to generate the Okta username that your users will use to log in to Okta.

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

      Email address option

      Select this option if you want your users' LDAP email address to be their Okta username. Note: Email addresses must be unique in LDAP.

      For example:

      ① If email addresses in LDAP are . . . ,

      ② and you select the Email address Okta username format . . . ,

      ③ enter in the Username field.


      User Id (UID) option

      Select this option only if the UID value in the LDAP directory is already formatted as an email address.

      For example:

      ① If the UID in LDAP is already formatted as an email address like . . . ,

      ② and you select the User Id (UID) Okta username format . . . ,

      ③ enter in the Username field.


      User Id (UID) + Configurable Suffix option

      Select this option only if the UID value in LDAP lacks an email suffix and you want end users to log in using a configurable email suffix.

      For example:

      ① If the UID in LDAP is user.1234 . . . ,

      ② and you select the User Id (UID) + Configurable Suffix Okta username format . . . ,

      ③ enter in the Configurable Suffix field . . .

      ④ enter in the Username field.


      User Id (UID) @ DomainA domain is an attribute of an Okta organization. Okta uses a fully-qualified domain name, meaning it always includes the top-level domain (.com, .eu, etc.), but does not include the protocol (https). option

      Select this option only if the UID value in LDAP lacks an email suffix and you want Okta user names to include your company's domain name as the email suffix.

      For example:

      ① If the UID in LDAP is user.1234 . . . ,

      ② and your company's domain name is yourdomainname . . . ,

      ③ and you select the User Id (UID) @ Domain Okta username format . . . ,

      ④ enter in the Username field.

    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 ProvisioningProvisioning is the enterprise-wide configuration, deployment, and management of multiple types of IT system resources. Specifically, provisioning provides users access to equipment, software, or services. This involves creating, maintaining and deactivating required business process automation objects and attributes in systems, directories, and applications. > Integration.

What's Next?

Now that you have installed the Okta LDAP agent you must configure the Okta and LDAP integration.

Configure your settings as described in Configure the Okta Java LDAP Agent.

Related Topics

Enable LDAP over SSL

Okta LDAP agent log information

Uninstall or re-install the Okta LDAP agent

LDAP configuration parameters

LDAP agent configuration changes