Configuration Parameters

Active - True for the active profile, false otherwise. This value is controlled for you by the scheduler admin server
Administrators - The name of the role to map to the core scheduler-administrator role. We recommend you set this to scheduler-administrator.
Password - The password to use when performing searches.
URL - The URL of the LDAP server; you can specify a space-separated list of LDAP servers.
Username - The username to use when performing searches.
GroupMemberField - The name of the attribute that contains the distinguished names of users that are a member of this group. Generally member
GroupNameField - The name of the attribute that contains the group name. Generally cn (short for Common Name).
Group Base DN - The point in the tree from which to start group searches.
GroupSearchExpression - The LDAP search expression to use for group searches. It accepts the following variables: ${userName}, and ${distinguishedName}.
IsolationAdminRole - The name of the role to map to the core scheduler-isolation-administrator role. We recommend you set this to scheduler-administrator.
ScreenReaderRole - The name of the role to map to the core scheduler-screen-reader role. We recommend you set this to scheduler-screen-reader.
SearchScope - How to perform searches. Possible values are: OBJECT, ONELEVEL, SUBTREE. The searches start at User Base DN for users and GroupSearchBase for groups/roles.
UserDNExpression - The expression to use to convert the username entered by the user in the login dialog into an LDAP distinguished name.
UserExactSearchExpression - The LDAP search expression to use when searching for a user. This must return exactly one result when executed for a given username or distinguished name. It accepts the ${userName} variable.
UserMailField - The name of the attribute that contains the user's email address. Generally mail.
UserNameField - The name of the attribute that contains the user name. Generally cn (short for Common Name).
Users - The name of the role to map to the core scheduler-user or redwood-login role. We recommend you set this to scheduler-user.
User Base DN - The point in the tree from which to start group searches.

Username and Password

Any user that can read all properties of all users that are to access Redwood Server can be used. The user must also be able to read all properties of all groups the users use as well as see each container object in the DN of all users and groups to be used. Usually any LDAP user should suffice, unless your LDAP implementation varies from the default. Please ask your LDAP Administrator for advice; if you are the LDAP Administrator, see the documentation of your LDAP software.

Finding Users and Groups in LDAP

Redwood Server uses the username specified in the login dialog to lookup the DN for the user and uses that to lookup the groups the user belongs to. The LDAP groups are mapped to Redwood Server roles; these are granted to the user.

The searches are performed with a Search Scope. If all your Redwood Server users and groups are in a single user-specific or group-specific OU, respectively, you use the Search Scope ONELEVEL.

The Search Scope accepts the following values:

Value	Meaning
OBJECT	Search for the exact object. Not recommended.
ONELEVEL	Search one level of the tree.
SUBTREE	Search any number of levels of the tree.

Redwood recommends you set this to SUBTREE.

The searches start at User Base DN for users and Group Search Base for groups/roles.

The LDAP search expression to use for user searches accepts the ${userName} variable; it contains the username specified in the login dialog.

The LDAP search expression to use for role/group searches accepts the following variables: ${distinguishedName}. You use (member=${distinguishedName}) for group search expressions.

These variables have the same meaning wherever they are used. The variable names are case-insensitive:

Variable	Meaning
${userName}	The username entered by the user in the login dialog.
${distinguishedName}	The distinguished name as created by UserDNExpression (if this is a search, then it is the exact value returned by the LDAP server).

The last two variables are used when the LDAP server returns distinguished name results that contain \, (the correct way to escape a comma ( ``, ) in a name), but does not accept them. Some versions of Active Directory have this problem.

For a user Roosevelt, Franklin D. in the Users container at example.com, the values of these three variables would be:

${distinguishedName} - CN=Roosevelt\, Franklin D.,CN=Users,DC=example,DC=com

User DN Expression and User Exact Search Expression

The expressions used to convert the username entered by the user in the login dialog into an LDAP distinguished name ( DN ).

You usually configure Redwood Server to perform an LDAP search to retrieve the distinguished name by setting the User DN Expression to SEARCH.

If the username is a part of the DN, you can use an expression such as CN=${username},OU=Users,DC=example,DC=com in the User DN Expression field, however, this is not recommended practice.

The User DN Expression takes the following values:

Value	Meaning
SEARCH	Run a search using UserExactSearchExpression. If this returns exactly one result, then the distinguished name of the user is the value of the distinguishedName attribute.
SEARCH:attribute	Run a search using UserExactSearchExpression. If this returns exactly one result, then the distinguished name of the user is the value of the attribute attribute.
Any other value	Create the distinguished name by string substitution. The ${userName} variable is required (not recommended).

