User authentication

CloudBees Build Acceleration uses account information from multiple sources. In most cases, the primary account information source is an external LDAP or Active Directory repository: both user and group information is retrieved from the repository. Local users and groups can be defined within CloudBees Build Acceleration.

Getting started

Go to the following directory on the Cluster Manager server: <ECloud install>/<arch>/conf
Make a copy of the ldap_template.xml file if you intend to use LDAP, or the ad_template.xml file if you prefer to use Active Directory. Save the copy in the conf directory as any name you choose or use the name: securityContext.xml.
Still working in conf, open the accelerator.properties file.
- Locate the following commented-out text string: #ACCELERATOR_SECURITY_CONTEXT_FILES=conf/securityContext.xml
- If you did not name your template copy securityContext.xml, replace `securityContext.xml ` with the file name you chose.
- Uncomment the `ACCELERATOR_SECURITY_… ` text string by removing the lead “” sign.
- Comment out `ACCELERATOR_SECURITY_CONTEXT_FILES= ` (which immediately follows the line you uncommented)
Use the LDAP information and examples in the following sections to fill in your own copy of the LDAP template.
Restart the Cluster Manager service.

For more information, see Stopping, Starting, or Restarting the Cluster Manager Service.
After the Cluster Manager is running, lsign in to the Cluster Manager UI as “admin”.
Go to Administration > Permissions .
Click Enable User or Enable Group.
Search for the desired user or group (or search for “*” to see all). If you set it up correctly, the requested LDAP users are visible.
Select the appropriate users or groups to enable using the corresponding checkbox(es).
Ensure that the desired permissions are set for the users or groups. (The online help system contains additional information about permissions.)

If you experience permissions issues while reading the ldap_template.xml or ad_template.xml copy, verify that the account that runs the Cluster Manager also has read permission for that file. To diagnose problems that cause Cluster Manager startup issues, including LDAP/Active Directory configuration problems, check <ECloud install>/<arch>/logs/accelerator.log.

Configuring LDAP

A number of options must be customized for any LDAP configuration. The following sample configuration is from the ldap_template.xml file. After the sample, see a list of properties with a description.

Sample LDAP configuration

<bean id="ldapDirectoryProvider"         class="com.electriccloud.security.ldap.    LdapDirectoryProviderImpl"><property name="providerName" value="LDAP"/><property name="url" value="ldap://myldaphost/dc=company,dc=com"/><property name="userBase" value="ou=People"/><property name="userSearchFilter" value="uid={0}"/><property name="userSearchSubtree" value="false"/><property name="userNameAttribute" value="uid"/><property name="fullUserNameAttribute" value="gecos"/><property name="emailAttribute" value="mail"/><!--<property name="managerDn" value="uid=admin,ou=People,dc=company,dc=com"/> --><!--<property name="managerPassword" value="password"/> --><!--<property name="groupBase" value="ou=Group"/> --><!--<property name="groupMemberFilter" value="(member={0})"/> --><!--<property name="groupMemberAttributes" value="member"/> --><!--<property name="groupSearchFilter" value="(objectClass=groupOfNames)"/> --><!--<property name="groupNameAttribute" value="cn"/> --><!--<property name="verifyCerts" value="true"/> --></bean>▼

The following properties configure LDAP mapping:

Property Description

emailAttribute

(optional) The attribute in a user record that contains the user’s email address. If the attribute is not specified, the account name and domain name are concatenated to form an email address.

fullUserNameAttribute

(optional) The attribute in a user record that contains the user’s full name (first and last name) for display in the UI. If this attribute is not specified or the resulting value is empty, the user’s account name is used instead.

managerDn

(optional) The DN of a user who has read-only access to LDAP user and group directories. If this property is not specified, the server attempts to connect as an unauthenticated user. Not all servers allow anonymous read-only access.

This user does not need to be an admin user with modify privileges.

managerPassword

(optional) If the managerDn property is set, this password is used to authenticate the manager user.

providerName

This human readable name is displayed in the user interface to identify users and groups that come from this provider.

userBase

This string is prepended to the basedn to construct the directory DN that contains user records.

userNameAttribute

The attribute in a user record that contains the user’s account name.

userSearchFilter

This LDAP query is performed in the context of the user directory to search for a user by account name. The string “{0}” is replaced with the user’s login ID. Typically, the query compares a user record attribute with the substituted user login ID.

userSearchSubtree

This property, if true, searches the entire subtree as identified by context. If false, (the default) then only the level identified by the context is searched.

url

The LDAP server URL is in the form protocol://<host>:<port>/basedn. Protocol is either ldap or ldaps (for secure LDAP). The port is implied by the protocol, but can be overridden if it is not at the default location (389 for ldap, 636 for ldaps). The basedn is the path to the top level directory that contains users and groups at this site. This is typically the domain name where each part is listed with a dc= and separated by commas.

Spaces in the basedn must be URL encoded (%20).

verifyCerts

(optional) This property enables certificate verification for LDAPS connections if true.

In addition to user information, the LDAP server can be queried for group information. This query is optional because the local group mechanism can refer to LDAP users as well as local users. However, the following elements can be used to tell the server how to map groups in LDAP:

Property Description

