Manage LDAP provisioning, import, and integration settings

After installing and configuring 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., you'll want to define the provisioning, import, and integration settings to meet the specific requirements of your orgThe Okta container that represents a real-world organization.. For example, you can define how user profiles are created and what action is taken when an account is deactivated.

Configure LDAP provisioning settings

  1. On the 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. Console, click Directory > Directory Integrations.
  2. Select the LDAP agent from the list of directories. It should be marked Not yet configured.
  3. Click the 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. tab, click Edit, and complete the following settings:
  4. Click Save.

The final section allows you map your LDAP attribute and set its value based on values stored in Okta. The attributes listed in the table are your LDAP attributes.

You can only add attributes to the directory profile if they are already in the directory, so Okta first does a schema discoveryAbility to import additional attributes to Okta step to populate the attribute picker. For Okta to discover the attribute, it must be added to an object within the User object hierarchy in the directory: user object, a parent object, or an auxiliary object.

The agent takes a few seconds to execute the schema discovery. When it’s done you’ll get a list of the attributes that Okta has the permissions to discover in the directory.

You will see a list of LDAP attributes that Okta has discovered and attempted to map to the default Okta user profile attributes. To edit these mappings, click the pencil icon.

Define your Okta Attribute Mappings. See Map profile attributes.

Configure LDAP to Okta import settings

  1. On the Okta Admin Console, click Directory > Directory Integrations.
  2. Select the LDAP agent from the list of directories.
  3. Click the Provisioning tab and select To Okta in the SETTINGS list.
  4. Click Edit and complete the following settings:
    • Schedule import – Select the frequency for importing users from LDAP to Okta.
    • Okta username format – Specify a username format. When you import users from LDAP, Okta uses this attribute to generate the Okta username. When you access Import Settings during LDAP setup, the username format matches the option you selected when you tested the configuration and you should not need to change it. You can also access this page later and select another option, if necessary. Note that Okta requires user names to be in email format, so ensure the selected option is appropriate for your environment.
    • Update application user name on — This setting cannot be changed.
    • Max Import Unassignment — If an unusual number of app unassignments occurs during an import, Okta triggers an alert to warn against the unintended deprovisioning of a large number of apps from users within an org. The Import Safeguard feature stops the import and suspends subsequent imports.For more details, see Import safeguards.
    • Activation emails — Select if you don't want to send new user activation emails.
    • Incremental import — Select to only import users that were created or updated since your last import. Matching rules are only evaluated on these users. This is the type of import performed by scheduled imports.
    • Decimal place
    • Maximum clock skew  — Incremental import relies on the modifyTimestamp attribute to determine whether an LDAP entry has been imported. However, the system clock on some on-premises LDAP servers could go backward, causing some updates to be missed. To prevent missed updates, set the clock skew to a value that is the maximum potential clock drift of the server. To improve the performance of incremental import, the modifyTimestamp attribute should be indexed on your LDAP server.
  5. Click Save.
  6. To define your User Creation & Matching settings, click Edit and complete the following settings:
    • Matching rules are used in the import of users from all apps and directories that allow importing. Establishing matching criteria allows you to specify how an imported user should be defined as a new user or mapped to an existing Okta user.
    • Imported user is an exact match to Okta user if: Select the match criteria that establishes whether an imported user exactly matches an existing Okta user. Choose any combination from the list of options to establish your criteria. For the new imported user to be considered an exact match, each option that you select must be true. Note that if you choose the third option, the first and second choices are disabled.
    • Allow partial matches: Partial matching occurs when the first and last name of an imported user matches that of an existing Okta user, but the user’s username or/and email address do not.
    • Confirm matched users: Select to automate the confirmation or activation of existing users. Unchecked, matches must be confirmed manually.
    • Confirm new users: Select to automate the confirmation or activation of a newly imported user. If this option is selected, you can uncheck it during import confirmation. Note that this feature does not apply for users who already exist in Okta.
    • For information on deprovisioning, see Provisioning and Deprovisioning Overview.
  7. Click Save.
  8. To define your Profile & Lifecycle Mastering settings, click Edit and complete the following settings:
    • When a user is reactivated in the app: Specify what action Okta should take if the user's account is reactivated in Okta.
      • Reactivate suspended Okta users — Reactivate suspended Okta users if they are reactivated in LDAP.
      • Reactivate deactivated Okta users — Reactivate deactivated Okta users if they are reactivated in LDAP.

  9. Click Save.