Common values for this parameter are:

For Active Directory: SEARCH
For systems that have the username as a part of the DN: CN=${username},OU=Users,DC=example,DC=com (not recommended)

Group Search Expression

The expression used to find the groups the user is a member of.

In most situations only a subset of the groups that exist in LDAP are relevant to Redwood Server. In these cases it is desirable to restrict which roles/groups are transferred from LDAP into Redwood Server.

There are two ways to configure this:

Use the LDAP tree structure
Use a naming convention

To use the tree approach: Put the Redwood Server roles under their own node in the tree (Active Directory calls this a Directory) and set the Group Base DN to that part of the tree. That way our search will only find the roles specific to Redwood Server.

For example, put all the scheduler specific roles under "CN=Scheduler,CN=Groups,DC=example,DC=com", and set Group Base DN to "CN=Scheduler,CN=Groups,DC=example,DC=com" and Groups Search Expression to (member=${distinguishedName}) (this means LDAP groups have a member property containing the DN of member users).

To use the naming convention approach: Set the GroupSearchExpression so that it will only find roles that start with certain prefix. For example to only find groups that have names starting with automation:

(&(member=${distinguishedName})(cn=automation*))

note

The expression you specify in the Groups Search Expression field is evaluated and all groups that the expression returns are assigned to the user. Setting this to (cn=automation*), without specifying any value for group member for example, will grant all users all roles.

Nested groups are common in ActiveDirectory environments; Microsoft has provided a matching rule for all groups, recursively, that a user is a member of. The OID of the matching rule is 1.2.840.113556.1.4.1941.

