<?xml version="1.0"?>
<!--
Copyright 2004 The Apache Software Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<document>
  <properties>
    <title>Jetspeed PSML Authorization</title>
    <subtitle>Documentation for Jetspeed-2 PSML Authorization</subtitle>
    <authors>
      <person name="David Sean Taylor" email="taylor@apache.org"/>
    </authors>
  </properties>
  <body>
<section name="Security Constraints">
<p>
<ul>
	 <li><a href="#The Security Constraint">Security Constraint</a></li>	      
	 <li><a href="#Declarative and Global Constraints">Declarative and Global Constraints</a></li>	 
    <li><a href="#Folder Constraints">Folder Constraints</a></li>
    <li><a href="#Page Constraints">Page Constraints</a></li>    
    <li><a href="#Spring Configuration">Spring Configuration</a></li>    
    <li><a href="#Subsite Security">Subsite Security</a></li>        
</ul>
</p>
<p>
Security Constraints are applied to pages and folders.  Security Constraints either grant or deny 
access to pages and folders.  Constraints can be defined in one of three places:
<ul>
    <li>1. <b>Global:</b> As declarations in the <b><i>page.security</i></b> file found in the root of the PSML tree.</li>
    <li>2. <b>Folder:</b> In the <b><i>folder.metadata</i></b> file optionally located in every directory</li>    
    <li>3. <b>Page:</b> In PSML files to constraint access to specific pages</li>
</ul>
</p>
<subsection name='Grants'>
<p>
Grants are associated with permissions, authorizing, or granting, a principal list 
access to a page or folder.    
A granting security constraint is the association of a list of one 
or more security principals combined with one or permissions. Grant constraints grant access to a page or folder
for the associated list of permissions. 
</p>
</subsection>
<subsection name='Denies'>
<p>
A deny security constraint is declared 
with one or more security principals; with no associated permissions. Deny constraints prohibit access
to the page or folder for the given list of principals. Note that deny constraints
must be listed before grant constraints.
</p>
</subsection>
<subsection name='Declarative and Referential Constraints'>
<p>
When working with pages and folder resource constraints, a constraint can be either 
a <b><i>declarative constraint</i></b> or a <b><i>referential</i></b> constraint.
Declarative constraints are declared and put to use right in place for the particular
page or folder resource. Where as referential constraints refer to a constraint declared
in a centralized security constraint resource: the <b><i>page.security</i></b> file. Each
site or subsite can have one <b><i>page.security</i></b> resource for declaring constraints
to be referenced in any page or folder.
</p>
</subsection>
</section>
<section name='The Security Constraint'>
<p>
A security constraint is an XML element found in a PSML file, a folder metadata file, or inthe global security declarations.
A security constraint has one attribute: the name. A security constraint has the following elements:
</p>
<ul>
    <li>roles - a comma-separated list of one or more role principals or * for all roles</li>
    <li>groups - a comma-separated list of one or more group principals or * for all groups</li>
    <li>users - a comma-separated list of one or more user principals or * for all users</li>
    <li>owner - a single user principal</li>
    <li>permissions - a comma-separated list of one or permissions (view,edit,help)</li>
</ul>    
<p>
The first four elements (roles, groups, users, owner) all define the principals who will either have a permission granted or denied.
</p>
<subsection name='Permissions'>
<p>
Permissions are the portal modes that are granted by the security constraint. Note that permissions are only granted, not denied.
The <b><i>view</i></b> permission is similiar to the <b><i>read</i></b> permission found in operating systems.
The <b><i>edit</i></b> permission is similiar to the <b><i>write</i></b> permission found in operating systems.
The <b><i>help</i></b> permission is similiar to the <b><i>info</i></b> permission found in some portals.
</p>
</subsection>

<subsection name='Roles'>
<p>
Constraints can be granted to one or more role principals for a set of permissions on a given resource.
Roles are derived from the authorized users list of role principals, i.e. the roles that the user is a member of.
If the authorized user is a member of any of the listed roles, the permission to the resource will be granted.
</p>
<source><![CDATA[
    <security-constraint>
      <roles>adminstrator, manager</roles>    
      <permissions>view, edit</permissions>
    </security-constraint>
]]></source>
Constraints can also deny role principals access to the entire resource.
If the authorized user is a member of any of the listed roles, all access to the resource is denied.
<source><![CDATA[
    <security-constraint>
      <roles>adminstrator, manager</roles>    
    </security-constraint>
]]></source>
</subsection>
<subsection name='Groups'>
    <p>
Constraints can be granted to one or more group principals for a set of permissions on a given resource.
Groups are derived from the authorized users list of group principals, i.e. the groups that the user is a member of.
If the authorized user is a member of any of the listed groups, the permission to the resource will be granted.
<source><![CDATA[
    <security-constraint>
      <groups>accounting, development</groups>    
      <permissions>view</permissions>
    </security-constraint>
]]></source>
Constraints can also deny group principals access to the entire resource.
If the authorized user is a member of any of the listed groups, all access to the resource is denied.
<source><![CDATA[
    <security-constraint>
      <groups>accounting, development</groups>    
    </security-constraint>
]]></source>
</p>
</subsection>
<subsection name='Users'>
    <p>