Property	Description
`groupBase`	(optional) This string is prepended to the `basedn` to construct the directory DN that contains group records.
`groupMemberAttributes`	(optional) A comma separated attribute names list that identifies a group member. Most LDAP configurations only specify a single value, but if there is a mixture of POSIX and LDAP style groups in the directory, multiple attributes might be required.
`groupMemberFilter`	(optional) This LDAP query is performed in the groups directory context to identify groups that contain a specific user as a member. There are two common forms of group record in LDAP directories: POSIX style groups where members are identified by account name, and `groupOfNames` or `uniqueGroupOfNames` records where members are identified by the full user DN. Both forms are supported, so the query is passed two parameters: “{0}” is replaced with the full user record DN, and “{1}” is replaced with the user’s account name.
`groupNameAttribute`	(optional) The group record attribute that contains the name of the group.
`groupSearchFilter`	(optional) This LDAP query is performed in the context of the groups directory to enumerate group records.

groupBase

(optional) This string is prepended to the basedn to construct the directory DN that contains group records.

groupMemberAttributes

(optional) A comma separated attribute names list that identifies a group member. Most LDAP configurations only specify a single value, but if there is a mixture of POSIX and LDAP style groups in the directory, multiple attributes might be required.

groupMemberFilter

(optional) This LDAP query is performed in the groups directory context to identify groups that contain a specific user as a member. There are two common forms of group record in LDAP directories: POSIX style groups where members are identified by account name, and groupOfNames or uniqueGroupOfNames records where members are identified by the full user DN. Both forms are supported, so the query is passed two parameters: “{0}” is replaced with the full user record DN, and “{1}” is replaced with the user’s account name.

groupNameAttribute

(optional) The group record attribute that contains the name of the group.

groupSearchFilter

(optional) This LDAP query is performed in the context of the groups directory to enumerate group records.

Determining LDAP mapping

A typical POSIX user record in LDAP looks similar to the example below. To set up a mapping for this record, it is necessary to identify various record components.

First, identify the path in the directory that contains user records. In this example, the build user has a distinguished name (dn) of uid=build,ou=People,dc=mycompany,dc=com. This name uniquely identifies the build user account and this path splits into three parts:

base dn: dc=mycompany,dc=com
user base: ou=People
user element: uid=build

The baseDn is the parent of the directory that contains users. This value is combined with the protocol and server to form the URL. In this case, the URL ends up as ldaps://dir/dc=mycompany,dc=com. The userBase is the portion of the path that identifies the directory containing all user account records. This value is used directly as the userBase configuration element. The remaining portion identifies the user without the People directory: uid=build. The user name is replaced in this value with the string “{0}” to form the userSearchFilter: uid={0}. This query allows the server to search for a user’s account name by looking for a record with a matching uid attribute. The final mapping step is to identify user record attributes that hold the account name, full user name, and (optionally) the user’s email address. In this example, the account name is uid (identified earlier), the full user name attribute is gecos, and there is no email attribute.

At this point, the server is able to authenticate a user, look up a user by name, and determine the user’s full name. For many installations this is sufficient.

Sample LDAP user record

# build, People, electric-cloud.com
dn: uid=jdoe, ou=People, dc=mycompany,dc=com
loginShell: /bin/bash
uidNumber: 508
gidNumber: 508
objectClass: account
objectClass: posixAccount
objectClass: top
objectClass: shadowAccount
uid: jdoe
gecos: John Doe
cn: John
homeDirectory: /net/filer/homes/build▼

Also, you can configure the server to look for LDAP groups that refer to user accounts. A typical group record is shown below. Like a user account, an LDAP group has a distinguished name with a baseDn, a group base, and a group element. In this case, the base dn is still dc=mycompany,dc=com. The groupBase configuration element is ou=Group, and the group name is cn=build_users.

The server must identify records in the directory that correspond to groups—it does this by applying the groupMemberFilter to the records in the groupBase directory. In this case, group records are members of the posixAccount object class, so the filter can be set to objectClass=posixGroup. To display a group by its name, the server must know which attribute represents the group name. In this case, set the groupNameAttribute to cn.

Finally, the server needs a filter to determine which accounts belong to the group and the attribute name that represents a single group member. Group membership can be identified in one of two ways. Either the members are listed by account name, or by their LDAP distinguished name. In this case, POSIX group membership is determined by account name, so set the groupMemberAttributes property to memberUid, and set the groupMemberFilter to memberUid={1}.

Sample LDAP group record

# build_users, Group, mycompany.com
dn: cn=build_users,ou=Group,dc=mycompany,dc=com
objectClass: posixGroup
objectClass: top
gidNumber: 100
memberUid: jdoe
memberUid: mary
cn: build_users▼

Sample Active Directory configuration

The following XML element defines parameters needed to connect to an Active Directory server and the query to use for looking up user information.

<bean id="adDirectoryProvider"
      class="com.electriccloud.security.ldap.ActiveDirectoryProvider">
     <property name="providerName" value="ActiveDirectory"/>
     <property name="url" value="ldap://server/dc=company,dc=com"/>
     <property name="managerDn" value="cn=myuser,cn=Users,dc=company,dc=com"/>
     <property name="managerPassword" value="mypw"/>
     <property name="userBase" value="cn=Users"/>
     <property name="userSearchFilter" value="(sAMAccountName={0})"/>
     <property name="userSearchSubtree" value="false"/>
     <property name="userNameAttribute" value="sAMAccountName"/>
     <property name="fullUserNameAttribute" value="name"/>
     <property name="emailAttribute" value="userPrincipalName"/><!-- <property name="groupBase" value=""/> --> <!-- <property name="groupMemberFilter" value="member={0}"/> --><!-- <property name="groupMemberAttributes" value="member"/> --> <!-- <property name="groupSearchFilter"value="(objectClass=group)"/> --> <!-- <property name="groupNameAttribute" value="cn"/> -->
     <property name="pageSize" value="500"/>
</bean>▼