3. Managing Users & Permissions

User Management in Polarion

The Administration interface provides access to all operations for managing Polarion ALM user accounts and permissions. An administrator with global (i.e. repository-wide) administration rights can access all user accounts in the Polarion system. An administrator with project-scope administration rights can access user accounts for users who are assigned to the project(s) for which he/she has administrative rights.

The User Management topic in the Navigation panel provides access to the following user management functions:

Users and Projects

When you are first beginning to use Polarion, the process of creating projects and user accounts may see a bit like the old "chicken or the egg" question - which comes first?

When you create a new project, you have the possibility to specify a user as the project lead. But if you haven't created user accounts yet, you'll need to come back to the project to specify this. When you create a user account manually (i.e. not automatically via LDAP or user self-create configuration), you have the possibility to specify what Project(s) the user has access to. If you haven't yet defined any projects, you have to return to the user account to assign project(s) after creating those in the system.

For a new Polarion system, you will probably create more user accounts than Projects initially, so the most efficient approach is probably to define projects first and then create user accounts, assigning each user to one or more projects in the process. Just remember to go back and specify a project lead for each project.

Creating User Accounts

There are two ways to create user accounts in the Polarion system:

  1. An Administrator creates accounts directly in Polarion

  2. Accounts are automatically created when new users try to log in

This section will cover both options. These assume that the password file is the desired user authentication method. It is also possible to have user accounts authenticated by an LDAP/Active Directory server, and to auto-create Polarion ALMaccounts from LDAP data. For information on LDAP interfacing, see Integrating Polarion Server with LDAP/Active Directory.

Keep in mind the following scenarios when deciding on your approach to user account creation:

  1. You have users on the LDAP server and want to synchronize them with Polarion.

    Use the LDAP Synchronization feature. When the users are synchronized, they will not be able to log in to Polarion until the administrator assigns them the role user.

  2. Users already exist on the LDAP server and you have turned on and set up role assignments for new users.

    When a new user logs in for the first time, a new user account is created, and the default role(s) are assigned.

  3. You have enabled the Create Account form in the system configuration.

    Users can create their own user account before logging in for the first time. All user credentials are written to the passwd file. The role(s) will be assigned according to the properties in the system configuration for auto-creation of users.

Creating a New User Account

This section describes the procedure for creating a new user account directly in the Polarion user interface.

You will need the following information at hand in order to create a new user account:

  • The new user's name (e.g. "Jean Schmidt").

  • The new user's e-mail address. Although not required to create a new account, if it is not specified the user will not receive any notifications.

To create a new user account:

  1. Log in with administrator rights (global or project scope).

  2. Enter the Administration interface.

  3. If you want to create a new user for a specific project, open that project. Otherwise, select Repository in the Open Project or Project Group dialog.

  4. In the Navigation panel, select User Management : Users.

  5. In the Users table, click the Create New User button. A form for entering new user account information appears.

  6. Enter information in the required fields (marked with a red asterisk) and any other information you want to specify at this time.

  7. Click the Create button to create the new user account.

Important

The Login Name field must be a unique value in the repository, and should not contain spaces. Acceptable characters include upper and lower case letters, numbers, dash, underscore, period, and the "at" sign (@). This field is case-sensitive for the end user..

New users must be assigned at least one Global role in the Global Roles section or they will not be able to access any content in the portal.

Also note that login permission is only granted to users assigned a role of user. By default, a new user is assigned the role everyone. If you do not also assign a role of user, either at the repository level, or in at least one project, the new user account will be disabled, and the string [disabled] appears in red text in the user's account page when the new user account is saved. (This applies to normal users. Administrator users do not need explicit permissions assigned, as the administrator role grants them all permissions in the scope.)

Specifying a License for User Accounts

If multiple licenses are present on your Polarion server, the License Type field appears on the user account form. The field provides a drop-down list of the licenses currently available. Select the license to be used by the new user you are creating.

