Settings for LDAP Authentication

In order to work with LDAP authentication, you must specify these settings in the server initialization file:

• In the start section for the server:

ADBX=<alt_auth>

where <alt_auth> specifies the name of the section that contains all settings required for LDAP authentication (for example, ADBX=LDAP_AUTH).

• In the section <alt_auth>, all settings required for LDAP authentication.

These settings and their values for LDAP authentication depend on the LDAP server’s configuration. ASG recommends, therefore, that you consult the LDAP server administrator to ensure that you specify the LDAP settings correctly.

The LDAP authentication settings consist of these components:

• Settings for authentication the Rochade Server at the LDAP server.
• Settings for searching in the LDAP directory.

Authentication of Rochade Server at the LDAP Server

Initially, the Rochade Server must authenticate itself at the LDAP server (such as, as a client) using one of these methods:

• AuthMethodServer=EXTERNAL authenticates the server via Kerberos using the credentials specified in the settings BindDN and BindPW or, if the settings are empty, the credentials of the user who started the server.
• AuthMethodServer=PLAIN authenticates the server via LDAP using the credentials specified in the settings BindDN and BindPW or, if the settings are empty, by performing an anonymous bind.

For details, see AuthMethodServer=EXTERNAL | PLAIN.

You can use the SSL setting to specify the encoding of the communication between the Rochade Server and LDAP (such as, encoded or uncoded).

This table provides an overview of the required and optional settings for communication with the LDAP server. For more information, see Description of the Settings for details.

Setting	[o]ptional/[m]andatory	Function
AuthMethod	m	Method that Rochade Server uses for authenticating users at the LDAP server.
AuthMethodServer	m	Method that Rochade Server uses for authenticating itself at the LDAP server.
BindDN	o	Name of a valid user.
BindPW	o	Password for the user specified in BindDN or anaccount file that contains encoded passwords.
BindPWMode	o	Specifies how LDAP interprets the value in BindPW.
CACERTFILE	o	UNIX and z/OS only. Specifies the location, which contains certificates for the certificate authorities (CAs) that the Rochade Server will trust.
Domain	o	The Kerberos realm to be used for authenticating the Rochade Server at the LDAP server
Host	m	DNS Name or IP address of the LDAP server.
KEYDBPW	o	Specifies the password for the z/OS gskkyman tool.
LdapDebug	o	Enables or disables the logging of LDAP debug messages.
MaxEntryPerQuery	o	Maximum number of data records requested from the LDAP server in any single request.
OnError	o	Specifies how the Rochade Server should react if it cannot reach the LDAP server.
PersistentConnection	o	Specifies whether the connection with the LDAP server is to be kept open.
Port	o	LDAP server’s port number.
REQUIRE_CERT	o	UNIX only. Specifies whether the Rochade Server requires a valid LDAP server certificate for startup.
SSL	m	SSL encoding of communication with the LDAP server.
TimeLimit	o	Maximum time the LDAP server can take for conducting a search

Searching in the LDAP Directory

User authentication via LDAP is done via the user’s login name. For searching in the LDAP directory, information on the schema and an appropriate search expression are required. In principle, the search for a user is conducted with the user’s login name; at the same time, all user groups are identified in which the user is a member. To accelerate the user authentication process, the Rochade server caches user password hash values and user group names for users for a certain time. The cache behavior can be modified by the settings CacheCaseSensitivity, CacheGroupRefreshPeriod, CachePwdLifeTime, and CacheSize.

This table provides an overview of the required and optional settings for searching in the LDAP directory. For more information, see Description of the Settings for detailed descriptions.

