LDAP Authentication

LDAP Cached Credentials

If you configure an instance to use LDAP cached credentials, it stores (caches) a copy of the credentials that it most recently used to authenticate each user. If an instance supports cached credentials and it cannot connect to the LDAP server, then it uses the cached LDAP credentials to authenticate users. This can be caused by an issue with the LDAP server itself or with the connection to the server.

To secure cached credentials, InterSystems IRIS stores all LDAP passwords in the security database as a one-way hash. If the instance cannot use the LDAP server to validate the user, it then attempts to confirm that:

• The hash of the entered password matches the hash of the stored password

• The cached expiration date from the last LDAP login has not been reached

If both conditions are true, the instance authenticates the user and login proceeds; otherwise, login fails.

LDAP Configuration Fields

An LDAP configuration includes the following fields:

• Login Domain Name — Required. The name of the LDAP configuration. This is typically in the form of example.com or example.org.

  If you enter a value that does not include a period, the system appends .com to it, so that example becomes example.com. If you enter a value in uppercase, the system puts in lowercase, so that EXAMPLE.COM becomes example.com. The system performs both transformations, if appropriate.

  The system uses the transformed value of the Name field to populate the LDAP Base DN to use for searches field.

• Description — Any text to describe the configuration.

• Copy from — Available only when creating a configuration. Whether or not InterSystems IRIS copies attributes from an existing LDAP configuration to specify initial values for this one.

• LDAP Enabled — Whether or not InterSystems IRIS can use the configuration to connect to an LDAP server.

• LDAP server is a Windows Active Directory server — Windows only. Whether or not the LDAP server is a Windows Active Directory server.

• LDAP hostnames — Required. The name(s) of the host(s) on which the LDAP server is running. Separate multiple hostnames using spaces as a delimiter. The complexity of each hostname can range from an unqualified hostname to fully-qualified hostname with a port number; the required form of the hostname(s) depends on the particular configuration.

  If the LDAP server is configured to use a particular port, you can specify it by appending “:portname” to the hostname; typical usage is not to specify a port and to let the LDAP functions use the default port. You can specify the domain example.com as your hostname if you have multiple replicated domain servers on your network like:

  ldapserver.example.com
  ldapserver1.example.com
  ldapserver2.example.com
  ldapserver3.example.com
  

  LDAP performs a DNS query for the addresses of all the matching LDAP servers and then automatically selects one to connect to.

  Important:

  Including a port number in the value of LDAP hostnames affects the TLS behavior when establishing a connection:

  • If the value specified contains a port number other than 636, such as ldapserver.example.com:389 and the Use TLS/SSL encryption for LDAP sessions check box is selected, then the instance attempts to establish a plaintext connection to the LDAP server and then issue a StartTLS command to encrypt the connection.

  • If the value specified for LDAP hostnames contains the port number 636, such as ldapserver.example.com:636, then the instance attempts to establish a TLS connection with the LDAP server directly—whether or not the Use TLS/SSL encryption for LDAP sessions check box is selected. Note, however, that connecting directly to port 636 from UNIX® client instances is not supported.

  For background, see the class reference for the %SYS.LDAP.Init()Opens in a new tab method.

• LDAP search information — varies by circumstances:

  • LDAP username to use for searches — For Windows Active Directory servers only. Required if available. The user name provided to the LDAP server to establish an initial connection and which is used to perform LDAP searches and lookups. This user is also known as the search user.

    The search user must have permission to read the entire LDAP database. It is important to ensure that the search user has uninterrupted access to the LDAP database. For example, the user’s LDAP account should be set so that:

    • The user cannot change the account’s password

    • The password never expires

    • The account never expires

    For more information on searching the LDAP database, see How LDAP Looks Up the Target User in Its Database.

  • LDAP search user DN — For all non-Windows platforms and Windows non-Active Directory servers. Required if available. The Distinguished Name (DN) of the user provided to the LDAP server to establish an initial connection and which is used to perform LDAP searches and lookups. This user is also known as the search user.

    The search user must have permission to read the entire LDAP database. It is also important to ensure that the search user has uninterrupted access to the LDAP database. For example, the user’s LDAP account should be set so that:

    • The user cannot change the account’s password

    • The password never expires

    • The account never expires

    For example, if the search user is “ldapsearchuser”, the LDAP DN (distinguished name) might be as follows:

    uid=ldapsearchuser,ou=People,dc=example,dc=com 
    

    For more information on searching the LDAP database, see How LDAP Looks Up the Target User in Its Database.

• LDAP username password — Available only when creating or modifying a configuration. The password associated with the account used for the initial connection.

• LDAP Base DN to use for searches — Required. The point in the directory tree from which searches begin. This typically consists of domain components, such as DC=example,DC=com.

• LDAP Base DN for Groups to use for searches — Required. The point in the directory tree from which searches for nested groups begin. This typically consists of organizational units and domain components, such as OU=IRIS,OU=Groups,DC=test,DC=com. By default, this is set to the same value as LDAP Base DN to use for searches.

• LDAP Unique search attribute — Required. A unique identifying element of each record, which therefore makes it appropriate for searches. For more information on searching the LDAP database, see How LDAP Looks Up the Target User in Its Database.

• Use TLS/SSL encryption for LDAP sessions — Whether or not the InterSystems IRIS instance and the LDAP server encrypt their communications using TLS (disabled by default).

  Important:

  InterSystems recommends that you enable TLS encryption for LDAP.

  For connections to Active Directory servers, note the following:

  • When enabled for an LDAP connection from an instance on Windows to an Active Directory server, the connection uses port 636 (which is a TLS-encrypted port).

  • When enabled for an LDAP connection from an instance on UNIX® to an Active Directory server, InterSystems IRIS first establishes the connection on port 389 (the unencrypted LDAP port); encryption is then turned on by a StartTLS call.

  InterSystems also recommends setting the LDAP server signing requirements parameter to Require signature on the Active Directory Server. This prevents any LDAP bind command on the server on port 389 to be executed unless the channel is encrypted with StartTLS. For more information, see Domain Controller: LDAP Server Signing RequirementsOpens in a new tab article on the Microsoft web site.

