Configuring a Central User Directory or LDAP

Before You Begin

This chapter describes how Integration Server uses an external directory to authenticate clients, rather than using internally defined user and group information. For information about using internally defined users and groups, refer to Managing Users and Groups. You can set up Integration Server to access information from an external directory if your site uses one of the following external directories for user and group information:

Central user management via Common Directory Services and My webMethods Server
Lightweight Directory Access Protocol (LDAP)

You can configure Integration Server to use only one external directory at a time, a central user directory or LDAP.

Important: If you are using My webMethods Server in your environment, Software AG recommends that you configure Integration Server to work with a central user management directory. If you want to use an LDAP server and you are using My webMethods Server, it is recommended that you configure LDAP using My webMethods Server. Configure Integration Server to work with the LDAP server directly only when you are not using My webMethods Server.

Before you continue reading this chapter, you may find it helpful to first understand how Integration Server uses user and group information. Read the following sections if you have not already done so.

Overview of How Integration Server Works with Externally Defined Users and Groups

The following sections provide information about how and when Integration Server interacts with users and groups defined in a central user directory or in LDAP, specifically:

How externally defined users and groups can be used in Integration Server.
When Integration Server accesses information about externally defined users and groups.
How Integration Server authenticates users who belong to externally defined groups or roles.

How the Server Uses Externally Defined Users and Groups

Integration Server can use externally defined information for the same purposes it uses internally-defined user and group information:

To authenticate clients using user names and passwords
To control who can configure and manage Integration Server
To control who can create, modify, and delete services using Software AG Designer
To control access to services and files that are available in Integration Server

Externally defined information does not replace ACLs. To control access to services and files, you still need to set up the ACLs that identify the groups that are allowed and denied access to specific services and files. However, you can assign externally defined groups to an ACL.

When you configure the server to use central user management or LDAP directory, externally defined users and groups are not displayed on the Security > User Management page. However, if an external group has been mapped to an Integration Server ACL, the group will be displayed on the Security > Access Control Lists page.

Note: If the name of an externally defined user group contains an apostrophe (‘), Integration Server will not display the group on the Security > Access Control Lists page.

When the Server Accesses Externally Defined Information

Integration Server obtains externally defined information to authenticate clients and to determine whether an ACL allows or denies an action.

Note: Client requests that require Integration Server to access a central user directory or an LDAP directory may take longer to complete than those that do not.

How Integration Server Authenticates Externally Defined Clients

When authenticating clients using user names and passwords, Integration Server always looks for the user account internally before looking in an external directory, specifically:

When Integration Server finds an internally-defined user account for the supplied user name, Integration Server authenticates the client using the internally-defined information. If the supplied user name and password combination is correct, authentication succeeds and Integration Server proceeds with the request. If authentication fails and an external directory is not configured, Integration Server rejects the request with an "Invalid credentials" error.
If authentication fails and an external directory is configured (either a central user directory or LDAP), Integration Server requests that the external directory authenticate the client. If authentication succeeds, Integration Server proceeds with the request. If authentication fails, Integration Server rejects the request with an "Invalid credentials" error.
For example, if a user account is defined in the My webMethods Server user directory, Integration Server authenticates the client using the information defined in the My webMethods Server database. If the supplied password is correct, Integration Server proceeds with the request. If the supplied password is not correct, Integration Server rejects the request.

Note: If the passwords are contained in an external authentication system other than Central Users or LDAP, you must create your own pluggable module to obtain this information. See Customizing Authentication Using JAAS for information about setting up a pluggable module.
If Integration Server cannot find either an internally or externally defined user account for the user, Integration Server rejects the request.

If the user does not supply a user name or password, the server uses the internally-defined Default user account. This account grants access to resources that allow anonymous access.

Note: A local user can have the same name as a user in an external user directory. If the locally defined user and the externally defined user have the same password and the supplied password is correct, Integration Server authenticates the user with the privileges defined locally. This occurs because Integration Server checks its local user list first. If the passwords are different for the locally and externally defined user accounts, Integration Server treats the user accounts as two different users. An authentication request for the user that includes the externally defined password results in the external directory authenticating the user and granting the user the externally defined privileges.

Configuring Central User Management

