source: trunk/doc/src/docbook/userdoc/project_permission.xml @ 5705

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: project_permission.xml 5705 2011-08-22 12:21:49Z nicklas $

  Copyright (C) 2007 Jari Häkkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson

  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/

  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 3
  of the License, or (at your option) any later version.

  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with BASE. If not, see <http://www.gnu.org/licenses/>.
-->

<chapter id="project_permission">
  <?dbhtml dir="project_permission"?>
  <title>Projects and the permission system</title>
    <sect1 id="project_permission.permissions">
      <title>The permission system</title>
      <para>
        BASE is a multi-user environment that supports cooperation
        between users while protecting all data against unauthorized
        access or modification. To make this possible an elaborate 
        permission system has been developed that allows an user to
        specify exactly the permission to give to other users and at the
        same time makes it easy to handle the permissions of multiple
        items with just a few interactions. For this to work smoothly there 
        are a few recommendations that all users should follow. The first
        and most important recommendation is:
      </para>
      
      <important>
        <title>Always use a project!</title>
        By collecting items in a project the life
        will be a lot easier when you want to share your data with others.
        This is because you can always treat all items in a project as one 
        collection and grant or revoke access to the project as a whole.
      </important>  
        
      <sect2 id="project_permission.permissions.levels">
        <title>Permission levels</title>
        
        <para>
          Whenever you try to create or access existing items in BASE the core will
          check that you have the proper permission to do so. There
          are several permission levels:
        </para>
        
        <variablelist>
          <varlistentry>
            <term>Read</term>
            <listitem>
              <para>
              Permission to read information about the item, such
              as the name and description.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>Use</term>
            <listitem>
              <para>
              Permission to use the information. In most cases this
              means linking with other items. For example, if you have permission
              to use a protocol you may specify that protocol as the extraction
              protocol when creating an extract from a sample. In the case of plug-ins,
              you need this permission to be able to execute them. 
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>Write</term>
            <listitem>
              <para>
              Permission to change information about the item.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Delete</term>
            <listitem>
              <para>
              Permission to delete the item.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Change owner</term>
            <listitem>
              <para>
                Permission to change the owner of an item. This is implemented as a
                <guilabel>Set owner</guilabel> function in the web client
                (<xref linkend="webclient.items.changeowner" />), where you can 
                change the owner of items that you have permission to do so on.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Change permissions</term>
            <listitem>
              <para>
              Permission to change the permissions on the item.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>Create</term>
            <listitem>
              <para>
              Permission to create new items. This permission can only be 
              given to roles.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Deny</term>
            <listitem>
              <para>
              Deny all access to the item. This permission can only be given 
              to roles.
              </para>
            </listitem>
          </varlistentry>
      
        </variablelist>
        <note>
          A user's permissions need to be reloaded for the permissions that have been
          changed should take effect. This is done either manually with the menu choice
          <menuchoice>
            <guimenu>BASE</guimenu>
            <guimenuitem>Reload permissions</guimenuitem>
          </menuchoice>
          or automatically next time the user logs in to BASE.
        </note>

      </sect2>
      
      <sect2 id="project_permission.permissions.checks">
        <title>Getting access to an item</title>
      
        <para>
          There are several ways that permission to access an item can
          be granted to you. The list below is a description of how the
          permission checks are implemented in the BASE core:
        </para>
        
        <orderedlist>
          <listitem>
            <para>
            Check if you are the root user. The root user has full 
            permission to everything and the permission check stops here.
            </para>
          </listitem>
          
          <listitem>
            <para>
            Check if you are a member of a role that gives you access to the
            item. Role-based permissions can only be specified based on
            generic item types and is valid for all items of that type.
            The role-based permissions also include a special deny permission
            that can prevents a user from accessing any item. In that case,
            the permission check stops here.
            </para>
          </listitem>
          
          <listitem>
            <para>
            Check if you are the owner of the item. As the owner you have full 
            permission to the item and the permission check stops here.
            </para>
          </listitem>
          
          <listitem>
            <para>
            Check if you have been granted access to the item by the
            sharing system (cf. <xref linkend="webclient.items.share"/>).
            The sharing system can grant access to individual users, groups of
            users and to projects. We recommend that you always use projects
            to share your items.
            </para>
          </listitem>
          
          <listitem>
            <para>
            Some items implement special permission checks. 
            For example:
            </para>
            
            <itemizedlist>
              <listitem>
                <para>
                News: You always have read access to news if today's date
                falls between the start and end date of the news item.
                </para>
              </listitem>
            
              <listitem>
                <para>
                Groups: You have read access to all groups where you
                are a member.
                </para>
              </listitem>
            
              <listitem>
                <para>
                Users: You have read permission to all users that share group
                membership with, excluding the <emphasis>Everyone</emphasis> group. 
                When a project is active, you also have read permission to all 
                users that are members of that project.
                </para>
              </listitem>
            
            </itemizedlist>
            
            <para>
              There are more items with special permission checks but
              we do not list those here.
            </para>
            
          </listitem>
          
        </orderedlist>
      </sect2>

      <sect2 id="project_permission.permissions.plugins">
        <title>Plug-in permissions</title>
        
        <para>
          Another aspect of the permission system is that plug-ins
          may also have permissions of their own. The default is that
          plug-ins run with the same permissions as the user that invoked
          the plug-in has. Sometimes this can be seen as a security risk
          if the plug-in is not trusted. A malicious plug-in can, for example,
          delete the entire database if invoked by the root user.
        </para>
        
        <para>
          An administrator can choose to give a plug-in only those
          permissions that is required to complete it's task. If the plug-in 
          permission system is enabled for a plug-in the default is to deny
          all actions. Then, the administrator can give the plug-in the same
          permissions as listed above. There is one additional twist to 
          the plug-in permission system. A permission can be granted regardless
          of if the user that invoked the plug-in had the permission or not, or
          a permission can be granted only if the user also has the permission.
          The first case makes it possible to develop a plug-in that allows
          users to do things that they normally do not have permission to do.
          The second case is the same as not using the plug-in permission system,
          except that unspecified permissions are always denied when the
          plug-in permission system is used.
        </para>
        
        <note>
          Plug-in developers can supply information about
          the wanted permissions making it easy for the administrator to 
          just check the permissions and accept them with just a single
          click if they make sense.
        </note>
        
        <para>
          See <xref linkend="plugins.permissions"/> for more information.
        </para>
        
      </sect2>
      
    </sect1>
    
    <sect1 id="project_permission.projects">
    
      <title>Projects</title>
      
      <para>
        Projects are an important part of the permission system for several
        reasons:
      </para>
      
      <itemizedlist>
        <listitem>
          <para>
          They do not require an administrator to setup and
          use. All regular users may create a project, add items 
          to it and share it with other users. You are in complete 
          control of who gets access to the project, the items it contains
          and which permission levels to use.
          </para>
        </listitem>
        
        <listitem>
          <para>
          All items in a project are treated as one collection. If a
          new member joins the team, just give the new person access
          to the project and that person will be able to access all
          items in the project.
          </para>
        </listitem>
      
        <listitem>
          <para>
          When you create new items, they are automatically shared
          using the settings from the active project. There is almost no 
          need to share items manually. All
          you have to remember is to set an active project, and
          this is easy accessible from the 
          <link linkend="webclient.intro.menubar">menu bar</link>.
          </para>
        </listitem>
        
        <listitem>
          <para>
          Filter out items that you do not want to see. When you have set
          an active project you may choose to only see items that are
          part of that project and no other items
          (<xref linkend="webclient.itemlist.presets"/>).
          </para>
        </listitem>
        
        <listitem>
          <para>
          It's easy to share multiple items between projects. Items
          may be part of more than one project. If you create a new
          project that builds on a previous one you can easily share
          some or all of the existing items to the new project from one
          central place, the <guilabel>Items</guilabel> tab on the project's
          single-item view.
          </para>
        </listitem>
      
      </itemizedlist>
      
    
      <sect2 id="project_permission.projects.active">
      
        <title>The active project</title>
        
        <para>
          The active project concept is central to the sharing system. 
          You should always, with few exceptions, have a project active 
          when you work with BASE. The most important reason is that 
          new items will automatically be shared using the settings in
          the active project. This considerably reduces 
          the time needed for managing access permissions. Without an 
          active project you would have to manually
          set the permission on all items you create. If you have hundreds
          of items this is a time-consuming and boring task best to be 
          avoided.
        </para>
        
        <para>
          If you work with multiple projects you will probably find the
          filtering function that hides items that are not part
          of the active project to be useful. As a matter of fact, if you
          try to access an item that is part of another (not active) project
          you will get an error message saying that you do not have 
          permission to access the item (unless you are the owner).
        </para>
      
        <sect3 id="project_permission.projects.active.set">
          <title>Selecting an active project</title>
          
          <para>
            Since it's important to always have an active project
            there are several ways to make a project  
            the active one.
          </para>
          
          <itemizedlist>
            <listitem>
              <para>
                The easiest way and the one you will probably use most of the time
                is to use the menu bar shortcut. Look in the menu for the project
                icon 
                (<guiicon>
                  <inlinemediaobject>
                    <imageobject>
                      <imagedata fileref="figures/project.gif" format="GIF" />
                    </imageobject>
                  </inlinemediaobject>
                </guiicon>). 
                Next to it, the name of the active project is displayed. If you see
                <guiicon>
                  <inlinemediaobject>
                    <imageobject>
                      <imagedata fileref="figures/no_active_project.gif" format="GIF" />
                    </imageobject>
                  </inlinemediaobject>
                </guiicon>
                <guilabel>- no active project -</guilabel>
                here, it means that you have not selected a project to work in. Click on the icon or
                project name to open a drop-down menu and select a project to set as
                the active project. If another project is already active it will
                automatically be inactivated.
              </para>
              <para>
                The most recently used projects are listed first, then the list is filled with the 
                rest of your projects up to a maximum of 15. If you have more projects an option to 
                display the remaining projects is activated.
              </para>
              <tip>
                <para>
                The sort order of the non-recent projects is the same as the sort order on the
                projects list page. If you, for example, want to sort the newest
                project first, select to sort by the <guilabel>Registered</guilabel> 
                column in descending order on the list page. The menu will automatically 
                use the same order.
                </para>
              </tip>
            </listitem>
          
            <listitem>
              <para>
              Use the <menuchoice><guimenu>BASE</guimenu>
              <guisubmenu>Select project</guisubmenu></menuchoice>
              menu and select the project from the submenu that opens
              up.
              </para>
            </listitem>
            
            <listitem>
              <para>
              Go to the <link linkend="webclient.intro.homepage">homepage</link>
              using the <menuchoice><guimenu>View</guimenu>
              <guisubmenu>Home</guisubmenu></menuchoice> menu and select
              a project from the list displayed there.
              </para>
            </listitem>
          </itemizedlist>
          
          <note>
            Only one project can be active at a time.
          </note>
          
          <warning>
            If you change the active project while viewing an item
            that you no longer has access to in the context of the
            new project an error message about missing permission
            will be displayed. Unfortunately, this is all that is displayed 
            and it may be difficult to navigate to a working page again.
            In the worst case, you may have to go to the login page and
            login again.
          </warning>
          
        </sect3>

        <sect3 id="project_permission.projects.active.autopermissions">
          <title>Default permissions for the active project</title>
          
          <para>
            When a project is active all new items you create are automatically
            shared using the settings from the active project. If the active project 
            has a permission template the permissions from the template are copied 
            to the new item. If the project doesn't have a permission template, the 
            new item is shared to the active project with the configured default
            level. By default, projects doesn't have a permission template
            and the default permissions are set to
            <emphasis>read</emphasis>, <emphasis>use</emphasis>, 
            <emphasis>write</emphasis> and <emphasis>delete</emphasis>. It is
            possible to change the default permission level by modifying the
            settings for the project. Simply open the edit-view page for the project
            and select the permissions you want and save. From now on, all new
            items will be shared with the specified permissions. Items that are
            already in the project are not affected by the change.
          </para>
        </sect3>

      </sect2>
        
      <sect2 id="project_permission.projects.share">
        <title>How to give other users access to your project</title>
        
        <para>
          First, you will need to open the <guilabel>Edit project</guilabel>
          dialog. Here is how to do that:
        </para>
        
        <orderedlist>
          <listitem>
            <para>
            Navigate to the single-item view of your project 
            from the <menuchoice><guimenu>View</guimenu>
            <guisubmenu>Projects</guisubmenu></menuchoice> list.
            </para>
          </listitem>
          
          <listitem>
            <para>
            Click on the &gbEdit;
            button to open the <guilabel>Edit project</guilabel>
            dialog.
            </para>
          </listitem>
          
          <listitem>
            <para>
            Switch to the <guilabel>Members tab</guilabel>. From this
            page you can add and remove users and change the access levels
            of existing ones.
            </para>
          </listitem>
        </orderedlist>
        
        <figure id="project_permission.projects.members">
          <title>Manage members of a project</title>
          <screenshot>
            <mediaobject>
              <imageobject><imagedata fileref="figures/project_members.png" format="PNG" /></imageobject>
            </mediaobject>
          </screenshot>
        </figure>
        
        
        <helptext external_id="project.edit.members" title="Project members">
          
          <variablelist>
            <varlistentry>
              <term><guilabel>Members</guilabel></term>
              <listitem>
                <para>
                The members list contains users
                and groups that are already members of the project. The list 
                shows the name and the permission level. The permission level 
                uses a one-letter code as follows:
                </para>
                <itemizedlist>
                <listitem><guilabel>R</guilabel> = Read</listitem>
                <listitem><guilabel>U</guilabel> = Use</listitem>
                <listitem><guilabel>W</guilabel> = Write</listitem>
                <listitem><guilabel>D</guilabel> = Delete</listitem>
                <listitem><guilabel>O</guilabel> = Set owner</listitem>
                <listitem><guilabel>P</guilabel> = Set permission</listitem>
                </itemizedlist>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><guilabel>Permissions</guilabel></term>
              <listitem>
                <para>
                When you select an user or group in the
                list the current permission will be checked. To change the
                permissions just check the permissions you want to 
                grant or uncheck the permissions you want to revoke.
                You may select more than one user and/or group
                and change the permissions for all of them at once.
                </para>
                
                <note>
                In most cases, you should give the project members
                <emphasis>use</emphasis> permission. This will allow an user 
                to use all items in the project as well as add new items to it. 
                If you give them write or delete permission they will be able 
                to modify or delete all items including those that they do not 
                own.
                </note>
                
                <note>
                The above note is not always true since the permission to
                an item in the project also depends on the permission that
                was set when adding the item to the project. The default 
                permission is <emphasis>delete</emphasis> and the above note 
                holds true. If the item's permission is manually changed to for 
                example, <emphasis>use</emphasis>, no project member can get 
                higher permission to the item.
                </note>
                
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><guibutton>Add users</guibutton></term>
              <listitem>
                <para>
                Opens a popup window that allows you to add
                users to the project. In the popup window, mark
                one or more users and click on the &gbOk;
                button. The popup window will only list users that you have
                permission to read. Unless you are an administrator, this
                usually means that you can only see users that: 
                </para>
                <itemizedlist>
                  <listitem>
                    <para>
                    you share group memberships with 
                    (the <emphasis>Everyone</emphasis> group doesn't count)
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                    are members of the currently active project, if any.
                    </para>
                  </listitem>
                </itemizedlist>
                <para>
                Users that already have access to the project are not included in the
                list. If you don't see a user that you want to add to the project,
                you'll need to talk to an administrator for setting up the proper
                group membership.
                </para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><guibutton>Add groups</guibutton></term>
              <listitem>
                <para>
                Opens a popup window that allows you to add
                groups to the project. In the popup window, mark
                one or more groups and click on the &gbOk;
                button. Unless you are
                an administrator, the popup window will only list groups 
                that you are a member of. It will not list groups that 
                are already part of the project.
                </para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term>&gbRemove;</term>
              <listitem>
                <para>
                Click on this button to remove the selected
                users and/or groups from the project.
                </para>
              </listitem>   
            </varlistentry>
          </variablelist>
          
          
          <para>
            Use the &gbSave; button to save your
            changes or the &gbCancel; button to
            close the popup without saving.
          </para>
        </helptext>

      </sect2>
      
      <sect2 id="project_permission.projects.items">
        <title>Working with the items in the project</title>
        
        <para>
        If you go to the single-item view for a project you will find
        that there is an extra tab, <guilabel>Items</guilabel>, on that
        page. 
        <figure id="project_permission.images.projecttabs">
          <title/>
          <screenshot>
            <mediaobject>
              <imageobject><imagedata fileref="figures/project_tabs.png" format="PNG" /></imageobject>
            </mediaobject>
          </screenshot>
        </figure>
        Clicking on that tab will display a page that is similar
        to a list view. However there are some differences:
        </para>
        
        <itemizedlist>
          <listitem>
            <para>
            The list is not limited to one type of item. It can display
            all items that are part of the project.
            </para>
          </listitem>
          
          <listitem>
            <para>
              It support only a limited set of columns (id, name, description and
              owner) since these are the only properties that are common
              among all items.
            </para>
          </listitem>
          
          <listitem>
            <para>
              The list cannot be sorted. This is due to a limitation in the 
              query system used to generate the list.
            </para>
          </listitem>
        </itemizedlist>
        
        <note>
          The list only works for the active project. For all other
          projects it will only display items that are owned by the
          logged in user.
        </note>
        
        <para>
          There are also several similarities:
        </para>
        
        <itemizedlist>
          <listitem>
            <para>
              It supports all of the regular multi-item 
              operations such as delete, restore, share
              and change owner.
            </para>
          </listitem>
          
          <listitem>
            <para>
              Clicking on the name of the item will take you to the
              single-item view of that item. Holding down <keycap>CTRL</keycap>, 
              <keycap>ALT</keycap> or <keycap>SHIFT</keycap> while clicking,
              will open the edit popup.
            </para>
          </listitem>
        </itemizedlist>
        
        <tip>
          <para>
          This list is very useful when you are creating a
          new project, in which you want to reuse items from 
          an old project.
          </para>
          
          <itemizedlist>
            <listitem>
              <para>
              Activate the old project and go to this view.
              </para>
            </listitem>
            
            <listitem>
              <para>
                Mark the checkbox for all items that you want to
                use in the new project.
              </para>
            </listitem>
            
            <listitem>
              <para>
                Click on the &gbShare; button
                and share the items to the new project.
              </para>
            </listitem>
          </itemizedlist>
          <para>
            If you have more than one old project, repeat the
            above procedure.
          </para>
        </tip>
        
      </sect2>
    
    </sect1>
    
    <sect1 id="project_permission.templates">
      <title>Permission templates</title>
    
      <para>
        A <emphasis>permission template</emphasis> is a pre-defined set of permissions
        for users, groups and/or projects. The template makes it easy to quickly share
        items to multiple users, groups and projects, possible with different permissions
        for everyone. There are three major use-cases were permission templates are useful:
      </para>
      
      <itemizedlist>
        <listitem>
          <para>
          A permission template can be associated with project. When the project is selected
          as the active project, the permissions from the template are copied to any new items
          that are created. Note that the new items may or may not be shared with the active
          project, depending on the settings in the permission template. 
          </para>
        </listitem>
        <listitem>
          <para>
          Permission templates can be selected in the <link linkend="webclient.items.share">share dialog</link>, 
          making it easier to manually share items to multiple users, 
          groups and projects in just a few clicks.
          </para>
        </listitem>
        <listitem>
          <para>
          Permission templates can be used with some batch item importers, making it easier
          for administrators which only needs a single data file even if the data belong to
          different projects.
          </para>
        </listitem>
      </itemizedlist>
      
      <para>
        Permission templates are managed from the <menuchoice><guimenu>View</guimenu>
        <guisubmenu>Permission templates</guisubmenu></menuchoice> menu. The template is
        a very simple item that only has a name (required) and a description (optional).
        We recommend that the names of the templates are kept unique, but this is not
        enforced by BASE. To assign permissions to the template use the 
        <guibutton>Set permissions</guibutton> button. This is the same dialog as the 
        <link linkend="webclient.items.share">share dialog</link>.
      </para>
      
      <note>
        <title>Permissions are copied</title>
        <para>
        When a permission template is used the permissions are <emphasis>copied</emphasis>
        to the items. Modifications to the template that are made afterwards doesn't
        affect the permissions for the items on which the template was used.
        </para>
      </note>
    </sect1>
</chapter>