Use the LDAP Interface to connect to Okta

The 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. Interface uses Universal DirectoryUniversal Directory enables you to store an unlimited amount of users and attributes from applications and sources like AD or HR systems. Any type of attributes are supported including linked-objects, sensitive attributes, and pre-defines lists. All of it accessible by all apps in our OIN catalog, over LDAP or via API. for authentication instead of an LDAP server or 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. (AD). The LDAP Interface lets you use Okta to centralize and manage your LDAP policies, users, and applications that support the LDAP authentication protocol.

The LDAP Interface is a cloud proxy that consumes LDAP commands and translates them to Okta API calls, providing a straightforward path to authenticate legacy LDAP apps in the cloud. To enhance security, you can also add Multi-Factor 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. (MFA) to your LDAP apps with Okta Verify Push and One-Time-Password (OTP).

The LDAP Interface lets you connect LDAP applications to Okta Universal Directory without installing and maintaining Okta 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.s:

The Okta LDAP agent synchronizes user profiles to or from an existing LDAP directory. The LDAP interface lets you migrate certain applications from LDAP or AD servers to Okta.

The Okta LDAP agent is usually deployed inside your firewall. The LDAP interface is managed in the cloud.

LDAP interface authentication policies go through the Okta sign on policy. To implement MFA for your LDAP apps, you can set up network zones for the LDAP apps that connect to Okta and then you apply MFA policies to these zones. Any connections coming from the LDAP apps are required to use MFA. You can also use policies to prevent MFA from being required when accessing LDAP apps.

Known limitations

Enable the LDAP interface

When you enable the LDAP interface, the values you use to connect to the LDAP Interface are displayed. Click View Logs to view LDAP Interface events in the log. The logs can help you troubleshoot connection issues.

  1. Sign in to 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 with Super adminThe super admin receives full access to every item in the Administrative Console and is the only role that can assign administrator roles to other user accounts. Accounts with other administrator role assignments have reduced functionalities to different permission sets. Contact Okta support to create an Okta Mastered account with Super Admin rights. privileges and click Directory > Directory Integrations.
  2. Select one of the following options:
    • If you do not have any directory integrations configured, click the Add LDAP Interface button.
    • If you do have other directory integrations configured, click Add Directory > Add LDAP Interface.
  3. The LDAP Interface is Active by default. To disable it, click the status button and select Deactivate. The status will show as Inactive.

LDAP Interface connection settings

The settings required to connect to Okta vary by application. The following table lists the values that might be required.

Key Value
Host Name

<org_subdomain>.ldap.<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).>.com

where <domain> is either oktapreview, okta, or okta-emea.

Port

StartTLS on port 389

or

LDAPS on port 636.

Base DN

[<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.=users or groups>],<dc=org_subdomain>, dc=<domain> , dc=com

where <domain> is either oktapreview, okta, or okta-emea.

User ID/Bind DN

uid=<username>,<dc=org_subdomain>,dc=<domain>,dc=com

where <domain> is either oktapreview, okta, or okta-emea.

Note: Must be an admin but can be a Read-only admin.

Password

<password for the admin user>

Additional User DN ou=Users
User Object class inetOrgPerson
User Name Attribute uid
User Password Attribute Okta does not expose passwords.
Group Object Class groupofUniqueNames
Group Object Filter
Group Members Attribute uniqueMember
User Members Attribute

memberOf

Note: memberOf is not an indexed value. Using memberOf will result in significantly slower search times.

Use MFA with the LDAP Interface

If your org has implemented MFA for admin users, you need to include your MFA token information and your admin password when you sign in to the LDAP Interface.

The format for entering your password and MFA token is:

<password,MFAtoken>

For example, you enter the following for Okta Verify:

password,123456

where password is your admin user password, and 123456 is the Okta Verify passcode.

For SMS-based and voice verification, the token needs to be generated prior to doing the BIND. For example, after you sign in and press Send Code, resulting in an SMS being sent to the phone. You can then do a BIND and SEARCH with that SMS in the format of password, text code.

Use case: Set up LDAP Interface for JIRA

The following images illustrate the values you enter when you set up an on premises instance of JIRA. You can use this example to help you set up other on premises applications with a similar configuration. Substitute okta or okta-emea with the appropriate values for your org.

NoteOkta does not expose passwords.

 

Use pagination control

The server-side max page size is set to 1000. As soon as the server sends 1001 entries, it will return error 4 (LDAP_SIZELIMIT_EXCEEDED). To overcome this limit, an LDAP client must request entries in a page of <= 1000. Using the ldapsearch command-line from OpenDJ, the example below demonstrates a search with page size of 2. If you use other tools your syntax may vary.