Map Okta user profile attributes to LDAP attributes

You can only add attributes to the directory profile if they are already in the directory, so Okta first does a schema discovery step to populate the attribute picker. For Okta to discover the attribute, it must be added to an object within the User object hierarchy in the directory: user object, a parent object, or an auxiliary object.

The agent takes a few seconds to execute the schema discovery. When it’s done you’ll get a list of the attributes that Okta has the permissions to discover in the directory.

Modify the integration settings

When you installed the Okta LDAP agent you defined the integration values. Use this procedure to modify the existing settings.

  1. On the Okta Admin Console, click Directory > Directory Integrations.
  2. Select the LDAP agent from the list of directories.
  3. Click the Provisioning tab and select Integration in the SETTINGS list
  4. In the Version section, 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.
  5. In the Configuration section, complete the following: 
    • 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.
  6. In the User section, complete the following:
    • 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.
    • User 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).
    • Account Enabled Value — The value that indicates that the account is unlocked (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.
  7. In the Extra User Attributes section, you can specify up to four additional attributes to be imported from LDAP.
  8. In the Role section, complete the following:
  1. Validate your configuration settings.
    1. Enter a Username in the Example username field.

      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.

Enable LDAP over SSL

To enable LDAP over SSL (LDAPS) and ensure a secure connection, import the certificate into the trust store. You must issue the import command on the server on which the Okta LDAP Agent is installed.

Before you begin

  • General — When using the keytool, make sure to always choose the keystore option.
  • Ubuntu / Debian — There is no upgrade path. The dpkg tool performs an uninstall and re-install, which deletes the cacerts file.
  • Centos — There is no upgrade path. Issuing yum localupdate <package name> replaces the jre folder, which deletes the cacerts. If the service had already been set up to use SSL, the service fails to start.
  • Windows — There is no upgrade path. The installer removes and re-adds the files. Also, the installer must be running when you are updating the cert store. Canceling the installer deletes the contents of the C:\Okta\Okta LDAP Agent folder.

To import the certificate into the trust store of the Okta LDAP Agent:

  1. Open a terminal and navigate to the jre/bin directory.

    Linux

    /opt/Okta/OktaLDAPAgent/jre/bin

    Windows

    C:\Program Files\Okta\Okta LDAP Agent\jre\bin

  1. Connect to the LDAPS port to confirm that the certificate you have is the one that the server is using:

    openssl s_clientEssentially, a client is anything that talks to the Okta service. Within the traditional client-server model, Okta is the server. The client might be an agent, an Okta mobile app, or a browser plugin. -connect <IP of your LDAP server>:<your SSOAn acronym for single sign-on. In a SSO system, a user logs in once to the system and can access multiple systems without being prompted to sign in for each one. Okta is a cloud-based SSO platform that allows users to enter one name and password to access multiple applications. Users can access all of their web applications, both behind the firewall and in the cloud, with a single sign in. Okta provides a seamless experience across PCs, laptops, tablets, and smartphones. port>

  1. Import the SSL certificate. When you are prompted for the default password, enter changeit.

    ./keytool -importcert -alias example.net.local -file /tmp/example.net.local.cer -keystore ../lib/security/cacerts

  1. List the current contents of the keystore:

    ./keytool -list -keystore ../lib/security/cacerts

  1. Complete the LDAP Agent installation as described in the relevant procedure above (Linux or Windows).

What's next

Delegated authentication and just in time (JIT) provisioning are configured by default, so you do not need to import users. Okta imports users when the user signs in to their Okta home pages (for example, mycompany.okta.com).

Now that you have installed the Okta LDAP agent and successfully integrated with LDAP, you'll want to map your LDAP attributes to their corresponding Okta user profile attributes. See Profile Editor and Profile Mapping.


Related topics

Uninstall or re-install the Okta LDAP agent

LDAP configuration parameters

Reconfigure an Okta LDAP agent

LDAP integration troubleshooting

Top