LDAP integration troubleshooting

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

The schema templates are 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 aren't changed.

Error when you install the agent

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

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

Check the log and look for this entry:

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

If the log contains this entry, you're probably attempting to install Java LDAP agent version 5.3.1 or later. Your environment is where 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 an allowlist.

Alternatively, you can choose to disable SSL pinning as described in the following procedures, but doing so disables a security enhancement provided by the agent.

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

Windows

Install the Okta LDAP Agent from a command line.

  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. In the Admin Console, go to Directory Directory Integrations.
    2. Click Add DirectoryAdd LDAP Directory.
    3. Review the installation requirements, and then click Set Up LDAP.
    4. Click Download Agent and select Download EXE Installer and download it to your Windows server.
  3. Open a command line and run this command: OktaADAgentSetup.exe OktaDisableSslPinning=1
  4. Complete the installation:
    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 page, 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 steps in Enable LDAP over SSL, the error Failed to connect to the specified LDAP server displays.)
  5. Click Next.
  6. 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 that the LDAP proxy server and LDAP server schemas are identical.

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

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

  1. Locate and open the Active Directory agent configuration file:C:\Program Files (x86)\Okta\Okta AD Agent\OktaAgentSetup.exe.config
  2. Change the SSL pinning enabled setting to True:"SslPinningEnabled" value="True"
  3. 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
  2. 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 to import LDAP role objects

Use case

You created a role in your LDAP directory, but the role isn't 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 DirectoryDirectory IntegrationsLDAPSettingsImport 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 many 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 aren't introduced into Okta during import. You can move these objects back in after the import is finished.

LDAP agent installation failure due to FIPS mode configuration

The following scenarios provide troubleshooting steps for resolving LDAP agent installation failure caused by FIPS mode configuration.

  • If the agent installation fails during the interactive flow, rerun the flow and select N when prompted to enable FIPS mode.

  • If an error occurs during the agent upgrade process, turn off FIPS mode by adding fipsMode=false to the configuration file, and then rerun the installation command.

Error when verifying username

When verifying your username, you receive the following error: Username: Does not match required pattern.

The username must be in an email format. Verify that the import settings are set correctly. See Install and configure the Okta LDAP agent.

Error after selecting the SSL checkbox

You selected the Use SSL connection checkbox and you receive the following error: Failed to connect to the specified LDAP server displays.

Make sure that you have enabled LDAP over SSL (LDAPS). See Enable LDAP over SSL.