Using LDAP

Caché provides support for authentication and authorization using LDAP, the Lightweight Directory Access Protocol. LDAP systems have a central repository of user information, from which Caché retrieves information. For example, on Windows, a domain controller using Active Directory is an LDAP server. This means that an instance of Caché running on this type of Windows domain can use LDAP for its authentication; if an instance is using LDAP authentication, it then also has the option of using LDAP authorization.

This chapter covers the following topics:

A Note on Securing Outbound LDAP Connections

This chapter describes using LDAP for authentication and authorization when connecting to Caché. If you are establishing an outbound connection from Caché to an LDAP server and need to secure the connection, Caché includes support for TLS for these purposes. This is described in the class documentation for %SYS.LDAPOpens in a new tab, in the content for the InitOpens in a new tab method.

Overview of Using LDAP with Caché

The procedure for configuring a Caché service or application to use an existing LDAP server for authentication (and optional authorization) is as follows:

Configure the LDAP server to use the registered LDAP properties.
On the LDAP Options page, configure Caché to use the LDAP server. This includes specifying the names of LDAP user properties to be used for setting the values of properties of Caché users.
Set up Caché to use LDAP. This involves enabling LDAP for the entire instance of Caché and then enabling it for the relevant services or applications.

Note:

This chapter primarily discusses the use of LDAP for both authentication and authorization. For information on using OS-based authentication in conjunction with LDAP authorization, see the Using LDAP Authorization with OS-Based Authentication section.

When a user attempts to authenticate to an instance of Caché that uses LDAP authentication, the process is:

The user is prompted for a user name and password. This user, who is trying to authenticate, is known as the “target user.”
Caché establishes a connection to the LDAP server using the values specified for the LDAP username to use for searches and LDAP username password. This user, who has privileges to search the LDAP database so that Caché can retrieve information, is known as the “search user.”
Once the connection is established, the next step is to look up the user in the LDAP database using the LDAP Unique search attribute.
If Caché locates the target user in the LDAP database, it retrieves the attributes associated with the user, such as the user’s initial roles and namespace.
Caché then attempts to authenticate the user to the LDAP database, using the user name and password provided in step 1.
If authentication succeeds, the user can then interact with Caché based on the privileges associated with the user’s roles and any publicly available resources. The user’s properties are displayed read-only in the Management Portal and are not editable from within Caché (since all the information is coming from outside Caché).

Notes on Using LDAP with Caché

Note the following points when using LDAP with Caché:

If you have more complex authentication and authorization requirements, it is also possible to use delegated authentication to authenticate using the LDAP server. This requires that you use calls to the %SYS.LDAPOpens in a new tab class as part of the custom authentication code in the ZAUTHENTICATE routine. For sample code that performs these actions, see the LDAP.mac routine in the SAMPLES namespace. For more details about delegated authentication and the ZAUTHENTICATE routine, see the “Delegated Authentication” chapter.
Caché supports LDAP version 3 protocols. Earlier LDAP protocols are not supported.
If you using the Caché LDAP APIs with certificates on UNIX® and need detailed debugging information, you may wish to use the ldapsearch program that is part of the OpenLDAP package. Once you have corrected any problems with certificates, the Caché LDAP APIs should also be corrected. The ldapsearch program may also be useful for debugging other LDAP connection problems.
If you need to authenticate to LDAP or use Caché authentication after collecting credentials through another mechanism, call $SYSTEM.Security.Login with those credentials to authenticate the user.

Using LDAP Authorization

In addition to performing authentication with LDAP, Caché supports LDAP authorization. To perform LDAP authorization with Caché, InterSystems recommends the use of LDAP groups.

LDAP groups are a way to assign privileges to users using an LDAP or Active Directory server. The names of groups are specified by the schema on the local LDAP server; typically, the local LDAP administrator defines these names (though Caché uses the predefined name structure described below). Each group has a distinguished name (DN) that uniquely identifies it. You can then assign each user to an LDAP group, and that group then determines the user’s access to Caché roles, routines, and namespaces. (Note that when defining these groups on your LDAP server, they should be created as security groups, and not distribution groups.)

