Install and Configure the Okta Java LDAP Agent Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka02a0000005ujmsaa&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2finstall-and-configure-the-okta-java-ldap-agent-1697779769
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
1
2
3
4
5
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Average Rating:
Install and Configure the Okta Java LDAP Agent
Published: Jan 31, 2018   -   Updated: May 15, 2018

okta-doc-source

Install and Configure the Okta Java LDAP Agent

To integrate Okta with your LDAP directory, install and configure the Okta Java LDAP agent. LDAP integration allows end users 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.

For more information about Okta's LDAP agent, see the LDAP Agent Deployment Guide.

Requirements

Okta can integrate with most LDAPv3 directories. The configuration wizard provides templates for the following distributions:

  • OpenDJ
  • OpenLDAP
  • Oracle Internet Directory

    Known Issue: Oracle Internet Directory (OID) 11.1.1.7.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.

  • IBM
  • Sun One LDAP 5.2+, 6.x and 7.x
  • Active Directory Lightweight Directory Services (AD LDS)

To integrate Okta with your LDAP instance, you need the following:

  • For Windows Agents – Windows Server 2008 or later 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.

  • 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 org.
  • 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 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.

Installing the LDAP Agent on Linux
  1. Select Directory > Directory Integrations.
  2. Select Add LDAP Directory.
  3. Review the installation requirements, and then click Set Up LDAP.
  4. Click Download Agent.
  5. From the drop-down menu, choose your required installer option (.rpm or .deb).
  6. 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.
  7. 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.

  1. Enter y to continue.

    A message displays indicating that the installation was successful. Instructions display describing how to run the agent configuration script.

  1. (Optional) If you want to enable LDAP over SSL (LDAPS), perform the procedure Enabling LDAP Over SSL, then return to this procedure and complete it.
  2. Issue the following command from root to run the script:

    /opt/Okta/OktaLDAPAgent/scripts/configure_agent.sh

    Note: Make sure that you run the script from root.

  1. When prompted, enter your org URL. This is provided in your browser in the LDAP Setup wizard.
  2. Enter the hostname of your LDAP server.
  3. Enter your LDAP admin DN.
  4. Enter your LDAP admin password.
  5. Enter your base DN.
  6. Indicate whether you are using SSL, and if so, enter the port number.
  7. Enter your LDAP server port number.
  8. If you are using a proxy, enter the proxy information, as prompted.
  9. When you are prompted to go to your Okta org to authenticate as an admin, copy the URL provided in the output and paste it into your browser.

    For example:

    Please visit the URL: https://myOrg.okta.com/oauth2/auth?code=12y2792a before Mon Jul 27 16:58:37 PDT to authenticate and continue agent registration.

  1. If necessary, log in to your Okta admin account.
  2. Click Allow Access to access the Okta API.

    Note: If an error message displays during this step, see Troubleshooting.

  1. Click Continue.
  2. At the message LDAP agent started! click Next.
  1. From your terminal window, start the LDAP agent by issuing the following command:

    service OktaLDAPAgent start

  1. To confirm that the agent is running, issue the following command:

    service OktaLDAPAgent status

    Note: LDAP schemas and configuration vary widely. Okta recommends having a LDAP browser available (for example, Apache Directory Studio) to query the LDAP directory.

  1. Continue to configure your LDAP settings as described below (see Configuring Your LDAP Settings ).