After pressing Save, the new user is added to users file (if the type is not the defaultUserLicense type.

Enabling New Account Creation Form

Administrators may optionally configure a Polarion installation to enable new users to self-create a new user account. When the system is so configured, the portal login page displays the following link:

Figure 3.1. Explicit Account Creation

Explicit Account Creation

Portal login page may allow new users to explicitly create a new account

When users click the link, a form appears which enables the user to specify account credentials, including user name, password, and email address for receiving notifications. When the form is submitted, the login screen appears again and the user can log in with the new credentials.

In cases where more than one product license is present on the server, it is also possible to configure which license type will be used by new users who self-create an account from the portal login page.

Enabling the Create New Account Form

This configuration is performed in the system properties file polarion.properties (follow link for location). To enable the new account form, feature set the enableCreateAccountForm option to true. To specify the license (or license group) for accounts created via the new account form, use the licenseForNewUserAccount property (see comments in the properties file for information about values). You can also specify the minimum length for passwords (minimalPasswordLength option) and role(s) for new users rolesForNewUserAccount option).

Configuring User Auto-create

The Auto-create feature makes it possible for new users to create user accounts by simply logging in to the portal. When Auto-create is enabled, then when a new user enters a user name and password in the portal login screen, a user account is automatically created, provided that the password supplied is valid for accessing the Subversion repository. The new user is also assigned the role(s) configured for new auto-created users. It is recommended to configure the Auto-create feature with at least a role that enables users to log in... the user role, for example.

To enable Auto-create:

  1. Log in with administrator permissions for the repository. Enter Administration if you are not already there after login.

  2. In Navigation, expand User Management and select Auto-create

  3. In the User Management > Auto-create page, check Enable Auto-create. The Global Roles list appears. The user role is selected by default.

  4. Specify the global (i.e. repository scope) role(s) to automatically apply to all auto-created user accounts. IMPORTANT: be sure you understand the roles and the permissions they grant to users, and recommended best practice for role assignments. For information, see Administration Reference: Default Roles and Permissions.

If more than one license type is present on your server, you may want to configure the license to be assigned to new auto-created 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 "Quick Help" in the License topic of global Administration.

Note

For Auto-create, the user specified in the login parameter of the polarion.properties file must have write access rights for the repository folders /.polarion/user-management/users and /.polarion/security in Subversion. This is not configured in default access file. You can configure it in Administration > User Management > Access Management (topic available in Polarion only), or in the SVN access file directly.

Enabling Users to Reset Password

You can configure Polarion to display a link on the portal login page that leads to some page you have set up for users to reset their password. You need to set two system properties in the polarion.properties system configuration file:

  • com.polarion.ui.login.resetPasswordLinkURL - the URL of your password reset page.

  • com.polarion.ui.login.resetPasswordLinkLabel - Link text to display on the portal login page.

See also: Advanced System Tuning.

Modifying Existing User Accounts

This section briefly covers several common modifications an administrator may be called upon to make to user accounts.

Accessing a User Account

To access an existing user account:

  1. Log in as administrator and enter the Administration interface.

  2. In the Navigation panel, select User Management : Users to load the Users table in the Working area.

  3. In the table, select the user account you want to modify. Remember that use user account you want may not be on the first page of the Users table of there are multiple pages. If necessary, use the Search field to search for the user's name.

Editing a user account

After accessing the desired account, click the Edit button in the Detail Pane of the Working Area. The following fields are modifiable:

  • Full Name

  • Email

  • Password

Changing a User's Password

To change a user password:

  1. Access the user account as described in Accessing a User Account.

  2. Open the account for editing using the Edit button.

  3. Enter the new password in the New Password field.

  4. Enter the new password again in the Re-enter Password field.

  5. Exit the Re-enter Password field to make sure your two entries match and correct the fields if they do not.

  6. Click the Save button to change the user's password.

Note

For information about passwords and password characters, see Administration Reference: Passwords.

Deleting Users

Repository administrators can delete a user provided that the user is not the Assignee of any Work Items. This is the only check performed. If a deleted user is Author of any Work Item(s), the ID of the deleted user appears italicized in the Author field of those items.

If Polarion is synchronized with LDAP, and a user is deleted in Administration, then the user's LDAP account is not deleted. The user will not be able to log into Polarion anymore, but can still to access the Subversion repository (via an external client, for example). Delete the user's account on LDAP if the user should not have continued access to the repository.

