Configure LDAP integration settings

After installing the Okta LDAP Agent, you'll need to configure the integration settings to allow data to be exchanged with Okta.

  1. In the Admin Console, go to DirectoryDirectory Integrations.
  2. Click the Okta LDAP Agent marked Not yet configured.
  3. Configure the following settings:
    • LDAP Version: Select an LDAP provider. See Supported LDAP directories.

      When you select an LDAP provider, provider-specific configuration values are automatically added. If your LDAP provider isn't in the list, complete the configuration fields manually, using information from your provider's documentation. Confirm that the default values are correct. Not all configuration settings must have values.

      After you select your LDAP provider, configure your integration, and use your integration in your org, you can't change this integration's provider. You need to create another integration and configure it with the different LDAP provider.

    • 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 org. 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, the 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.
    • 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: 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.

      The filter must follow the 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 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 isn't 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 more user attributes to import from LDAP.
  5. Complete the Group or Role section. Typically, only one of these is used.

    Group

    • Group Search Base: Enter the DN of the container for group searches (that is, the root of the group subtree) that contains the groups to import into your Okta org. For example: ou=groups, dc=example, dc=com.
    • Group Object Class: Enter the objectClass of the group that Okta uses in its query when importing groups. For example, groupofnames, groupofuniquenames, posixgroup.
    • Group Object Filter: An auto-populated value when a supported LDAP provider is selected. (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 are explicitly posixGroup and (objectclass=posixGroup), leave this field empty. If you're using posixGroup, it's best to configure the member attribute value to memberUID and the user attribute value to uid. Consider the following two scenarios:
      • If the specified group object and group filter are both posixGroup, then enter memberUid in the User Attribute field.
      • If the specified group object and group filter are something other than posixGroup, then leave the User Attribute field blank.

    Role

    • 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).
  6. Configure the following settings in the Validation configuration section:
    1. Example username.

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

      Okta requires usernames be in an email format. Configuring these options correctly ensures that your usernames satisfy this requirement.

      • Email address

        Select this option if you want a user's LDAP email address to be their Okta username. Email addresses must be unique in LDAP.

        For example, if email addresses in LDAP are user.name@example.com, and you select the Email address Okta username format, enter user.name@example.com in the Username field.

      • Employee Number (employeeNumber)

        Select this option to use a user's employee number as the Okta username.

      • Common Name (CN)

        Select this option to use a user's common name as the Okta username.

      • User Id (UID)

        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 user.name@example.com, and you select the User Id (UID) Okta username format, enter user.name@example.com in the Username field.

      • User Id (UID) + Configurable Suffix

        Select this option only if the UID value in LDAP lacks an email suffix and you want end users to sign 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 yourconfigurablesuffix.com in the Configurable Suffix field, and enter user.1234@yourconfigurablesuffix.com in the Username field.

      • User Id (UID) @ Domain

        Select this option only if the UID value in LDAP lacks an email suffix and you want Okta usernames 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 user.1234@yourdomainname.com in the Username field.

      • Choose from schema

        Select this option to use a single-value, LDAP string attribute as the Okta username. A list of available attributes appears when you select this option.

    2. Enter a Username.

      Enter the username of a user in the specified username format. The username that you enter uniquely identifies a single user in your LDAP directory. Okta runs a query that retrieves the following list of details for that specific user. Validate that the 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 aren't listed here, group imports might fail later.
    1. Click Test Configuration.

      When your configuration settings are valid, the message Validation successful! displays along with information about the returned user object. If there's a problem with your configuration or if the user isn't found, you're prompted to review your settings.

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

    After validating your settings, Okta begins the LDAP schema discovery process.