Caché´ supports three predefined structures for group names. Each of these uses a prefix for the group, where the prefixes are intersystems-Role-, intersystems-Namespace-, and intersystems-Routine-, so conforming group names are of the form intersystems-Role-role-name, intersystems-Namespace-namespace-name, and intersystems-Routine-routine-name, and these names specify groups for initial roles, an initial namespace, and an initial routine, respectively. To use this feature, the names must follow this structure. (Names are not case-sensitive.)

Note:

A user can only belong to one routine group and one namespace group.

For example, a user might have groups defined such as:

CN=intersystems-Role-Admin,OU=Groups,OU=Brasilia,DC=mysite,DC=com
CN=intersystems-Role-%Operator,OU=Groups,OU=Brasilia,DC=mysite,DC=com
CN=intersystems-Namespace-USER,OU=Groups,OU=Brasilia,DC=mysite,DC=com
CN=intersystems-Routine-INTEGRIT,OU=Groups,OU=Brasilia,DC=mysite,DC=com

In this case, after logging in, the user would get the roles Admin and %Operator, with a default namespace of USER, and a default routine of INTEGRIT.

If the user does not belong to any group with a name in this form, then Caché sets the value of that attribute for the user to ""; hence, if the user is not a member of a group that defines intersystems-Routine- as the initial portion of its name, then Caché sets the startup routine for that user to "" (and Caché places the user in programmer mode). If a user is assigned to a group that specifies a role for the user, but that role is not defined on the instance where they are logging in, then they do not have that role on that instance.

For example, suppose that a user belongs to the following groups:

intersystems-Role-Admin
intersystems-Role-Application1
intersystems-Role-Application2

If the role Application2 is not defined on the system they are logging into, Caché only assigns the Admin and Application1 roles.

Note:

While InterSystems recommends the use of LDAP groups rather than the use of user-defined attributes for managing role, routine, and namespace definitions, Caché does support the use of user-defined attributes.

Setting Up a Role Required for Login

If you are using LDAP authentication or OS-based LDAP authorization — especially if your organization has multiple instances of Caché, then InterSystems strongly recommends that each instance have a role that is required for connecting to it:

For each instance, create the role that is required for login. Do this according to the instructions in the “Creating Roles” section of the “Roles” chapter.
For each instance, enter the newly created role in the Role required to connect to this system field on the System Security Settings page (System Administration > Security > System Security > System-wide Security Parameters).
Add an LDAP group with a name of form intersystems-Role-rolename that includes the name of the newly created role.

This mechanism prevents users from accessing instances where they are insufficiently privileged. Otherwise, a user who holds various roles on one instance may then have those same roles on an instance where this is not intended.

Important:

If the Role required to connect to this system field is left blank, a user with sufficient general privileges can connect and gain access to a system that uses OS-based LDAP authorization, provided that they had enough roles assigned to them to log in.

For example, suppose there are two systems, TEST and PRODUCTION. To secure each of these productions, create a role on TEST called TESTACCESS and a role on PRODUCTION called PRODUCTIONACCESS. On TEST, set the value of the Role required to connect to this system field to TESTACCESS; on PRODUCTION, set it to PRODUCTIONACCESS. Then, if a user is only allowed to access the TEST system, assign that user the TESTACCESS role only and do not assign the PRODUCTIONACCESS role to the user. For users who can access either system, assign them both PRODUCTIONACCESS and TESTACCESS roles.

Using Nested Groups

On Active Directory, LDAP groups include support for what are known as nested groups. A nested group is a group that is a member of a second group, which means that all the users who are members of the nested group are also members of the second group. For example, suppose that there are two LDAP groups defined, known as ABC and DEF. You can make the ABC group a member of the DEF group. This means that if a user is a member of the ABC group, then they are also a member of the DEF group without explicitly assigning the user to that group.