To delete a user:

  1. Log in with administrator permissions for the repository.

  2. Go to Global Administration (open Repository, or click Global Administration if you are in project Administration).

  3. In Navigation, expand User Management and select Users.

  4. In the top portion of the Users page, select the user you wish to delete, either by browsing the list, or using the Search field.

    When the user is selected in the top portion of the page, the user's detail appears in the lower portion of the page.

  5. In the toolbar of the detail portion of the page, click the Delete button and respond to the confirmation prompt.

    If the button is disabled, it means the user has some Work Item(s) assigned and therefore cannot be deleted..

Resolving Users Who Cannot Be Deleted

If you find a user cannot be deleted, you need to locate the Work Items assigned to him/her and either unassign or reassign the items.

To resolve the issue of a non-deletable user :

  1. Note the ID of the user you wish to delete. Then open the Repository. If you are in Administration, click the link Return to Portal.

  2. In Navigation, select Work Items.

  3. In the Table view, enter the following query string into the Query Builder:

    assignee.id:[USER_ID]

    Where [USER_ID] is the ID of the user you wish to delete. This query will retrieve all the Work Items in the repository for which the user is an Assignee.

  4. For each item, either unassign the user or reassign the item to a different user. Use Bulk Edit to select multiple Work Items and apply the change of Assignee to all selected items at once.

    Run the above query again to be sure there are no Work Items remaining assigned to the user.

After completing the above steps, you can return to Repository Administration where you should now be able to delete the user as described above.

Configuring User Roles

User roles control the portal content a user can access, and what level of access the user has to project artifacts and data. For example, a someone assigned a project_admin role generally can make changes to project artifacts, while someone with a project_user role would typically have read-only access. What a user with a given role can access is controlled by the permissions configuration. In Polarion, permissions are applied to roles, and roles are assigned to users.

User roles can be assigned in the repository scope, and in individual projects. Repository-scope roles control permissions of users when they log in to the repository. Project-scope roles control permissions of users when they log into a project.

User roles are configured in the User Management > Roles topic in the Administration interface. The level of access for each defined role is configured in User Management > Permissions Management. Configured roles can be assigned to users in either User Management > Roles, or User Management > Users.

Default Roles

Polarion comes pre-configured with several default user roles for different scopes. These are documented in the Administration Reference: Default Roles and Permissions.

Managing Role Definitions

You can add or delete role definitions for the repository or a project. If you add a new role definition, you will need to configure permissions for it in User Management: Permissions Management (see Configuring User Permissions). If you assign a role to a user without defining permissions for the role, the user assigned it will not be able to access anything in the repository. Also, access rights for the Subversion repository should be adjusted for the new role in User Management > Access Management (topic available only when using a Polarion product license), or in the SVN access file directly.

Adding a Role Definition

To add a new role definition:

  1. Log in with administrator permissions for the scope in which you want to define the new role, and enter Administration.

  2. If adding a repository-scope role, select Repository in the Open dialog, otherwise, select the project for which you want to add a new role definition.

  3. In Navigation, expand User Management and select Roles. The Roles administration page appears, listing the roles currently configured for the scope in which you are working.

  4. In the page toolbar, click the Create New Role button.

    A new role definition form appears in the lower half of the page.

  5. I Enter a role identifier in the ID field. For example: project_tester. Don't use spaces in the ID.

  6. In the Users section of the page, select the user(s) to whom you want to assign the new role. (This is optional - you can assign the role to users at a later time.)

  7. Click the Create button to save the new role definition.

  8. Open User Management > Permissions Management, click the By Role tab, and select the new role you just created in the Role list.

  9. Grant all the permissions you want users who are assigned the role to have, and click Save when finished.

Deleting a Role Definition

To delete an existing role definition:

  1. Log in with administrator permissions for the scope having the role definition you want to delete, and enter the Administration interface.

  2. In Navigation, expand User Management and select Roles.

  3. On the Roles page, in the table listing currently configured role definitions, select the role definition you want to delete.

  4. IMPORTANT: In the role definition detail form (lower part of the page), check the list of users who are assigned the role you are about to delete, and make sure these users have some other role assigned... at least the repository-scope user role, for example. After you delete the role definition, any users who were assigned only that role and no other will not be able to access anything in the portal.

    When you are ready to proceed, click the Delete button and confirm the action when prompted.

