Skip to main content

LDAP Authorization

In addition to performing authentication with LDAP, InterSystems IRIS supports LDAP authorization. InterSystems recommends the use of LDAP groups rather than LDAP attributes for managing role, routine, and namespace definitions.

Overview of Configuring LDAP Authorization

To configure an InterSystems service or application to use LDAP for authorization:

  1. Configure the instance for LDAP or OS-based authentication

  2. For LDAP authorization:

    1. Design the groups for LDAP authorization on InterSystems IRIS instances

    2. Configure the LDAP server to use those groups

Configure Authorization with LDAP Groups

LDAP Groups and InterSystems IRIS

LDAP groups allow you to assign privileges to users using an LDAP server:

  • The schema on the LDAP server specifies the names of groups. Typically, the LDAP administrator defines these names; InterSystems IRIS uses one of three predefined name structures described below.

  • Each group has a distinguished name (DN) that uniquely identifies it.

  • Each group specifies access to an InterSystems IRIS role, routine, or namespace

InterSystems IRIS supports LDAP groups that provide authorization for:

  • A single instance

  • Multiple instances

  • All instances

To set up groups for InterSystems IRIS:

  1. Determine if you are going to use groups for a single instance, for multiple instances, or for all instances.

  2. Create one or more groups with names that follow the appropriate naming convention. Each group specifies a user’s role, default namespace, or default routine; since a user can have multiple roles, it is valid to belong to multiple groups that specify roles.

    Note:

    Note that when defining these groups on your LDAP server, they should be created as security groups, and not distribution groups.

  3. Configure your LDAP users to specify which ones belong to which groups. This requires that, for each user’s LDAP account, you assign the user to multiple groups to specify one or more roles, a default namespace, and a default routine. This determines which roles each user has after logging in, the user’s default namespace, and the user’s default routine.

  4. Configure the local InterSystems IRIS instance so that there are definitions for all the roles that are specified on the LDAP server.

LDAP Authorization Group Models

InterSystems IRIS supports for three kinds of group authorization using LDAP.

Create LDAP Authorization Groups for a Single Instance (Single-Instance Groups)

InterSystems IRIS allows you to create LDAP groups that provide authorization for only a single instance; hence, each of these is known as a single-instance group. To create this kind of authorization group:

  1. On the InterSystems IRIS instance, confirm or modify the value of the LDAP parameter Authorization Instance ID. By default, its value is NodeName_InstanceName, where NodeName is the machine on which the InterSystems IRIS instance is running and InstanceName is the name of that instance.

    To set the parameter’s value manually:

    1. In the Management Portal, go to the Security LDAP Configurations page (Management Portal > System Administration > System Security > LDAP Configurations).

    2. On that page, select the configuration to edit by clicking on its name.

    3. On the page for editing the configuration that appears, select Use LDAP Groups for Roles/Routine/Namespace.

    4. Next, in the Authorization Instance ID field, enter the value for the parameter and click Save.

  2. On the LDAP server, define role, namespace, and routine groups with names that conform to the required InterSystems structure and that use the Instance keyword, followed by the value of the Authorization Instance ID. Note that these strings are not case sensitive. These group names are of the form:

    intersystems-Instance-AuthorizationInstanceIDValue-Role-RoleName

    intersystems-Instance-AuthorizationInstanceIDValue-Routine-RoutineName

    intersystems-Instance-AuthorizationInstanceIDValue-Namespace-NamespaceName

    where:

    • AuthorizationInstanceIDValue is the value specified for the Authorization Instance ID field

    • RoleName, RoutineName, and NamespaceName are each the name of the role, default routine, or default namespace.

      Note:

      A user can have any number of roles; typically, access to the system requires at least one role. A user can have only one default routine and one default namespace; however, these are not required, so a user may have no default routine and no default namespace.

  3. On the InterSystems IRIS instance, configure a role associated with each group.

For example, suppose you are running an application on an instance called Test that is on a machine called Node1. You wish to set up three categories of users:

  • Application users — Can only run the application

  • Administrative users — Can run various administrative tools and the application

  • Superusers — Have full access

To set up this authorization model, create the following groups on the LDAP server:

