Install and configure the Okta LDAP agent

Install the 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. 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. to let your users authenticate to Okta using their LDAP credentials without replicating those credentials into the cloud.

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 Okta 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 Okta LDAP agent 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 Okta 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. On 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 groupsGroups allow you to organize your end users and the apps they can access. Assigning apps to large sets of end users is made easier with 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 the Okta LDAP agent on the Okta LDAP Agent Proxy Configuration page, and then click Next.

If the LDAP proxy server returns its own schema, issues importing user data can occur when the proxy server schema and LDAP server schemas are different. To avoid data importation issues, make sure the LDAP proxy server and LDAP server schemas are identical.

  1. To register the Okta LDAP agent with the Okta service, enter your Okta subdomain name, and then click Next.
  2. On the Okta Sign In page, enter the username and password for your Okta admin account, and then click Sign In.
  3. Click Allow Access to access the Okta API. Note: If an error message appears, see Locate the Okta LDAP agent log.
  4. Click Finish.
  5. Configure the LDAP integration settings.

Configure LDAP integration settings

  1. On the Okta Admin Console, click Directory > Directory Integrations.
  2. Click the Okta LDAP agent marked Not yet configured.
  3. Configure the following settings:

    When you select an LDAP provider, provider-specific configuration values are automatically added. If your LDAP provider is not on the list, complete the configuration fields manually. Confirm the default values are correct. Not all configuration settings must have values.

    • Unique Identifier Attribute — An auto-populated value defined by the selected LDAP provider. This value defines the unique immutable attribute of all imported LDAP objects (users and groups). Only objects possessing this attribute can be imported into your Okta orgThe Okta container that represents a real-world organization.. 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 — An auto-populated value defined by the selected LDAP provider. The attribute on all LDAP objects containing the Distinguished Name value.
  4. In the User section, configure the following settings:
    • User Search Base — Enter the Distinguished Name (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 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 — Optional. Enter a comma-separated list of auxiliary objectClasses to use in Okta import queries. For example, auxClass1,auxClass2.
    • User Object Filter — An auto-populated value defined by the selected LDAP provider. The default is 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 — Enter the attribute that indicates whether or not the user account is disabled in Okta. If this attribute equals the value specified in the Account Disabled Value field, the user account is deactivated.
    • Account Disabled Value — Enter the value that indicates that the account is locked (for example, TRUE).
    • Password Attribute — Enter the user password attribute.
    • Password Expiration Attribute — An auto-populated value when a supported LDAP provider is selected. If your directory provider is not in the list, see your LDAP server documentation or configuration for the password expiry value. Often, this attribute is a Boolean value.
    • Extra User Attributes — Optional. Enter additional user attributes to import from LDAP.
  1. Complete the Group or Role section. Typically, only one of these is used.
  1. Configure the following settings in the Validation configuration section:
    1. 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, Okta begins the LDAP schema discovery process.