Assigning Roles to Users

You can assign one or more roles to any user. A role definition must already exist in order for the role to be assigned to users.

It is possible to assign a user multiple roles in a project, but this is not the recommended practice. In particular, the roles project_admin and project_user should be used exclusively, adding only the project_assignable role if the user should appear in the list of users in the Assignee field. In general, assign the role the provides the user all the permissions needed to perform his/her tasks, and no more.

For example, by default the project_admin provides all the permissions of a project_user, so you do not need to assign it in addition to project_admin.

TIP

You can easily check what permissions are granted by a role assignment. Select the role name on the By Role tab in Administration: User Management: Permissions Management (click Expand All).

To assign a role to one or more users:

  1. Log in with administrator permissions for the scope in which you want to make role assignments, and enter Administration.

  2. Use the Open Project or Project Group dialog to select Repository, or a project.

  3. In the Navigation panel, select User Management : Roles.

  4. In the Roles table, select the role you want to assign to users.

  5. In the Users table (lower half of the page), click Edit.

  6. In the Name column of the Users table, select a user in the drop-down list. The selected user will be assigned the selected role.

  7. To assign more users to this role, click the icon in the Actions column, and select another user in the Name list in the new table row.

  8. When you have added all the users you want to assign the role, click the Save button to complete the assignment(s).

The Assignable Role

Users must have a role of assignable and/or project_assignable in order to have Work Items assigned to them.

If users report that they are missing in Assignee lists, an administrator should make sure such users are assigned the assignable role in the appropriate scope.

The user Role

By default, permission to log in to the portal is granted to users having a role of user. If a user cannot log in, check the assigned roles and make sure a repository-scope role of user is assigned. When a new user account is created, this role is not automatically assigned. You can tell if the user does not have this role if the user account page shows [disabled] in red text. See also: Creating User Accounts.

Synchronizing Roles with Repository

The Roles page of Administration provides the Synchronize SVN Access File button on the page toolbar. The button updates the access file of the Subversion repository, synchronizing it with the role definitions and user role assignment configurations. (Only the first part of the access file is affected, not the directory rules in the second part). It ensures that access file contains group for every user role and that group membership is in sync with role assignment.

Generally, an administrator should only need to run this synchronization if people with an assigned role cannot access repository resources as expected. This can either be from externally editing the access file, or manually changing the user-roles.xml configuration file in the repository. Run the Synchronize SVN Access File once the manual file modifications are complete.

Configuring User Permissions

Permissions are an important security issue. You should plan to spend some time with this topic so that you can be sure to configure permissions appropriately.

Permissions can be configured globally for each repository, and for each project. Projects inherit permissions from the repository scope, and changes to the project settings override the same settings in the repository scope.

Permissions are tied to roles rather than to users. Users are assigned one or more roles and these govern what they have permission to access and do. Therefore, you should configure roles before you configure permissions.

Important

Granting permissions for Polarion does not automatically grant repository permissions. Permission to create projects, edit projects or modify administration in Polarion does not open the required repository access for those actions. You need to make sure your Subversion access permissions are configured so that Polarion permissions do not conflict with repository access permissions. For information, see the Administrator's Guide topic Repository Access Management.

To access the permissions configuration:

  1. Log in with administrator permissions for the scope you want to configure (repository or project).

  2. If you are not in Administration when you log in, enter the Administration interface (via the Administration link in the tool view of Navigation).

  3. Open the repository or project you wish to configure (see User Guide: Accessing Projects).

  4. In Navigation, expand User Management and select Permissions Management. The Permissions Management page loads.

    You can configure permissions either by individual permission, or by role. Select the tab for the configuration approach you want to use (see next sections for details).

When reviewing and editing permissions, keep in mind the color scheme from the following figure:

Figure 3.2. Permissions Color Scheme

Permissions Color Scheme

Color scheme indicates if permissions are inherited or explicit

By Permission Tab

The By Permission tab enables you to:

  • View the categories of Permissions, and access individual Permissions within each category. Categories represent areas of the system for which access is controlled by permissions: projects, Documents, or Work Items, for example.

  • View all of the roles to which a selected Permission is granted.

  • Grant or revoke the selected Permission from one or more roles.

