Table of contents 1 Groups...2 2 People...2 3 Authentication...3 4 Directory Service... 4 4.1 Connection Properties... 5 4.2 User Retrieval Properties...6 4.3 User Attribute Properties...7 4.4 Group Retrieval Properties... 8 4.5 Group Attribute Properties... 9 5 Search vs. Lookup...10 6 Groups Omitted...10
The following discussion assumes that you have an LDAP server, configured as follows: host: localhost (assuming it is running on the local host) port: 389 suffix: "dc=example,dc=com" rootdn: "cn=admin,ou=people,dc=example,dc=com" rootpw: "myldappw" (set according to your LDAP server instructions) and that the data in your directory is configured as follows: dc=example,dc=com ou=groups cn=development cn=support cn=quality Assurance... ou=people uid=admin... The object classes used by the "ou=groups" and "ou=people" entries are 'organizationalunit' and 'top'. 1. Groups The object classes used by each Groups entry are 'GroupOfUniqueNames' and 'top'. Each group entry will have a 'cn' attribute which represents the group name (the common name) and one 'uniquemember' attribute for each member of the group. Each uniquemember entry will be the distinguished name of the member (see below). For example: uniquemember: uid=admin,ou=people,dc=example,dc=com uniquemember: uid=bill,ou=people,dc=example,dc=com... 2. People The object classes used by each People entry are 'inetorgperson', 'organizationalperson' and 'person'. With this configuration, each user's Distinguished Name (dn) will be: uid=uid,ou=people,dc=example,dc=com where UID is the user's login name. Page 2
If your LDAP server utilizes a different configuration, some of the LDAP-specific property values may have to be changed. For example, if the object classes used to represent users in your configuration don't contain an attribute named 'uid', then properties which depend on the 'uid' attribute will need to be modified. There will be more about this later. 3. Authentication ActiveWorkflow is distributed with a simple mechanism for authentication, using a CSV file containing user names and passwords. To authenticate usernames and passwords against an LDAP directory instead, minor changes to the ActiveWorkflow configuration are required. First, you must modify the properties in the AuthenticationService properties file, as follows: login.module Modify the login.module value to be LDAP. login.module: LDAP module.is.external Used to indicate whether or not the module is configured external to ActiveWorkflow. For LDAP, this should be set to false: module.is.external: false ldap.url Set to the URL of your LDAP server. In the typical configuration, mentioned above, the URL would be: ldap.url: ldap://localhost:389/ ldap.dn.mapping This property is used to look up a user in the LDAP server, based on the login name provided. The value of the property is a template used to create the actual LDAP query string. The variable parameter ${username} will be replaced by the user's login name. The result should be the distinguished name of the user. In our typical configuration, above, the distinguished name of the 'admin' user is "uid=admin,ou=people,dc=example,dc=com". An ldap.dn.mapping template for this configuration would therefore be: ldap.dn.mapping: uid=${username},ou=people,dc=example,dc=com ldap.mechanism This property is used to specify the authentication mechanism used by the LDAP server. The default mechanism used is "simple". For example: Page 3
ldap.mechanism: simple Once these properties are set and you have updated your deployed Control Center, you should be able to log into the ActiveWorkflow Administrator web application using your LDAP-based credentials. 4. Directory Service ActiveWorkflow also integrates with a directory service, which provides policies with access to information about the people and groups in an organization. For example, a Policy can send an email to the assignee of a Process by looking up the assignee's email address from the directory service by calling the lookupemail() method of a com.unify.nxj.bpm.engine.util.navigator object. The ActiveWorkflow Server assumes that users in the directory service are identified by a unique string (hereinafter referred to as a username), which can be used to retrieve information specific to that user. To use a directory service, the ActiveWorkflow server needs to know how to do the following tasks: Authenticate with the directory service (if necessary) Look up user entries Look up group entries These tasks are performed in different ways, depending on the directory service to be used. For the LDAP directory service, the ActiveWorkflow server needs to know how to structure the queries used to locate the appropriate entries in the database. To configure the ActiveWorkflow Server to use an LDAP directory service, some of the ActiveWorkflow properties will need to be modified, as follows: First, you must verify the properties in the DirectoryService properties file, as follows: moduleclass This needs to be set to the ActiveWorkflow class which implements the desired directory service. For LDAP, this should be set as follows: moduleclass: com.unify.nxj.bpm.engine.services.directory.ldapdirectorymodule directory.config This is the property file used to set the module class-specific properties, used by the module. For LDAP, this should be set as follows: Page 4
directory.config: LdapDirectoryModule.properties Next, you will need to verify the property settings in the file specified by the directory.config property. In this case, LdapDirectoryModule.properties. This property file contains several property settings, grouped into sections. Connection Properties User Retrieval Properties User Attribute Properties Group Retrieval Properties Group Attribute Properties 4.1. Connection Properties The connection properties section includes the 'url' setting for the LDAP server as well as the 'auth*' settings for authentication. The 'url' setting should be set to the URL of your LDAP server. An example, using the typical configuration mentioned above would be: url: ldap://localhost:389/ The 'auth*' properties are used to specify the authentication mechanism used to communicate with the LDAP server. If your LDAP server allows anonymous access, you can set the mechanism to "none", as in: authmechanism: none If your LDAP server requires authentication, you will need to set up the authentication properties, as follows: authmechanism Different LDAP servers support different authentication mechanisms but a mechanism supported by most servers is 'simple'. The 'simple' mechanism uses clear text user names and passwords. To use this mechanism, set the authmechanism property as follows: authmechanism: simple Other values for the authmechanism property can be used, but may require additional system properties to be set in the JVM of the application server, or may require additional configuration of the LDAP server. The value of the authmechanism property is used as the Context.SECURITY_AUTHENTICATION property when creating the JNDI initial context. For more information on the use of other authentication mechanisms, see Sun's Page 5
documentation on JNDI and LDAP security. authprincipal This is set to the distinguished name of the principal used for authentication. This is normally set to the root dn, configured for your LDAP server. Using the typical configuration mentioned above, it would be set as follows: authprincipal: cn=admin,ou=people,dc=example,dc=com authcredentials This is used to specify the password for the user specified by the authprincipal property. Using the typical configuration, it would be set as follows: authcredentials: myldappw 4.2. User Retrieval Properties The user retrieval properties section includes the properties used to look-up users in the LDAP directory system. The following properties are available: user.startingcontextname This property specifies the LDAP context in which users will be looked up or searched. For the typical configuration mentioned above, this would be set as follows: user.startingcontextname: dc=example,dc=com user.searchbytitlestring A template for the LDAP query string that is used to search for all users with a given title. This search is conducted on the subtree defined by having the user.startingcontextname context as the root context of the subtree. The String '${title}' will be replaced by the title being searched for. user.searchbytitlestring: (&(objectclass=person)(title=${title})) will search for all entries where an objectclass of "person" is used, and where the entry's 'title' attribute is equal to the specified title. user.searchbyusernamestring A template for the LDAP query string that is used to search for a user with a given username. This search is conducted on the subtree defined by having the Page 6
user.startingcontextname context as the root context of the subtree. The String '${username}' will be replaced by the username being searched for. Note that either this property or user.lookupbyusernamestring must be specified. For performance reasons, if both are specified, the lookup will be used and the search will be ignored. user.searchbyusernamestring: (&(objectclass=person)(uid=${username})) will search for all entries where an objectclass of "person" is used, and where the entry's 'uid' attribute is equal to the specified username. user.lookupbyusernamestring A template for the LDAP name of the user being looked up. This name must be relative to the LDAP context defined by user.startingcontextname. The string '${username}' will be replaced by the username being looked up. Either this property or user.searchbyusernamestring must be specified. For performance reasons, if both are specified, the lookup will be used and the search will be ignored. user.lookupbyusernamestring: uid=${username},ou=people will be combined with the starting context to construct a fully- qualified distinguished name. Given the typical configuration mentioned earlier, and searching for the user 'admin', this would result in a distinguished name of: "uid=admin,ou=people,dc=example,dc=com" which represents a single user within our LDAP directory service. 4.3. User Attribute Properties The user attribute properties section includes the properties used to indicate the attribute name used for each element of the user entry in the LDAP directory service. The actual attribute names depend on the object classes used to represent the user entries and the schema in use by the particular LDAP server. The following list shows the available properties and the values which would be used in the typical configuration, mentioned earlier. Page 7
user.emailattributename: mail user.firstnameattributename: givenname user.lastnameattributename: sn user.usernameattributename: uid user.passwordattributename: userpassword user.titleattributename: title 4.4. Group Retrieval Properties The group retrieval properties section includes the properties used to look-up groups in the LDAP directory system. The following properties are available: group.startingcontextname This property specifies the LDAP context in which groups will be looked up or searched. For the typical configuration mentioned above, this would be set as follows: group.startingcontextname: dc=example,dc=com group.searchbymemberstring A template for the LDAP query string that is used to search for all groups that have a given user as one of their members. This search is conducted on the subtree defined by having the group.startingcontextname context as the root context of the subtree. The String '${username}' will be replaced by the user name of the group member being searched for. group.searchbymemberstring: (&(objectclass=groupofuniquenames)(uniquemember=d=${username},ou=people,dc=example,dc will search for all entries where an objectclass of "groupofuniquenames" is used, and where the entry's 'uniquemenber' attribute is equal to the generated member name. In our case, the member name is the distinguished name of the member's user entry. group.searchbygroupnamestring A template for the LDAP query string that is used to search for a group with a given groupname. This search is conducted on the subtree defined by having the group.startingcontextname context as the root context of the subtree. The String '${groupname}' will be replaced by the group name being searched for. Either this property or group.lookupbygroupnamestring must be specified. For performance reasons, if both are specified, the lookup will be used and the search will be ignored. Page 8
group.searchbygroupnamestring: (&(objectclass=groupofuniquenames)(cn=${groupname})) will search for all entries where an objectclass of "groupofuniquenames" is used, and where the entry's 'cn' attribute is equal to the specified group name. group.lookupbygroupnamestring A template for the LDAP name of the group being looked up. This name must be relative to the LDAP context defined by group.startingcontextname. The string '${groupname}' will be replaced by the groupname being looked up. Either this property or group.searchbygroupnamestring must be specified. For performance reasons, if both are specified, the lookup will be used and the search will be ignored. group.lookupbygroupnamestring: cn=${groupname},ou=groups will be combined with the starting context to construct a fully- qualified distinguished name. Given the typical configuration mentioned earlier, and searching for the 'Development' group, this would result in a distinguished name of: "cn=development,ou=groups,dc=example,dc=com" which represents a single group within our LDAP directory service. 4.5. Group Attribute Properties The group attribute properties section includes the properties used to indicate the attribute name used for each element of the group entry in the LDAP directory service. The actual attribute names depend on the object classes used to represent the group entries and the schema in use by the particular LDAP server. The ActiveWorkflow server assumes that each member of a group will be stored as a separate value of the membership attribute, rather than having the membership list concatenated into a single value of the membership attribute. The following list shows the available properties and the values which would be used in the typical configuration, mentioned earlier. group.groupnameattributename: cn group.membershipattributename: uniquemember Page 9
5. Search vs. Lookup The ActiveWorkflow Engine supports two different methods of retrieving User and Group information from an LDAP server: lookup and search. The lookup method involves retrieving the attributes of a User or Group object by its LDAP name. The search method involves searching an LDAP context (specified by the startingcontextname property) and all of its sub contexts (recursively) for objects matching a given search filter. Each method has advantages over the other and they are appropriate for different LDAP configurations. For example, Users may be stored in the LDAP directory in such a manner that it is impossible to write a lookupstring that will allow access all the users. On the other hand, if such a lookupstring can be written, it is likely to be faster to lookup users by name than to search for them (although actual performance will differ between LDAP servers). 6. Groups Omitted For performance reasons, the current implementation of the LdapDirectoryModule does not include the Groups in User objects returned by methods of the DirectoryModule interface. If Group information for a User is needed, a separate call to getgroupsforuser() can be made. Page 10