Setting	[o]ptional/[m]andatory	Function
CacheCaseSensitivity	o	Specifies how Rochade Server searches user entries in the cache.
CacheGroupRefreshPeriod	o	Specifies the time after which Rochade Server re-analyzes the group assignment of a user from the LDAP directory.
CachePwdLifeTime	o	Specifies the maximum time a password hash value in the cache remains valid.
CacheSize	o	Specifies the maximum number of entries in the cache.
EnableGroupSearch	o	Switch to enable or disable group assignment searches.
GroupBaseDN	o/m	Distinguished name of the LDAP entry that is the start object for searching for user groups. Mandatory only when using the standard LDAP group search.
GroupFilter	o/m	LDAP filter expression that specifies object classes for user groups in the schema. Mandatory only when using the standard LDAP group search.
GroupScope	o/m	Specifies how the search should be performed in the tree segment specified in the GroupBaseDN. Mandatory only when using the standard LDAP group search.
LoginAttributeName	m	Name of an attribute of the object class declared in UserFilter, containing the user’s login name.
RejectBlankPassword	o	Switch to allow or disallow LDAP login with blank passwords.
UserBaseDN	m	LDAP entry in the LDAP directory tree that is the start object for searching for users.
UserFilter	m	LDAP filter expression that specifies object classes for users in the schema.
UserGroupAssociationAttribute	o/m	Name of the object class attribute in which the associations between user object and group object are stored. Mandatory only when using the standard LDAP group search.
UserGroupAssociationDirection	o/m	Association direction that is modeled in the LDAP schema and applies to the attribute specified in UserGroupAssociationAttribute. Mandatory only when using the standard LDAP group search.
UserScope	m	Specifies how the search should be performed in the tree segment specified in the UserBaseDN.

Description of the Settings

LDAP Server Settings

Methodist=EXTERNAL | PLAIN

–

Section: [<alt_auth>]

This setting specifies how Rochade Server authenticates users at the LDAP server. These are the possible values:

•

EXTERNAL - Windows only. Authenticates users by performing a Kerberos logon using the credentials that they entered in the Rochade client.

•

PLAIN - Default. Authenticates users by performing an LDAP bind using the credentials that they entered in the Rochade client.

AuthMethodServer=EXTERNAL | PLAIN

–

Section: [<alt_auth>]

This setting specifies how Rochade Server authenticates itself at the LDAP server. These are the possible values:

•

EXTERNAL - Windows only. Authenticates the server by performing a Kerberos logon with the user name and password specified in BindDN and BindPW or the credentials of the user who started the server if you leave those settings empty (which is the recommended method).

•

PLAIN - Default. Authenticates the server by performing an LDAP bind with the user name and password specified in BindDN and BindPW or performs an anonymous bind if you leave those settings empty.

BindDN=<dn_name>

–

Section: [<alt_auth>]

•

<dn_name> specifies the name of a user with read and search access to the LDAP directory. If you set the AuthMethodServer setting to EXTERNAL, you must specify only the user name. For example:

BindDN=KnownReader

However, if you set the AuthMethodServer setting to PLAIN, you must specify the user’s distinguished name. For example:

BindDN=CN=KnownReader,OU=Users,DC=Example,DC=com

•

You must specify the BindDN setting only if the LDAP server does not permit anonymous search for users in the directory.

BindPW=<password> | [<identifier>]@<account_file>

–

Section: [<alt_auth>]

•

<password> specifies the password of the user specified in BindDN.

For example: BindPW=secret

•

