Integrating Polarion server with LDAP/Active Directory

LDAP can be used to verify user credentials instead of a password file in a stand-alone setup. The access file is used to define the user groups and access rights to individual repository locations. User accounts can either be manually created in Polarion (with user names corresponding to LDAP) or auto-created by Polarion based on existing LDAP users. (All necessary software for LDAP - including the Apache modules - are bundled with the Polarion distribution for Windows.) This topic explains the basics of integrating LDAP/Active Directory with the Polarion server.

User credentials can be authenticated against the Subversion password file or against an LDAP server. The default configuration supports both local and LDAP users.

Warning:

If you want to introduce LDAP-only authentication in an existing Polarion installation where existing users are currently authenticated against a password file, you must delete the users from the password file and have them re authenticated via LDAP. This is necessary only if you want to replace password file authentication with LDAP authentication. (You can configure Polarion to use either method.)

In a new installation, users are authorized using the Subversion integrated policy access functions (directives AuthzSVNAccessFile and AuthUserFile) in the polarionSVN.conf file. If you have an LDAP infrastructure, you can make Polarion authorize users against the LDAP database. Information on performing this configuration, together with some examples, is provided in the polarionSVN.conf configuration file. The file is located at: [POLARION_HOME]\bundled\apache\conf\extra\polarionSVN.conf (Windows), OR /etc/apache2/conf.d/polarionSVN.conf or /etc/httpd/conf.d/polarionSVN.conf (Linux, depending on distro). After modifying the configuration file, the Apache server must be restarted to reflect the changes. For more information about the Apache LDAP modules and their capabilities, visit these web pages:

Authentication Failover

Authentication failover or fall-back is provided by the Apache HTTP server. For example, Apache can be configured to switch to LDAP authentication if a user logging on is not matched in the passwd file, and to fall back to a secondary LDAP server if the primary server is offline. Information on this configuration is provided in Apache's documentation (see http://httpd.apache.org/docs/2.4/mod/mod_authnz_ldap.html#authldapurl). Pay particular attention to the host:port setting.

Note:

Excerpt from the Apache's documentation:

"The name/port of the LDAP server (defaults to localhost:389 for LDAP, and localhost:636 for LDAPS). To specify multiple, redundant LDAP servers, just list all servers, separated by spaces. mod_authnz_ldap will try connecting to each server in turn, until it makes a successful connection."

"Once a connection has been made to a server, that connection remains active for the life of the httpd process, or until the LDAP server goes down."

"If the LDAP server goes down and breaks an existing connection, mod_authnz_ldap will attempt to reconnect, starting with the primary server, and trying each redundant server in turn. Note that this is different than a true round-robin search."

Configure Polarion for LDAP user synchronization

If you just want to have Subversion (and Polarion) authenticate user credentials against LDAP instead of a password file then you can skip this section. However, if you want to auto-create users from LDAP or synchronize the users defined in LDAP with Polarion users, then you need to configure Polarion as well.

The LDAP Configuration page in Administration lets you activate LDAP synchronization and configure Polarion to work with your LDAP server. When LDAP is enabled and configured, you can also explicitly invoke synchronization from this page.

To access the configuration page:

  1. Log on with administrator permissions for the repository. If you have a clustered server environment, you need these permissions for the repository of any server instance you want to configure for LDAP synchronization.

  2. Go to Global Administration if you're in a project, or Administration if you're working in the Default Repository.

  3. In Navigation, expand User Management and select LDAP Configuration.

Edit the configuration:

The LDAP Configuration page has several sections. The settings for configuring Polarion to work with your LDAP server are in the LDAP Server Connection Settings section. The settings are disabled until you select Enable LDAP Synchronization in the User Synchronization with LDAP section.

The rest of the settings are information about the LDAP server — the host URL, etc. If you are not the administrator for your organization's LDAP server, you may need to consult with them to obtain the information needed for these settings. Help text explaining the purpose of each of the settings is embedded in the LDAP Configuration page.

Explicitly Invoking Synchronization:

