FusionForge

Difference between revisions of "RBAC"

From FusionForge Wiki
Jump to: navigation, search
(Pre-defining roles in Project Templates: Adding more on templates)
m
 
(19 intermediate revisions by 4 users not shown)
Line 1: Line 1:
'''Warning:''' This is only true starting with FusionForge 5.1. Previous versions have a slightly more reduced system.
+
[[Category:User documentation]]
 +
[[Category:Development]]
 +
This page in other versions: [[RBAC/6.1|6.1]]
 +
----
 +
FusionForge uses the [https://en.wikipedia.org/wiki/Role-based_access_control Role-Based Access Control] or RBAC model for permissions.
  
The permissions in FusionForge are managed along the Role-Based Access Control (''RBAC'') model.  In short, individual users don't have permissions, but they have a set of '''roles''', and each role has a set of '''permissions'''.  When a user tries to accomplish an action that's restricted, the available roles are checked; if one of the roles has the required permisson, the action can go on.  If none of the roles available to the user at that time have the permission, the action is denied.
+
Users don't have direct permissions; instead they have '''roles''' and each role has '''permissions'''.
  
The RBAC model used here is an extension of what was used up until FusionForge 5.0, designed as part of the [[Coclico]] project and more formally documented on [http://wiki.planetforge.org/index.php/RBAC_API Planetforge.org].
+
When a user requests a restricted action, her roles are checked: if one of her roles has the required permisson, the action can go on. If none of her roles have the permission, the action is denied by default.
 +
 
 +
This RBAC implementation was designed as part of the Coclico project and more formally documented on http://wiki.planetforge.org/index.php/RBAC_API planetforge.org ([[RBAC API|local copy]]).
  
 
= Roles =
 
= Roles =
  
The roles can be described according to how they're defined:
+
Roles have a class:
* ''Explicit roles'' will serve to group users with similar permissions. When a user is logged in, the available roles include all the roles the user is a member of.
+
* ''Implicit'' roles: hard-coded, applies on a whole class of users: 
* ''Implicit roles'' have pre-defined functionnally. FusionForge includes two such roles:
+
** ''LoggedIn'': grant rights to people with a current session ; grey area wrt SCM access
** the ''LoggedIn'' role is available everytime a session is open (which can be used to grant some rights to people with an account on the forge);
+
** ''Anonymous'': ''always'' available, to anonymous (non-logged-in) and identified users (cumulative with their other roles)
** the ''Anonymous'' role is ''always'' available, whether logged in or not (so it can be used to allow some actions even for non-authenticated users).  Note that the permissions acquired via the Anonymous role are not lost when a session is opened: both roles are active, as well as any roles the user might have otherwise.
+
* ''Explicit'' roles: directly assigned to a particular user. They can group users with similar permissions.
 +
 
 +
Roles also have a scope:
 +
* ''Global roles'' are forge-wide, not attached to a project in particular. This includes ''implicit'' roles. They also typically include a ''Forge admin'' and ''News admin'' role, configured to grant permissions on forge site administration and front page news approval respectively.
 +
* ''Project roles'' are attached to a specific base project. When a user is assigned a project role, she's considered as a member of the project. However, a project role can reference other projects (see "sharing a list of users" below). You can define a different role (with different permissions) for project admins, developers, managers, trainees, tech support, and so on. 
 +
 
 +
Recap:
 +
* implicit & global (anonymous, loggedin)
 +
* explicit & global (forgeadmin, newsadmin, ... ; per-user)
 +
* explicit & !global (for a particular project ; per-user)
 +
 
 +
== Sharing a list of users between projects ==
 +
 
 +
Global and project roles can be referenced ("linked to") from other projects, so that the same role (hence the same set of users) can be assigned permissions in multiple projects.
  
Roles can also be described according to their scope:
+
For instance, you can define a list of staff members; that list can be described as an explicit global role (a list of users). If that role is marked as ''shared'', a project can reference it and grant it permissions (for instance, commit access), and not have to update membership when new people join the staff, or when employees leave.
* ''Project roles'' are roles created within a project.  They can typically include a role for developers, a role for project managers, a role for trainees, a role for tech support, and so on.  As soon as a user is assigned one (or more) role(s) in a project, they're considered as a member of the project. One such particular role is "Admin" which automatically grants Project Admin like permissions for that role.
 
* ''Global roles'' are roles not attached to a project in particular, but forge-wide.  Along with the LoggedIn and Anonymous roles (which are global), a typical forge will have a ''Forge admin'' role, and a ''News admin'' role.  These two last roles will be configured to have the appropriate permissions for administering the forge and approving the news for the front page, respectively.
 
  
== Permissions sharing between projects ==
+
This may also be used for projects / subprojects links, where all project admins are automatically admins of subprojects.
Project roles and global roles can be "shared", which allows referencing ("linking to") them in other projects, so that permissions granted to one role in a project can be "delegated" automatically in other depending projects.  For instance, one may want to define a list of staff members; that list can be described as an explicit global role (a list of users).  If that role is shared, a project can reference it and grant it permissions (for instance, commit access), and not have to update membership when new people join the staff, or when employees leave. This may also be used for projects / subprojects links, where all project admins are automatically admins of subprojects, etc.
 
  
 
= Permissions =
 
= Permissions =
Permissions are defined on a "tool".  For project tools such as trackers, the project admin can configure the permissions on the tool for each of the roles that are referenced by the project; that includes the project's own roles, of course, as well as the external roles (global or coming from another project).  There are a few "global" permissions, such as approval of projects, approval of news to the front page, and forge administration.  These global permissions can only be granted to global roles (by a forge admin, i.e. someone with the forge administration rights).
 
  
Note that some permissions automatically grant others: a role with the "project admin" permission will have all the permissions on all the tools of the project, so there's no point in adding or removing individual permissions on trackers from that role; similarly, the "forge admin" permission gives all permissions on all parts of the forge, so there's no need to grant individual permissions.
+
Permissions are available for each FusionForge feature:
 +
* site permissions (assigned by site admins):
 +
** forge_admin: access to site administration, and on all projects and features
 +
** forge_stats: access to site statistics
 +
** forge_read: FIXME unused
 +
** approve_projects: can approve new projects
 +
** approve_news: can approve front page news
 +
* project permissions (assigned by project admins):
 +
** project admin: access to project administration and all project features
 +
** project_read: project visibility (useful for private projects)
 +
** tracker_admin/pm_admin/forum_admin: administration for trackers/task managers/forums
 +
** tracker/pm/forum: permission on a specific tracker/task manager/forum
 +
** new_tracker/new_pm/new_forum: default permissions for new trackers/task managers/forums
 +
** scm: source repositories (no/read-only/read-write)
 +
** docman: document manager
 +
** frs: file release system
  
Permissions related to anonymous access, or access for non-members, are handled with the Anonymous and LoggedIn roles, respectively.  As a consequence, unreferencing the Anonymous role from a project effectively makes that project unavailable for people not logged in.
+
Note that some permissions automatically grant others: "project admin" grants permissions on all project tools, so there's no point in adding or removing permissions from that role; similarly, "forge admin" grants all permissions on all parts of the forge.
 +
 
 +
Permissions related to anonymous access and access for non-members are handled with the Anonymous and LoggedIn roles.  As a consequence, unlinking the Anonymous role from a project makes that project unavailable for people not logged in.
  
 
= Pre-defining roles in Project Templates =
 
= Pre-defining roles in Project Templates =
Line 37: Line 69:
 
Should you wish to customize a project template so that its roles are similar to the traditional roles of gforge/fusionforge up to 5.1, there's a <tt>populate_template_project.php</tt> script ready for you.
 
Should you wish to customize a project template so that its roles are similar to the traditional roles of gforge/fusionforge up to 5.1, there's a <tt>populate_template_project.php</tt> script ready for you.
  
[[Category:User documentation]]
+
= Tables =
 +
 
 +
Note: the ''pfo'' prefix is for PlanetForge.Org, where the spec for RBAC was designed.
 +
 
 +
* pfo_role: list of roles
 +
** home_group_id: role ownership by this project (with implied <tt>role_project_refs</tt> project link), user project membership (through <tt>pfo_user_role</tt>), NULL means ''global'' role
 +
** is_public: role is shared, default to false
 +
* pfo_role_setting: role permissions, one row for each permission
 +
** ref_id: object the permission applies to (project, external project, forum ID, tracker ID...)
 +
* pfo_user_role: N*M relationship, what roles are available for each user
 +
* role_project_refs: link external roles to a project; linked role will also have <tt>pfo_role_setting</tt> entries for that project
 +
* pfo_role_class: could be hardcoded, provides a description for pfo_role.role_class (explicit/anonymous/logged-in)

Latest revision as of 17:16, 13 January 2018

This page in other versions: 6.1


FusionForge uses the Role-Based Access Control or RBAC model for permissions.

Users don't have direct permissions; instead they have roles and each role has permissions.

When a user requests a restricted action, her roles are checked: if one of her roles has the required permisson, the action can go on. If none of her roles have the permission, the action is denied by default.

This RBAC implementation was designed as part of the Coclico project and more formally documented on http://wiki.planetforge.org/index.php/RBAC_API planetforge.org (local copy).

Roles

Roles have a class:

  • Implicit roles: hard-coded, applies on a whole class of users:
    • LoggedIn: grant rights to people with a current session ; grey area wrt SCM access
    • Anonymous: always available, to anonymous (non-logged-in) and identified users (cumulative with their other roles)
  • Explicit roles: directly assigned to a particular user. They can group users with similar permissions.

Roles also have a scope:

  • Global roles are forge-wide, not attached to a project in particular. This includes implicit roles. They also typically include a Forge admin and News admin role, configured to grant permissions on forge site administration and front page news approval respectively.
  • Project roles are attached to a specific base project. When a user is assigned a project role, she's considered as a member of the project. However, a project role can reference other projects (see "sharing a list of users" below). You can define a different role (with different permissions) for project admins, developers, managers, trainees, tech support, and so on.

Recap:

  • implicit & global (anonymous, loggedin)
  • explicit & global (forgeadmin, newsadmin, ... ; per-user)
  • explicit & !global (for a particular project ; per-user)

Sharing a list of users between projects

Global and project roles can be referenced ("linked to") from other projects, so that the same role (hence the same set of users) can be assigned permissions in multiple projects.

For instance, you can define a list of staff members; that list can be described as an explicit global role (a list of users). If that role is marked as shared, a project can reference it and grant it permissions (for instance, commit access), and not have to update membership when new people join the staff, or when employees leave.

This may also be used for projects / subprojects links, where all project admins are automatically admins of subprojects.

Permissions

Permissions are available for each FusionForge feature:

  • site permissions (assigned by site admins):
    • forge_admin: access to site administration, and on all projects and features
    • forge_stats: access to site statistics
    • forge_read: FIXME unused
    • approve_projects: can approve new projects
    • approve_news: can approve front page news
  • project permissions (assigned by project admins):
    • project admin: access to project administration and all project features
    • project_read: project visibility (useful for private projects)
    • tracker_admin/pm_admin/forum_admin: administration for trackers/task managers/forums
    • tracker/pm/forum: permission on a specific tracker/task manager/forum
    • new_tracker/new_pm/new_forum: default permissions for new trackers/task managers/forums
    • scm: source repositories (no/read-only/read-write)
    • docman: document manager
    • frs: file release system

Note that some permissions automatically grant others: "project admin" grants permissions on all project tools, so there's no point in adding or removing permissions from that role; similarly, "forge admin" grants all permissions on all parts of the forge.

Permissions related to anonymous access and access for non-members are handled with the Anonymous and LoggedIn roles. As a consequence, unlinking the Anonymous role from a project makes that project unavailable for people not logged in.

Pre-defining roles in Project Templates

Project templates are the place to define pre-defined project roles for various classes of users with different permissions, so that these will apply automatically to projects created from these templates.

For instance, a forge admin may prepare two templates : "Public Project Template" and "Private Project Template", for "public projects" and "private projects" resp. so that the visibility of the project to anonymous and logged in (non-member) users are respectively set to "visible" and "hidden". Thus, all projects created reusing these visibility permissions set in those templates will be either visible or hidden, only accessible to their members (i.e. those with another explicit role in the project, typically set with a "visible" visibility.

Also, one may typically wish to define more roles corresponding to non-admin members and admin members of the project. The default Project Template does only provide such an Admin role.

Should you wish to customize a project template so that its roles are similar to the traditional roles of gforge/fusionforge up to 5.1, there's a populate_template_project.php script ready for you.

Tables

Note: the pfo prefix is for PlanetForge.Org, where the spec for RBAC was designed.

  • pfo_role: list of roles
    • home_group_id: role ownership by this project (with implied role_project_refs project link), user project membership (through pfo_user_role), NULL means global role
    • is_public: role is shared, default to false
  • pfo_role_setting: role permissions, one row for each permission
    • ref_id: object the permission applies to (project, external project, forum ID, tracker ID...)
  • pfo_user_role: N*M relationship, what roles are available for each user
  • role_project_refs: link external roles to a project; linked role will also have pfo_role_setting entries for that project
  • pfo_role_class: could be hardcoded, provides a description for pfo_role.role_class (explicit/anonymous/logged-in)