Directory Provider Management

createDirectoryProvider

Creates a new Active Directory or LDAP directory provider.

You must specify a providerName.

Arguments Descriptions

providerName

Name for a LDAP directory provider that must be unique.

This human-readable name appears in the user interface to identify users and groups from this provider.

Argument type: String

allowNestedGroupsApprovers

(Optional) <Boolean flag - 0|1|true|false >

Determines whether users in nested LDAP groups should be allowed to approve a manual task when a parent LDAP group is assigned as an approver for the task and recursive traversal of group hierarchy is enabled for the directory provider.

Argument type: Boolean

commonGroupNameAttribute

(Optional) The attribute in a group record that contains the common group name. If specified, this name is used only when searching for groups from an external provider. Use this argument if the groupNameAttribute or the uniqueGroupNameAttribute is set to distinguishedName, which is not searchable.

Argument type: String

description

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

Argument type: String

domainName

(Optional) The domain name from which Active Directory servers are automatically discovered.

Argument type: String

emailAttribute

(Optional) The attribute in an LDAP 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.

Argument type: String

enableGroups

(Optional) <Boolean flag - 0|1|true|false > Determines whether or not to enable external groups for the directory provider. This argument defaults to "true".

Argument type: Boolean

fullUserNameAttribute

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

Argument type: String

groupBase

(Optional) The string is prepended to the basedn to construct the directory domain name (DN) that contains group records.

Argument type: String

groupMemberAttributes

(Optional) A comma-separated attribute name 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 may be required.

Argument type: String

groupMemberFilter

(Optional) This LDAP query is performed in the groups directory context to identify groups containing a specific user as a member. 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 to parameters: "{0}" is replaced with the full user record DN, and "{1}" is replaced with the user’s account name.

Argument type: String

groupNameAttribute

(Optional) The attribute in a group record that contains the name of the group.

Argument type: String

groupSearchFilter

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

Argument type: String

managerDn

