head	1.7;
access;
symbols;
locks; strict;
comment	@# @;


1.7
date	2001.07.30.18.40.43;	author leonardr;	state Exp;
branches;
next	1.6;

1.6
date	2001.07.18.21.29.05;	author leonardr;	state Exp;
branches;
next	1.5;

1.5
date	2001.07.18.21.27.43;	author leonardr;	state Exp;
branches;
next	1.4;

1.4
date	2001.07.18.21.24.59;	author leonardr;	state Exp;
branches;
next	1.3;

1.3
date	2001.07.18.21.23.32;	author leonardr;	state Exp;
branches;
next	1.2;

1.2
date	2001.07.18.18.15.39;	author leonardr;	state Exp;
branches;
next	1.1;

1.1
date	2001.07.18.18.00.11;	author leonardr;	state Exp;
branches;
next	;


desc
@@


1.7
log
@Action cleanup. Some role actions, and Audit Log - View, had three actions apiece when one would do. We're now down to 76 actions.
@
text
@<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
 <head>
  <title>Helm Permission Overview</title>
 </head>

<body>

<h1>Helm Permission Overview</h1>
Leonard Richardson &lt;leonardr at collab dot net&gt;<br>
July 18, 2001<br>
<small>$Id: permissions.html,v 1.6 2001/07/18 21:29:05 leonardr Exp $</small>

<h1>Helm Permission System</h1>

<h2>Overview</h2>

<p>Helm has a flexible role-based permission system which provides
several degrees of freedom. Following are formal and informal
definitions of the permission system, with examples.

<h2>Formal Definition</h3>

<p>User U can perform action A on an object O in project P iff U has
role R in project P and R has A on a resource matching O, and either P
is not locked or A is not affected by project locking.

<p>A resource R matches an object O iff the name of O matches the
regular expression associated with R, 'name' being defined on a
per-object-type basis.

<p>User U has a role R in project P iff U has a direct or derived role
in P, or belongs to a user group G with a direct or derived role in P.

<p>User U has a direct role in project P iff an approved mapping
exists in HELM_USER_ROLE_PROJECT between U's user ID and P's project
ID. A mapping is approved iff its APPROVED_BY field is the user ID of
a user besides the special *Nobody user.

<p>User U has a derived role R in project P iff U has a role in a
project Q, where P is a member of Q and the following conditions are
met:

<ul>

<li>It is not the case that Q is a category but P is not.

<li>It is not the case that P is private and R has the
  "blockRecursionIntoPrivateProjects" attribute set.

</ul>

<p>Project P is a member of project Q iff there is a mapping in
HELM_PROJECT_PROJECTGROUP in which P's ID occurs in PROJECT_ID and Q's
ID occurs in PROJECT_GROUP_ID. This includes projects and their
subprojects, and project groupings (such as categories and project
groups) and the projects associated with them.

<h2>Informal definition</h2>

<p>The rest of this document is a more reader-friendly explanation of
the permission system definition, using examples from a sample
Helm installation.

<h3>Example Installation</h3>

<p>The following diagrams describe the project and user layout for an
example installation with, in addition to the system projects, project
groups, and user groups, the following: three project groups, four
categories, five public projects, and four private projects,

<h4>Project structure</h4>

<pre>
                          Host
                          |
                          Domain
                          |
 +---+----+------+------+------+------+----+----+----+
 |   |    |      |      |      |      |    |    |    |
 www look Group1 Group3 Cat1   Cat4   Pub1 Prv2 Pub5 Prv3
          |      |      |      |      |    |
          +-Pub2 +-Pub1 +-Pub1 +-Prv2 Pub2 Pub4
          |      +-Cat3 +-Prv1        |
          Group2 +-Prv2 |             Prv1
          |             Cat2          |
          +-Pub1        |             Pub3
          +-Cat1        +-Pub3
          +-Prv1        |
                        Cat3
                        |
                        +-Pub5

Legend:
-------
Group#: A project group.
Cat#: A [public] category
Pub#: A public project
Prv#: A private project

</pre>

<p>www, look, Domain, and Host are all private. Project groups may
only be private. All categories in this example are public, though
categories can be private.

<h4>User structure</h4>