Note:

Depending on the structure and size of the local LDAP database, using nested groups can slow down users’ login time. Hence, when configuring Caché to use an LDAP server, if you select Search nested Groups for Roles/Routine/Namespace, this can have an effect on performance: selecting this returns nested groups and has slower logins, while not selecting it does not return nested groups and is faster.

Configuring Caché to Use an LDAP Server

This section describes the following topics:

Specifying Configuration Information for LDAP in Caché

To use LDAP authentication with Caché, the first step is to configure Caché for its interactions with the LDAP server. This includes information required to:

Connect to and query the LDAP server
Retrieve the required information about the user being authenticated

All this information is specified on the Management Portal LDAP Options page (System Administration > Security > System Security > LDAP Options).

When this page is first displayed, only a single field is visible, the Allow LDAP authentication field. Checking this field displays all the fields for configuration information for connecting the Caché instance to the LDAP server (false by default). There are a standard set of fields and there can also be customized fields. When connecting to an LDAP server, Caché refers to various fields for its information; the end-user can do the same. The fields are:

LDAP server is a Windows Active Directory server — Windows only. Specifies whether or not the LDAP server is a Windows Active Directory server (true by default).
LDAP domain name — Windows only. Specifies the name of the domain where the LDAP server is located. This field is only editable for a Windows Active Directory server. This field is populated with a value based on the IP address of the DNS name of the current LDAP server.
LDAP host names — Specifies the name(s) of the host(s) on which the LDAP server is running. The complexity of each host name can range from an unqualified host name to fully-qualified host name with a port number; the required form of the host name(s) depends on the particular configuration. This field is populated with a value based on the IP address of the DNS name of the current LDAP server.
To specify multiple host names, separate the names by spaces. If the LDAP server is configured to use a particular port, you can specify it by appending “:portname” to the host name; typical usage is not to specify a port and to let the LDAP functions use the default port, such as:
```
ldapserver.example.com
ldapserver.example.com ldapbackup.example.com
```
LDAP search information — varies by operating system:
- LDAP username to use for searches — Windows only. 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, to establish this on Windows, set its User cannot change password and Password never expires attributes and set the value of its Account expires attribute to Never.
  For more information on searching the LDAP database, see the section “Searching the LDAP Database.”
- LDAP DN to use for searches — UNIX® only. 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 operating-system 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 Distinguished Name might be as follows:
```
uid=ldapsearchuser,ou=People,dc=example,dc=com 
```
  For more information on searching the LDAP database, see the section “Searching the LDAP Database.”
LDAP username password — Specifies the password associated with account used for the initial connection.
LDAP Base DN to use for searches — Specifies the point in the directory tree from which searches begin. This typically consists of domain components, such as DC=intersystems,DC=com.
LDAP Unique search attribute — Specifies a unique identifying element of each record, which therefore makes it appropriate for searches. For more information on searching the LDAP database, see the section “Searching the LDAP Database.”
Use TLS/SSL encryption for LDAP sessions — Specifies if TLS/SSL encryption protect data being passed between the Caché server and the LDAP server (false by default).
TLS/SSL certificate file — UNIX® only. Specifies the location of the file containing any TLS/SSL certificates (in PEM format) being used to authenticate the server certificate, if needed. For Windows, see “Specifying a Certificate File on Windows.”
Use LDAP Groups for Roles/Routine/Namespace — Specifies if 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. Selecting the use of groups 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 the “Configuring the LDAP Server to Use Registered LDAP Properties” section for details.
Search nested Groups for Roles/Routine/Namespace (only active if LDAP groups are selected and only relevant for Active Directory) — Specifies if search returns all a user’s nested groups. See the “Using Nested Groups” section for more information on nested groups.
User attribute to retrieve comment attribute — Specifies the attribute whose value is the source for the Comment property for a user. This property is described in the section Properties of Users, in the “Users” chapter.
User attribute to retrieve full name from — Specifies the attribute whose value is the source for the Full name property for a user. This property is described in the section Properties of Users, in the “Users” chapter.
User attribute to retrieve default namespace (not active if LDAP groups are selected) — Specifies the attribute whose value is the source for the Startup namespace property for a user. This property of a Caché user is described in the section Properties of Users, in the “Users” chapter; this LDAP property is described in the section “Registered LDAP Properties.”
User attribute to retrieve default routine (not active if LDAP groups are selected) — Specifies the attribute whose value is the source for the Tag^Routine property for a user. This property of a Caché user is described in the section Properties of Users, in the “Users” chapter; this LDAP property is described in the section “Registered LDAP Properties.”
User attribute to retrieve roles (not active if LDAP groups are selected) — Specifies 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 a Caché user’s roles, see the Roles tab of a user’s Edit User page; this LDAP property is described in the section “Registered LDAP Properties.”
LDAP attributes to retrieve for each user — Specifies 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.