To return all groups a user is a member of, you use the (&(objectCategory=Group)(member:1.2.840.113556.1.4.1941:=${distinguishedName)) syntax.

Note that this matching rule is available as of Windows Server 2008 ActiveDirectory.

Nested and dynamic groups are common on Tivoli Directory Server; IBM has provided system class attributes ibm-allMembers and ibm-allGroups:

ibm-allMembers - returns all users that are members of the search base group or any of its member groups.
ibm-allGroups - returns all nested and dynamic groups the base user is a member of.

Note that the Tivoli Directory Server search strategy differs from OpenLDAP and ActiveDirectory; you specify the target user or group as the search base and retrieve the special system class attribute. You only use the search string to filter out any unwanted results.

Example

Your users are in the following OU's:

OU=IT,OU=Example,OU=Europe,OU=France,OU=Paris,OU=8,OU=Finance
OU=IT,OU=Example,OU=Europe,OU=France,OU=Paris,OU=5,OU=Finance
OU=IT,OU=Example,OU=Europe,OU=France,OU=Marseille,OU=2,OU=Finance
OU=IT,OU=Example,OU=Europe,OU=France,OU=Lyon,OU=4,OU=Finance
OU=IT,OU=Example,OU=Europe,OU=Germany,OU=Berlin,OU=Pankow,OU=Finance
OU=IT,OU=Example,OU=Americas,OU=Chicago,OU=Avalon Park,OU=Finance
...

If only users in OU=IT,OU=Example,OU=Europe,OU=France,OU=Paris,OU=8,OU=Finance are going to use Redwood Server, you can set Search to ONELEVEL and User Search Base to DC=example,DC=com,OU=IT,OU=Example,OU=Europe,OU=France,OU=Paris,OU=8,OU=Finance. Note that you could set Search to SUBTREE, which means that users in OU's below OU=IT,OU=Example,OU=Europe,OU=France,OU=Paris,OU=8,OU=Finance for example OU=IT,OU=Example,OU=Europe,OU=France,OU=Paris,OU=8,OU=Finance,OU=Controllers will be able to access Redwood Server as well.

If only users from Paris, France, are going to use Redwood Server, you must set Search to SUBTREE and User Search Base to DC=example,DC=com,OU=IT,OU=Example,OU=Europe,OU=France,OU=Paris.

If only users from Europe (includes France and Germany) are going to use Redwood Server, you must set Search to SUBTREE and User Search Base to DC=example,DC=com,OU=IT,OU=Example,OU=Europe.

If users from more than one continent are going to use Redwood Server, you must set Search to SUBTREE and User Search Base to DC=example,DC=com,OU=IT,OU=Example.

warning

The performance decreases drastically when searching multiple layers of OU's due to the amount of objects in the various OU's that are searched - keep the number of OU's to be searched as small as possible! Always use the last common OU; avoid setting a User Search Base to DC=example,DC=com if all users that are going to use Redwood Server are in sub-OU's of OU=IT,OU=Example,DC=example,DC=com, for example.

Setting Search to OBJECT will only ever work if the User Search Base points to a user; this user will be the only valid user to be allowed to use Redwood Server, which is not really handy. The OBJECT is there for consistency only with other LDAP tools.

Role mapping

By default the LDAP role names and the core, predefined, and access roles are the same, as shown below:

LDAP Role Name	Core Role Name
scheduler-user	scheduler-user
scheduler-administrator	scheduler-administrator
scheduler-isolation-administrator	scheduler-isolation-administrator
scheduler-screen-reader	scheduler-screen-reader
scheduler-it-user	scheduler-it-user
scheduler-business-user	scheduler-business-user

So to grant a user access to the scheduler, you grant them the LDAP role scheduler-user or scheduler-administrator.

You can change how the mapping works by changing the LDAP profile using the scheduler administration tool.

Securing the LDAP Connection

To enable encrypted communications between Redwood Server and an LDAP server, you have to ensure that the Java Cryptography Extension (JCE) is installed and that the underlying JVM in which Redwood Server runs trusts the certificate of your LDAP server. Redwood Server supports LDAPS not, however, LDAP with StartTLS.

To enable secure communication, you simply specify ldaps: instead of ldap: in the URL, such as ldaps://<server>:<port>. Note that the certificate used by your LDAP server must be trusted the JVM. If it is self-signed, you can import it into a keystore and specify the keystore in your JVM parameters:

Retrieving the CA Root Certificate From Microsoft Certification Authority

Open Certification Authority on your CA Windows Server.
Select Properties from the context-menu of your CA (Usually named <nt_domain>-<hostname>-CA).
On the General tab, select the appropriate certificate and choose View Certificate.
Choose Copy to File on the Details tab.
In the wizard, choose DER (first option), choose Next.
Enter a file path for the certificate and give it a name.
This certificate can be imported as such with keytool.

Using powershell

PS C:\Windows\system32> set-location cert:\localmachine\My
PS Cert:\localmachine\My> Get-ChildItem | Format-Table Subject, FriendlyName, Thumbprint -AutoSize

Subject                                 FriendlyName Thumbprint
-------                                 ------------ ----------
CN=EXAMPLE-DC1-CA, DC=EXAMPLE, DC=com                B0167046CAC26E7011E7E23BB7FA2FB6B8A07445
CN=DC1.EXAMPLE.com                                   8DC674FFBE2DF2CB6B6286819891486640437414
CN=dc1.example.com                                   39DD411BD25066954039F9EC37227509AAF44092

PS Cert:\localmachine\My> Export-Certificate -Cert 39DD411BD25066954039F9EC37227509AAF44092 -File c:\Users\Administrator\cert.crt -Type cert

Examples Installing the Certificate

Redwood recommends you import the root certificate used to sign certificate requests in your organization when you use self-signed certificates. If you use one of many certificate providers, these should, in theory, already be trusted by Java and Redwood Server.

You install the CA root certificate using keytool as follows:

keytool -importcert -file <certificate_file> -keystore <keystore> -alias <alias>

<certificate_file> - the root certificate to import
<keystore> - the keystore for the JVM to use. By default, the keystore is either <java_home>/lib/security/jssecacerts of <java_home>/lib/security/cacerts; the default password is changeit. You can also use a specific keystore for Redwood Server
alias - a name for the certificate

PS c:\example>c:\jdk\bin\keytool -importcert -file cert.cer -keystore c:\jdk\lib\security\cacerts -alias LDAPS
[...]
Trust this certificate? [no]:  yes
Certificate was added to keystore

In cases where you do not have access to the root certificate, you use openssl to retrieve the actual certificate and trust that. In the below examples awk/powershell is used to filter out all lines between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- (inclusive).

In the second command, keytool is used to import the certificate.

Note that these steps will have to be repeated when the certificate is updated.

The following example should work on Unix:

$ openssl s_client -connect pr2.example.com:636 </dev/null 2>/dev/null | awk '/BEGIN CERTI/,/END CERTI/' > cert.pem
$ ${JAVA_HOME}/bin/keytool -importcert -file cert.pem -keystore ${JAVA_HOME}/lib/security/cacerts -alias LDAPS

Enter keystore password:
[...]
Trust this certificate? [no]:  yes
Certificate was added to keystore

The following example should work on Windows in powershell.exe:

Note that you must type Q and then <Enter> multiple times with openssl on Windows for it to exit once it has finished and is waiting for commands.

PS C:\example>openssl s_client -connect pr2.example.com:636 > cert.pem.tmp
[...]
PS C:\example>
PS c:\example> [regex]$regex =
>> @'
>> (?ms)-----BEGIN CERTIFICATE-*
>> (.+?)
>> -----END CERTIFICATE-*
>> '@
PS c:\example> $regex.Matches("$(get-content cert.pem.tmp -Raw)").Value > cert.pem
PS c:\example>c:\jdk\bin\keytool -importcert -file cert.pem -keystore c:\jdk\lib\security\cacerts -alias LDAPS
[...]
Trust this certificate? [no]:  yes
Certificate was added to keystore

You use -Djavax.net.debug=all as a JVM parameter to troubleshoot network connections.

The following JVM parameters can be used to specify a different keystore:

-Djavax.net.ssl.trustStore="C:/redwood/example.ks"
-Djavax.net.ssl.trustStorePassword="sillyPassword"

Example LDAP Setups

Sample Configuration - Active Directory

The following excerpts are used to determine the values of the fields to use. In this example, John Smith is financial controller of Example Inc. and member of the Backoffice Users group.

John Smith

cn: John Smith
codePage: 0
co: UK
company: Example Software
countryCode: 250
department: Finance
description: Financial Controller
displayName: John Smith
distinguishedName: CN=John Smith,OU=Users,OU=London,DC=example,DC=com
dn: CN=John Smith, OU=Users, OU=London, DC=example,DC=com
employeeID: JSMITH
givenName: John
instanceType: 4
l: London
mail: John.Smith@example.com
mailNickname: jsmith
manager: CN=John Doe,OU=Users,OU=London,DC=example,DC=com
memberOf: CN=Backoffice Users,OU=Security Groups,OU=Hamburg,DC=example,DC=com
memberOf: CN=Finance EMEA,OU=Special Accounts,DC=example,DC=com
memberOf: CN=Finance,OU=Mailinglists,OU=London,DC=example,DC=com
memberOf: CN=IM_London,OU=Special Accounts,DC=example,DC=com
memberOf: CN=Processing Users,OU=Security Groups,OU=Hamburg,DC=example,DC=com
name: John Smith
objectCategory: CN=Person,CN=Schema,CN=Configuration,DC=example,DC=com
objectClass: organizationalPerson
objectClass: person
objectClass: top
objectClass: user
physicalDeliveryOfficeName: London
postalCode: 21720
primaryGroupID: 513
proxyAddresses: smtp:jsmith@example.com
proxyAddresses: SMTP:John.Smith@example.com
sAMAccountName: jsmith
showInAddressBook: CN=All Users,CN=All Address Lists,CN=Address Lists Container,CN=Example,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=example,DC=com
showInAddressBook: CN=Default Global Address List,CN=All Global Address Lists,CN=Address Lists Container,CN=Example,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=example,DC=com
sn: Smith
telephone: +44 (0) 163 234 5678
title: Financial Controller
userAccountControl: 512
userPrincipalName: jsmith@example.com
wWWHomePage: www.example.com

Backoffice Users

dn: CN=Backoffice Users, OU=Special Accounts, DC=example,DC=com
name: Backoffice Users
instanceType: 4
groupType: 8
member: CN=John Smith,OU=Users,OU=London,DC=example,DC=com
member: CN=Erika Mustermann,OU=Users,OU=Hamburg,DC=example,DC=com
member: CN=Corinne Berthier,OU=Users,OU=Paris,DC=example,DC=com
member: CN=Example Support,OU=Users,OU=London,DC=example,DC=com
member: CN=Tolvan Tolvansson,OU=Users,OU=London,DC=example,DC=com
member: CN=John Doe,OU=Users,OU=Hamburg,DC=example,DC=com
member: CN=System Administration,OU=Users,OU=London,DC=example,DC=com
objectClass: top
objectClass: group
distinguishedName: CN=Backoffice Users,OU=Special Accounts,DC=example,DC=com
objectCategory: CN=Group,CN=Schema,CN=Configuration,DC=example,DC=com
sAMAccountName: BackofficeUsers
cn: Backoffice Users

Based on the above LDIF information, the following settings can be determined:

Users reside in different OU's, in this case country-specific OU's, so the user base must be DC=example,DC=com as that is the deepest common property.
Groups reside in OU=Special Accounts, OU=example,DC=com as well as OU=Security Groups,OU=<city>,DC=example,DC=com, however, Redwood Server specific groups are all in the same OU, so the group base is OU=Security Groups,OU=Hamburg,DC=example,DC=com.
At Example, you want to log in with the Widows (ActiveDirectory) username, which is sAMAccountName, so UserNameField is set to sAMAccountName.
From John's LDIF excerpt, you see that the attribute containing the email address is mail, so the UserMailField is set to mail.
When you look at John's LDIF again, you see that the attribute that stores groups is named memberOf, so GroupMemberField must be set to memberOf.
When you look at the Backoffice Users LDIF excerpt, you see the group name is stored in the CN property, so the GroupNameField can be set to CN - note that it could also be set to NAME.
From the Backoffice Users LDIF, we also see that users do not reside in the same OU, so the SearchScope must be set to SUBTREE.
Since the attribute used for authentication (sAMAccountName)) is not part of the DN, we set UserDNExpression to SEARCH.
Since we want the user to specify the sAMAccountName, we need to use this to search for users; so UserExactSearchExpression must be set to (sAMAccountName=${userName}).
When we look at the Backoffice Users LDIF excerpt, we see that group members are listed in the member attribute; so we set GroupSearchExpression to (member=${distinguishedName}).
The only fields left now are group fields; from the excerpts Example uses at least these two groups: CN=Processing Users,OU=Security Groups,OU=Hamburg,DC=example,DC=com and CN=Backoffice Users,OU=Security Groups,OU=Hamburg,DC=example,DC=com, the System Administrator at Example was happy to provide the missing group names.