<pre>
Host users  Domain users  UserGroup1  alice  bob  carol
|           |             |
+-root      +-alice       +-alice
            +-bob         +-carol
            +-carol
</pre>

<h3>Actions</h3>

<p>Every nontrivial thing you could possibly do to a Helm system or
the associated development tools is captured in one or more
actions. There are about 100 actions, catalogued in the <a
href="http://helm.tigris.org/docs/actions.html">Helm Actions
document</a> (http://helm.tigris.org/docs/actions.html).

<p>Actions are stored in the HELM_ACTION table. 

<h3>Resources</h3>

<p>Most actions are an all-or-nothing affair; a role either has a
given action or does not. However, the "VersionControl" family of
actions and the "Project Page - View" action may be granted on a
portion of the relevant filespace rather than the project's entire CVS
tree or web space. These portions are represented as
resources. Resources are stored in the HELM_RESOURCE table. A resource
consists of a description and a regular expression. When permission
checks happen on files, the name of the file is compared against the
resource and succeeds or fails depending on the regular expression
match.

<p>For instance, a role with "VersionControl - Update" on
"/src/java/.*" allows someone with that role to do <tt>cvs up</tt> or
<tt>cvs co</tt> only on files matching "/src/java/.*". A role with
"Project Page - View" on "*Spec*\.html" can view only those documents
in the project webspace which match "*Spec*\.html". You get the idea.

<p>A resource can be defined locally within a project. If you have the
"Resource - Add" action in a project, you can create a resource with
visibility limited to that project and its subprojects.

<h3>Roles</h3>

<p>A role consists of a name, a description, some attribute settings,
and set of mappings between actions and resources. Actions which do
not make use of resources are automatically associated with the ".*"
resource. Roles are stored in the HELM_ROLE table; their
action-resource mappings are stored in HELM_ROLE_ACTION_RESOURCE; and
their attributes are stored in HELM_ATTRIBUTE_VALUE.

<p>A role, like a resource, can be defined locally within with a
project. If you have "Role - Add" in a project, you can create a role
specifically for that project. Your project-specific role can assign
actions to resources created specifically for your project.  This
gives you extremely fine-grained control over your CVS repository and
web space.

<h3>Role Assignments</h3>

<p>Role assignments are kept in the HELM_USER_ROLE_PROJECT table. A
role assignment maps a USER_ID from HELM_USER, a ROLE_ID from
HELM_ROLE, and a PROJECT_ID from HELM_PROJECT, and an APPROVED_BY
field (another USER_ID). APPROVED_BY may be the special "*Nobody"
user, in which case the role is pending (eg. having been requested but
not approved) and the user does not get any permissions from it.

<h3>User Role Recursion</h3>

<p>The USER_ID in HELM_USER_ROLE_PROJECT may refer to an individual
user, or it may refer to a user group. User groups are managed from
the UserGroupList servlet using the UserGroup family of actions. User
group memberships are kept in the HELM_USER_USERGROUP table, which
maps the user IDs of users to the user IDs of the groups they
inhabit. 

<p>User groups transfer roles recursively. If a user group has an
entry in HELM_USER_ROLE_PROJECT, then for permssions purposes every
user in that user group is treated as though they had an equivalent
entry in HELM_USER_ROLE_PROJECT. User groups cannot currently be
members of other user groups, so the recursion always bottoms out
after one iteration.

<p><b>Examples:</b> If you give the Project Owner role in Pub5 to the
UserGroup1 group, that is the same, permissions-wise, as giving it
individually to both alice and carol.

<p>The Domain Users user group is granted the Registered User role in
Domain. This means that alice, bob, and carol all effectively have
the Registered User role in Domain.


<h3>Project Role Recursion</h3>

<p>A similar, but more complicated, situation prevails with the
PROJECT_ID field in HELM_USER_ROLE_PROJECT. The PROJECT_ID may be a
reference to any project in the project tree, and in general roles
will recurse downward. If you have a role in project P, and a mapping
in HELM_PROJECT_PROJECTGROUP indicates that Q is a child of P, then
for permission purposes you have the same role in project Q. This rule
is applied recursively to arbitrary depth, with the following
exceptions:

<ul>

<li>If P is a category but Q is not (P being just a regular project
categorized under Q), then having a role in P does not give you the
same role in Q. Being in charge of mantaining a category is not the
same as being in charge of the projects within that category. Also,
since it is easy to put a project into a category you control,
allowing roles to recurse from categories to non-categories would let
anyone in charge of a category to gain permissions on any other
project they could view.

<li>If Q is private, and the role you have in P has the
"blockRecursionIntoPrivateProjects" attribute set, then you do not get
the role in Q. This holds regardless of whether or not P is private.

</ul>

<p><b>Examples:</b> <p>Suppose alice has the Developer role in
Cat1. This gives her the Developer role in Cat2 (a subcategory of
Cat1) and in Cat3 (a subcategory of Cat2, and therefore of Cat1). It
does not give her the Developer role in Pub1, Prv1, Pub3, or Pub5,
since roles do not recurse from categories to non-categories.

<p>Suppose bob has the Project Owner role in Group1. This gives him
the Project Owner role in Group2 (a subgroup of Group1), Pub2 (a
member of Group1), Pub1, Cat1, and Prv1 (members of Group1), Cat2 and
Cat3 (subcategories of Cat1). bob gets Project Owner in Group2 and
Prv1 because the Project Owner role does not have the
"blockRecursionIntoPrivate" attribute. Note that although bob gets
Project Owner in Cat1 and its subcategories, he does not get Project
Owner in any of the non-category projects in Cat1.

<p>As mentioned previously, the Domain Users user group has Registered
User in Domain. Registered User has the
"blockRecursionIntoPrivateProjects" attribute, so the Registered User
assignment is only valid in the public subprojects of Domain. Every
user in Domain Users effectively has Registered User only in Cat1,
Cat2, Cat3, Cat4, Pub1, Pub2 (a public subproject of Pub1), and
Pub3. These users do not have Registered User in Pub3 because it Pub3,
though public, is a subproject of a private project. Pub3 is a member
of the Cat2 category, but roles do not recurse from categories to
non-categories.  Domain Users, therefore, do not get Registered User
in Pub3.

<h3>Other Complications</h3>

<p>If you try to exercise an action in a locked project, and the
action has its AFFECTED_BY_PROJECT_LOCK field set to true, then the
action will not go through, even if it would otherwise succeed. This
is to prevent any action from succeeding on a locked project if it
might change the project's state (so actions like "Project - Edit",
"VersionControl - Add", and "News Item - Add" are all disabled when a
project is locked, and not even root can make them go through on a
locked project). The "Project - Lock" action, which also governs
unlocking, is of course not affected by project lock.

