Managing DSM user authentication and user authorization with LDAP

Use LDAP to manage both Data Server Manager (DSM) user authentication and user authorization (Administrator or User).

About this task

You can use an external LDAP server to both authenticate DSM users and manage DSM user authorization. You can use the following modes to both manage your DSM user authentication and authorization using LDAP:

Simple mode

Use simple mode (refer table 2) to authenticate if the DSM user exists in a centralized location on the LDAP side. and all entries under this centralized location are assumed to be the DSM user. This mode assumes that two proper groups exist in the same location in LDAP for authorizing DSM users:

One group contains distinguished names (DNs) of users who have an exact mapping to DSM users that have an administrator role.
The other group is for users with a standard user role.

Ensure that the following requirements are met for simple mode:

All DSM users must be in the same container of the LDAP directory. The DSM users in this container must belong to at least one of the user and administrator groups. Any entries in this container not belonging to one of these groups will not be treated as DSM user
The two groups for privileges must be siblings in a container of the LDAP directory. The value of the members in the groups must be the DNs of the users.
The member attribute of the groups must be accessed anonymously, or by a bind account with proper privileges in LDAP.

Advanced mode

Users can use advanced mode (refer table 3) if the DSM users/groups exist in multiple locations on the LDAP side. All entries that meet the customized search conditions, and that belong to at least one of the groups under those locations, are assumed as DSM user

DSM locates specific users in an LDAP directory and retrieves all users from the LDAP server by doing LDAP searches with customized search filters from several base DNs. Therefore, it must be possible for the related locations to be accessed anonymously; otherwise, the search can be done by a bind account with a proper privilege in LDAP.

The selected attribute for DSM login for each user must be unique on the LDAP side.

RACF mode

All z/OS users performing authentication and authorization based on z/OS Tivoli Directory Server with RACF data back end must follow the configuration described in table 4 while performing the following procedure. All DSM users must be grouped under profiletype=USER sub-tree and all Groups must be grouped under profiletype=GROUP sub-tree. All groups must contain member DN information under racfgroupuserid attribute.

Note: To use Simple, Advanced, and RACF mode, refer to Table 1.

Procedure

If IBM Data Server Manager is not installed, run the setup shell script to complete your installation.
Stop the DSM service or application you are running.
Go to the location where you installed DSM and open the /Config folder.
Open the dswebserver_override.properties file and enable the following options:
- LDAP authentication: dsweb.customauth.ldap=true
- LDAP privilege management: dsweb.customauth.privilegesinldap=true

From the same directory, open the customldap.properties file and set the following LDAP properties:

Table 1. LDAP basic information (simple, advanced and RACF mode)
Parameter name	Description	Example or format
ldap.host	Host name or IP address of LDAP server.	`localhost`
ldap.port	Port number of LDAP server.	`389`
ldap.bind.dn	Distinguished name (DN) of a bind account for DSM.	`CN=dsmadmin,CN=DSMdata,DC=DataServerManager,DC=COM`
ldap.bind.password	Encrypted password of a bind account for DSM.	`wtiv2_xxxxxxxx...` Note: To generate an encrypted password, use the script at <dsm install location>/dsutil/bin/crypt.sh(.bat)

Table 2. LDAP user and group information (simple mode)
Parameter name	Description	Example or format
ldap.user.parent.dn	The DN that uniquely identifies the LDAP parent node.	`ou=DBAUnit,dc=example,dc=com` Where ou is the organizational unit (group) the user belongs to; dc represents each component of the domain `dataservermanager.com`. Entries under this node are treated as DSM users.
ldap.user.rdn.attribute.type	The attribute type of the user's relative distinguished name (RDN) in LDAP, which is used to get the username from the user node. For example, `cn` (common name). This is the value that is used to log into Data Server Manager.	`cn, uid, etc`
ldap.group.parent.dn	The DN that uniquely identifies the LDAP parent node. The entries under this node are treated as a DSM group.	`ou=Groups,dc=example,dc=com`
ldap.group.rdn.attribute.type	The attribute type of the group's RDN in LDAP. The value for this attribute points to a DSM group (`ou`).	`cn, gid, etc`
ldap.group.rdn.admin	The RDN attribute value for the DSM administrator group.	`DSMadmin`
ldap.group.rdn.user	The RDN attribute value for the DSM user group.	`DSMuser`
ldap.group.member.attribute.type	The attribute type that is used to store authorized users in a group. The default is `member`. Use this type to define the relationship between group and user in the LDAP Group entry.	`member`