The top half of the page presents a tree of Permissions, organized into categories. Expand the category nodes to see the individual Permissions. For example, the Work Items category contains Permissions applicable to Work Items... permission to view, permission to modify, etc.

When you select a Permission, the lower half of the screen displays the Applicable Roles table. This table lists the roles to which the selected Permission may be granted, and shows which roles have actually been granted the selected Permission (by a check mark in the Granted column. For example, if you select Permission to READ under Work Items, you can quickly see which roles have been granted this permission.

To grant or revoke permission:

  1. Select the Permission in the By Permissions tree.

  2. In the toolbar of the permissions editor pane (lower half of the page), click the Edit button. The table is now editable.

  3. To grant the selected Permission to a role, check the box next to the role name in the Granted column.

    To revoke the selected permission from a role to which it is currently granted, clear the check box next to the role name in the Granted column.

  4. Click Save to update permissions, or Cancel to abandon your changes.

By Role Tab

The By Role tab enables you to:

  • Select a role and view the Permissions currently granted to it.

  • Grant or revoke Permissions for the selected role.

The By Role page presents a tree of Permissions, organized into categories. Expand the category nodes to see the individual Permissions. For example, the Work Items category contains Permissions applicable to Work Items... permission to view, permission to modify, etc. The Permissions show the granted/not granted status for the role currently selected in the Roles list. That list displays the roles configured for the current scope (repository or project) in Administration: User Management: Roles.

To view the Permissions currently granted to a role:

  1. Select the role in the Roles list.

  2. Expand categories to see the Permissions. If the check box for a Permission is checked, that Permission is currently granted for the selected role.

To grant additional Permissions to the selected role, simply check the box next to any Permission when the desired role is selected in Roles. To revoke a Permission, clear the applicable check box.

Defining Permissions for Artifact Sets

You may sometimes need to control permissions explicitly for certain specific artifacts or some attribute thereof, such as fields of Work Items. For example, a project might require explicit permissions control on some specific Work Items or Documents, which is more restrictive than the general permissions for these artifact types. You can accomplish this more granular level of permissions control with the per-dataset permissions management feature, which enables you to create "Custom Sets" of permissions applied to an explicit set of artifacts.

You can create Custom Sets for:

  • Work Items

  • Documents

  • Pages

  • Classic Wiki Pages

  • Plans

  • Test Runs

A Custom Set is for one artifact type only. That is, you cannot have a Custom Set that controls permissions for some Wiki pages and some Documents. Each Custom Set controls permissions for a set of artifacts that match a query, which you specify when creating the Custom Set. For example, suppose you have permissions defined for Documents in general, but a project contains some Documents that are typed as "Customer Requirements", and management wants more restricted access for these than for Documents in general. You can create a Custom Set containing a query that retrieves these types of Documents as a set, and then define permissions for that set which will override the less restrictive permissions on Documents in general.

When you create a Custom Set, it appears in the relevant artifact category when you expand it in the permissions editor. For example, if you create a Custom Set for Documents named "Customer Requirements Documents", it will appear when you expand the Documents category in either of the tabs. Another entry, "Other Documents" will be automatically created, which contains the pre-existing permissions for Documents.

Figure 3.3. Custom Set

Custom Set

Custom Set for Documents. Existing permissions moved to "Other Documents".

Custom Sets can be created both in the Global configuration and per-project. Global Custom Sets are used in projects if the project does not define any Custom Set. If a project defines at least one Custom Set, then no Global Custom Sets are used in the project. If you create a new Custom Set in a project where a Global Custom Set was used before, the update saves both Custom Sets: the new one plus a copy of the global one. A globally defined Custom Set cannot be edited in the project scope.

If an artifact matches the query in more than one Custom Set in a given scope, then its permissions are controlled by the first Custom Set in the permissions category for its artifact type. For example, if a Document matches the query in "Custom Set 1" and "Custom Set 3" in the Documents category, its permissions will be controlled by "Custom Set 1".

When querying a Custom Set, it is possible to use query expanders (that is, query elements such as SQL, linkedWorkItems, PLAN, TEST_RECORDS that are decomposed to list of IDs in the background) in queries. When using these, care must be taken that user has the necessary permissions for all data accessed by the query. It is also possible to use the variable $[user.id] in a Custom Set query. However, for simple cases of assignee and author, it is recommended to use dynamic roles (author and assignee for Work Items, document_author for Documents, comment_author for Comments and Document Comments, and lead for Project).

Creating a Custom Set

To create a new Custom Set:

  1. Open the project you want to configure and enter Administration.

  2. In Navigation, expand User Management and select Permissions Management.

  3. Select the By Permission tab if it is not the current tab.

  4. Click the Custom Set button (see figure in previous section), and select an artifact type from the drop-down menu.

  5. In the Add Work Items Custom Set dialog, enter a name for the new Custom Set in the Title field. Then enter the Lucene syntax for a query that will retrieve the artifacts to be regulated by this Custom Set (see Query Tip, below).

  6. Click the Create button to finish the operation and create the new Custom Set.

You can now expand the new Custom Set and set permissions in the same way you set permissions for the artifact type, as described earlier in this chapter. Only items that match the query will be affected.

QUERY TIP: You need to be sure the query you enter will access all the items that should have their permissions regulated by the Custom Set. One way to ensure this is to go to the Work Items topic in the project and use the Query Builder in the Table view to construct the query. You can browse the results and fine-tune the query as needed. Once you are sure you have the correct set of artifacts, you can click the drop-down icon on the Query Builder and select Convert to Text. You can then copy the text of the query to your clipboard, and paste it to the Query field of your Custom Set.

Query for Permission Custom Sets

You can also query for Document, Page, Plan and Test Run permission custom sets.

Let's say that you want to search for a document so that you can assign permissions to it for external users.

id:DOCNAME1 OR DOCNAME2
                

If you wanted to refine your search to particualar document type you'd use: type:[document type]

For example:

type:[generic]
                

The following parameters will also work in a query:

Table 3.1. Additional Query Parameters

attachments

attachments.author.id

attachments.author.name

attachments.fileName

attachments.title

author.id

author.name

branchedFrom.id

comments.text

created

derivedFrom.id

derivedFrom.location

externalWorkItems

(Referenced Work Items)

id

moduleLocation

moduleName

outlineNumbering

project.id

space.id

status

type

updated

updatedBy.id

updatedBy.name

Managing Custom Sets

When you select a Custom Set, its properties are available in the lower pane of the Permissions Management page. Here you can:

  • Edit the name of the Custom Set.

  • Modify the query string for the Custom Set.

  • Move the Custom Set up or down in the list of Custom Sets for the artifact type. This is only available if more than one Custom Set exists for the type. (Position in the list can be important. If an item matches the query of more than one Custom Set, its permissions will be controlled by the first Custom Set in the list.)

  • Delete the current Custom Set. After deletion, the permissions of items revert to the general permissions defined for the artifact type in the relevant scope.

Setting Permissions for Work Item Fields

Administrators can configure the READ and MODIFY permission for most Work Item fields to grant or deny read and/or modify permissions to different user roles. For example, if local laws prohibit employers from revealing how much time an employee has worked to other employees, an administrator can deny read permission for the Time Spent field to appropriate user roles.

Work Item field permissions are located in: Administration: User Management > Permissions Management: Work Items > Fields. As with other permissions, you can access the specific permission via a listing of the permissions (By Permission tab) or by selection of a user role (By Role tab).

Note that denying permission to READ also denies permission to MODIFY. Keep in mind that denying one or both these permissions may impact users' ability to perform such tasks as creating new Work Items, reusing Work Items, and importing Work Items. See notes in the following sections for more specific information.

Field READ Permission

When configuring Work Item field permissions, keep in mind the following points:

  • If fields severity, priority and any other fields required for creating new Work Items are read-denied due to the permissions configuration, then affected users cannot duplicate or move Work Items or reuse Documents containing Work Items.

  • If read permission is denied for the Attachments field, then user will not be able to see images, or add them to rich text fields, as these are treated as attachments to Work Items.

  • In the LivePlan, if a user has only items in which READ permission is denied in one of the fields listed in the plan, then no items for that user will appear in the LivePlan.

  • For import/export and round-trip operations:

    • The value of READ-denied Work Item fields are not shown in exported files when a user who is denied the permission exports the item(s).

    • If a user re-importing a round-trip document is denied READ permission for any field(s), the READ-denied fields are ignored by the round-trip importer.

    • IMPORTANT: If a user who is denied READ permission for some fields exports Work Items for round-trip, and round-trip re-import is subsequently performed by an different user who is not denied READ permission (admin user, for example), then all changed field values in the re-imported file are imported and replace the respective current values in the portal.

    • If any import/export operation cannot be completed because a user is denied some field-level READ permission, the operation will fail with a message citing limited permissions as the reason.

For a listing of Work Item fields having the READ permission, see the Administration Reference topic Fields With READ Permission.

Important Permissions Ramifications

It is important for administrators configuring permissions to understand several ramifications and potential user impacts that may not be readily apparent.

  • To be able to modify Work Items in a Document, users must be granted:

    • Permission to MODIFY fields Description and Title.

    • Permission to MODIFY CONTENT for Documents (including Documents in a Document Custom Set).

  • By default, users can delete Heading type Work Items without having the permission to DELETE Work Items. To require that permission for deleting Headings, set the system property headingsObeyDeletePermission=true in the system configuration file polarion.properties.

  • If Test Steps are displayed in a Document and they are not editable, but Title and Description fields are editable, then user can modify Work Items in the Document, but not the Test Steps field.

  • If permission to READ is denied for the Attachments field of Work Items, then images in the Description field and other rich text fields will not be visible to affected users, as images are attached to Work Items.

Permissions for Test Runs

The adding and resolving of comments on Test Runs are controlled by the two permissions: "Permission to COMMENT" and "Permission to RESOLVE COMMENTS". By default, users with a Reviewer, PRO, or REQUIREMENTS license can add and resolve comments on Test Runs, if their role allows it. If this is not desired, you should explicitly deny these permissions for any roles that you do not wish to allow to have them.

The comment permission is a child of "Permission to MODIFY". If you grant that permission to some role that does not currently have it, the "Permission to COMMENT" is granted as well unless you explicitly deny it.

Configuring User Time-splitting

In some cases, users may regularly split their working time between two or more projects (i.e. time sharing). The Live Plan project planning engine can account for this and factor such splits into the live project plan, provided the user's split time between projects is configured in his/her user account. This section explains how to configure user time splitting between projects.

Accessing the Time-split Configuration

To access a user's time-splitting configuration:

  1. While in the Administration interface, select Repository, or any project in the Open Project or Project Group dialog.

  2. In the Navigation panel, expand User Management and select Users. The table of users for the selection appears in the top pane of the Content Pane.

  3. Scroll or use Search to locate the user whose time is to be split between projects, and select the relevant row in the table. The user's detail appears in the lower part of the Content Pane.

    In the table, the Time-split Assignments column displays the current split time assignments, if any, for the selected user.

  4. Click the Edit button in the user detail pane to place the user detail form in edit mode.

  5. Scroll down, if necessary, and locate the Time-split Assignments section. This is where you assign the percentage of the user's time for each project.

Assigning Split Work Time

Each row in the Time-split Assignments section lists a project for which the currently selected user has Work Items assigned. (You cannot split a user's work time into a project for which the user has no assigned Work Items.) You use the % of Total Time column to assign of percentage of the user's total working time to two or more projects.

Important

The values you enter in % of Total Time must be integer values (and you do not need to enter the % sign). For example: 25 is a valid entry, while 33.3 is invalid and will result in an error message when you save changes.

It is not possible to save the configuration if the sum of all time-split assignments is more than 100.

The configuration splits the user's total working time between the different projects. That time is a combination of the Global Working Calendar configuration and the selected user's Personal Working Calendar configuration.

Effect on Live Plan

When a user has working time shared between two or more projects, this is reflected in the Live Plan chart. In the Repository and Project Group scope, the chart shows additional lines for a user with time splitting configured, if there are Work Items assigned to user in the configured projects. The lines are labeled by the user name followed by the configured percent in parenthesis. For example: Jan Almsman (20%). If the sum of configured time-split assignments is less than 100, then an extra line is shown for the remaining percentage if there are Work Items assigned to user in other projects for which for which no time-split assignment is specified in the configuration. The estimate of the Work Items for planning is multiplied by the ratio of the configured percentage. (So 20% means then the estimate is multiplied by 5.)

In the project scope, one line for the user is shown if there are items assigned to this user and there is some percent of time-split configured. If the total time splitting configured for specified projects is 100, and there are unresolved items assigned to the user in other projects, those items are not planned, nor are they displayed in Live Plan, and the warning is logged.

Planning of the Work Items from the different "rows" in the Live Plan which belong to the same user is independent (i.e., planning engine does not compare priorities etc.) except for items with a "depends on" link.

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 section 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.

Important

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 re-authenticate 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 login 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.

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 re-connect, starting with the primary server, and trying each redundant server in turn. Note that this is different than a true round-robin search."

Configuring 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 in with administrator permissions for the repository. If you have a clustered mult-server environment, you need these permissions for the repository of any server instance you want to configure for LDAP synchronization.

  2. Open the repository (see User Guide: Accessing Projects).

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

Editing 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 check the Enable LDAP Synchronization box.

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 checked, the synchronization operation will create 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 checked, the Polarion accounts of existing users will be 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 will be 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 checked.

Configuring 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 "Quick Help" in the License topic of global Administration.

Configuring 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 in. 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. 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 Configuring Polarion for LDAP User Synchronization).

To invoke the synchronization process navigate to Administration > User Management > LDAP Configuration and click the Synchronization button. This takes you to the Users synchronization page. Click the Synchronize button to synchronize users from the configured LDAP server to the Polarion user scheme. If you click on the Update existing button, then not only new users will be inserted into the Polarion user scheme, but existing users fields will be updated as well, and existing user data will be overwritten by LDAP data. The list of user fields taken from the LDAP server is specified in theldap-config.xml configuration file. Polarion displays the result of the synchronization: the number of new, updated and existing users.

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 Configuring Polarion for LDAP User Synchronization), then the newly created user is synchronized with information provided by the LDAP server.