[ldap-tools]$ ldapsearch -h example.<domain>.com -p 636 --useSSL -X --simplePageSize 2 -b "dc=example,dc=<domain>,dc=com" -D "uid=<login>,ou=users,dc=example,dc=<domain>,dc=com" -w -s SUB "objectclass=*" dn dn: dc=example,dc=<domain>,dc=com dn: ou=users,dc=example,dc=<domain>,dc=com
Press RETURN to continue dn: ou=groups,dc=example,dc=<domain>,dc=com dn: uid=example@example.com,ou=users,dc=example,dc=<domain>,dc=com Press RETURN to continue dn: uid=example2@dc=example,dc=<domain>,dc=com,ou=users,dc=example,dc=<domain>,dc=com dn: uid=example.com,ou=users,dc=example,dc=<domain>,dc=com Press

Troubleshooting

The following information provides general troubleshooting information to help you narrow down the causes of errors before contacting Support.

Time limit exceeded

If an LDAP request takes more than two minutes to evaluate, the LDAP Interface stops evaluating and returns error code 3 (time limit exceeded).

SSL connection errors for Java-based clients

If you receive an error similar to the following, all it tells you is that there was a handshake failure.

 

Connection failed, reason: An error occurred while attempting to send the LDAP message to server example.com:636: SSLHandshakeException(message='Received fatal alert: handshake_failure', trace='getSSLException(Alerts.java:192) /

If you use the -Djavax.net.debug=ssl option and rerun your code, you'll see:

** ClientHello, TLSv1.1 RandomCookie: GMT: 1533235844 bytes = { 170, 242, 15, 98, 234, 169, 49, 26, 115, 187, 61, 59, 207, 79, 238, 178, 101, 91, 146, 111, 234, 35, 3, 227, 163, 195, 75, 47 } Session ID: {} Cipher Suites: [TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDH_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_DSS_WITH_AES_128_CBC_SHA, TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA, SSL_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA, TLS_EMPTY_RENEGOTIATION_INFO_SCSV] Compression Methods: { 0 } Extension elliptic_curves, curve names: {secp256r1, secp384r1, secp521r1, sect283k1, sect283r1, sect409k1, sect409r1, sect571k1, sect571r1, secp256k1} Extension ec_point_formats, formats: [uncompressed] Extension server_name, server_name: [type=host_name (0), value=&lt;org&gt;.ldap.okta.com] Connection reader for connection 0 to &lt;org&gt;.ldap.okta.com:636, WRITE: TLSv1.1 Handshake, length = 145
Connection reader for connection 0 to &lt;org&gt;.ldap.okta.com:636, READ: TLSv1.2 Alert, length = 2 Connection reader for connection 0 to &lt;org&gt;.ldap.okta.com:636, RECV TLSv1.2 ALERT: fatal, handshake_failure Connection reader for connection 0 to &lt;org&gt;.example.okta.com:636, called closeSocket() Connection reader for connection 0 to &lt;org&gt;.example.okta.com:636, handling exception: javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure

The above message shows that the client sent a TLSv1.1 packet and the server responded with TLSv1.2 and it rejected the request.

SSL troubleshooting for C-based clients

For C-based clients, you can use SSLTap or openSSL. For example, the following failure shows SSL handshake failure due to SSLv3.

[ldap-tools]$ openssl s_client -connect <org>.ldap.okta.com:636 -ssl3 CONNECTED(00000003) 140736084694024:error:1408F10B:SSL routines:SSL3_GET_RECORD:wrong version number:s3_pkt.c:365: --- no peer certificate available --- No client certificate CA names sent --- SSL handshake has read 5 bytes and written 0 bytes --- New, (NONE), Cipher is (NONE) Secure Renegotiation IS NOT supported No ALPN negotiated SSL-Session: Protocol : SSLv3 Cipher : 0000 Session-ID: Session-ID-ctx: Master-Key: Key-Arg : None PSK identity: None PSK identity hint: None SRP username: None Start Time: 1533239615 Timeout : 7200 (sec) Verify return code: 0 (ok)

 

Handshake failure due to unsupported cipher

The following is an example that shows that SSL handshake is rejected due to unsupported cipher.

[ldap-tools]$ openssl s_client -connect <org>.ldap.okta.com:636 -tls1_2 -cipher DES-CBC3-SHA CONNECTED(00000003) 140736084694024:error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure:s3_pkt.c:1498:SSL alert number 40 140736084694024:error:1409E0E5:SSL routines:ssl3_write_bytes:ssl handshake failure:s3_pkt.c:659: --- no peer certificate available --- No client certificate CA names sent --- SSL handshake has read 7 bytes and written 0 bytes --- New, (NONE), Cipher is (NONE) Secure Renegotiation IS NOT supported No ALPN negotiated SSL-Session: Protocol : TLSv1.2 Cipher : 0000 Session-ID: Session-ID-ctx: Master-Key: Key-Arg : None PSK identity: None PSK identity hint: None SRP username: None Start Time: 1533239822 Timeout : 7200 (sec) Verify return code: 0 (ok)

 


Related topics

Network Zones

Security Policies

Top