(Optional) The domain name (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.

Argument type: String

managerPassword

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

Argument type: String

membershipAttribute

(Optional) Attribute defined on an LDAP user or group entry used by the LDAP provider to specify the group membership.

Argument type: String

membershipFilter

(Optional) LDAP filter to search for groups to which an LDAP user or group belongs.

Argument type: String

nestedGroupDepthLimit

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

Argument type: Integer

notifyUsersInNestedGroups

(Optional) <Boolean flag - 0|1|true|false >

Determines whether users in nested LDAP groups should be included when notifications for a parent LDAP group are sent and recursive traversal of group hierarchy is enabled for the directory provider.

Argument type: Boolean

providerType

(Optional) Type string for a directory provider: <ldap|activedirectory>

Argument type: ProviderType

realm

(Optional) This is an identifier (string) used for LDAP directory providers so users and groups (within LDAP) can be uniquely identified in "same name" collisions across multiple directory providers. The realm is appended to the user or group name when stored in the CloudBees CD/RO server. For example, < user >@dir (where the realm is set to "dir").

Argument type: String

traverseHierarchy

(Optional) <Boolean flag - 0|1|true|false > Determines whether or not to enable recursive traversal of group hierarchy for nested group membership information. This argument defaults to "true".

Argument type: Boolean

url

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

Argument type: String

useSSL

(Optional) <Boolean flag - 0|1|true|false > Use this flag to define whether or not SSL is used for server-agent communication, or if you need to use SSL to communicate with your Active Directory servers. The default is "true".

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.

Argument type: Boolean

userBase

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

Argument type: String

userNameAttribute

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

Argument type: String

userSearchFilter

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

Argument type: String

userSearchSubtree

(Optional) < Boolean flag — 0|1|true|false >

If 1 or true, CloudBees CD/RO recursively searches the subtree below the user base.

Argument type: Boolean

Positional arguments

providerName

Response

None or a status OK message.

ec-perl

syntax: $<object>->createDirectoryProvider(<providerName>, {<optionals>});

Example

$ec->createDirectoryProvider("AD3", {url => "ldaps://pdc/dc=coname3.dc=com", providerType => "activedirectory"});▼

ectool

syntax: ectool createDirectoryProvider <providerName> {optionals]

Example

ectool createDirectoryProvider AD3 --url "ldaps://pdc/dc=coname3.dc=com" --providerType activedirectory▼

deleteDirectoryProvider

Deletes an Active Directory or LDAP directory provider.

You must specify a providerName.

Arguments	Descriptions
providerName	The name of the directory provider that you want to delete. Argument Type: String

Arguments

Descriptions

providerName

The name of the directory provider that you want to delete.

Argument Type: String

Positional arguments

providerName

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteDirectoryProvider(<providerName>);

Example

$ec->deleteDirectoryProvider('AD3');▼

ectool

syntax: ectool deleteDirectoryProvider <providerName>

Example

ectool deleteDirectoryProvider 'AD3'▼

getDirectoryProvider

Retrieves a directory provider by name.

You must specify a providerName.

Arguments	Descriptions
providerName	The name of the directory provider that must be unique. Argument Type: String

Arguments

Descriptions

providerName

The name of the directory provider that must be unique.

Argument Type: String

Positional arguments

providerName

Response

One directoryProvider element.

Note: For security reasons, the managerPassword field is never returned.

ec-perl

syntax: $<object>->getDirectoryProvider(<providerName>);

Example

$ec>getDirectoryProvider("AD3");▼

ectool

syntax: ectool getDirectoryProvider <providerName>

Example

ectool getDirectoryProvider "AD3"▼

getDirectoryProviders

Retrieves all directory providers.

Arguments	Descriptions
None	–

Arguments

Descriptions

None

–

Positional arguments

None

Response

Zero or more directoryProvider elements.

ec-perl

syntax: $<object>->getDirectoryProviders();

Example

$ec->getDirectoryProviders();▼

ectool

syntax: ectool getDirectoryProviders

Example

ectool getDirectoryProviders▼

modifyDirectoryProvider

Modifies an existing LDAP directory provider.

You must specify the providerName.

Arguments Descriptions

providerName

The name of the directory provider that must be unique.

Argument Type: String

allowNestedGroupsApprovers

(Optional) <Boolean flag - 0|1|true|false >

Determines whether users in nested LDAP groups should be allowed to approve a manual task when a parent LDAP group is assigned as an approver for the task and recursive traversal of group hierarchy is enabled for the directory provider.

Argument type: Boolean

commonGroupNameAttribute

(Optional) The attribute in a group record that contains the common group name. If specified, this name is used only when searching for groups from an external provider. Use this argument if the groupNameAttribute or the uniqueGroupNameAttribute is set to distinguishedName, which is not searchable.

Argument Type: String

description

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

Argument Type: String

domainName

(Optional) The domain from which Active Directory servers are automatically discovered.

Argument Type: String

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.

Argument Type: String

enableGroups

(Optional) < Boolean flag— 0|1|true|false >

This determines whether or not to enable external groups for the directory provider. Defaults to true.

Argument Type: Boolean

fullUserNameAttribute

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

Argument Type: String

groupBase

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

Argument Type: String

groupMemberAttributes

(Optional) A comma-separated attribute name 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.

Argument Type: String

groupMemberFilter

(Optional) This LDAP query is performed in the group directory context to identify groups containing a specific user as a member. 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.

Argument Type: String

groupNameAttribute

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

Argument Type: String

groupSearchFilter

(Optional) A filter name: this LDAP query is performed in the context of the groups directory to enumerate group records.

Argument Type: String

managerDn

(Optional) The DN of a user who has read 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.

Argument Type: String

managerPassword

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

Argument Type: String

membershipAttribute

(Optional) Attribute defined on an LDAP user or group entry used by the LDAP provider to specify the group membership.

Argument type: String

membershipFilter

(Optional) LDAP filter to search for groups to which an LDAP user or group belongs.

Argument type: String

nestedGroupDepthLimit

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

Argument type: Integer

newName

(Optional) New name of the directory provider.

Argument Type: String

notifyUsersInNestedGroups

(Optional) <Boolean flag - 0|1|true|false >

Determines whether users in nested LDAP groups should be included when notifications for a parent LDAP group are sent and recursive traversal of group hierarchy is enabled for the directory provider.

Argument type: Boolean

providerType

(Optional) Type string for a directory provider: < ldap|activedirectory > .

Argument Type: DirectoryType

realm

(Optional) This is an identifier (string) used for LDAP directory providers so users and groups (within LDAP) can be uniquely identified in "same name" collisions across multiple directory providers. The realm is appended to the user or group name when stored in the CloudBees CD/RO server. For example, < user >@dir (where the realm is set to "dir").

Argument Type: String

traverseHierarchy

(Optional) <Boolean flag - 0|1|true|false > Determines whether or not to enable recursive traversal of group hierarchy for nested group membership information. This argument defaults to "true".

Argument type: Boolean

url

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

Argument Type: String

useSSL

(Optional) < Boolean flag— 0|1|true|false >

If this is set to 1 or true, SSL is used for communication. The default is 1 or true.

Argument Type: Boolean

userBase

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

Argument Type: String

userNameAttribute

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

Argument Type: String

userSearchFilter

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

Argument Type: String

userSearchSubtree

(Optional) < Boolean flag— 0|1|true|false >

If this is set to 1 or true, CloudBees CD/RO recursively searches the subtree below the user base.

Argument Type: Boolean

useSSL

< Boolean flag— 0|1|true|false > Use this flag to define whether or not SSL is used for server-agent communication, or if you need to use SSL to communicate with your Active Directory servers. Default is "true".

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.

Argument Type: Boolean

Positional arguments

providerName

Response

Returns a modified LDAP directory provider element.

ec-perl

syntax: $<object>->modifyDirectoryProvider(<providerName>, {<optionals>});

Example

$ec->modifyDirectoryProvider("AD3", {emailAttribute => "email"});▼

ectool

syntax: ectool modifyDirectoryProvider <providerName> [optionals]

Example

ectool modifyDirectoryProvider "AD3" --emailAttribute "email"▼

moveDirectoryProvider

Moves an Active Directory or LDAP directory provider in front of another specified provider or to the end of the list.

You must specify a providerName.

Arguments Descriptions

Arguments	Descriptions
providerName	The name of the directory provider that must be unique. Argument Type: String
beforeProviderName	Moves this directory provider ( `providerName` ) to a place before the name specified by this option. If omitted, `providerName` is moved to the end. Argument Type: String

providerName

The name of the directory provider that must be unique.

Argument Type: String

beforeProviderName

Moves this directory provider ( providerName ) to a place before the name specified by this option. If omitted, providerName is moved to the end.

Argument Type: String

Positional arguments

providerName

Response

None or a status OK message.

ec-perl

syntax: $<object>->moveDirectoryProvider(<providerName>, {<optionals>});

Example

$ec->moveDirectoryProvider("AD3", {beforeProviderName => "AD2"});▼

ectool

syntax: ectool moveDirectoryProvider <providerName> [optionals]

Example

ectool moveDirectoryProvider "AD3" --beforeProviderName "AD2"▼

testDirectoryProvider

Tests that a specific user name and password combination work with the specified directory provider settings.

You must specify userName and password (the command will prompt for the password if it is omitted).

Arguments Descriptions

userName

The name of the user you are testing for this provider.

Argument Type: String

password

The password for the user that you are testing for this provider. The command will prompt for the password if it is omitted.

Argument Type: String

allowNestedGroupsApprovers

(Optional) <Boolean flag - 0|1|true|false >

Determines whether users in nested LDAP groups should be allowed to approve a manual task when a parent LDAP group is assigned as an approver for the task and recursive traversal of group hierarchy is enabled for the directory provider.

Argument type: Boolean

commonGroupNameAttribute

(Optional) The attribute in a group record that contains the common group name. If specified, this name is used only when searching for groups from an external provider. Use this argument if the groupNameAttribute or the uniqueGroupNameAttribute is set to distinguishedName, which is not searchable.

Argument Type: String

description

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

Argument Type: String

domainName

(Optional) The domain from which Active Directory servers are automatically discovered.

Argument Type: String

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.

Argument Type: String

enableGroups

(Optional) < Boolean flag— 0|1|true|false > Determines whether or not to enable external groups for the directory provider. Defaults to "true".

Argument Type: Boolean

fullUserNameAttribute

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

Argument Type: String

groupBase

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

Argument Type: String

groupMemberAttributes

(Optional) A comma separated attribute name 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.

Argument Type: String

groupMemberFilter

(Optional) This LDAP query is performed in the groups directory context to identify groups containing a specific user as a member. 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.

Argument Type: String

groupNameAttribute

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

Argument Type: String

groupSearchFilter

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

Argument Type: String

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.

Argument Type: String

managerPassword

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

Argument Type: String

membershipAttribute

(Optional) Attribute defined on an LDAP user or group entry used by the LDAP provider to specify the group membership.

Argument type: String

membershipFilter

(Optional) LDAP filter to search for groups to which an LDAP user or group belongs.

Argument type: String

nestedGroupDepthLimit

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

Argument type: Integer

notifyUsersInNestedGroups

(Optional) <Boolean flag - 0|1|true|false >

Determines whether users in nested LDAP groups should be included when notifications for a parent LDAP group are sent and recursive traversal of group hierarchy is enabled for the directory provider.

Argument type: Boolean

providerType

(Optional) Type string for a directory provider: <ldap|activedirectory>.

Argument Type: DirectoryType

realm

(Optional) This is an identifier (string) used for LDAP directory providers so users and groups (within LDAP) can be uniquely identified in "same name" collisions across multiple directory providers. The realm is appended to the user or group name when stored in the CloudBees CD/RO server. For example, < user >@dir (where the realm is set to "dir").

Argument Type: String

traverseHierarchy

(Optional) <Boolean flag - 0|1|true|false > Determines whether or not to enable recursive traversal of group hierarchy for nested group membership information. This argument defaults to "true".

Argument type: Boolean

url

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

Argument Type: String

useDefaults

(Optional) < Boolean flag - ` 0|1|true|false` >

If this argument is set to 1 or true, the default values will be used for all fields that are not specified.

Argument Type: Boolean

useSSL

(Optional) < Boolean flag - ` 0|1|true|false` >

If this argument is set to 1 or true, SSL is used for communication.

Argument Type: Boolean

userBase

(Optional) This string is prepended to the base DN to construct the directory DN that contains user records.

Argument Type: String

userNameAttribute

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

Argument Type: String

userSearchFilter

(Optional) A filter name. 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.

Argument Type: String

userSearchSubtree

(Optional) < Boolean flag - ` 0|1|true|false` > If "true", recursively search the subtree below the user base.

Argument Type: Boolean

useSSL

(Optional) < Boolean flag - ` 0|1|true|false` > Use this flag to define whether or not SSL is used for server-agent communication, or if you need to use SSL to communicate with your Active Directory servers. Default is "true".

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.

Argument Type: Boolean

Positional arguments

userName, password

Response

Three queries are returned: One query authenticates the user userAuthenticationTest, one query retrieves information about the user findUserTest, and one shows the results of finding groups where the user is a member findGroupsTest.

ec-perl

syntax: $<object>->testDirectoryProvider(<userName>, <password>, {<optionals>});

Example

$ec->testDirectoryProvider("testUser", "testUserPassword",
            {providerType => "activedirectory",
               domainName => "example.com",
              useDefaults => 1,
                managerDn => "testManager",
          managerPassword => "testManagerPassword"});▼

ectool

syntax: ectool testDirectoryProvider <userName> <password> …

Example

ectool testDirectoryProvider testUser testUserPassword --providerType activeDirectory
   --domainName example.com
   --useDefaults 1
   --managerDn testManager
   --managerPassword testManagerPassword▼