After configuring Polarion to work with your LDAP server, you can explicitly invoke synchronization. The LDAP Configuration page has several sections. The controls for explicit synchronization are at the top of the page. There are two options for synchronization:

  • Create New Users: When selected, synchronization creates new Polarion user accounts for the new LDAP-registered users added since the last synchronization. The LDAP configuration specifies parameters controlling which Groups, etc. are synchronized.

  • Update Existing Users: When selected, the Polarion accounts of existing users are updated with any changes for the same users on the LDAP server. For example, if a user's email address has changed in the user's LDAP record, the user's Polarion account is updated with the new address during the synchronization.

After selecting your desired option(s), click Synchronize. (It is enabled when an option is selected.)

Set an LDAP bind password:

The following property in the polarion.properties file sets the LDAP bind password if your LDAP configuration requires one:

ldap.bind.password

Note:

It is empty by default and must be edited directly in the polarion.properties file.

Configure the Default License:

If more than one license type is present on your Polarion server, you may want to configure the license to be assigned to new users. Specify the license in the licenseForNewUserAccount property in the polarion.properties file. (Windows: polarion/configuration/polarion.properties, Linux: %POLARION_HOME%/etc/polarion.properties). See the comments for this property in the configuration file for more information. If concurrent license groups are defined in the global configuration, you can specify a concurrent license group in the licenseForNewUserAccount property rather than a license. For information on these groups, see the embedded help text in the License topic of Global Administration.

Configure Default user Role(s):

New users created via LDAP synchronization are assigned a default Polarion user role according to the setting in the system property rolesForNewUserAccount. The default role is user, which has minimal permissions and allows a new user to log on. You can decide to specify a different default role or multiple default roles. Comments for this property in the polarion.properties file give details on how to set the value.

The polarion.properties file resides on the server's file system. You can open and edit it in a text editor.

Tip:

See the Quick Help section of the LDAP Configuration administration page for more information.

(AdministrationUser Management LDAP Configuration)

Synchronize Polarion users with LDAP

When LDAP-only authentication is set up you cannot create new users using Polarion. Instead, you should create new users in the LDAP server and then synchronize the Polarion user scheme with LDAP. However you can use the user synchronization action regardless of what Subversion authentication type is used; it is just required that the synchronization is enabled and properly configured (as described in Configure Polarion for LDAP User Synchronization).

To begin the synchronization process:

  1. Navigate to AdministrationUser Management LDAP Configuration.

    The following Synchronize UserId with LDAP options appear:

  2. Select the Create New Users checkbox to synchronize users on the configured LDAP server with the Polarion user scheme.

  3. If you select the Update Existing Users checkbox, then existing user fields are updated, and existing user data is overwritten by LDAP data.

    Note:

    The list of user fields is taken from the ldap-config.xml file.

  4. Select the Update User Groups checkbox to synchronize all User Groups with an LDAP Search Filter value.

  5. Click Synchronize. An Info dialog box displays the synchronization results.

Caution:

The synchronization results report does not include changes done by queries on User Groups. It only shows changes done by the query configured on the LDAP Configuration administration page.

(For example the report might show 0 created users when some users were in fact created by User Group synchronization.)

Tip:

How to handle LDAP sync errors:

Check the LDAP report and look for errors.

(Each error contains a stored exception as its cause. This exception can be further investigated.)

For Example: 

dialog.ldapSynchronization.errorSynchronizingUsers: uri: subterra:data-service:objects:/default/${UserGroup}nonExistingGroup (com.polarion.platform.persistence.UnresolvableObjectException))

Use a Job to automatically synchronize Polarion users with LDAP

There are two jobs that can be used to automatically synchronize Polarion users with LDAP:

1. General LDAP User Synchronization

Instead of manually synchronizing Polarion users from LDAP using the Polarion UI (Global AdministrationUser ManagementLDAP Configuration), you can execute it automatically by setting up the polarion.jobs.ldap.users.synchronization job in Polarion's Scheduler.

It supports the following parameters:

  • <createUsers>; Possible Values: "true" or "false"

  • <updateUsers>; Possible Values: "true" or "false"

(If parameters are not specified, default values of "false" are assigned when the job is executed.)

