Administering roles and permissions

The three key concepts to understand are actions and resources.

• Permissions are a combination of the actions that can be performed and the resources upon which they can be used.
• Actions include activities such as reading, writing, editing, deleting, creating and suggesting.
• Resources are anything that is added to a site, such as projects or users.

When choosing what permission to grant to users it is important to keep in mind the minimum rights the user needs. For instance, if you want a user to be able to suggest a project document to the administrator for approval, you should grant the user Project Document - Suggest permission but not the Project Document - Approve permission. Likewise, if you would like a user to be able to view their own profile without being able to change it, you should grant them the User - View - Self permission but not the User - Edit - Self permission. For a full list of permissions with descriptions see Actions and permissions.

Every user on this site is able to access features and conduct activities based upon roles the user has been granted. There are two kinds of roles:

• Domain roles give users access to generalized information and actions throughout the site. Domain administrators assign and configure domain roles to all users on this site. Every new user automatically gets the "registered user" domain role by virtue of being registered on your domain. It is also possible to create other domain roles; more about this is covered in Adding roles below.
• Project roles are limited to resources and actions within a project. Domain administrators also can configure project roles, but by design Project owners usually assign project roles to users when they become project members.

Roles are either assigned to users through membership in a project, or through association with project groups or user groups. All roles have a default set of permissions associated with them. These permissions govern the users' ability to conduct certain actions on this site.

As a domain or host administrator, you can:

• Use and assign existing roles.
• Alter existing roles by changing the permissions, actions, and/or resources that are associated with them.
• Create entirely new roles and designate permissions for them. See Adding roles.

You can also tailor roles and permissions for sets of users by creating user groups, and for sets of projects by making project groups. For more information about this, see Creating and editing project groups and Creating and editing user groups.

Editing user role assignments

The Edit user page allows you to edit the user's profile information including the user's role assignments. The fields and options relevant to the user's roles are:

Group memberships

The user's affiliation with any user group or project group in this domain are listed here. User groups and project groups are created and configured by you as the Domain administrator. See Creating and editing project groups and Creating and editing user groups for more information.

Domain-wide roles

Domain roles assigned or conferred to the user are listed here. These are generalized roles that permit the user to view site pages and conduct site actions not associated with specific projects. See previous Understanding roles and permissions above.

Submit changes button

This button submits any modifications to the individual user account made in the fields above. Modifications to the user's roles are separate actions.

Project Roles

Roles the user holds that are associated with specific projects are listed here, grouped by project name. Project names link to project home pages. This list includes both public and private projects. See Understanding roles and permissions above for a more comprehensive discussion of roles. You can remove roles from the individual user's account by selecting the Delete checkbox in line with the role and clicking the Update roles button.

Detailed role info

These links lead to secondary screens with more detailed information about the roles associated with the current user:

• Direct and derived roles displays two different sets of roles held by the user. Direct roles are those roles expressly assigned to the user. For example, the user requested and was approved for a certain role in a project. Derived roles are roles that the user acquires through User group and Project group affiliations. When a user belongs to a user group that is assigned a role, that role appears on this page as a derived role. Likewise, when the user is a member of a project associated with a project group, the user derives the project group's roles.
• Details of permissions displays the Permissions for user page which tabulates every permission the user holds in your domain.

Note that when individual users are part of particular project groups or user groups, you can assign attributes and modify multiple user accounts associated with those groups by using the Edit project group or Edit user group pages. See Creating and editing project groups and Creating and editing user groups for more information.

Other operations

The Delete user link removes the current user account. A confirmation message prompts you for verification before this action is completed.

Editing roles

This site features a set of default roles that you may view using the Roles link in the Administration navigation bar. This displays the Roles page which contains a listing of all roles. Domain level roles appear on the Domain tab and project level roles appear on the Project tab. A brief description of each role is included.

To view or modify a roles properties and permissions, click on the role name link in the Roles page. This page consists of two sections. The first contains the list of individual permissions associated with a role. Each permission listed on the Edit Role page is characterized by both the site resource and site action that it enables, i.e. "Project - Suggest" or "Version Control - Update." The Resource(s) column defines in which site resources each permission is effective. The default is for each permission to apply to all available resources.

As Domain administrator, you have the option to modify the default roles for the site by changing the permissions associated with them as needed. Placing a check mark in the boxes next to a permission removes this permission from the role.

If you wish to add permissions to a role, click the Add new permission to role link at the top of the Permissions section of the Edit role page. This screen gives you a list of all available permissions. Select the permissions you wish to add to the role by placing check marks in the appropriate boxes.

In addition to editing roles by adding and removing permissions, you can modify or limit which resources the permissions associated with that role will apply to. The resource section on the Add new permissions to role page lets you determine to which site resources to allocate the role's new permissions.

• Selecting the All available resources option applies the selected permissions for this role universally to all site resources available to this role, including both web content and source code.
• Choosing the All web pages option limits the selected permission for this role specifically to web pages. This means the scope of these permissions does not pertain to any source code level access, but only to web page content. For example, assigning the "Version Control - Commit" permission to a role and choosing "All web pages" option as the resource limits users with this role to only being able to check out and commit web page content, not project source code.

After you have selected the permissions to add and determined the site resources to apply these to, click the Add permissions button.

See Viewing and adding resources for more information about site resources.

Default Roles