</body>
</html>@


1.6
log
@Corrected capitalization.
@
text
@d12 1
a12 1
<small>$Id: permissions.html,v 1.5 2001/07/18 21:27:43 leonardr Exp $</small>
d160 5
a164 5
project. If you have "Project Role - Add" in a project, you can create
a role specifically for that project. Your project-specific role can
assign actions to resources created specifically for your project.
This gives you extremely fine-grained control over your CVS repository
and web space.
@


1.5
log
@Moved example system to informal definition.
@
text
@d12 1
a12 1
<small>$Id: permissions.html,v 1.4 2001/07/18 21:24:59 leonardr Exp $</small>
d25 1
a25 1
role R in project P and R has A on a resource matching O, and either p
@


1.4
log
@Moved informal definition to its own subsection.
@
text
@d12 1
a12 1
<small>$Id: permissions.html,v 1.3 2001/07/18 21:23:32 leonardr Exp $</small>
d22 44
a65 1
<h2>Example System</h2>
d72 1
a72 1
<h3>Project structure</h3>
d107 1
a107 1
<h3>User structure</h3>
a115 39

<h2>Formal Definition</h3>

<p>User U can perform action A on an object O in project P iff U has
role R in project P and R has A on a resource matching O, and either p
is not locked or A is not affected by project locking.

<p>A resource R matches an object O iff the name of O matches the
regular expression associated with R, 'name' being defined on a
per-object-type basis.

<p>User U has a role R in project P iff U has a direct or derived role
in P, or belongs to a user group G with a direct or derived role in P.

<p>User U has a direct role in project P iff an approved mapping
exists in HELM_USER_ROLE_PROJECT between U's user ID and P's project
ID. A mapping is approved iff its APPROVED_BY field is the user ID of
a user besides the special *Nobody user.