<identifier> specifies an application identifier in the account file for which the user is authenticated (for example, rochade//neptun:8888).

•

<account_file> specifies an account file containing the authentication information for the user specified in BindDN. For information on how to create the account file, see the ASG-Rochade Account Utility Quick Start Reference in the techdoc directory of your Rochade installation.

For example: BindPW=rochade//neptun:8888@MyAccounts.acc

If you specify an application identifier, Rochade Server searches the account file for an entry that contains the correct combination of application identifier and user name; otherwise, it searches only for the user name.

If Rochade Server finds a corresponding entry, it uses the password encrypted in that entry to authenticate itself at the LDAP server (using the method specified in the AuthMethodServer setting). If it does not find an appropriate entry in the account file, LDAP access is denied.

BindPWMode=PLAIN | ROACC

–

Section: [<alt_auth>]

•

PLAIN - Default. Specifies that the BindPW value represents the password of the user specified in BindDN.

•

ROACC - Specifies that the BindPW value represents the name of the account file and optional application name.

This example demonstrates the account file access via the application name SCANORAC:

BindDN=ORACLE

BindPWMode=ROACC

BindPW=SCANORAC@roacc.acc

This example demonstrates the account file access via a user name:

BindDN=uid=manager,dc=example,dc=com

BindPWMode=ROACC

BindPW=@/home/rochade/appl/roacc.acc

CACERTFILE<cert>

–

Section: [<alt_auth>]

•

This setting is relevant only for z/OS and UNIX operating systems and if the setting SSL has the value YES or START_TLS.

•

<cert> specifies the location that contains the certificates for the CAs that the Rochade Server will trust.

•

<cert> must contain the certificate for the CA that signed the LDAP server certificate. If the CA was not a root CA, <cert> must contain the certificates for all CAs up to the root CA. Ask your LDAP administrator to provide you the appropriate file, key database or keyring.

•

Under UNIX, <cert> is the name of a file in PEM format.

•

Under z/OS, <cert> is either the name of a key database or an RACF keyring.

You can use the gskkyman tool to create a key database and to import a certificate in PFX/PKCS#12 format into the key database. You must specify the password for the key database in the KEYDBPW setting. For more information, see KEYDBPW=<password>.

Use this format to specify a RACF keyring:

[<user_id>/]<keyring_name>.

If you do not specify a <user_id>, the current user is used as default.

If you specify a RACF keyring, you must not specify the KEYPWD setting.

CacheCaseSensitivity=ON | OFF

–

Section: [<alt_auth>]

This setting specifies how Rochade Server searches user entries in the cache (the setting should correspond to the configuration of your LDAP server):

•

ON - Specifies that Rochade Server performs case-sensitive search.

•

OFF - Default. Specifies that Rochade Server performs case-insensitive search.

CacheGroupRefreshPeriod=<n>

–

Section: [<alt_auth>]

•

This setting specifies the time in seconds after which Rochade Server re-analyzes the group assignment of a user from the LDAP directory.

•

Valid values for <n> range from 1800 (such as, 30 minutes) through 28800 (such as, 8 hours). The default value is 72000 (such as, 2 hours).

CachePwdLifeTime=<n>

–

Section: [<alt_auth>]

•

This setting specifies the maximum time in seconds that a password hash value in the cache remains valid. If the limit is reached, the password is rechecked against LDAP.

•

The valid values for <n> range from 60 (such as, 1 minute) through 604800 (such as, 7 days). The default value is 36000 (such as, 10 hours).

CacheSize=<n>

–

Section: [<alt_auth>]

This setting specifies the maximum number of entries in the cache. Valid values for <n> range from 0 (such as, no entries) through 1000. The default value is 100.

Domain=<kerbos_realm>

–

Section: [<alt_auth>]

where <kerbos_realm> is the Kerberos realm to be used for authentication (such as, the area of the network for which the KDC is responsible). Usually, this is the Windows domain name in uppercase letters. This setting is required only if the settings AuthMethod or AuthMethodServer have the value EXTERNAL.

EnableGroupSearch=NO | YES | @<methodfile>

–

Section: [<alt_auth>]

This setting disables or enables the LDAP group search:

•

NO - Disables the LDAP group search.

If you specify NO, then the settings of GroupBaseDN, GroupFilter, GroupGroupAssociationAttribute, GroupGroupAssociationDirection, and GroupScope are ignored and do not need to be specified.

•

YES - Default. Enables the standard LDAP group search.

•

@<methodfile> - Enables the extended LDAP group search and specifies the path and name of the group access method file, which defines the methods for obtaining the group data.

GroupBaseDn=<dn>

–

Section: [<alt_auth>]

where <dn> is a character string in RFC 2253-specific format that specifies the distinguished name of the LDAP entry in the directory tree, with which the search for user groups should start. This enables you to limit the search for user groups to specific tree segments in the LDAP directory. For example, this setting specifies that the search for user groups should start with the LDAP entry Dev:

GroupBaseDN=OU=Dev,DC=ITX,DC=com

GroupFilter=<ldap_expr>

–

Section: [<alt_auth>]

where <ldap_expr> is an LDAP filter expression that defines the object classes of LDAP directory entries that represent a user group in the LDAP server’s schema. Valid values for <ldap_expr> are LDAP search expressions referring to objectClass.

Examples 1 and 2 specify a filter for object classes representing user groups for different LDAP servers.

Example 1: Default schema of an Active Directory Server:

GroupFilter=(objectClass=group)

Example 2: Default schema of a SunOne5.2 Directory Server:

GroupFilter=(objectClass=groupOfUniqueNames)

GroupGroupAssociationAttribute=<name>

–

Section: [<alt_auth>]

where <name> is the name of the attribute containing the associated groups. The attribute must be modeled in the object class for user groups and must contain the distinguished names of the referenced user groups. Only attribute names that are actually defined in the schema of the object class for users or user groups are valid.

Examples 1 and 2 specify the attribute containing the association between user groups for different LDAP servers.

Example 1: Default schema of an Active Directory Server:

GroupGroupAssociationAttribute=memberOf

Example 2: Default schema of a SunOne5.2 Server:

GroupGroupAssociationAttribute=uniquemember

GroupGroupAssociationDirection=SPECIFIC | GENERAL

–

Section: [<alt_auth>]

This setting specifies the association direction between different user groups (the association attribute specified in the setting GroupGroupAssociationAttribute can mean either that a user group A contains a user group B, or, vice versa, that user group A is contained in user group B). These are the possible values:

•

SPECIFIC - The user group contains another user group.

•

GENERAL - The user group is contained in another user group.

Examples 1 and 2 specify the association direction of the association attribute for different LDAP servers.

Example 1: Default schema of an Active Directory Server:

GroupGroupAssociationDirection=GENERAL

Example 2: Default schema of a SunOne5.2 Server:

GroupGroupAssociationDirection=SPECIFIC

GroupScope=BASE | LEVEL | SUBTREE

–

Section: [<alt_auth>]

This setting specifies how the search should be conducted in the tree segment specified in GroupBaseDN. These are the possible values:

•

BASE - Only in root node.

•

LEVEL - All direct children of the root node.

•

SUBTREE - All offspring of the root node, including itself.

Host=<name>

–

Section: [<alt_auth>]

This setting specifies the LDAP server’s name in the network. You can specify either the DNS name or the IP address for <name>.

KEYDBPW=<password>

–

Section: [<alt_auth>]

This setting is relevant only for z/OS and UNIX operating systems. It specifies the password for the gskkyman tool. For more information, see Settings for LDAP Authentication.

LdapDebug=NO | YES

–

Section: [<alt_auth>]

The LdapDebug setting controls the logging of LDAP debug messages:

•

NO - Default. LDAP debug messages are not logged.

•

YES - LDAP debug messages are logged for these operations:

All major steps

All operations that open a connection to the LDAP server

All search operations of the LDAP server

All bind operations of the LDAP server

LoginAttributeName=<name>

–

Section: [<alt_auth>]

where <name> is the name of the attribute in the object class specified in UserFilter in which the user’s login name is stored. Permitted values are only attribute names that are actually defined for the object class for users in the schema.

Examples 1 and 2 specify the attribute in the object class for users that contains the login name for users for different LDAP servers.

Example 1: Default schema of an Active Directory Server:

LoginAttributeName=sAMAccountName

Example 2: Default schema of a SunOne5.2 Server:

LoginAttributeName=uid

MaxEntryPerQuery=<number>

–

Section: [<alt_auth>]

where <number> specifies the maximum number of data records in a package that is requested from the LDAP server.

The specified value must be less than the LDAP server’s Query Size Limit in order to circumvent limitations of the LDAP Server concerning the number of data records that can be transmitted in a single response. The default value is 500.

OnError=SHUTDOWN

–

Section: [<alt_auth>]

This setting controls Rochade Server’s behavior if it cannot reach the LDAP server:

•

If you specify the setting, the Rochade Server will shut down if a logon attempt is made but the LDAP server cannot be reached.

•

If you do not specify the setting, the Rochade Server continues its operation and only throws a RoException if a logon attempt fails.

PersistentConnection=NO | YES

–

Section: [<alt_auth>]

•

NO - The LDAP connection is opened and closed with each request.

•

YES - Default. The LDAP connection is kept open until the LDAP server closes it or the Rochade Server is shut down.

Port=<number>

–

Section: [<alt_auth>]

This setting specifies the port number on which the LDAP server is running. The default value is 389 for non-SSL access and 636 for SSL encoded communication.

RejectBlankPassword=NO | YES

–

Section: [<alt_auth>]

This setting rejects or allows anonymous LDAP login with blank passwords:

•

NO - Default. Allows login with blank passwords.

•

YES - Rejects login with blank passwords.

REQUIRE_CERT=demand | hard | allow | never

–

Section: [<alt_auth>]

•

This setting is relevant only for UNIX operating systems.

•

Specifies whether the Rochade Server requires a valid LDAP server certificate:

–

demand or hard - Rochade Server requests the LDAP server certificate. If a bad or no certificate is provided, the server terminates.

–

allow - Rochade Server requests the LDAP server certificate. If a bad or no certificate is provided, the server continues its operation.

–

never - Rochade Server does not request the LDAP server certificate.

SSL=NO | YES | START_TLS

–

Section: [<alt_auth>]

This setting specifies the SSL encoding of the communication with the LDAP server. These are the permitted values and their functions:

•

NO - Default. No encoding.

•

YES - The entire communication is SSL encoded.

•

START_TLS - The default port is used to establish the connection to the LDAP server. After the connection is established, SSL encoding is used (such as, the Rochade Server uses a start_tls request, see also RFC2830).

TimeLimit=<time>

–

Section: [<alt_auth>]

where <time> is the time, specified in seconds, within which the LDAP server must conclude a search. The value must be in the range between 1 and 32,000. The default value is 120 seconds.

UserBaseDN=<dn>

–

Section: [<alt_auth>]

where <dn> specifies the distinguished name of the LDAP entry in the directory tree, with which the search for users should start (such as, the root node for the search). This enables you to limit the search for users to specific tree segments in the LDAP directory. <dn> is a character string in RFC 2253-specific format.

This example specifies that the search for users should start with the LDAP entry DB:

UserBaseDN=OU=DB,OU=Dev,DC=ITX,DC=com

UserFilter=<ldap_expr>

–

Section: [<alt_auth>]

where <ldap_expr> specifies an LDAP filter expression that defines the object class of LDAP directory entries representing a user in the LDAP server’s schema.

Permitted values for <ldap_expr> are LDAP search expressions referring to objectClass. Examples 1 and 2 specify a filter for object classes representing user groups for different LDAP servers.

Example 1: Default schema of an Active Directory Server:

UserFilter=(objectClass=user)

Example 2: Default schema of a SunOne5.2 Directory Server:

UserFilter=(objectClass=inetPersonOrg)

UserGroupAssociationAttribute=<name>

–

Section: [<alt_auth>]

where <name> is the name of the attribute containing the association between user and user groups.

The attribute can be modeled either in the object class for users or in the object class for user groups. This attribute contains the Distinguished names of the referenced LDAP entries.

Only attribute names that are actually defined in the schema of the object class for users or for user groups are permitted.

Examples 1 and 2 specify the attribute containing the association between users and user groups for different LDAP servers.

Example 1: Default schema of an Active Directory Server:

UserGroupAssociationAttribute=memberOf

Example 2: Default schema of a SunOne5.2 Server:

UserGroupAssociationAttribute=uniquemember

UserGroupAssociationDirection=TO_USER | TO_GROUP

–

Section: [<alt_auth>]

This setting describes the association direction that is modeled in the LDAP schema and applies to the attribute specified in UserGroupAssociationAttribute. These are the possible values:

•

TO_GROUP association from a user to a user group. In this case, the association attribute must exist in the object class for users.

•

TO_USER association from a user group to a user. In this case, the association attribute must exist in the object class for user groups.

Examples 1 and 2 specify the association direction of the association attribute for different LDAP servers.

Example 1: Refers to the memberOf attribute in the default schema of an Active Directory Server:

UserGroupAssociationDirection=TO_GROUP

Example 2: Refers to the member attribute in the default schema of a SunOne5.2 Server:

UserGroupAssociationDirection=TO_USER

UserScope=BASE | LEVEL | SUBTREE

–

Section: [<alt_auth>]

This setting specifies how the search should be conducted in the tree segment specified in UserBaseDN. These are the possible values:

•

BASE - Only in root node.

•

LEVEL - All direct children of the root node.

•

SUBTREE - All offspring of the root node, including itself.