Caché Security Administration Guide
Using LDAP
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   

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.LDAP, in the content for the Init 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:
  1. 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.
  2. 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.
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:
  1. The user is prompted for a user name and password. This user, who is trying to authenticate, is known as the “target user.”
  2. 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.”
  3. Once the connection is established, the next step is to look up the user in the LDAP database using the LDAP Unique search attribute.
  4. 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.
  5. Caché then attempts to authenticate the user to the LDAP database, using the user name and password provided in step 1.
  6. 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é:
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.)
A user can only belong to one routine group and one namespace group.
For example, a user might have groups defined such as:
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:
If the role Application2 is not defined on the system they are logging into, Caché only assigns the Admin and Application1 roles.
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 LDAP Authorization with OS-Based Authentication — 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:
  1. 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.
  2. 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.
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.
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:
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:
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 Services.
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:
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:
  1. Enable LDAP authentication for entire instance:
    1. 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.
      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.
    2. 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.
  2. Enable LDAP authentication for services and applications, as appropriate.
The following services support LDAP authentication:
These fall into several categories of access modes:
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.Users class to return this information.
Configuring the LDAP Server to Use Registered LDAP Properties
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:
To use these attributes, the procedure on the LDAP server is:
  1. 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.)
  2. Add the fields (as few or as many as required) to the schema.
  3. Populate their values for the entries in the LDAP database.
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'

attributetype ( 1.2.840.113556.1.8000.2448.2.2 NAME 'intersystems-Routine'
        DESC 'InterSystems Routine'
        SYNTAX{128} SINGLE-VALUE )
attributetype ( 1.2.840.113556.1.8000.2448.2.3 NAME 'intersystems-Roles'
        DESC 'InterSystems Roles'
        EQUALITY caseIgnoreMatch
        SYNTAX )
# 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:
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.