Central user management involves using a single location to store and manage information about users of webMethods products. You can use Integration Server Administrator to grant users in a central directory access to Integration Server functionality and services. For example, you can assign a My webMethods Server role or group to an ACL.

If a user will access Integration Server or Trading Networks through My webMethods interfaces, create the users in My webMethods Server and then use Integration Server Administrator to give them access to the necessary areas. If such users are already defined in an external directory such as LDAP, you can configure My webMethods Server to work with the external directory. When configured this way, authentication and authorization requests are still made by the Integration Server; however, the server creates the connection to the external directory using the directory settings defined by the My webMethods Server database.

Users defined in a central location, such as the My webMethods Server user directory, are sometimes referred to as central users. The ability to use a central user directory for authentication is provided by the common directory services that are part of My webMethods Server.

Requirements for Integration Server to Use Central User Management

My webMethods Server must be installed and configured to use an external database.
My webMethods Server clustering must be configured even if Integration Server connects to a standalone My webMethods Server. This is because the client-side common directory services APIs used by Integration Server to communicate with My webMethods Server functions as a cluster node. My webMethods Server must be started at least once to enable My webMethods Server clustering.
Note: Beginning with My webMethods Server 10.0, My webMethods Server must use a Universal Messaging server as its JMS provider. My webMethods Server uses a JMS provider for cluster communication and synchronization.
Integration Server must have a JDBC connection pool that points to the My webMethods Server database component, and the CentralUsers functional alias must point to that connection pool. On the Settings > Resources page, MWS SAML Resolver URL field must point to your My webMethods Server host and port.
The Single Sign On with My webMethods Server must be configured to point to the My webMethods Server host and port. For more information about this property, see Configuring the MWS Single Sign-On Resource Setting.

Note: When Integration Server is successfully configured to use central user management, and the logging level for the server log facility 0024 User Manager is set to at least Info, Integration Server logs the message

[ISS.0024.0012I] Central User
												Management initialized successfully

upon startup.

If you later want to stop using central user management, follow the instructions in Connecting Integration Server to Database Components in an External RDBMS, but in the Associated Pool Alias list, click None for the CentralUsers function, and then restart Integration Server.

Note: Integration Server updates the Anonymous ACL automatically to include the My webMethods Users Role from My webMethods Server.

For more information about configuring My webMethods Server for common directory services and clustering, see Administering My webMethods Server.

Note: If Central User Management is configured to use LDAP over SSL, set the javax.net.ssl properties in the custom_wrapper.conf file.

Considerations for My webMethods Server Query Roles

Integration Server can slow or terminate unexpectedly when handling service invocations if Integration Server has to evaluate all roles defined in My webMethods Server, including LDAP query and database query roles. You might encounter this issue when invoking Integration Server services using WS Client Connectors from a CAF application, especially if the following conditions are true:

When there are LDAP query and database query roles defined in My webMethods Server.
Common Users is enabled in Integration Server.
The services have ACLs assigned to them.

Evaluation of these roles depend on external query execution and might impact Integration Server performance.

You can control whether Integration Server evaluates LDAP or database query roles in the server using the watt.cds.skip.role.types extended setting. If LDAP or database query roles are not used for any ACL management in Integration Server with Central Users enabled, you might consider disabling the query roles evaluation function.

For more information about using the watt.cds.skip.role.types extended setting, see Server Configuration Parameters.

Overview of Using LDAP

If your site uses Lightweight Directory Access Protocol (LDAP) for user and group information, you can configure the Integration Server to obtain user and group information from the external directory. You can configure Integration Server to use more than one LDAP directory at a time, allowing Integration Server to work with different LDAP directories for users in different locations or different organizations. In addition, you can maintain multiple LDAP directories so that one directory serves as a backup for another.

Important: If you want to use an LDAP server to store user information and you are using My webMethods Server, it is recommended that you configure LDAP using My webMethods Server. Configure Integration Server to work with LDAP server directly only when you are not using My webMethods Server.

LDAP protocols are designed to facilitate sharing information about resources on a network. Typically, they are used to store profile information (login ID, password, etc.). You can also use them to store additional information. Integration Server uses LDAP for performing external authentication.