intersystems-Instance-Node1_Test-Role-Administrator
intersystems-Instance-Node1_Test-Role-LocalApplication 
intersystems-Instance-Node1_Test-Role-%All 
intersystems-Instance-Node1_Test-Routine-LocalApplication 
intersystems-Instance-Node1_Test-Routine-%SS
intersystems-Instance-Node1_Test-Routine-%pmode
intersystems-Instance-Node1_Test-Namespace-%SYS
intersystems-Instance-Node1_Test-Namespace-USER

Next, create the roles that corresponds to each category of user:

  • Administrator

  • LocalApplication

Note:

You do not need to create a %All role, because it already exists.

Finally, create the three categories of users:

  • Application users — Can run only the application, LocalApplication; are assigned to the following LDAP groups:

    • intersystems-Instance-Node1_Test-Role-LocalApplication

    • intersystems-Instance-Node1_Test-Routine-LocalApplication

    • intersystems-Instance-Node1_Test-Namespace-USER

  • Administrative users — Can run various administrative tools and the application; are assigned to the following LDAP groups:

    • intersystems-Instance-Node1_Test-Role-LocalApplication

    • intersystems-Instance-Node1_Test1-Role-Administrator

    • intersystems-Instance-Node1_Test-Routine-%SS

    • intersystems-Instance-Node1_Test-Namepace-%SYS

  • Superusers — Have %All access; are assigned to the following LDAP groups:

    • intersystems-Instance-Node1_Test-Role-%All

    • intersystems-Instance-Node1_Test-Namespace-%SYS

    • intersystems-Instance-Node1_Test-Routine-%pmode

Create LDAP Authorization Groups for Multiple Instances (Multiple-Instance Groups)

InterSystems IRIS allows you to create LDAP groups that provide authorization for multiple instances; hence, each of these is known as a multiple-instance group. To create this kind of authorization group:

  1. Determine how the various instances are sharing information among groups. This determines the group for each instance and the information to which users have access.

  2. For each instance in the group, modify the value of the LDAP parameter Authorization Group ID to be the same as the other instances in the group.

    To set the parameter’s value manually:

    1. In the Management Portal, go to the Security LDAP Configurations page (Management Portal > System Administration > System Security > LDAP Configurations).

    2. On that page, select the configuration to edit by clicking on its name.

    3. On the page for editing the configuration that appears, select Use LDAP Groups for Roles/Routine/Namespace.

    4. Next, in the Authorization Group ID field, enter the value for the parameter and click Save.

  3. On the LDAP server, set up role, namespace, and routine groups that conform to the required InterSystems structure and that use the Group keyword, followed by the value of the Authorization Group ID. Note that these strings are not case sensitive. These group names are of the form:

    intersystems-Group-AuthorizationGroupIDValue-Role-RoleName

    intersystems-Group-AuthorizationGroupIDValue-Routine-RoutineName

    intersystems-Group-AuthorizationGroupIDValue-Namespace-NamespaceName

    where:

    • AuthorizationGroupIDValue is the value specified for the Authorization Group ID field

    • RoleName, RoutineName, and NamespaceName are each the name of the role, default routine, or default namespace.

      Note:

      A user can have any number of roles; typically, access to the system requires at least one role. A user can have only one default routine and one default namespace; however, these are not required, so a user may have no default routine and no default namespace.

  4. Configure the required roles on all the instances that are using them.

For example, suppose you have seven ECP application servers attached to five database servers. Two of the database servers are a failover pair, and the other three are async reporting members. All these servers (both the application servers and the database servers) run the SALES application. The application’s end users need a more limited set of privileges and its administrative users need greater privileges. Hence, you set up three categories of users:

  • Application users — Can only run the application

  • Application server administrators — Can run the application; have full access to the application servers and no access to the database servers

  • Database administrators — Have full access to the application servers and administrative access to the database servers

To configure LDAP authorization to support these requirements:

  • Set the Authorization Group ID on the applications servers to SALESAPP

  • Set the Authorization Group ID on the database servers to SALESDB

On the LDAP server, define the groups as follows:

intersystems-Group-SALESAPP-Role-%All
intersystems-Group-SALESAPP-Role-LocalApplication 
intersystems-Group-SALESAPP-Routine-LocalApplication
intersystems-Group-SALESAPP-Routine-%pmode
intersystems-Group-SALESAPP-Namespace-USER
intersystems-Group-SALESAPP-Namespace-%SYS
intersystems-Group-SALESDB-Role-Administrator
intersystems-Group-SALESDB-Routine-INTEGRIT
intersystems-Group-SALESDB-Namespace-%SYS

Next, create the roles that corresponds to each category of user:

  • Administrator

  • LocalApplication

Note:

You do not need to create a %All role, because it already exists.

Finally, create the three categories of users:

  • Application users – Can only run the application, LocalApplication; are assigned to the following LDAP groups:

    • intersystems-Group-SALESAPP-Role-LocalApplication

    • intersystems-Group-SALESAPP-Routine-LocalApplication

    • intersystems-Group-SALESAPP-Namespace-USER

  • Application server administrators — Can run the application, have full access to the application servers, and have no access to the database servers; are assigned to the following LDAP groups:

    • intersystems-Group-SALESAPP-Role-LocalApplication

    • intersystems-Group-SALESAPP-Namespace-USER

    • intersystems-Group-SALESAPP-Role-%All

    • intersystems-Group-SALESAPP-Routine-%pmode

  • Database administrators — Have full access to the application servers and administrative access to the database servers; are assigned to the following LDAP groups:

    • intersystems-Group-SALESAPP-Role-%All

    • intersystems-Group-SALESAPP-Routine-%pmode

    • intersystems-Group-SALESAPP-Namespace-%SYS

    • intersystems-Group-SALESDB-Role-Administrator

    • intersystems-Group-SALESDB-Routine-INTEGRIT

    • intersystems-Group-SALESDB-Namespace-%SYS

At this point, there is a fully functioning authorization model, but it does not include any superuser access to the database servers (that is, with %All). To add such access, create and add users to the following new group:

intersystems-Group-SALESDB-Role-%All

Configure LDAP Authorization Groups with Mirroring

In you are using LDAP and mirroring, InterSystems recommends using multiple-instance LDAP groups to configure authorization. Create the required multiple-instance groups and configure all the users on all members (including any async members) to use these groups.

Consider the following example, which is based on the group structure defined in the example above. Suppose, additionally:

  • There is a mirror called SALESDBMIR which is a failover pair and three reporting async members

  • You wish to have users with %All, but only on the failover pair

To configure authorization for this mirror:

  1. To provide full access to the failover pair, create the group

    intersystems-Group-SALESDBMIRFAILOVER-Role-%All

  2. To provide full access to the asynchronous members, create the group

    intersystems-Group-SALESDBMIRASYNC-Role-%All

  3. Set the LDAP parameter Authorization Instance ID on each member in the failover pair to SALESDBMIRFAILOVER.

    Important:

    Because a disaster recovery (DR) async member may be promoted to failover member, the Authorization Instance ID for any DR async should also be set to SALESDBMIRFAILOVER

  4. Set the LDAP parameter Authorization Group ID on the mirror’s asynchronous members to SALESDBMIRASYNC.

  5. Next, create the mirror administrators, who have %All access to the application servers; administrative access to the nonmirrored database servers; and %All access to the failover pair only. These users are assigned to the following LDAP groups:

    • intersystems-Group-SALESAPP-Role-%All

    • intersystems-Group-SALESAPP-Routine-%pmode

    • intersystems-Group-SALESAPP-Namespace-%SYS

    • intersystems-Group-SALESDB-Role-Administrator

    • intersystems-Group-SALESDB-Routine-INTEGRIT

    • intersystems-Group-SALESDB-Namespace-%SYS

    • intersystems-Group-SALESDBMIRFAILOVER-Role-%All

  6. Finally, create the full administrators, who have %All access to all the members (the application servers, the database servers, the failover pair, and the asynchronous members). These users are assigned to the following LDAP groups:

    • intersystems-Group-SALESAPP-Role-%All

    • intersystems-Group-SALESDB-Role-%All

    • intersystems-Group-SALESDBMIRFAILOVER-Role-%All

    • intersystems-Group-SALESDBMIRASYNC-Role-%All

Create Universal LDAP Authorization Groups

