Connecting to Okta using the LDAP Interface
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 allows cloud-based LDAP authentication against 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. 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). Because these apps are authenticated against Universal Directory, Okta can control access and centralize credentials for 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. This also enables you to centralize and manage all your LDAP resources (policies, users, apps) within Okta. You can also add seamless MFA to your LDAP apps with Okta Verify Push and OTP, providing an extra layer of security.
With typical LDAP integrations, a physical 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. is required. The LDAP Interface allows you to connect LDAP applications to Okta Universal Directory without installing and maintaining physical LDAP agents:
The LDAP agent is meant to synchronize identities to or from an existing LDAP directory. The LDAP interface, on the other hand, allows you to migrate certain apps off of unnecessary LDAP or AD servers and onto Okta.
But in certain cases, you may not be in a position to deprecate your LDAP or AD servers, in which case synchronization may be the more pragmatic solution. Additionally, unlike the LDAP interface which Okta manages in the cloud, the LDAP agent usually has to be deployed inside your firewall.
With the LDAP interface, authentication is done directly against Okta. In addition, the LDAP interface supports other LDAP functions like search.
All the authentication policies for the LDAP interface go through the Okta sign on policy. If you want to require that LDAP apps use MFA you can set up specific network zones for the LDAP apps that will be connecting to Okta and MFA policies for those zones. Then any connections coming from those LDAP apps will be required to use MFA. You can also do the reverse and use policies to prevent MFA from being required when accessing LDAP apps.
- Admins are able to configure an application that currently authenticates users against an LDAPv3 directory to authenticate against Okta's LDAP interface instead.
- Admins are also able to perform basic search functionality via LDAP SEARCH commands.
- Only READ-only commands are supported. WRITE commands are not supported.
- Okta must be the source of truth for the apps.
- The server allows a page size of 1000 entries. If the size of the result exceeds the page size, an LDAP error code is returned. For a large result set, use Simple Pagination Control. For details, refer to https://www.ietf.org/rfc/rfc2696.txt.
- Support for TLS 1.2 only.
- Supports Okta Verify and OTP for multifactor verification.
- Unix or Linux-based PAM authentication is not supported.
- Only Okta 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. are supported. AD Groups and 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. groups are not returned.
- Ability to search on memberOf results in longer search times.
- You must use an Okta user ID. If you are using samAccountName as a log in value for your apps, authentication will fail.
- For LDAP searches that query uniquemember and memberOf attributes, the LDAP Interface iterates through all pages before returning membership response back to the 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. .
- LDAPi defines memberOf as a virtual operational attribute. It is returned only if :
- memberOf is requested in the list of attributes, or
- all operational attributes are requested using '+'
Querying the memberOf attribute may have impact on the rate limits of your orgThe Okta container that represents a real-world organization.. Therefore, it is best to query this attribute only when necessary. Improvements were also made to additional operational attributes that were part of LDAP core schema. This list includes hasSubordinates, structuralObjectClass, entryDN, subschemaSubentry, and numSubordinates. Note that numSubordinates is not calculated for users and groups containers.
- Sensitive attributes and LDAP Interface searches - LDAP Interface search filters that reference sensitive attributes or attributes that do not exist in the schema will not return any results.
For example, if a custom attribute Employee Number is sensitive, then the filter employeenumber=123-45-6789 will not return any results, nor will the filter (|(employeenumber=*)(uniqueIdentifier=*).
Additionally, LDAPi search filters that reference attributes that are not in the schema will not return any results. For example, if the attribute xyz does not exist in the schema, then the filter xyz=foo will not return any results, nor will the filter (|(xyz=*)(bar=*)).
When using Okta Verify multifactor authentication with the LDAP interface, the IP address reported will be the appserver IP rather than the client IP. This is due to limitations in being able to forward the client IP through LDAP.
When you enable the LDAP interface, you see the key values you will use to connect to the LDAP interface. You can also view LDAP interface events in the log on this page, using the View Logs link. These log events can be helpful for troubleshooting if you have issues connecting.
To enable the LDAP interface:
- While signed in as a 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., navigate to Directory > Directory Integrations.
- Do one of the following:
- 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.
- The LDAP Interface is Active by default. To disable it, click the status button and select Deactivate. The status will show as Inactive.
The specific steps to connect to Okta using the LDAP protocol will vary by application. This section provides Okta-specific values you may be prompted for.
<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.
StartTLS on port 389
LDAPS on port 636.
[<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||
where <domain> is either oktapreview, okta, or okta-emea.
Note: Must be an 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. but can be a Read-only admin.
<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||
Note: memberOf is not an indexed value. Using memberOf will result in significantly slower search times.
If your org has implement multifactor authentication (MFA) for admin users, you will be required to include your MFA token information along with your admin password when signing in to the LDAP Interface.
If MFA is enabled, the format for entering your password and MFA token is:
For example, if using Okta Verify, you would enter the following:
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.
Setting up LDAP interface for JIRA on-prem
The series of screen shots below illustrate the values required for setting up Jira on-prem. Use these as a guide for other on-prem applications that may use a similar configuration. The examples below use oktapreview. Substitute okta or okta-emea as appropriate for your org.
Note: Okta does not expose passwords.
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.
The following information provides general troubleshooting information to help you narrow down the causes of errors before contacting Support.
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.
If you use the -Djavax.net.debug=ssl option and rerun your code, you'll see:
Connection reader for connection 0 to <org>.ldap.okta.com:636, READ: TLSv1.2 Alert, length = 2 Connection reader for connection 0 to <org>.ldap.okta.com:636, RECV TLSv1.2 ALERT: fatal, handshake_failure Connection reader for connection 0 to <org>.example.okta.com:636, called closeSocket() Connection reader for connection 0 to <org>.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.
Handshake failure due to unsupported cipher
The following is an example that shows that SSL handshake is rejected due to unsupported cipher.