Using your existing LDAP information allows you to take advantage of a central repository of user and group information. System administrators can add and remove users from the central location. Users do not need to remember a separate password for webMethods applications; they can use the same user names and passwords that they use for other applications. Remember to use your LDAP tools to administer users or groups stored in an external directory.

About LDAP and Caching

For LDAP, after accessing user information, the Integration Server caches it to improve performance. If the information remains in the cache for one hour without being accessed, or if the cache space is needed for a more recent request, the Integration Server deletes the information from the cache.

If the server receives subsequent requests that require the information it has in cache, the Integration Server uses the cached information rather than accessing the external directory.

Configuring the Server to Use LDAP

About this task

To configure the server to use LDAP, you need to:

Instruct Integration Server to use the LDAP protocol
Define one or more configured LDAP servers that the Integration Server is to use for these users
If an LDAP provider is SSL-enabled, you can set the JVM Truststore Alias field on the Security > Certificates page to point to the trusstore alias that contains the certificates required to establish a secure connection with the LDAP server.
Note: The value of the JVM Truststore Alias field is used as the value of the watt.server.ssl.trustStoreAlias parameter. As an alternative to using the JVM Truststore Alias, you can set the watt.server.ssl.trustStoreAlias parameter.

Software AG recommends that you use central user management instead of configuring Integration Server to use one more LDAP directories for external user management. For more information about central user management, seeConfiguring Central User Management and Administering My webMethods Server.

To specify LDAP as the external provider

Procedure

Open the Integration Server Administrator if it is not already open.
Go to Security > User Management.
Click LDAP Configuration.
Click Edit LDAP Configuration.
Next to Provider, select LDAP.

Integration Server issues a prompt to verify that you want to change the setting. Click OK. If your Integration Server is configured to central user management, you must disable it before you can configure LDAP. For information about disabling central user management, see Configuring Central User Management.

Enter the following information:

For this field...	Specify...
Cache Size (Number of Users)	The maximum number of LDAP users Integration Server can keep in memory in the user cache. The default is 10. Once the limit is reached, Integration Server selects users for removal from the cache based on how long they have been idle. As a result, activity can extend the time a user remains in the cache. As a general rule, specify a cache size equivalent to 5-10% of the number of users in your LDAP system. However, if only a few sessions are ever logged on simultaneously, set the cache size to be the same as the number of simultaneous sessions.
Credential Time-to-Live (Minutes)	The number of minutes an LDAP user's credentials (userid and password) can remain in the credential cache before being purged. The default is 60 minutes. When a user first attempts to log in, Integration Server creates a user object and checks the user's credentials against the LDAP directory. Integration Server stores the credentials so that subsequent requests to authenticate will be made against the cached credentials, not the LDAP directory. For security reasons, you can control the length of time these cached credentials are valid. The credentials are secure because they are stored using a one-way hashing function, and cannot be recovered from the cache. If a user attempts to log in with credentials that do not match the cached version, Integration Server flushes the cache and checks the credentials against the LDAP directory. If the credentials are valid, the Integration Server caches them; otherwise, the cache remains empty. For normal secure environments, a time-to-live value between one hour and one day is adequate. For higher security environments, a time-to-live of between one and five minutes may be more appropriate. The Time-to-Live is absolute; therefore, activity will not cause the credentials to remain in cache longer.

For this field...

Specify...

Cache Size (Number of Users)

The maximum number of LDAP users Integration Server can keep in memory in the user cache. The default is 10.

Once the limit is reached, Integration Server selects users for removal from the cache based on how long they have been idle. As a result, activity can extend the time a user remains in the cache.

As a general rule, specify a cache size equivalent to 5-10% of the number of users in your LDAP system. However, if only a few sessions are ever logged on simultaneously, set the cache size to be the same as the number of simultaneous sessions.

Credential Time-to-Live (Minutes)

The number of minutes an LDAP user's credentials (userid and password) can remain in the credential cache before being purged. The default is 60 minutes.

When a user first attempts to log in, Integration Server creates a user object and checks the user's credentials against the LDAP directory. Integration Server stores the credentials so that subsequent requests to authenticate will be made against the cached credentials, not the LDAP directory.