Installing the LDAP Agent on Windows
  1. Go to Directory > Directory Integrations.
  2. From the drop-down menu, select Add LDAP Directory.
  3. Review the installation requirements, and then click Set Up LDAP.
  4. Click Download Agent.
  5. From the drop-down menu, select the .exe installer and download it to your Windows server.
  6. Double click the file and then click Run.
  7. If the message displays Do you want to allow the following program to make changes to this computer?, click Yes.
  8. Click Next.
  9. At the license agreement, click Next.
  10. At the Installation options dialog box, specify an installation folder, and then click Install.
  11. (Optional) If you want to enable LDAP over SSL (LDAPS), perform the procedure Enabling LDAP Over SSL, then return to this procedure and complete it.
  12. 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:

      ldap.mycompany.com:389

    • 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 Enabling LDAP Over SSL, the error Failed to connect to the specified LDAP server displays.)
  1. Click Next.
  2. (Optional) Enter a proxy server for your LDAP agent on the Okta LDAP Agent Proxy Configuration page, and then click Next.
  3. To register the LDAP Agent with the Okta service, enter your Okta subdomain name, and then click Next.
  4. On the Okta Sign In page, enter the username and password for your Okta admin account, and then click Sign In.
  5. Click Allow Access to access the Okta API.

    Note: If an error message displays during this step, see Troubleshooting.

  1. Click Finish when the installation is complete.
  2. Continue to configure your LDAP settings as described below (see Configuring Your LDAP Settings ).
Uninstalling the LDAP Agent

When you uninstall and reinstall your LDAP agent, you must decide whether or not you also want to remove the old Okta API token from your system. If you are performing an upgrade, you are not required to do so. To remove the API token, you must delete the Okta LDAP Agent folder, and deactivate and remove your old LDAP agent.

Note: If you intend to continue using an LDAP agent, to avoid downtime you must have at least two agents running before you uninstall one of them.

Uninstalling the LDAP Agent on Windows

  1. On your Windows server, go to Start > Control Panel > Programs > Programs and Features.
  2. Select the Okta LDAP Agent, and then click Uninstall/Change.
  3. Uninstalling your LDAP agent leaves the agent configuration data on your hard drive. To remove the configuration data, go to \Program Files\Okta and delete the Okta LDAP Agent folder. Deleting this folder removes the agent configuration data and the API Token from your hard drive. The API token for the server is still valid in Okta, so it is important that you remove the configuration data.

Uninstalling the LDAP Agent on Linux

On your Linux server, issue the appropriate command:

Debian:

dpkg --remove OktaLDAPAgent

RPM:

yum remove OktaLDAPAgent

Issuing the remove command removes the agent, all the agent configuration data, and the API Token from your hard drive. The API token for the server is still valid in Okta so it is important to remove the configuration data.

Reinstalling the LDAP Agent

Installing the LDAP agent does not overwrite the configuration data in the Okta LDAP Agent folder. If you want to reinstall and create a new API token, make sure you delete the Okta LDAP Agent folder (as described above) before you reinstall the LDAP agent. Then perform the following steps to reinstall your LDAP agent and deactivate and remove the old LDAP agent in Okta.

  1. Perform the LDAP agent installation procedure for your operating system (Installing the LDAP Agent on Linux or Installing the LDAP Agent on Windows ) as described above.
  2. Go to Directory > Directory Integrations > LDAP, and then click the Settings tab.
  3. Your agents are listed under Agent Monitors. Confirm that your reinstalled LDAP agent is connected to Okta and appears in the list. Make sure to have at least one LDAP agent online.

    If you are performing an upgrade or reinstall and you do not want to revoke the Okta API token of the old LDAP agent, you are finished. Otherwise, proceed to the next step.

  1. Under Agent Monitors, click Deactivate for the old LDAP agent and then click Ok to confirm. Deactivating the agent revokes its API token.
  2. Under Agent Monitors, click Remove for the old LDAP agent and then click Ok to confirm.
Configuring Your LDAP Settings

After you install the LDAP agent, you must continue the configuration through the Okta Admin Dashboard as described in the following phases:

Phase Ⓐ — LDAP Configuration

Phase Ⓑ — Import Settings

Phase Ⓒ — Provisioning Features