Constraints can be granted to one or more user principals for a set of permissions on a given resource:
The current user must be one of the listed principals in the comma-separated list in order to grant permission to the resource.
<source><![CDATA[
    <security-constraint>
      <users>joey, deedee, johnny</users>    
      <permissions>view, edit, help</permissions>
    </security-constraint>
]]></source>
Constraints can also deny user principals access to the entire resource.
If the authorized user is in the list, all access to the resource is denied.
<source><![CDATA[
    <security-constraint>
      <users>fred</users>    
    </security-constraint>
]]></source>
</p>
</subsection>
<subsection name='Combinations'>
<p>
Note that you can grant or deny permissions to a collection of one or more principal types. For example, here we grant view and edit permissions
to the roles (manager, developer), and to the groups (QA and Research), and to the particular user (dilbert):
If the authorized user is a member of any of the listed roles, groups, or users, the permission to the resource will be granted.
</p>
<source><![CDATA[
    <security-constraint>
      <roles>hacker, coder, guru</roles>    
      <groups>unix, linux, freebsd</groups>
      <users>betty, fred, barney, wilma</users>      
      <permissions>view, edit</permissions>
    </security-constraint>
]]></source>
<p>
Constraints can also deny combinations of principals access to the entire resource.
If the authorized user is a member of any of the listed groups, roles or users, all access to the resource is denied.
</p>
<source><![CDATA[
    <security-constraint>
      <roles>hacker, coder, guru</roles>    
      <groups>unix, linux, freebsd</groups>
      <users>betty, fred, barney, wilma</users>      
    </security-constraint>
]]></source>
</subsection>
<subsection name='All *'>
<p>
The * can be applied to roles, groups, users or permissions to imply ALL.
<source><![CDATA[
    <security-constraint>
      <users>*</users>      
      <permissions>*</permissions>
    </security-constraint>
]]></source>
</p>
</subsection>
<subsection name='Owner'>
    <p>
    TODO
    </p>
</subsection>
</section>
<section name='Declarative and Global Constraints'>
<p>
Declarative constraints are declared in the <b><i>page.security</i></b> file of the root of a site or subsite.
Declarative constraints are referenced in pages and folders with the <b><i>security-constraints-ref</i></b> tag.
Global constraints are also declarative constraints. They are also defined and found in the <b><i>page.security</i></b> file in the root PSML repository.
The difference with global constraints is ...
Note that there can be more than one <b><i>page.security</i></b> files in a subsite Jetspeed installation.
</p>
<source><![CDATA[
  <security-constraints-def name="admin">
    <security-constraint>
      <roles>admin</roles>
      <permissions>view, edit</permissions>
    </security-constraint>
  </security-constraints-def>
  <global-security-constraints-ref>admin</global-security-constraints-ref>
]]></source>
<subsection name='Default Constraints'>
<p>
    Several security constraint declarations are made in the default deployment of Jetspeed:
<table>
    <tr>
        <th>name</th>
        <th>grants</th>
        <th>permissions</th>        
        <th>global</th>
    </tr>
    <tr>
        <td>admin</td>
        <td>roles: admin</td>
        <td>view, edit</td>        
        <td>yes</td>
    </tr>
    <tr>
        <td>manager</td>
        <td>roles: manager</td>
        <td>view</td>        
        <td>no</td>
    </tr>
    <tr>
        <td>users</td>
        <td>roles: user, manager</td>
        <td>view</td>        
        <td>no</td>        
    </tr>
    <tr>
        <td>public-view</td>
        <td>users: *</td>
        <td>view</td>        
        <td>no</td>        
    </tr>
    <tr>
        <td>public-edit</td>
        <td>users: *</td>
        <td>view, edit</td>        
        <td>no</td>        
    </tr>    
</table>    
</p>    
</subsection>
</section>
<section name='Folder Constraints'>
<p>
Folder Security constraints are placed in a <b><il>security-constraints list</il></b> in the <b><i>folder.metadata</i></b> file optionally found in each folder in the site.
Note that the absence of a <b><i>folder.metadata</i></b> or security constraints within that file means that the folder will
inherit the constraints of the parent folder, all the way up to the root folder of the site or subsite. Folder constraints do
not inherit across subsites. Folder security constraints are made up of declarative security constraints and referential security
constraints. Here is an example of both, the first being a referential constraint, the second a declarative constraint:
<source><![CDATA[
  <security-constraints>
    <security-constraints-ref>public-view</security-constraints-ref>
    <security-constraint>
      <groups>engineering</groups>
      <permissions>view</permissions>
    </security-constraint>    
  </security-constraints>
]]></source>
</p>
<p>
Note that all security constraints must be placed within a <b><i>security-constraints</i></b> collection.
</p>
</section>
<section name='Page Constraints'>
<p>
Page Security constraints are placed <b><il>security-constraints list</il></b> 
in <b><i>PSML</i></b> files and are optional.
Note that the absence of a  security constraints list within that file means that the folder will
inherit the constraints of the folder in which it resides.  Page security constraints are made up of 
declarative security constraints and referential security
constraints. Here is an example of both, the first being a referential constraint, the second a declarative constraint:
</p>
<source><![CDATA[
  <security-constraints>
    <security-constraints-ref>global-view</security-constraints-ref>
    <security-constraint>
      <groups>accounting</groups>
      <permissions>view, edit</permissions>
    </security-constraint>    
  </security-constraints>
]]></source>
<p>
Note that all security constraints must be placed within a <b><i>security-constraints</i></b> collection.
</p>
</section>
<section name="Spring Configuration">
<p>
TODO: page-manager.xml enabling
</p>
</section>
<section name="Subsite Security">
<p>
subsite security
</p>
</section>
</body>
</document>