For security reasons, you can control the length of time these cached credentials are valid. The credentials are secure because they are stored using a one-way hashing function, and cannot be recovered from the cache. If a user attempts to log in with credentials that do not match the cached version, Integration Server flushes the cache and checks the credentials against the LDAP directory. If the credentials are valid, the Integration Server caches them; otherwise, the cache remains empty.

For normal secure environments, a time-to-live value between one hour and one day is adequate. For higher security environments, a time-to-live of between one and five minutes may be more appropriate.

The Time-to-Live is absolute; therefore, activity will not cause the credentials to remain in cache longer.

Click Save Configuration.

To finish configuring Integration Server to use an LDAP directory, continue to the procedure Defining an LDAP Directory to Integration Server.

Defining an LDAP Directory to Integration Server

About this task

To define an LDAP directory to Integration Server

Procedure

Open the Integration Server Administrator if it is not already open.
Go to Security > User Management.
Click LDAP Configuration.
Click Add LDAP Directory.

On the Settings > LDAP Directory > Add page, enter the following information:

For this parameter	Specify...
Directory URL	The complete URL of the LDAP server. The URL has the format `protocol`://`hostname`:`portnumber` where The `protocol` is LDAP for standard connections or LDAPS for secure connections. The `host` is the host name or IP address of the LDAP server. The `port` is the port on which the server is running. The port is optional. If omitted, the port defaults to 389 for LDAP, or 636 for LDAPS. For example, specifying the URL `ldaps://ldapserv1:700` would create a secure connection to the LDAP server running on the non-standard port 700 on the host called ldapserv1. If you specify ldaps, Integration Server attempts to make a secure connection to the directory server using an SSL socket. If the directory server is configured to use SSL, it will have a server certificate in place to identify itself to clients. This certificate must be signed by an authority to prove its validity (i.e. the server certificate is signed by a CA). By default, the Integration Server will only trust certificates signed by a signing authority whose CA certificate is in the Integration Server's trusted CAs directory. Refer to Configuring Integration Server for Secure Communications for instructions on configuring the trusted CAs directory and finding the CA certificate.
Principal	The user ID the Integration Server should supply to connect to the LDAP server, for example, `o=webm.com` or `dc=webm,dc=com`. This user should not be the Administrator account, but a user that has permission to query groups and group membership. If your LDAP server allows anonymous access, leave this field blank.
Credentials	The password the Integration Server should supply to connect to the LDAP server, that is, the Principal's password. The Integration Server encrypts this password according to the settings specified on the Outbound Passwords page. For more information, see Configuring Integration Server for Secure Communications.
Connection Timeout (seconds)	The number of seconds the Integration Server will wait while trying to connect to the LDAP server. After this time has passed, the Integration Server will try the next configured LDAP server on the list. The default is 5 seconds. Increase this number if your network has latency problems. If most requests will be from batch processes, you can increase this number to be 30 seconds or more.
Minimum Connection Pool Size	The minimum number of connections allowed in the pool that the Integration Server maintains for connecting to the LDAP server. When the Integration Server starts, the connection pool initially contains this minimum number of connections. The Integration Server adds connections to the pool as needed until it reaches the maximum allowed, which is specified in the Maximum Connection Pool field. The default is 0.
Maximum Connection Pool Size	The maximum number of connections allowed in the pool that the Integration Server maintains for connecting to the LDAP server. When the Integration Server starts, the connection pool initially contains a minimum number of connections, which are specified in the Minimum Connection Pool field. The Integration Server adds connections to the pool as needed until it reaches the maximum allowed. The default is 10.
Synthesize DN	Builds a distinguished name by adding a prefix and suffix to the user name. The Synthesize DN method can be faster than the Query DN method (see below) because it does not perform a query against the LDAP directory. However, if your LDAP system does not contain all users in a single flat structure, use the Query DN method instead. DN Prefix A string that specifies the beginning of a DN you want to pass to the LDAP server. DN Suffix A string that specifies the end of a DN you want to pass to the LDAP server. For example, if the prefix is "cn=" and the suffix is ",ou=Users" and a user logs in specifying "bob", the Integration Server builds the DN `cn=bob,ou=Users` and sends it to the LDAP server for authentication. Note: Be sure to specify all the characters required to form a proper DN. For instance, if you omit the comma from the suffix above, that is, you specify "`ou=Users`" instead of "`,ou=Users`", the Integration Server will build the invalid DN (`cn=bobou=Users`).
Query DN	Builds a query that searches a specified root directory for the user. Use this method instead of the Synthesize DN method (see above) if your LDAP directory has a complex structure. UID Property A property that identifies an LDAP userid, such as `"cn"` or `"uid"`. User Root DN Enter the full distinguished name. For example, if you specify `ou=users,dc=webMethods,dc=com`, the Integration Server will issue a query that starts searching in the root directory `ou=users` for a common name that matches the name the user logged in with.
User Email	Specifies the name of the attribute that is used to store users' email addresses. For example, "mail".
Default Group	An Integration Server group with which the user is associated. The user is allowed to access services that members of this Integration Server group can access. This access is controlled by the ACLs with which the group is associated. If you also specify a value in the Group Member Attribute field, the user has the same access as members of the Integration Server group and members of LDAP groups that have been mapped to an Integration Server ACL. Important: Do not specify Anonymous as the default group if any user in this group needs to have administrator privileges. The default ACL denies the Anonymous group and will not allow access the root page. Choose the appropriate group in the Default Group field to ensure that the required ACLs get assigned to your group. Important: You must specify a value in the Group Member Attribute field, the Default Group field, or both.
Group Member Attribute	The name of the attribute in a group's directory entry that identifies each member of the group. This value is usually "member" or "uniqueMember", but can vary depending on the schema of the LDAP directory. Integration Server uses this information during ACL checking to see if the user attempting to log in belongs to an LDAP group that has been mapped to an ACL. If no value is specified here, Integration Server does not check for membership in an LDAP group. As a result, the user's ability to access Integration Server services is controlled by the Integration Server group specified in the Default Group field. Note: You must specify a value in the Group Member Attribute field, the Default Group field, or both.
Group ID Property	A property that identifies an LDAP group, such as CN.
Group Root DN	The full distinguished name. For example, if you specify `ou=groups,webMethods,dc=com,` Integration Server will issue a query that will display all the LDAP groups. Note: You must specify values in the Group ID Property and Group Root DN fields.