The table below shows the configuration parameters and suggested values for an Active Directory setup for 'example.com', with the username being the Windows user name (otherwise known as the SAM Account Name):

Parameter	Value
URL	ldap://ldap1.example.com:389 ldap://ldap2.example.com:389
Username	cn=Bind User,OU=Users,OU=Hamburg,DC=example,DC=com
Password	changeme
Retype	changeme
GroupBaseDN	OU=Security Groups,OU=Hamburg,DC=example,DC=com
UserBaseDN	DC=example,DC=com
UserNameField	sAMAccountName
UserMailField	mail
GroupMemberField	memberOf
GroupNameField	cn
SearchScope	SUBTREE
UserDNExpression	SEARCH
UserExactSearchExpression	(sAMAccountName=${userName})
GroupSearchExpression	(member:1.2.840.113556.1.4.1941:=${distinguishedName})
AdminRole	Processing Administrators
IsolationAdminRole	Processing Isolation Administrators
UserRole	Processing Users
ScreenReaderRole	Blind Users
ITUserRole	IT Users
BusinessUserRole	Backoffice Users

Sample Configuration - OpenLDAP

	Field	Value
	Name	Example
Connection Details	URL	ldaps://ldap.example.com:636
Connection Details	Username	jdoe
Connection Details	Password	***********
Connection Details	Retype	***********
Search Roots	Group Base DN	OU=Group,DC=example,DC=com
Search Roots	User Base DN	OU=People,DC=example,DC=com
User/Group Attribute Fields	User Name Field	uid
User/Group Attribute Fields	User Mail Field	mail
User/Group Attribute Fields	Group Member Field	memberOf
User/Group Attribute Fields	Group Name Field	cn
Search Details	Search Scope	SUBTREE
Search Details	User DN Expression	uid=${username},OU=People,DC=example,DC=com
Search Details	User Search Expression	(uid=${username})
Search Details	Group Search Expression	(memberUid=${username})
Group to Role Mappings	Administrator	scheduler-admin
Group to Role Mappings	Isolation Administrator	scheduler-isolation
Group to Role Mappings	User	scheduler-user
Group to Role Mappings	Screen Reader	scheduler-screen-reader

Sample Configuration - IBM Tivoli Directory Server

	Field	Value
	Name	Example
Connection Details	URL	ldaps://ldap3.example.com:636
Connection Details	Username	jdoe
Connection Details	Password	***********
Connection Details	Retype	***********
Search Roots	Group Base DN	${distinguishedName}
Search Roots	User Base DN	OU=People,DC=example,DC=com
User/Group Attribute Fields	User Name Field	uid
User/Group Attribute Fields	User Mail Field	mail
User/Group Attribute Fields	Group Member Field	ibm-AllGroups
User/Group Attribute Fields	Group Name Field	cn
Search Details	Search Scope	SUBTREE
Search Details	User DN Expression	uid=${username},OU=People,DC=example,DC=com
Search Details	User Search Expression	(uid=${username})
Search Details	Group Search Expression	"objectclass=*"
Group to Role Mappings	Administrator	scheduler-admin
Group to Role Mappings	Isolation Administrator	scheduler-isolation
Group to Role Mappings	User	scheduler-user
Group to Role Mappings	Screen Reader	scheduler-screen-reader

Product Documentation

Configuring LDAP Manually