<p>User U has a derived role R in project P iff U has a role in a
project Q, where P is a member of Q and the following conditions are
met:

<ul>

<li>It is not the case that Q is a category but P is not.

<li>It is not the case that P is private and R has the
  "blockRecursionIntoPrivateProjects" attribute set.

</ul>

<p>Project P is a member of project Q iff there is a mapping in
HELM_PROJECT_PROJECTGROUP in which P's ID occurs in PROJECT_ID and Q's
ID occurs in PROJECT_GROUP_ID. This includes projects and their
subprojects, and project groupings (such as categories and project
groups) and the projects associated with them.

<h2>Informal definition</h2>
@


1.3
log
@Added formal definition and examples.
@
text
@d12 1
a12 1
<small>$Id: pagination-HOWTO.html,v 1.9 2001/03/26 19:45:11 dlr Exp $</small>
d111 3
a113 1
<h2>Actions</h2>
d123 1
a123 1
<h2>Resources</h2>
d146 1
a146 1
<h2>Roles</h2>
d162 1
a162 1
<h2>Role Assignments</h2>
d171 1
a171 1
<h2>User Role Recursion</h2>
d196 1
a196 1
<h2>Project Role Recursion</h2>
d251 1
a251 1
<h2>Other Complications</h2>
@


1.2
log
@Doh, I committed entirely the wrong document.
@
text
@d1 14
a14 1
Helm Permission System
d18 3
a20 1
<p>TODO: Put overview here.
d24 49
a72 4
<p>TODO: Construct diagram showing a sample Helm project tree for use
in demonstrating role recursion.

<p>TODO: Also construct example roles and user/user group mappings?
d74 1
a74 1
<h2>Formal definition</h3>
d106 2
a107 2
HELM_PROJECT_PROJECTGROUP in which P's ID occurs in PROJECT_ID and q's
id occurs in PROJECT_GROUP_ID. This includes projects and their
d185 9
d222 27
d261 2
@


1.1
log
@New document: Helm permission system overview.
@
text
@d1 1
a1 2
<h1>Field Guide to the Helm Permissioning System</h1>
<h3>By Leonard Richardson</h3>
d3 161
a163 1
<h2>Groups</h2>
a164 53
<p>First, you should understand groups. There are two types of groups:
user groups and project groups. They are represented in the database
as users and projects--project groups can have CVS and issue tracking
just like regular projects (however, user groups may not log in as
regular users). In addition, user groups may contain users, and
project groups may contain projects. Groups may not contain groups
(except in one special case).

<p>Categories are a type of project group. A particular project may
belong to multiple categories, and of course one category may contain
many projects. So it is with project groups in general, and user
groups.

<p>Project and user groups are managed from a suite of servlets, the
entry point to which is {Project,User}GroupList. As a domain or host
admin, you can manage groups by following the appropriate "Administer
{Project,User} Groups" link from your start page.


<h2>Roles and their assignment</h2>

A role is a set of permissions (what exactly constitutes a permission
is described below). Roles are defined ahead of time (though they can
be changed on the fly) and assigned to users in projects. The role
system is designed to reflect the semantics of what we say when we
talk about our association with projects: "I am a developer on Helm."
is reflected by the fact that I have the Developer role in the Helm
project.

Remember that user groups and projects are, for most intents and
purposes, treated as users and projects, respectively. You can give a
role in a project to an entire group of users

Note that there is a terminology problem here. Projects are said to be
members of a project group if they are associated with that
group. This is "membership" in the sense of set membership. Similarily
with users in user groups. Users cannot be members of project groups
in this sense, nor projects members of user groups. However, it's
common for users to be described as being "members" of a project or
project group if they have a role in that project or project
group. (In fact, the servlet which shows which users have a role in a
given project is called ProjectMembers). This is "membership" in the
sense of organizational membership. One of these usages of the term
"membership" has got to go.

<h2>Actions and extents</h2>

<p>An action is an English description of some activity which might be
performed on a Helm installation. Examples of actions are "Project -
Delete", "Mailing List - List", and "User - Add". In general, the name
of an action consists of the object to which it applies
(eg. "Project"), and the sort of code it enables to be run against a
given instance of that object 
@