InterSystems IRIS allows you to create LDAP groups that provide authorization for all its instances that use a single LDAP server; these are known as universal authorization groups. To create this kind of authorization group:

  1. Enable the use of universal authorization groups for the current instance:

    1. In the Management Portal, go to the Security LDAP Configurations page (Management Portal > System Administration > System Security > LDAP Configurations).

    2. On that page, select the configuration to edit by clicking on its name, which displays the page for editing that configuration.

    3. On the page for editing the configuration, select Use LDAP Groups for Roles/Routine/Namespace.

    4. Select Allow Universal group authorization.

    5. Click Save.

  2. On the LDAP server, set up role, namespace, and routine groups that conform to the required InterSystems structure. Note that these strings are not case sensitive. These group names are of the form:

    intersystems-Role-RoleName

    intersystems-Routine-RoutineName

    intersystems-Namespace-NamespaceName

    where RoleName, RoutineName, and NamespaceName are each the name of the role, default routine, or default namespace.

    Note:

    A user can have any number of roles; typically, access to the system requires at least one role. A user can have only one default routine and one default namespace; however, these are not required, so a user may have no default routine and no default namespace.

  3. Configure the required roles on all the instances that are using the LDAP server.

For example, suppose you have an application called LocalApplication and you wish to grant various levels of access to it for users on all the InterSystems IRIS instances that use your LDAP server. Define the following LDAP groups:

intersystems-Role-%All
intersystems-Role-Administrator
intersystems-Role-LocalApplication
intersystem-Routine-%SS
intersystem-Routine-LocalApplication
intersystems-namespace-USER
intersystems-namespace-%SYS

Next, create the roles that corresponds to each category of user:

  • Admin

  • LocalApplication

Note:

You do not need to create a %All role, because it already exists.

Finally, create the three categories of users:

  • Application users – Have access to the application on all servers; are assigned to the following LDAP groups:

    • intersystems-Role-LocalApplication

    • intersystems-Routine-LocalApplication

    • intersystems-Namespace-USER

  • Administrators — Have administrative access to all servers; are assigned to the following LDAP groups:

    • intersystems-Role-Administrator

    • intersystems-Routine-%SS

    • intersystems-Namespace-%SYS

  • Superusers — Have full access to all servers; are assigned to the following LDAP groups:

    • intersystems-Role-%All

Other Topics for LDAP Authorization with LDAP Groups

Topics include:

LDAP Group Definition Structure

Group definitions typically include:

  • The group name

  • A declaration of the group’s organizational unit: OU=Groups

  • A declaration of the domain component (DC) such as DC=example,DC=com

  • Any other required information

For example, some possible group definitions might be:

CN=intersystems-Role-Administrator,OU=Groups,DC=intersystems,DC=com
CN=intersystems-Group-MyGroup-Namespace-USER,OU=Groups,DC=intersystems,DC=com
CN=intersystems-Instance-MyNode:MyInstance-Routine-INTEGRIT,OU=Groups,DC=intersystems,DC=com 

Mix Different Kinds of Groups

You can use universal groups in conjunction with single-instance or multiple-instance roles.

For example, suppose you:

  • Have an application on multiple instances

  • Are using universal groups

  • Have a user named UserOne who can run the application on all instances, but cannot use it as an administrator on any machine

You would like for UserOne to:

  • Continue to be able to run the application on all instance

  • Additionally, to be able to administer the application on a particular instance, called APPTEST, on a particular machine, called Test

To do this:

  1. Set the authorization instance ID on the APPTEST instance on the Test machine to Test:APPTEST

  2. Create the following group on the LDAP server:

    intersystems-Instance-Test_APPTEST-Role-Administrator

  3. Assign this group to UserOne on the LDAP server

  4. Create the Administrator role on the APPTEST instance on the Test machine and grant it administrative access

You can also mix authorization groups in other ways. For example, if UserTwo has %All permission on all the instances authenticating to the LDAP server, you can give UserTwo exclusive administrative permission on an instance called SECRET on a machine called Server10. To do this, disable Allow universal groups access and then go through the process of assigning an intersystems-Instance-Server10_SECRET-Role-Administrator to that user.

Use Nested Groups

On an Active Directory LDAP server, 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.

How LDAP Groups Regulate Access to InterSystems IRIS

