Home  /  Security Features of InterSystems IRIS  /  Security Administration Guide  /  Using LDAP

Security Administration Guide
Using LDAP
[Back]  [Next] 
InterSystems: The power behind what matters   

InterSystems IRIS™ provides support for authentication and authorization using LDAP, the Lightweight Directory Access Protocol. LDAP systems have a central repository of user information, from which InterSystems IRIS retrieves information. For example, on Windows, a domain controller using Active Directory is an LDAP server. This means that an instance of InterSystems IRIS 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 InterSystems IRIS. If you are establishing an outbound connection from InterSystems IRIS to an LDAP server and need to secure the connection, InterSystems IRIS 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 InterSystems IRIS
The procedure for configuring an InterSystems service or application to use an existing LDAP server for authentication (and optional authorization) is as follows:
  1. On the LDAP Options page, configure InterSystems IRIS to use the LDAP server. This includes specifying the names of LDAP user properties to be used for setting the values of properties of InterSystems IRIS users.
  2. Set up InterSystems IRIS to use LDAP. This involves enabling LDAP for the entire instance of InterSystems IRIS 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 InterSystems IRIS 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. InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS 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. InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS (since all the information is coming from outside InterSystems IRIS).
Notes on Using LDAP with InterSystems IRIS
Note the following points when using LDAP with InterSystems IRIS:
Using LDAP Authorization
In addition to performing authentication with LDAP, InterSystems IRIS supports LDAP authorization. To perform LDAP authorization with InterSystems IRIS, 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 InterSystems IRIS 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 InterSystems IRIS 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.)
InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS sets the startup routine for that user to "" (and InterSystems IRIS 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, InterSystems IRIS 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, InterSystems IRIS 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 InterSystems IRIS, 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 InterSystems IRIS 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 InterSystems IRIS to Use an LDAP Server
This section describes the following topics:
Specifying Configuration Information for LDAP in InterSystems IRIS
To use LDAP authentication with InterSystems IRIS, the first step is to configure InterSystems IRIS 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 InterSystems IRIS 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, InterSystems IRIS 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 InterSystems IRIS 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, InterSystems IRIS 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 InterSystems IRIS instance and the LDAP server:
Once InterSystems IRIS has located the user, it retrieves attribute information. It retrieves information about every named attribute in the InterSystems IRIS LDAP configuration fields (described in Specifying Configuration Information for LDAP in InterSystems IRIS), and it retrieves all values associated with each attribute. Note that InterSystems IRIS retrieves all values associated with all attributes specified for the user in the InterSystems IRIS LDAP configuration fields; it is not possible to configure it to retrieve only a subset of these.
Setting Up LDAP-Based Authentication
Once InterSystems IRIS 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 InterSystems IRIS is unable to connect to the LDAP server, then InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS facility), that user has a type of “InterSystems IRIS password user”. If a user attempts to log in using LDAP authentication and is successfully authenticated, InterSystems IRIS determines that this user already exists as an InterSystems IRIS user — not an LDAP user — and so login fails.
If you wish to have any LDAP attributes of the current user stored on the InterSystems IRIS 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 InterSystems IRIS, 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
InterSystems IRIS 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 InterSystems IRIS using credentials from the operating system login and to have the appropriate roles in InterSystems IRIS 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 Console on Windows.