Table 3. LDAP user information and DSM privilege group information (advanced mode)
Parameter name	Description	Example or format
ldap.use.advanced.mode	Change this value to enable or disable LDAP advanced mode.	`true` or `false`
ldap.user.base.dn	Base DNs for searching DSM users in LDAP.	`BaseDN1;BaseDN2;...;BaseDNn`
ldap.user.search.filter	Search filter for searching DSM users in LDAP.	`(\| (objectClass=person) (objectClass=organizationalPerson) (objectClass=inetOrgPerson) )`
ldap.user.login.attribute.type	Attribute for DSM users to input as the User ID (UID) when logging in to DSM.	`mail`
ldap.groups.admin	DNs and attribute types that are used to store group members who have an administrator role in DSM.	`adminGroupDN1:MemberAttributeType1; adminGroupDN2:MemberAttributeType2; ...; adminGroupDNn:MemberAttributeTypen`
ldap.groups.user	DNs and attribute types that are used to store group members who have a user role in DSM.	`userGroupDN1:MemberAttributeType1; userGroupDN2:MemberAttributeType2; ...; userGroupDNn:MemberAttributeTypen`

Table 4. LDAP user and group information (RACF mode)
Parameter name	Description	Configuration value or format
ldap.user.parent.dn	The DN that uniquely identifies the user's parent node.	`profiletype=USER,suffix`where `suffix` depends on your system.
ldap.user.rdn.attribute.type	The user's relative distinguished name (RDN) in LDAP, which is used to get the username from the user node.	`racfid`
ldap.group.parent.dn	The DN that uniquely identifies the group parent node.	`profiletype=GROUP,suffix` where `suffix` depends on your system.
ldap.group.rdn.attribute.type	Relative distinguished name (RDN) of groups in LDAP.	`racfid`
ldap.group.rdn.admin	The RDN attribute value for the DSM administrator group. Multiple group names are supported.	`ADMING1;ADMING2;...;ADMINGn`
ldap.group.rdn.user	The RDN attribute value for the DSM user group. Multiple group names are supported.	`ADMINU1;ADMINU2;...;ADMINUn`
ldap.group.member.attribute.type	The attribute type that is used to store users in a group.	`racfgroupuserids`
ldap.use.advanced.mode	Change this value to enable or disable LDAP advanced mode.	`false`

Save your changes and close the customldap.properties file.
Restart your Data Server Manager service or application.
Log in to Data Server Manager.
For simple mode, the value of the attribute set in ldap.user.rdn.attribute.type is treated as the DSM user name. The value should be the RDN value of user entries.
For advanced mode, the value of the attribute set in ldap.user.login.attribute.type is treated as the DSM user name. It must be a unique value in the LDAP directory.
Manage privileges.
DSM user privileges are stored in LDAP and cannot be managed from within DSM. Administrators can view the role of each user. The DSM Administrator cannot change console privileges from within DSM.
In simple mode, if a user belongs to both the administrator group and the user group, that user will have an administrator role.

