Configure 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 chiclets 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.
Note: If you find the instructions in this topic do not match what you see in your user interface, refer to Configure the Okta Java LDAP Agent: new user interface instead.
Okta can integrate with most LDAPv3 directories. The configuration wizard provides templates for the following distributions:
- Oracle Internet Directory
- Sun One LDAP 5.2+, 6.x and 7.x
- Active DirectoryActive Directory (AD) is a directory service that Microsoft developed for the Windows domain networks. It is included in most Windows Server operating systems as a set of processes and services. Initially, Active Directory was only in charge of centralized domain management. Lightweight Directory Services (AD LDS)
To integrate Okta with your LDAP instance, you need the following:
- For Windows Agents – Windows Server 2008 R2 or later, including Windows Server 2019, is required for the Windows-based agent. The Windows server must be able to reach the LDAP host and port.
Note: You must be running IE 10 or later on your Windows Server.
- To improve the security of our integrations, we now only communicate using the TLS1.2 security protocol. For Windows 2008 R2 TLS 1.2 is disabled by default and must be enabled through the registry. If you have Windows 2008 R2, ensure the following regkeys are set correctly:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server] "Enabled"=dword:00000001
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server] "DisabledByDefault"=dword:00000000
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\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. ] "Enabled"=dword:00000001
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client] "DisabledByDefault"=dword:00000000
- For Linux Agents – The Linux-based agent must be installed on an RPM-enabled Linux distribution such as CentOS or Red Hat. We also support DPKG enabled Linux distributions such as Debian or Ubuntu.
- An Okta administrator account to connect the agent with your Okta orgThe Okta container that represents a real-world organization..
- An LDAP user to perform binds and queries from the agent to your LDAP directory. This user must have the ability to look up 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. or roles in the Directory Information Tree (DIT).
To improve the performance of incremental import, the modifyTimestamp attribute should be indexed on your LDAP server.
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.
- Oracle Internet Directory — Oracle Internet Directory (OID) 18.104.22.168.0 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 OUAn acronym of Organizational Unit. Organizational units are Active Directory containers into which you can place users, groups, computers, and other organizational units. It is the smallest scope or unit to which you can assign Group Policy settings or delegate administrative authority./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.
After you install the LDAP agent, you must continue the configuration through 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. Dashboard as described in the following steps:
- Return to Directory > Directory Integrations.
- Click the LDAP agent from the list of directories. It should be marked Not yet configured.
- 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.
- 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:
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.
- 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.
① If the specified group object and group filter is posixGroup . . . ,
② then enter memberUid in the User Attribute field.
① 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).
- Validate your configuration settings.
- 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.
- If email addresses in LDAP are email@example.com . . . ,
- and you select the Email address Okta username format . . . ,
- enter firstname.lastname@example.org 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.
- If the UID in LDAP is already formatted as an email address like email@example.com . . . ,
- and you select the User Id (UID) Okta username format . . . ,
- enter firstname.lastname@example.org 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.
- 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 . . .
- enter email@example.com 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.
- 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 firstname.lastname@example.org in the Username field.
If you wish to use a custom username to sign in to Okta, use the Custom option and the Okta Expression language to map the Okta username format. You can preview your changes to validate your mapping expression. Expressions allow you to concatenate attributes, manipulate strings, convert data types, and more. Okta supports a subset of the Spring Expression Language (SpEL) functions. Find a comprehensive description of the supported functions under Okta Expression Language.
- 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.
- Unique ID
- Distinguished Name
- Full Name
- 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.
- Select an Okta username format.
- 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.
Click Import Settings under LDAP Settings on the left side of the page and configure the following settings:
- Schedule import – Select how often you want Okta to import users from LDAP.
- 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.
- Select Activation emails if you don't want to send new user activation emails.
- Import Matching Rules — Matching rules are used in the import of users from all apps and directories that allow importing. If there is an existing Okta account, LDAP allows you to import and confirm users automatically. Select the automatic confirmation option that matches the policies of your organization. For details on the matching rules, see Import Matching Rules
- Profile MasterA profile master is an application (usually a directory service such as Active Directory, or human capital management system such as Workday) that acts as a source of truth for user profile attributes. A user can only be mastered by a single application or directory at any one time. For more details, see the Profile Master page.
When users are mastered by attribute, we call this attribute-level mastery (ALM). ALM delivers finer grain control over how profiles are mastered by allowing admins to specify different profile masters for individual attributes. Profile mastering only applies to Okta user profiles, not app user profiles. For more details, see Attribute Level Mastering. — This option is enabled by default. Profile masteringMastering is a more sophisticated version of read (import) users. Mastering defines the flow and maintenance of user-object attributes and their lifecycle state. When a profile is mastered from a given resource (application or directory), the Okta user profile’s attributes and lifecycle state are derived exclusively from that resource. In other words, an Okta user mastered by Active Directory (or HR system) has an Okta profile. However, the profile isn’t editable in Okta by the user or Okta admin, and derives its information exclusively from Active Directory. If the lifecycle state of the user in Active Directory moves to Disabled, the linked Okta user also switches to the corresponding lifecycle state of Deactivated on the next the read (import). makes LDAP the identity authority for connected users. When enabled, user profiles are not editable in Okta and changes are synced to Okta during provisioning events. You can disable this option to have LDAP treated as a normal application. If you disable this feature, user updates you perform in LDAP are not pushed back to the user in Okta. For example, if you change a user's name in LDAP , the change does not affect the Okta user. If you disable LDAP as the profile master, you cannot reset a user's LDAP password in Okta because their credentials are still being managed by LDAP.
You can, however, disable Delegated AuthenticationAuthentication is distinct from authorization, which is the process of giving individuals access to system objects based on their identity. Authentication merely ensures that the individual is who he or she claims to be, but says nothing about the access rights of the individual. Authentication methods and protocols include direct auth, delegated auth, SAML, SWA, WS-Fed, and OpenID Connect. (see here) and enable the Sync Password option to push passwords to LDAP. This means that your users have their delegated Okta password, but any subsequent password updates are pushed to LDAP.
- Sync Password — Enable this option if you want each user's LDAP password to be synced to their Okta password. Any subsequent password changes are pushed to the on-premise LDAP server. To enable the Sync Password option, Delegated Authentication must be disabled. Organizations using both Active Directory (AD) and LDAP can now synchronize their user passwords from AD through Okta to LDAP.
For information about Profile Attributes and Mappings, see Using Custom Attributes with LDAP.
If there is an existing Okta account, LDAP allows you to import and confirm users automatically. Select the automatic confirmation option that matches the policies of your organization:
Note: This feature does not apply to CSV-imported user lists.
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.
The imported user is an exact match to an Okta user if: 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 email address do not.
Confirm matched users: Select to automate the confirmation or activation of existing users. Unchecked, matches are 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.
Incremental Import Settings
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.
Note: To improve the performance of incremental import, the modifyTimestamp attribute should be indexed on your LDAP server.
- This is an Early AccessEarly Access (EA) features are opt-in features that you can try out in your org by asking Okta Support to enable them. Additionally, the Features page in the Okta Admin Console (Settings > Features) allows Super Admins to enable and disable some EA features themselves. feature. To enable it, please contact Okta Support.
Create Users — Selecting Enable creates or links a user in LDAP for members of Groups in Okta where LDAP is assigned. If LDAP is the highest priority Profile Master, Okta user profiles are automatically updated based on changes made in LDAP.
- Activation email recipient — Specify where to send the new LDAP account credentials. The recipient is responsible for distributing the credential information to the appropriate user.
- RDN attribute name — Select the attribute type to be used for user Relative Distinguished Name (the leftmost portion of the user Distinguished Name).
You can customize the attribute value on the Profile Editor page.
Note: If you set the RDN attribute to UID, you must map the attribute to the Okta userName attribute. The attribute type you select must be mapped correctly in Profile Editor for this LDAP instance, in the same direction for provisioning.
- Update User Attributes — Okta updates a user's attributes in LDAP when the appAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in. is assigned. Future attribute changes made to the Okta user profile automatically overwrite the corresponding attribute value in LDAP.
- Deactivate Users — Deactivates users' LDAP account when they are unassigned in Okta or their Okta account is deactivated. Accounts can be reactivated if the app is reassigned to a user in Okta.
- Sync Password — Enable this option if you want each user's LDAP password to be synced to their Okta password. Any subsequent password changes are pushed to the on-premise LDAP server. To enable the Sync Password option, Delegated Authentication must be disabled.
LDAP supports Schema discovery. For information about Schema discovery, see About schema discovery.
Now that you have installed the Okta LDAP agent and successfully integrated with LDAP, your next step is to map your LDAP attributes to their corresponding Okta user profile attributes. For information about Profile Attributes and Mappings, see Profile Editor and Profile Mapping.