Click Save Changes.

The LDAP Directory List displays the added the LDAP directory.
Click Move Up/Move Down to order the directories in the list based on their priority.

Note: If you define multiple LDAP servers, Integration Server will search the LDAP directories in the order in which they are displayed on the Security > User Management > LDAP Configuration page. If Integration Server does not find the user in the first LDAP directory, it will search in order through the list.

Mapping an LDAP User's Access to ACLs

As with Integration Server groups, you can associate LDAP groups with ACLs to control access to Integration Server resources. Associating an LDAP group with an ACL is referred to as mapping. ACL mapping to LDAP groups can be done directly through the Security > ACLs page. For more information about allowing groups access to ACLs, refer to Allowing or Denying Group Access to ACLs.

Stopping Use of an LDAP as an External Directory

About this task

If you no longer want to use LDAP as an external directory, you can update the configuration to remove the external directory configuration settings.

To stop using a LDAP as an external directory

Procedure

Open the Integration Server Administrator if it is not already open.
Go to Security > User Management.
Click Edit LDAP Configuration.
Click Local in the Provider field.
Click Save Configuration.
Click OK.
Restart your Integration Server.

Considerations for User Accounts and Groups

This section provides information about user accounts and groups that you should consider if you are using an external directory for user and group information.

You should keep internal and external user accounts and group names unique.It might get confusing if you have an external user account that has the same user name as an internal user account or an external group with the same group name as an internal group. For more information, see About Keeping Internal and External User Accounts and Group Names Unique.
You cannot use the Integration Server Administrator to manage (i.e., create, edit, or delete) Central Users.You must use My webMethods Server to administer Central Users and Directories. Refer to Administering My webMethods Server for more information.
You cannot use the Integration Server Administrator to manage (i.e., create, edit, or delete) LDAP user and group information. To make changes to LDAP directories, follow your site's standard directory update procedures.
You can perform package replication without using the predefined Replicator account.You can use a different account for package replication as long as the subscription requester specifies an account that is a member of a group that is assigned to the Replicators ACL. For more information, see About User Groups and Package Replication.