To comply with Internet standards of mail management, any system that includes an SMTP server supporting mail relaying or delivery must support the reserved mailbox "postmaster" as a local name. And in the same way, for any system that includes an a HTTP server, "webmaster" is the local name. In the case of CollabNet Enterprise Edition, we support these mandatory mail IDs - postmaster@<domainname> and webmaster@<domainname>.

The mailer@daemon.<domainname> is the mail ID where messages are recieved from the email server itself.  Usually you only hear from the email server when it has trouble delivering an email you sent.

The Domain Contact is the email address where the system sends system-generated notifications about general events. The domain contact is generally by default admin@host.<domainname> where delivery is ensured to a recipient appropriate for the referenced service or role. This email should be assigned to a domain administrator who will take the responsibilty of attending to the cries of help or simply routine notifications from the system.

To change or confirm an email address as the Domain Contact;

1. Log in as the domain administrator.
2. Click the Administration tab.
3. Click the link Configure Domain.
4. In the section Framework (Domain Settings), you will see an editable field Domain Contact.

If you are a member of a project you will receive email from that ID. For example;

1. Navigate to a project.
2. Click the links Membership > Invite new members.
3. Specify the user name in the People To Invite field and submit.
4. Now the newly added user will receive an email from the mail ID specified in the field Domain contact. By default it is admin@<domain name> 

Adding roles

You have the option to create custom roles and assign the appropriate permissions to them to meet the needs of your site and/or projects within your domain. You should take some time to plan the scope of any new role you create before beginning the creation process. You can create roles for the domain or projects. Host roles enable associated user actions across all domains. Domain roles enable associated user actions across the site. Project roles enable associated user actions within the projects only. You can create roles that are specific to one or more particular projects or associate the roles across all projects.

To add new roles:

1. Select Roles from the Administration navigation bar to access the Roles page.
2. Select either the Project or Domain tab depending on the level of the role you wish to add.
3. Click the Add new project role link if you are on the Project tab or the Add new domain role link if you are on the Domain tab to display the Add new role page. Depending on which section you linked from, this page will allow you to define and add either project or domain roles.
4. Select the visibility of the role (applies only to project roles). This determines at what level the project role can be seen. Selecting the Domain level allows visibility at both the domain and project level, while the Project level will make the role only visible at the project level.
5. Enter a name and a description of the role. The role name can be up to 99 characters in length and cannot include a period (.).
6. Select the level of functionality required for this role. Each functional item controls the level of access for the role.
   • Requestable: makes the role requestable by users on the site. If this item is not selected, the role must be assigned by an administrator or a project owner.
   • Ownership role: grants users with this role "ownership" of functions within the project. Owners receive administrative email pertaining to the function of which they have ownership.
   • Grant role on subproject creation: grants the role to users who create new subprojects.
   • Block recursion into private projects: when checked prevents this role from being granted recursively in private subprojects. Users with a recursion-blocked role in a project will have the role recursively only in the project's public subprojects. For example, if the "games project has a private subproject called "Dominoes" and a public subproject called "Pinochle", a user with the Project owner role in the "Games" project cannot have the Project owner role in the "Dominos" subproject but can have the Project owner role in the "Pinochle" subproject.
7. Assign permissions to the role. You can do this by either cloning an existing role or assigning specific permissions. To clone an existing role, select a role from the drop down menu. To assign specific permissions, click the check box under the Add field by the name of the permission you desire.
8. Click the Create role button. Use this feature with extreme caution! Assigning permissions to roles may have security implications.

Deleting roles

You can delete project or domain roles that are no longer used or needed. You should exercise caution when using this feature because once deleted the role cannot be retrieved.

To delete a role click the Delete link next to the role you wish to delete. If no Delete link appears for a role, then that role is still associated with users and/or user groups. You must first remove every assignment of the role, in every project. See Editing user role assignments above for more information on removing role assignments.

About resources and actions

Resources are all of the different elements used in this site including tools, content, projects, and web pages. User roles and permissions on this site are defined by the specific resources they apply to. For example, each of these permissions -- "Project - Suggest," "Version Control - Modify" -- is comprised of a certain resource on this site and the action being permitted within that resource. In these two examples, the resources are, respectively: project, and version control.

Resource patterns are described on this site using regular expressions in perl 5 format. Thus, the pattern or regular expression meaning all available resources is ".*".

As the domain administrator, you can view existing resource patterns by clicking the Resource patterns link in the Administration menu. The default items in the Resource patterns page are "All applicable resources" and "All web pages". Clicking on the resource link displays the Edit resource pattern screen where there is a short, identifying description and the pattern that represents the resource as a regular expression.

You can also create new resource patterns to increase your ability to control user access. For example, you might decide that you want to create new user roles with permissions that only apply to certain types of files. If these were Java files, you could define that as a resource pattern using the regular expression "^.*\.java$". Then you could either create new roles or modify existing roles by adding permissions limited to the "^.*\.java$" resource pattern.

Note: Resource Patterns are expressed using Perl syntax, and not shell syntax.

Deleting resource patterns

As a domain administrator, you can delete resource patterns. To access the screen:

1. Log in to CollabNet as the domain administrator.
2. Click the Administration tab.
3. Click the link Resource Patterns.
4. Click the Delete link against the Resource Pattern you wish to delete.

You cannot delete a Resource Pattern that is associated to a particular permission which in turn is assigned to a role, unless you revoke the association before you attempt to delete the Resource Pattern.