In advanced mode, if a user belongs to several groups, that user's role will be the one that is highest among the groups. For example, if sam belongs to three groups, with roles user, user, and administrator, then the role of sam is administrator.
Configure parameters of LDAP connection pooling in customldap.properties file. If the value is not configured, a default value will be used.
The parameters are as follows:
- ldap.connection.timeOutMill - Specifies the timeout value in millisecond of a single connection. Default is 15 minutes.
- ldap.connection.pool.lifo- Determines whether or not the pool returns idle objects in last-in-first-out order. The default setting for this parameter is true.
- ldap.connection.pool.maxActive - Controls the maximum number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. When non-positive, there is no limit to the number of objects that can be managed by the pool at one time. When maxActive is reached, the pool is said to be exhausted. The default setting for this parameter is 8.
- ldap.connection.pool.maxIdle- Controls the maximum number of objects that can sit idle in the pool at any time. When negative, there is no limit to the number of objects that may be idle at one time. The default setting for this parameter is 8.
- ldap.connection.pool.max- Specifies the maximum amount of time to wait for an idle object when the pool is exhausted and whenExhaustedAction setting is WHEN_EXHAUSTED_BLOCK.
- ldap.connection.pool.minEvictableIdleTimeMill- Specifies the minimum amount of time that an object may sit idle in the pool before it is eligible for eviction due to idle time. When non-positive, no object will be dropped from the pool due to idle time alone. This setting has no effect unless timeBetweenEvictionRunsMill is > 0. The default setting for this parameter is 30 minutes.
- ldap.connection.pool.minIdle - Specifies the minimum number of idle objects in my pool.
- ldap.connection.pool.numTestsPerEvictionRun- Determines the number of objects examined in each run of the idle object evictor. This setting has no effect unless timeBetweenEvictionRunsMill is > 0. The default setting for this parameter is 3.
- ldap.connection.pool.softMinEvictableIdleTimeMill- Specifies the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any), with the extra condition that at least "minIdle" object instances remain in the pool. When non-positive, no objects will be evicted from the pool due to idle time alone. This setting has no effect unless timeBetweenEvictionRunsMill is > 0. and it is superseded by minEvictableIdleTimeMill is (that is, if minEvictableIdleTimeMill is positive, then softMinEvictableIdleTimeMill is ignored). The default setting for this parameter is -1 (disabled).
- ldap.connection.pool.testOnBorrow- When testOnBorrow is set, the pool will attempt to validate each object before it is returned from the borrowObject() method. Objects that fail to validate will be dropped from the pool, and a different object will be borrowed. The default setting for this parameter is false.
- ldap.connection.pool.testOnReturn- When testOnReturn is set, the pool will attempt to validate each object before it is returned to the pool in the returnObject(T) method. Objects that fail to validate will be dropped from the pool. The default setting for this parameter is false.
- ldap.connection.pool.testWhileIdle- Indicates whether or not idle objects should be validated using the factory's PoolableObjectFactory.validateObject(T) method. Objects that fail to validate will be dropped from the pool. This setting has no effect unless timeBetweenEvictionRunsMill is > 0. The default setting for this parameter is false.
- ldap.connection.pool.timeBetweenEvictionRunsMill- Indicates how long the eviction thread should sleep before "runs" of examining idle objects. When non-positive, no eviction thread will be launched. The default setting for this parameter is -1 ( that is, idle object eviction is disabled by default).
- ldap.connection.pool.whenExhaustedAction- Specifies the behavior of the borrowObject() method when the pool is exhausted. WHEN_EXHAUSTED_FAIL, WHEN_EXHAUSTED_GROW, WHEN_EXHAUSTED_BLOCK. The default whenExhaustedAction setting is WHEN_EXHAUSTED_BLOCK and the default maxWait setting is -1. By default, therefore, borrowObject will block indefinitely until an idle instance becomes available.
For more information, refer to Apache common pool.
Note: The following configuration is recommended to prevent connection timeout issues:
```
ldap.connection.pool.testOnBorrow=true
ldap.connection.pool.minEvictableIdleTimeMillis=60000
ldap.connection.pool.timeBetweenEvictionRunsMillis=120000
```