About Keeping Internal and External User Accounts and Group Names Unique

Software AG recommends that you keep user names and group names unique between internal and external user accounts and groups. Having an external user account that has the same user name as an internal user account, or an external group with the same group name as an internal group might get confusing. If you do have identically named user names or group names, the server always uses the internally-defined information.

To avoid confusion, Software AG recommends that you do not set up user accounts or groups internally if you are using an external directory. The exceptions are the predefined user accounts Default, Administrator, Developer, Replicator, and the predefined groups Everybody, Administrators, Developers, Replicators, and Anonymous. You cannot delete these user accounts and groups; therefore, make sure the internal accounts and groups have the correct definitions.

An exception to the above diagram is that all internally-defined users are members of the internally-defined Everybody group.

About User Groups and Package Replication

Although Integration Server is distributed with a predefined Replicator account, you can use a different account for package replication. As long as the subscription requester specifies an account that is a member of a group that is assigned to the Replicators ACL, that user can perform replication.

When publishing a package to another server, the publishing server uses the account specified by the subscription requester. For example, if the subscription requester (either the publisher or the subscriber) specified account DEPT01, the publisher will log into the subscriber server as DEPT01. DEPT01 must be a member of a group that is assigned to the Replicators ACL on the subscriber server.

Refer to Copying Packages from One Server to Another for more information about package replication.

About Granting Administrator Privileges to External Users

The Administrators ACL controls who has administrator privileges. Because you cannot assign externally defined users to internally-defined groups, you cannot grant externally defined users administrator privileges by assigning them to the internally-defined Administrators group. Instead, you need to set up an externally defined group for administrators. Then, add the externally defined group of administrators to the Administrators ACL.

To make a group of central users IS Administrators, you will need to add their group or role to the following ACLs:

Administrators ACL
Default ACL
Developers ACL
Internal ACL
Replicators ACL
Anonymous ACL (if their role/group is not part of this already)

Note: If you configured Integration Server to use central user management, the Anonymous ACL automatically includes the My webMethods users role.

Granting Administrator Privileges to an Externally Defined User

About this task

To grant administrator privileges to an externally defined user

Procedure

Set up an externally defined user account for the user if one does not already exist.
Set up an externally defined administrators group if one does not already exist.

Important: Do not name the externally defined group "Administrators". The name of the group must not be the same name as any internally-defined group.
Make the externally defined user a member of the externally defined administrators group (ISAdmins in the picture above).
Update the Administrators ACL to include the externally defined administrators group in the Allowed list.

Refer to Allowing or Denying Group Access to ACLs for information on how to include externally defined administrators to the Allowed list.

Granting Developer Privileges to External Users

About this task

The Developers ACL controls who can connect to the Integration Server from Software AG Designer to create, modify, and delete services that reside on the server. Because you cannot assign externally defined users to internally-defined groups, you cannot grant externally defined users developer privileges by assigning them to the internally-defined Developers group. Instead, you need to set up an externally defined group for Designer. Then, add the externally defined group to the Developers ACL.

To grant developer privileges to an externally defined user

Procedure

Set up an externally defined user account for the user if one does not already exist.
Set up an externally defined developers group if one does not already exist.

Important: Do not name the externally defined group "Developers". The name of the group must not be the same name as any internally-defined group.
Make the externally defined user a member of the externally defined developers group (ISDevs in the picture above).
Update the Developers ACL to include the externally defined developers group in the Allowed list.

Refer to Allowing or Denying Group Access to ACLs for information on how to include externally defined developers to the Allowed list.

Granting Access to Services and Files to External Users

You create ACLs that control access to services and files and assign them to the specific services and files that you want to protect.

To grant access to a service or file, the server first uses internally-defined information to determine whether the client is a member of allowed or denied groups listed in the ACL. If the server cannot find the information internally, it obtains externally defined information to determine if the ACL allows or denies access.

If you want to allow an externally defined user access to a service or file, update the ACL that protects the service or file to identify the external user's group or role as an Allowed group in the ACL. Similarly, if you want to explicitly deny an externally defined user access to a service or file, update the ACL that protects the service or file to identify the external user's group or role as a Denied group in the ACL.