• File with Certificate Authority certificate(s) to authenticate the LDAP server — UNIX® only. The location of the file containing any TLS certificates (in PEM format) being used to authenticate the server.

  On Windows, to specify the location of a file containing any TLS certificates (in PEM format) being used to authenticate the server certificate to establish a secure LDAP connection, use Microsoft Certificate ServicesOpens in a new tab. Certificates must be installed in the Certificates (Local Computer)\Trusted Root Certification Authorities certificate store.

• Allow ISC_LDAP_CONFIGURATION environment variable — If you are using OS-based LDAP and multiple domains, specifies whether or not to use the ISC_LDAP_CONFIGURATION environment variable. If the environment variable is defined, then OS-based LDAP uses it to determine which LDAP configuration to use for authentication.

• Use LDAP Groups for Roles/Routine/Namespace — Whether or not the user’s roles, routine, and namespace come from the user’s group memberships (true by default); if not, then they come from the attribute fields of the user’s LDAP record. If you select this field, the system enables and disables other fields (see each subsequent field for details).

  Note:

  InterSystems recommends the use of LDAP groups for authorization, rather than LDAP attributes (including InterSystems registered LDAP properties). If you have existing code or are otherwise required to use registered properties, see Configure Authorization with LDAP Attributes for details.

• Search Nested Groups for Roles/Routine/Namespace — Only active if LDAP server is a Windows Active Directory server and Use LDAP Groups for Roles/Routine/Namespace are selected. Whether or not search returns all of a user’s nested groups. See Nested Groups for more information on nested groups.

• Organization ID prefix for group names — Only active if Use LDAP Groups for Roles/Routine/Namespace is selected. See LDAP Group Name Configuration for more information.

• Allow Universal group Authorization — Only active if Use LDAP Groups for Roles/Routine/Namespace is selected. Whether or not searches use the attributes on the LDAP server that are relevant for all InterSystems IRIS instances. See Create Universal LDAP Authorization Groups for more information.

• Authorization Group ID — Only active if Use LDAP Groups for Roles/Routine/Namespace is selected. The multiple-instance group to which this instance belongs. See Create LDAP Authorization Groups for Multiple Instances (Multiple-Instance Groups) for more information.

• Authorization Instance ID — Only active if Use LDAP Groups for Roles/Routine/Namespace is selected. The single-instance group to which this instance belongs. See Create LDAP Authorization Groups for a Single Instance (Single-Instance Groups) for more information.

• User attribute to retrieve default namespace (not active if LDAP groups are selected) — The attribute whose value is the source for the Startup namespace property for a user. This property of an InterSystems IRIS user is described in User Account Properties; this LDAP property is described in Configure Authorization with LDAP Attributes.

• User attribute to retrieve default routine (not active if LDAP groups are selected) — The attribute whose value is the source for the Tag^Routine property for a user. This property of an InterSystems IRIS user is described in User Account Properties; this LDAP property is described in Configure Authorization with LDAP Attributes.

• User attribute to retrieve roles (not active if LDAP groups are selected) — The attribute whose value determines the roles to which a user is assigned. When creating this attribute, it must be specified as an LDAP multivalued attribute. For information about an InterSystems IRIS user’s roles, see the Roles tab of a user’s Edit User page; this LDAP property is described in Configure Authorization with LDAP Attributes.

• User attribute to retrieve comment attribute — The attribute whose value is the source for the Comment property for a user. This property is described in User Account Properties. Once a user has logged in, you can retrieve the value of this property using the Security.Users.Get() method.

• User attribute to retrieve full name from — The attribute whose value is the source for the Full name property for a user. This property is described in User Account Properties. Once a user has logged in, you can retrieve the value of this property using the Security.Users.Get() method.

• User attribute to retrieve mail address — The attribute whose value is the source for the Email address property for a user. This property is described in User Account Properties. Once a user has logged in, you can retrieve the value of this property using the Security.Users.Get() method.

• User attribute to retrieve mobile phone — The attribute whose value is the source for the Mobile Phone Number property for a user. This property is described in User Account Properties. Once a user has logged in, you can retrieve the value of this property using the Security.Users.Get() method.

• User attribute to retrieve mobile provider from — The attribute whose value is the source for the Mobile Phone Service Provider property for a user. This property is described in User Account Properties. Once a user has logged in, you can retrieve the value of this property using the Security.Users.Get() method.

• LDAP attributes to retrieve for each user — Any attributes whose values are the source for any application-specific variables. Application code can then use the Get method of the Security.UsersOpens in a new tab class to return this information.

The values of the fields of an LDAP configuration are stored in an instance of the Security.LDAPConfigsOpens in a new tab class.

Note on LDAP/Kerberos Configuration Fields

If Kerberos authentication is enabled for an instance, then the page for creating an LDAP configuration is Edit LDAP/Kerberos configurations page. It has the same fields as the Edit LDAP configurations page, as described in LDAP Configuration Fields.

The Security LDAP Configurations Page

The Portal’s Security LDAP Configurations page (System Operation > LDAP Configurations) displays a list of the instance’s LDAP configurations. Click the name of a configuration to view its properties. If Kerberos authentication is enabled for the instance, this is called the Security LDAP/Kerberos configurations page (System Operation > LDAP/Kerberos configurations).