To access the auto-create configuration file:

  1. While the Administration interface open the Repository scope (click Open),

  2. In the Navigation panel, select User Management : Auto-create.

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

The autocreate-config.xml file contains the tag <autocreate-config> which has an element <enabled>. The default value in this element is false. To enable Auto-create, replace this value with true. You may also want to adjust the list of roles that should be assigned to auto-created users in element <globalRoles>. Then use the controls in the Upload New Global Configuration section to upload the modified configuration file back to the repository.

Network-authenticated Users (SSO)

Polarion supports single sign-on (SSO) for users authenticated on the network. For information, please see Administrator's Guide: Advanced Administration: Configuring Single Sign-on (SSO).

Configuring the User Accounts Vault

Some features need to have a user name and a password specified in the configuration in order for the feature to work properly. For example, a scheduled job that imports automated test results needs credentials of a user on whose behalf it creates the Test Cases and Test Runs. For security reasons, administrators may not want certain user credentials stored in the underlying configuration file in the file system.

The User Accounts Vault provides a secure way to store user credentials, and enables administrators to reference them in a secure way in configurations. For each user account that needs to have its credentials specified in configurations, you create a Key and associate the user name and password with it. Then in configurations, instead of supplying the concrete user name and password, you supply the Key value from the User Account Vault. Polarion automatically resolves Key references when necessary.

The User Account Vault can be configured in the global (Repository) scope only. To access the configuration:

  1. Log in with administrator permissions for the repository.

  2. Open the Repository and enter Administration.

  3. Expand User Management and select User Account Vault

The User Account Vault page presents a table of currently configured Keys. You can add new Keys, edit existing Keys (e.g. change the password), or delete existing Keys. Before deleting any Key, be sure it is not used in any configuration, especially in scheduled jobs, which will fail if a nonexistent Key is specified in the job configuration.

TIP

It is not recommended to create Keys for credentials people who use Polarion. Rather, keys should refer to special user accounts created for automated data access.

For example there is a user "polarion" which is the system user. This user needs to be specified for jobs like the one cited above for test result imports. You should create a Key for this user in the vault and specify that Key in all configurations requiring system user credentials, rather than the actual user name and password.