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 be either 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 Apache modules - is 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, it is necessary to delete the users from the password file and have them reauthenticate via LDAP. This is necessary only if you want to replace password file authentication with LDAP authentication. (It is possible to 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 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

The possibility for authentication failover or fall-back is provided by 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 documentation (see http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html#authldapurl). Pay particular attention to the host:port setting.

Note:

Excerpt from the Apache 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 configure Polarion to auto-create users from LDAP (as described in Configuring Auto-creation of Users) or to synchronize the users defined in LDAP with Polarion users (as described in Synchronization of Polarion users with LDAP), then you need to configure Polarion as well.

The LDAP Configuration page of Administration enables you to 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 organizations LDAP server, you may need to consult with that administrator 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 2 options for synchronization:

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

  • 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 selection the desired option(s), invoke the synchronization using the Synchronize button, which is enabled when any of the options are selected.

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. Note that if concurrent license groups are defined in the global configuration, it is possible to 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 the 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 system configuration file polarion.properties provide details about how to set the value.

The polarion.properties file resides on the server's file system (see System Properties File Location). You can open and edit it using a text editor application.

Synchronization of 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 check box to synchronize users on the configured LDAP server with the Polarion user scheme.

  3. If you select the Update Existing Users check box, 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. Click Synchronize. An Info dialog box displays the synchronization results.

The Auto-create feature is independent of use of an LDAP server. (It can be used with ordinary Subversion authentication as well.) However if LDAP user synchronization is enabled (see Configure Polarion for LDAP User Synchronization), then a newly created user is synchronized with information provided by the LDAP server.

To access the auto-create configuration file:

  1. Click Administration.

  2. Select the Repository scope.

  3. Use the link in the Configuration section (Content Pane) 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 ldap-config.xml file.

  6. Click (Download icon) to download a local copy of the ldap-config.xml file, and then open it in a text editor.

  7. If <auto-config> <enabled> 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 (Upload icon) to commit your updated file the repository.