Example 1: (Don't create new users but update existing users)

<job id="polarion.jobs.ldap.users.synchronization" name="Perform user update from LDAP">
<createUsers>false</createUsers>
<updateUsers>true</updateUsers>
</job>

  • The job appears in the Monitor under the name Perform user update from LDAP.

  • It will attempt to synchronize the users in Polarion with those in LDAP. If it finds new users, they are not created. If existing users are out of sync, they are updated.

Example 2: (Create new users and update existing users) 

<job cronExpression="0 0 7 * * ?" id="polarion.jobs.ldap.users.synchronization" name="Synchronize Polarion users with LDAP"
<createUsers>true</createUsers>
<updateUsers>true</updateUsers>
</job>

  • The job appears in the Monitor under the name Synchronize Polarion users with LDAP.

  • It is executed every day at 7a.m. and attempts to synchronize the users in Polarion with those in LDAP. If it finds new users, they are created. If existing users are out of sync, they are updated.

2. LDAP Synchronization of Polarion Users in User Groups

You can also synchronize users in Polarion for a specific set of User Groups by setting up and running the polarion.jobs.ldap.userGroups.synchronization job in Polarin's Scheduler.

It synchronizes each User Group with the Search Filter that was entered on the Group's page in Administration.

(AdministrationUser ManagementGroups)

It supports the following parameters:

  • <createUsers>: (Boolean parameter, set to "false" by default.)

  • <updateUsers>: (Boolean parameter, set to "false" by default.)

  • <updateAllUserGroups>: (Boolean parameter, set to "false" by default.)

    If set to "true" anything set in <userGroupIds> is ignored and all Users Groups are updated.

  • <userGroupIds>: A list of Groupd IDs. (Handled as empty by default if not otherwise specified.)

Example 1:

<job id="polarion.jobs.ldap.userGroups.synchronization" name="Update all User Groups">
<createUsers>true</createUsers>
<updateAllUserGroups>true</updateAllUserGroups>
</job>

The job appears in the Monitor under the name Update all User Groups.

It synchronizes users in Polarion. If it finds new users, they are created. If existing users are out of sync, they will not be updated. All User Groups will be checked and the necessary users assigned to them.

Example 2: 

<job id="polarion.jobs.ldap.userGroups.synchronization" name="Update some User Groups">
<createUsers>true</createUsers>
<updateUsers>true</updateUsers>
<userGroupIds>
<userGroupId>dev-user-group</userGroupId>
<userGroupId>qa-users</userGroupId>
</userGroupIds>
</job>

The job appears in the Monitor under the name Update some User Groups.

It tries to synchronize the Polarion users from the dev-user-group and qa-users Groups defined in the job. If it finds new users, they are created. If existing users are out of sync, they are updated. Only the defined User Groups are synchronized. All other User Groups and their LDAP queries are ignored.

Caution:

Do not leave <userGroupId></userGroupId> under <userGroupIds> without a value in the Scheduler. The synchronization job will fail with an error.

Configure Auto-creation of Users

The Auto-create feature is independent of the use of an LDAP server. (It can also be used with ordinary Subversion authentication.) However, if LDAP user synchronization is enabled, then a newly created user is synchronized with the information provided by the LDAP server. For succesful user updates, and users authorized via the polarionSVN.conf file, both the file and Polarion's LDAP configuration need to be set up correctly.

The AuthBasicProvider property also needs to be set to 'ldap'.

To access the auto-create configuration file:

  1. Click Administration.

  2. Select the Repository scope.

  3. Use the link in the Configuration section to download a local copy of the autocreate-config.xml file.

  4. Click User ManagementAuto Create.

  5. Click Navigate to Repository Browser, on the right, to access the autocreate-config.xml file.

  6. Click to download a local copy of the autocreate-config.xml file and open it in a text editor.

  7. If the <enabled> tag within <autocreate-config> is set to true, then Auto-create is enabled.

  8. (Optional) You may also want to adjust the list of roles that are assigned to auto-created users in the <role> elements contained within the <global-roles> element.

  9. When you've finished configuring the file, save it and click to commit your updated file the repository.

LDAP Search filter