Directory providers

CloudBees CD/RO supports Active Directory and LDAP directory providers. This section contains instructions for creating an Active Directory or LDAP directory provider and editing those configurations. Use the following links to go the section you need:

To create a new Active Directory provider

To create a new LDAP directory provider

Examples for directory provider field descriptions

To edit an existing directory provider

Creating a new Active Directory provider

Enter information in the fields as follows to specify your existing Active Directory users and groups to communicate with CloudBees CD/RO. For examples of information you enter in the these fields, see the table after the following description sections.

Field Name Description

General section

Provider Name

This name identifies users and groups that come from this provider.

Description

(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> … </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

For example, the following HTML:

<p>
<span style="font-family: Arial;">
  <i>Note:</i> For more information about the <b>abc</b> object, see
         <a href="https://www.google.com/">https://www.google.com</a>.
</span>
</p>▼

renders as follows:

<i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.▼

URL Discovery

Select the method to retrieve the URL for the Active Directory server. Auto-discovery using DNS automatically discovers Active Directory servers on the given domain. Alternatively, you can specify a custom URL to an Active Directory server.

Domain Name

The domain where Active Directory servers are automatically discovered. For example, example.com

Use SSL

Select this box if you want to use SSL when the CloudBees CD/RO server contacts your Active Directory server.

Transport Layer Security (TLS) has replaced Secure Sockets Layer version 3.0 (SSLv3) on the CloudBees CD/RO web server and the CloudBees CD/RO server.

URL

This is an explicit URL to the Active Directory server. The 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 you can override the port if you cannot use the default location (default is port 389 for ldap or 636 for ldaps). The basedn is the path to the top-level directory that contains users and groups at this site. Typically, this is the domain name where each part is listed with a dc= and separated by commas.

Spaces in the basedn must be URL encoded (use %20 for spaces). If your site uses redundant directory servers for failover, you can enter multiple URLs separated by spaces.

Query User Name

The name of a user who has read-only access to user and group directories in Active Directory. This is the user name to use for fetching user and group information. When you provide a domain name, you can provide the simple name, for example, myuser instead of electric-cloud\myuser. When you provide an explicit URL, you need to provide a distinguished name, for example: ` cn=myuser,ou=Users,dc=electric-cloud,dc=com`.

Query User Password

The password for the query user.

Membership Options section

The membership options control whether the nested group hierarchy in the configured Active Directory server will be used by CloudBees CD/RO. See LDAP Group Hierarchy for details on how the nested group hierarchy in Active Directory is used by CloudBees CD/RO.

Recursively Traverse Group Hierarchy

Select this to enable recursive traversal of the group hierarchy for nested group membership information. If Recursively Traverse Group Hierarchy is selected, select the LDAP_MATCHING_RULE_IN_CHAIN template for both the Membership Filter and Group Member Filter fields in the "Group Options" section to allow Active Directory to return the nested group membership information.

Membership Filter

Active Directory filter to use when searching for groups to which an Active Directory user or group belongs.

Include Nested Group Users in Notifications

Select this to include users in nested Active Directory groups when notifications for a parent Active Directory group are sent and Recursively Traverse Group Hierarchy is selected.

Include Nested Group Users as Approvers

Select this to allow users in nested Active Directory groups to complete or approve a manual task when a parent Active Directory group is assigned as an assignee or an approver for the task and Recursively Traverse Group Hierarchy is selected.

Because users who are authorized to approve the manual task will typically also be notified of the approval request, we recommend that Include Nested Group Users in Notifications be selected (enabled) when Include Nested Group Users as Approvers is selected.

User Options section

When creating an Active Directory provider, the CloudBees CD/RO server automatically sets default values for any options (fields) that are empty. The default values match the most common Active Directory configurations. After the provider is created, you can view and modify defaults by modifying the provider.

User Base

This string is prepended to the `basedn ` to construct the directory DN containing user records.

User Search Filter

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 to the substituted user login ID.

User Name Attribute

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

Full User Name Attribute

(Optional) This is the attribute in a user record that contains the user’s full name (first and last) 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.

User Email Attribute

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

Search User Subtree

Select this check box to search the specified directory by the user base and all directories below. If this check box is not selected, the search is limited to the specified directory only.

Group Options section

If you do not need group information at this time, do not enter information in the Group section, the group test fails without this information, but the test successfully authenticates users if both "user tests" are successful.

When creating an Active Directory provider, the CloudBees CD/RO server automatically sets default values for the options/fields that remain empty. These default values match the most common Active Directory configurations. After the provider is created, you can view and modify the defaults by modifying the provider.

Enable Groups

Select this check box to enable external groups for this directory provider.

Group Base

(Optional) This string is prepended to the `basedn ` to construct the directory DN containing group records.

Group Member Filter

(Optional) This LDAP query is performed in the groups directory context to identify groups that contain a specific user. Two common forms of group records in LDAP directories are: POSIX style groups where members are identified by account name, and groupOfNames or uniqueGroupOfNames records where members are identified by the full user DN. CloudBees CD/RO supports both forms, 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.

Group Member Attributes

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

Group Search Filter

(Optional) This LDAP query is performed in the context of the groups directory to enumerate group records. You can choose from common templates that include either security or distribution groups (or both). These templates are based on the most common Active Directory settings.

Unique Group Name Attribute

(Optional) This is the group record attribute that contains the group name. To prevent group name overlap between multiple directory providers (or within the same provider in a multi-forested Active Directory server), we recommend setting this attribute to the distinguishedName.

Common Group Name Attribute

The Unique Group Name Attribute may not be searchable if using the distinguishedName. In this case, the Common Group Name Attribute can be used to search for groups, depending on the filter used.

After filling in all fields, click the Test button. Three tests validate the information you supplied:

user authentication
user identified in Active Directory
find all groups where the user is a member

If there is a test failure, correct the information you supplied and retest. Click Save after successful test results. New, defined directory providers will appear in the table on the Directory Provider web page.

To create a new LDAP directory provider

Enter information in the fields as follows to specify your existing LDAP users and groups to communicate with CloudBees CD/RO. For examples of information you enter in the these fields, see the table after the following description sections.

Field Name Description

General section

Provider Name

This name identifies users and groups that come from this provider.

Description

For example, the following HTML:

<p>
<span style="font-family: Arial;">
  <i>Note:</i> For more information about the <b>abc</b> object, see
         <a href="https://www.google.com/">https://www.google.com</a>.
</span>
</p>▼

renders as follows:

<i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.▼

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 you can override the port if you cannot use the default (default port is 389 for ldap and 636 for ldaps). The basedn is the path to the top-level directory that contains users and groups at this site. Typically, this is the domain name where each part is listed with a dc= and separated by commas.

Spaces in the basedn must be URL encoded (use %20 for spaces). If your site uses redundant directory servers for failover, you can enter multiple URLs separated by spaces.

Realm

This is the realm of the LDAP directory provider, which is used to create unique user names when you have multiple providers. For example, if the realm is example.com, users are saved as myuser@example.com.

Query User Name

This is the name of a user who has read-only access to the user and group directories in LDAP. This is the user name to use for fetching user and group information. When providing a domain name, you can provide the simple name, for example, myuser. When providing an explicit URL, you need to provide a distinguished name, for example: cn=myuser,ou=Users,dc=electric-cloud,dc=com.

Query User Password

This is the password for the query user.

Membership Options section

The membership options control whether nested group hierarchy in the configured LDAP server will be used by CloudBees CD/RO. See xLDAP Group Hierarchy for details on how the nested group hierarchy in the LDAP server is used by CloudBees CD/RO.

Recursively Traverse Group Hierarchy

Select this to enable recursive traversal of the group hierarchy for nested group membership information.

Membership Attribute

Attribute defined on an LDAP user or group entry that is used by the LDAP provider for specifying the group membership. memberOf is the membership attribute used by most LDAP servers.

Nested Groups Depth Limit

Maximum number of group hierarchy levels that will be traversed for retrieving nested group membership information.

Setting a high value for this option will impact the system performance when traversing the LDAP group hierarchy because a higher group hierarchy depth will result in a proportionally large number of network calls between the CloudBees CD/RO system and the LDAP server. The actual performance will depend on the system configurations of the CloudBees CD/RO servers, the LDAP server, and the network latency.

Include Nested Group Users in Notifications

Select this to include users in nested LDAP groups when notifications for a parent LDAP group are sent and Recursively Traverse Group Hierarchy is selected.

Include Nested Group Users as Approvers

Select this to allow users in nested LDAP groups to complete or approve a manual task when a parent LDAP group is assigned as an assignee or an approver for the task and Recursively Traverse Group Hierarchy is selected.

Because users who are authorized to approve the manual task will typically also be notified of the approval request, we recommended that Include Nested Group Users in Notifications be selected (enabled) when Include Nested Group Users as Approvers is selected.

User Options section

User Base

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

User Search Filter

User Name Attribute

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

Full User Name Attribute

User Email Attribute

(Optional) This is 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.

Search User Subtree

Select this check box to search the specified directory by the user base and all directories below. If this check box is not selected, the search is limited to the specified directory only.

Groups Options section

Note: If you do not need group information at this time, do not enter information in the Group section, the group test fails without this information, but the test successfully authenticates users if both user tests are successful.

Enable Groups

Select this checkbox to enable groups.

Group Base

(Optional) This string is prepended to the `basedn ` to construct the directory DN containing group records.

Group Member Filter

(Optional) This LDAP query is performed in the groups directory context to identify groups containing a specific user. Two common forms of group records in LDAP directories are: POSIX style groups where members are identified by account name, and groupOfNames or uniqueGroupOfNames records where members are identified by the full user DN. CloudBees CD/RO supports both forms, so the query is passed with two parameters: "{0}" is replaced with the full user record DN, and "{1}" is replaced with the user’s account name.

Group Member Attributes

(Optional) This is a comma-separated attribute name list identifying a group member. Most LDAP configurations only specify a single value, but if you have a mixture of POSIX and LDAP style groups in the directory, multiple attributes might be required.

Group Search Filter

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

Unique Group Name Attribute

(Optional) This is the group record attribute containing the group name.

Common Group Name Attribute

The Unique Group Name Attribute may not be searchable if using distinguishedName. In this case, the Common Group Name Attribute is used if searching for groups, depending on the filter.

After fillingin all fields, click the Test button. Three tests validate the information you supplied:

user authentication
user identified in LDAP
find all groups where the user is a member

Examples for directory provider field descriptions

The following table provides examples for filling in the fields described above:

Field Name LDAP example ActiveDirectory example

Field Name	LDAP example	ActiveDirectory example
Provider Type	`LDAP`	`ActiveDirectory `
Domain Name	`N/A`	`example.com`
Realm	`example.com`	`N/A `
URL	`ldap://dir.example.com/dc=company,dc=com `	`ldaps://server/dc=company,dc=com `
Query User Name	`uid=JohnDoe,ou=People,dc=company,dc=com `	`cn=myuser,cn=Users,dc=company,dc=com `
Query User Password	`mypw`	`mypw`
User Base	`ou=People`	`cn=Users`
User Search Filter	`uid={0} `	`(&(\|(userPrincipalName={0})(sAMAccountName={0}))` ` (objectClass=user)) `
User Name Attribute	`uid `	`userPrincipalName`
Full User Name Attribute	`gecos`	`name `
User Email Attribute	`mail`	`mail `
Group Base	`ou=Group`	`cn=Groups`
Group Member Filter	`(\|(member={0})(memberUid={1})) `	`member={0} `
Group Member Attribute	`member,memberUid `	`member `
Group Search Filter	`(\|(objectClass=groupOfNames)` ` (objectClass=posixGroup)) `	`(objectClass=group) `
Unique Group Name Attribute	`distinguishedName`	`distinguishedName `
Common Group Name Attribute	`cn`	`cn`

Provider Type

LDAP

`ActiveDirectory `

Domain Name

N/A

example.com

Realm

example.com

`N/A `

URL

`ldap://dir.example.com/dc=company,dc=com `

`ldaps://server/dc=company,dc=com `

Query User Name

`uid=JohnDoe,ou=People,dc=company,dc=com `

`cn=myuser,cn=Users,dc=company,dc=com `

Query User Password

mypw

User Base

ou=People

cn=Users

User Search Filter

`uid={0} `

(&(|(userPrincipalName={0})(sAMAccountName={0})) ` (objectClass=user)) `

User Name Attribute

`uid `

userPrincipalName

Full User Name Attribute

gecos

`name `

User Email Attribute

mail

`mail `

Group Base

ou=Group

cn=Groups

Group Member Filter

`(|(member={0})(memberUid={1})) `

`member={0} `

Group Member Attribute

`member,memberUid `

`member `

Group Search Filter

(|(objectClass=groupOfNames) ` (objectClass=posixGroup)) `

`(objectClass=group) `

Unique Group Name Attribute

distinguishedName

`distinguishedName `

Common Group Name Attribute

cn

To edit an existing directory provider

You may change any previously supplied information in the fields. After editing any fields, click the Test button. The same three tests validate the information you supplied:

user authentication
user identified in the directory provider
find all groups where the user is a member

If there is a test failure, correct the information you supplied and retest. Click Save after successful test results. Edited, redefined directory providers will appear in the table on the Directory Provider web page.