Phase Ⓐ — 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, 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.
    • User Object Class — The objectClass of a user that Okta uses in its query when importing users. For example, inetorgperson, posixaccount, posixuser.
    • This is an Early Access feature. To enable it, please contact Okta Support.
      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 — The user attribute that indicates whether a password is expired.
    • 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

    • 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.
    • 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 — The attribute on the user object that the membership attribute points to. If this value is left blank, the user object DN is used by default.

      Example 1

      ① If the specified Member Attribute is uniquemember . . . ,

      ② and uniquemember contains the DN attribute of the user  . . . ,

      ③ then enter DN in the User Attribute field.

      Example 2

      ① If the specified Member Attribute is posixuser . . . ,

      ② and posixuser contains the UID attribute of the user  . . . ,

      ③ then enter UID in the User Attribute field.

    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).
  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 user.1234@example.com . . . ,

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

      ③ enter user.1234@example.com 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 user.1234@example.com . . . ,

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

      ③ enter user.1234@example.com 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 yourconfigurablesuffix.com in the Configurable Suffix field . . .

      ④ enter user.1234@yourconfigurablesuffix.com in the Username field.

       

      User Id (UID) @ Domain 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 user.1234@yourdomainname.com 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.

Phase Ⓑ — Import Settings

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 Master — This option is enabled by default. Profile mastering 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 Authentication (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 Active Directory.

Import Matching Rules

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.

Imported user is an exact match to 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/and 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

This is an Early Access feature. To enable it, please contact Okta Support.

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.

Phase Ⓒ — Provisioning Features

  • This is an Early Access 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.

      RDN_LDAPAgent3

      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.

      RDN_LDAPAgent4

  • Update User Attributes — Okta updates a user's attributes in LDAP when the app 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. This is an EA feature for LDAP users. For information about Schema discovery, see About schema discovery. For information about Profile Attributes and Mappings, see Profile Editor and Using Custom Attributes with Active Directory.

This completes your LDAP directory integration. By default, delegated authentication and JIT provisioning are configured, so you do not need to import users. Okta imports users when they sign into their Okta home pages (for example, mycompany.okta.com).

Enabling 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 Java LDAP Agent is installed.

Important 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 Java 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_client -connect <IP of your LDAP server>:<your SSO 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).
Changing Your Agent Configuration

To change your LDAP configuration, choose the method appropriate for your platform.

Windows

Uninstall and then reinstall the agent, and then specify new configuration settings during setup.

Linux

  1. Run an update script by issuing the following command from the command line:

    /opt/Okta/OktaLDAPAgent/scripts/update.sh

  1. Issue any of the following commands:
CommandDefinitionExample
[-b]ldap.dn.baseNewBaseDN
[-a]ldap.admin.dnNewLDAPAdminDN
[-w]ldap.admin.passwordNewLDAPPassword
[-h]ldap.hostNewLDAPHost
[-p]ldap.portNewLDAPPort

You can combine parameters. For example:

/opt/Okta/OktaLDAPAgent/scripts/update.sh -h 192.168.3.81 -p 389

Obtaining Log Information

Windows

The LDAP agent logs information to:

C:\Program Files\Okta\Okta LDAP Agent\logs\agent.log

You can modify the log level by editing the log4j configuration file at:

C:\Program Files\Okta\Okta LDAP Agent\conf\log4j.properties

Linux

The LDAP agent logs information to:

/opt/Okta/OktaLDAPAgent/logs/agent.log

You can modify the log level by editing the log4j configuration file at:

/opt/Okta/OktaLDAPAgent/conf/log4j.properties

Troubleshooting

To troubleshoot LDAP issues, obtain an LDAP browser such as Apache Directory Studio.

Note that the schema templates are merely suggestions based on common values. Each LDAP environment is unique and might require you to override the default values with your environment-specific settings. You can use Apache Directory Studio to examine attributes for existing users and groups to verify the template values, or you can select the appropriate setting.

Changing templates modifies all template default values. Settings that you override are not changed.

Error when installing the agent

During agent installation, after clicking Allow Access, the following error message displays:

Failed to parse response from Okta and Unable to register the agent. Error code 12.

Check the log and look for the entry,

javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No valid public key found in certificate chain.