Specifying a Certificate File on Windows

On Windows, to specify the location of a file containing any TLS/SSL 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.

Note:

Certificates must be installed in the Certificates (Local Computer)\Trusted Root Certification Authorities certificate store.

Searching the LDAP Database

Once Caché has established a connection to the LDAP server as the search user, the next step is to retrieve information about the target user. To do this, Caché checks the user name provided at login against values in the LDAP database for the LDAP Unique search attribute. (The name of this attribute is often “sAMAcccountName” for a Windows LDAP server and “uid” for a UNIX® LDAP server.)

When looking up a user with the LDAP Unique search attribute, the form of the user name depends on the operating system of both the Caché instance and the LDAP server:

When connecting from Windows to Windows, it can simply be login name of the user, such as “testuser”.
For any other type of connection, it must include the full DN (distinguished name) of the user. When connecting from UNIX® to a Windows LDAP server, this is case-sensitive. For example:
- When connecting from UNIX® to Windows, it might be CN=testuser,OU=Users,OU=Cambridge.
- When connecting from any operating system to UNIX®, it might be uid=testuser,ou=people.

Once Caché has located the user, it retrieves attribute information. It retrieves information about every named attribute in the Caché LDAP configuration fields (described in “Specifying Configuration Information for LDAP in Caché”), and it retrieves all values associated with each attribute. Note that Caché retrieves all values associated with all attributes specified for the user in the Caché LDAP configuration fields; it is not possible to configure it to retrieve only a subset of these.

Setting Up LDAP-Based Authentication

Once Caché has been configured for use with LDAP, the next step is to enable it for the instance’s relevant services or applications. This procedure is:

Enable LDAP authentication for entire instance:
1. From the Management Portal home page, go to the Authentication/CSP Session Options page (System Administration > Security > System Security > Authentication/CSP Session Options ), select Allow LDAP authentication.
2. On the Authentication Options page, you also have the option of selecting Allow LDAP cache credentials authentication. If this is selected and Caché is unable to connect to the LDAP server, then Caché uses the copy of the LDAP credentials that it last cached to authenticate the user. This can be useful if there is a failure in the connection to the LDAP server or if the LDAP server becomes unavailable.
  
  Note:
  
  If a user password has changed on the LDAP server after the last login and Caché uses the LDAP credentials cache for authentication, authentication can only occur with the old password.
3. Click Save to apply the changes.
With LDAP authentication enabled for the instance, an LDAP check box appears on the Edit Service page for relevant services and the Edit Web Application page for those applications.
Enable LDAP authentication for services and applications, as appropriate.

The following services support LDAP authentication:

%Service_Bindings
%Service_CSP
%Service_CacheDirect
%Service_CallIn
%Service_ComPort
%Service_Console
%Service_Login
%Service_Terminal
%Service_Telnet

These fall into several categories of access modes:

Local access —
%Service_CallIn, %Service_ComPort, %Service_Console, %Service_Login, %Service_Terminal, %Service_Telnet
To use LDAP authentication with local connections, enable it for the service.
Client/Server access —
%Service_Bindings, %Service_CacheDirect,
To use LDAP authentication with client/server connections, enable it for the service.
Web access —
%Service_CSP
To use LDAP authentication with web connections (through CSP or Zen), enable it for the web application. Enabling it for the service also allows the CSP Gateway itself to authenticate using LDAP authentication.

After Authentication — The State of the System

Any user who is initially authenticated using LDAP authentication is listed in the table of users on the Users page (System Administration > Security > Users) as having a Type of “LDAP user”. If a system administrator has explicitly created a user through the Management Portal (or using any other native Caché facility), that user has a type of “Caché password user”. If a user attempts to log in using LDAP authentication and is successfully authenticated, Caché determines that this user already exists as a Caché user — not an LDAP user — and so login fails.

If you wish to have any LDAP attributes of the current user stored on the Caché server, specify these in the LDAP attributes to retrieve for each user field of the LDAP Options page (System Administration > Security > System Security > LDAP Options). Your application can then use the Get method of the Security.UsersOpens in a new tab class to return this information.

Configuring the LDAP Server to Use Registered LDAP Properties

Important:

InterSystems recommends using LDAP groups for LDAP authorization.

InterSystems has registered three field names that are available for use with an LDAP schema to store authorization information. Each has its own dedicated purpose:

intersystems-Namespace — The name of the user’s default namespace (LDAP OID 1.2.840.113556.1.8000.2448.2.1).
intersystems-Routine — The name of the user’s default routine (LDAP OID 1.2.840.113556.1.8000.2448.2.2).
intersystems-Roles — The name of the user’s login roles (LDAP OID 1.2.840.113556.1.8000.2448.2.3).

To use these attributes, the procedure on the LDAP server is:

Enable the attributes for use. To do this, modify the value of objectClass field in the LDAP schema by appending the intersystemsAccount value to its list of values. (intersystemsAccount has an LDAP OID of 1.2.840.113556.1.8000.2448.1.1.)
Add the fields (as few or as many as required) to the schema.
Populate their values for the entries in the LDAP database.

Note:

It is not required to use the registered LDAP schema names. In fact, you may already use existing attributes from your LDAP schema.

For example, with a UNIX® LDAP server, to define the schema for using LDAP authentication with Caché, use the content that appears the following definitions:

# Attribute Type Definitions

attributetype ( 1.2.840.113556.1.8000.2448.2.1 NAME 'intersystems-Namespace'
        DESC 'InterSystems Namespace'
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 SINGLE-VALUE )

attributetype ( 1.2.840.113556.1.8000.2448.2.2 NAME 'intersystems-Routine'
        DESC 'InterSystems Routine'
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{128} SINGLE-VALUE )
 
attributetype ( 1.2.840.113556.1.8000.2448.2.3 NAME 'intersystems-Roles'
        DESC 'InterSystems Roles'
        EQUALITY caseIgnoreMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
 
# Object Class Definitions
 
objectclass ( 1.2.840.113556.1.8000.2448.1.1 NAME 'intersystemsAccount' SUP top AUXILIARY
        DESC 'Abstraction of an account with InterSystems attributes'
        MAY ( intersystems-Routine $ intersystems-Namespace $ intersystems-Roles ) )

This content goes to two locations:

Place it in the intersystems.schema file in the /etc/openldap/schema/ directory.
Include it, along with any other content, in the /etc/openldap/slapd.conf file.

Using LDAP Authorization with OS-Based Authentication

Caché allows you to configure your system to support operating-system–based authentication, and then to perform authorization via LDAP. This is known as Operating System LDAP authorization. It allows a user authenticate to Caché using credentials from the operating system login and to have the appropriate roles in Caché by having them automatically retrieved from an LDAP server. Operating system LDAP authorization is available in the Terminal on UNIX®, Linux, and MacOS, and in the Caché Console on Windows.