Through their LDAP groups, users receive roles along with a default namespace and a default routine. If the user’s granted roles lack sufficient privilege for any required point of access for an instance, the user then is denied access that instance; for example, if a user lacks sufficient privilege to use their default routine, that user is denied access.

The following rules also apply:

  • If a user is assigned to a group for a role, but that role is not defined on the instance where the user is logging in, then the user does not have that role on that instance.

  • If a user is assigned to a group for a default routine, but that routine is not defined on the instance where the user are logging in, then the user cannot connect to the instance.

  • If a user is assigned to a group for a default namespace, but that namespace is not defined on the instance where the user are logging in, then the user cannot connect to the instance.

Configure LDAP Authorization with Operating System–Based Authentication

Topics include:

Operating System LDAP 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 or OS/LDAP. It allows a user to authenticate to InterSystems IRIS using credentials from the operating system login and then to have their authorization information retrieved from an LDAP server. Operating system LDAP authorization is available in the Console on Windows and in the Terminal and on UNIX®, Linux, and macOS.

To configure OS/LDAP:

  1. Enable OS-based authentication with LDAP authorization for an InterSystems IRIS instance.

  2. As with standard LDAP authentication, set up a role that is required in order to be able to log in to the instance.

  3. Enable OS/LDAP for the %Service_Console and %Service_Terminal services.

  4. Configure authorization. This occurs in the same manner as that which accompanies LDAP authentication, as described in Configure LDAP Authorization for InterSystems IRIS.

  5. If you are using multiple domains, optionally configure OS/LDAP for simplified prompting.

Enable OS/LDAP for an InterSystems IRIS Instance

To use OS/LDAP, first enable it for the instance:

  1. From the Management Portal home page, go to the Authentication/Web Session Options page (System Administration > Security > System Security > Authentication/Web Session Options).

  2. On the Authentication/Web Session Options page, select Allow Operating Systems LDAP authentication.

  3. Click Save to apply the changes.

Enable OS/LDAP for the %Service_Console and %Service_Terminal Services

To enable OS/LDAP for the instance’s relevant services or applications:

  1. With LDAP authentication enabled for the instance, an Operating System LDAP Authorization check box appears on the Edit Service page for %Service_Console and %Service_Terminal, which are the services that support OS/LDAP.

  2. Enable LDAP authentication for those services, as appropriate.

OS/LDAP with a Single Domain and Multiple Domains

OS/LDAP supports the use of a single domain or multiple domains.

When InterSystems IRIS is configured to support only a single domain:

  1. The system prompts the user for a username and password for the first login.

  2. For subsequent logins, there is no prompt because the operating system has already authenticated the user.

When InterSystems IRIS is configured to support multiple domains:

  1. The system prompts the user for a username and password for the first login.

  2. For subsequent logins, the operating system prompts for a username and password by default. You can configure InterSystems IRIS to prevent this prompting; see the next section.

Configure OS/LDAP with Multiple Domains for Simplified Prompting

If you are using OS/LDAP and multiple domains, you can configure the instance for simplified prompting. By default, users are prompted for a username and password at every login. You can configure InterSystems IRIS so that there is only a username/password prompt when a user first logs in, and that subsequent connections are authenticated without prompting.

To configure InterSystems IRIS for this behavior:

  1. For each user, create the environment variable ISC_LDAP_CONFIGURATION with a value of the domain in which the user is authenticating.

  2. For each domain in which users are authenticating:

    1. Ensure that there is an LDAP configuration or create one.

    2. For that LDAP configuration, select the Allow ISC_LDAP_CONFIGURATION environment variable check box, which enables use of the environment variable.

Configure Authorization with LDAP Attributes

For LDAP authorization, InterSystems recommends the use of LDAP groups. However, InterSystems also supports authorization using LDAP attributes. There are three registered OIDs 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 (OID 1.2.840.113556.1.8000.2448.2.1).

  • intersystems-Routine — The name of the user’s default routine (OID 1.2.840.113556.1.8000.2448.2.2).

  • intersystems-Roles — The name of the user’s login roles (OID 1.2.840.113556.1.8000.2448.2.3).

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.

Note:

It is not required to use the registered LDAP schema names. In fact, you may 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 in 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.

Feedback