If the log contains the above entry, then you are probably attempting to install Java LDAP agent version 5.3.1 or later and your environment is one in which the agent's support for SSL certificate pinning prevents communication with the Okta server. This is most likely to occur in environments that rely on SSL proxies. To allow installation to complete in this case, Okta recommends that you bypass SSL proxy processing by adding the domain okta.com to a whitelist.

Alternatively, you can choose to disable SSL pinning as described below, but be aware that doing so disables a security enhancement provided by the agent.

To disable support for SSL certificate pinning, perform the procedure below appropriate for your operating system:

Windows

Note: Some of these steps use the Okta Active Directory agent setup modules. This is strictly for functionality; Active Directory is not required to use LDAP.

Install the agent from a command line as follows:

  1. Perform steps 1 through 5 of the procedure Installing the LDAP Agent on Windows.
  2. Instead of double-clicking the file as directed in step 6, open a command line and enter the following:

    OktaADAgentSetup.exe OktaDisableSslPinning=1

  1. Press Enter.
  2. Complete the installation as described in Installing the LDAP Agent on Windows.

If you want to re-enable support for SSL certificate pinning if it was disabled:

  1. Locate and open the AD agent configuration file:

    C:\Program Files (x86)\Okta\Okta AD Agent\OktaADAgentSetup.exe.config

  1. Change the SSL pinning enabled setting to True:

    "SslPinningEnabled" value="True"

  1. Save the configuration file and restart the agent.

Linux

  1. From a command line, change the SSL pinning enabled setting to false:

    $ sudo /opt/Okta/OktaLDAPAgent/scripts/configure_agent.sh -sslPinningEnabled false

  1. Save the configuration file and restart the agent.

If you want to re-enable support for SSL certificate pinning after you have completed installation, open OktaLDAPAgent.conf and change the SSL pinning enabled setting to true.

For more information about SSL certificate pinning, see the article by the Open Web Application Security Project.

Difficulty importing LDAP role objects

Use case

You created a new role in your LDAP directory, but the role is not imported into Okta when users assigned to the role sign in to Okta, even though JIT is enabled.

When does Okta bring LDAP roles into Okta?

Okta brings LDAP roles into Okta only during imports, not during JIT. Once brought into Okta, LDAP roles are represented as groups.

When does Okta bring LDAP groups into Okta?

Okta brings LDAP groups into Okta during imports and JIT.

Workarounds

If you don’t want to import all user accounts into Okta, consider implementing any of the following workarounds in your Preview org. If you get the results that you expect, you can then implement the workaround in your Production org.

Import a group into Okta that has the same membership as a particular LDAP role

  1. Create a group in LDAP that has the same membership as the role in LDAP that you want to import.

  2. Using either JIT provisioning or an LDAP Import, bring that group and its membership into Okta and assign it to the desired application or integration.

Perform an LDAP import into Okta without confirming undesired objects

  1. In Okta, go to Directory > Directory Integrations > LDAP > Settings > Import Settings.

  2. In the Import Matching Rules section, scroll down to When no match found and select Manually confirm new user. This ensures that no new user accounts are created in Okta automatically when you run an import.

  3. Run an import against your LDAP directory to import the group you created in Step 1. Group members are added to the group later when they JIT into Okta.

Temporarily segregate inactive LDAP accounts

If you don’t want to perform an import because your LDAP directory contains a large number of inactive user accounts, you can perform the following workaround to identify likely inactive accounts and segregate them before you import:

  1. Run a query against your LDAP directory for the attribute lastlogon (or another attribute that filters for inactive accounts).

  2. Move the inactive user objects out of their synchronization container to ensure they are not introduced into Okta during import. You can move these objects back in after the import is finished.

Error when verifying username

When verifying your username, you receive the error

Username: Does not match required pattern

The username must be in an email format. Verify that the import settings are set correctly as described in the Validate Configuration Settings step of the Configure Your LDAP Settings procedure.

Error after selecting the SSL check box

You selected the Use SSL connection check box and you receive the error

Failed to connect to the specified LDAP server displays.

Make sure that you have enabled LDAP over SSL (LDAPS) when configuring the LDAP agent.

Post a Comment