Changeset 3298


Ignore:
Timestamp:
May 7, 2007, 2:50:08 PM (14 years ago)
Author:
Nicklas Nordborg
Message:

References #526: Write "Projects and the permission system"

Now ready for reading.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/userdoc/project_permission.xml

    r3246 r3298  
    3030  <?dbhtml dir="project_permission"?>
    3131  <title>Projects and the permission system</title>
    32     <sect1 id="project_permission.introduction">
    33       <title>Introduction</title>
     32    <sect1 id="project_permission.permissions">
     33      <title>The permission system</title>
    3434      <para>
    3535        BASE is a multi-user environment that supports cooperation
    3636        between users while protecting all data against unauthorized
    3737        access or modification. To make this possible an elaborate
    38         permission system has been developed that allows users to
     38        permission system has been developed that allows a user to
    3939        specify exactly the permission to give to other users and at the
    4040        same time makes it easy to handle the permissions of multiple
     
    4545     
    4646      <important>
    47         Always use a project! By collecting items in a project the life
     47        <title>Always use a project!</title>
     48        By collecting items in a project the life
    4849        will be a lot easier when you want to share your data with others.
    4950        This is because you can always treat all items in a project as one
     
    5152      </important> 
    5253       
    53       <sect2 id="project_permission.introduction.levels">
     54      <sect2 id="project_permission.permissions.levels">
    5455        <title>Permission levels</title>
    5556       
     
    6465            <term>Read</term>
    6566            <listitem>
     67              <para>
    6668              Permission to read information about the item, such
    6769              as the name and description.
     70              </para>
    6871            </listitem>
    6972          </varlistentry>
     
    7275            <term>Use</term>
    7376            <listitem>
     77              <para>
    7478              Permission to use the information. In most cases this
    7579              means linking with other items. For example, if you have permission
     
    7781              protocol when creating an extract from a sample. In the case of plugins,
    7882              you need this permission to be able to execute them.
     83              </para>
    7984            </listitem>
    8085          </varlistentry>
     
    8287          <varlistentry>
    8388            <term>Write</term>
    84             <listitem>Permission to change information about the item.</listitem>
     89            <listitem>
     90              <para>
     91              Permission to change information about the item.
     92              </para>
     93            </listitem>
    8594          </varlistentry>
    8695
    8796          <varlistentry>
    8897            <term>Delete</term>
    89             <listitem>Permission to delete the item.</listitem>
     98            <listitem>
     99              <para>
     100              Permission to delete the item.
     101              </para>
     102            </listitem>
    90103          </varlistentry>
    91104
     
    93106            <term>Change owner</term>
    94107            <listitem>
     108              <para>
    95109              Permission to change the owner of an item. This is implemented
    96               as a <guilabel>Take ownership</guilabel> function in the web
    97               client, where you can take the ownership of an item that you
    98               don't already own.
     110              as a <link linkend="webclient.items.takeownership">Take ownership</link>
     111              function in the web client, where you can take the ownership of 
     112              items that you don't already own.
     113              </para>
    99114            </listitem>
    100115          </varlistentry>
     
    102117          <varlistentry>
    103118            <term>Change permissions</term>
    104             <listitem>Permission to change the permissions.</listitem>
     119            <listitem>
     120              <para>
     121              Permission to change the permissions.
     122              </para>
     123            </listitem>
    105124          </varlistentry>
    106125         
     
    108127            <term>Create</term>
    109128            <listitem>
    110               Permission to create new items. This permission is only be used
    111               for roles.
     129              <para>
     130              Permission to create new items. This permission can only be
     131              given to roles.
     132              </para>
    112133            </listitem>
    113134          </varlistentry>
     
    115136            <term>Deny</term>
    116137            <listitem>
    117               Deny all access to the item. This permission is only be used
    118               for roles.
     138              <para>
     139              Deny all access to the item. This permission can only be given
     140              to roles.
     141              </para>
    119142            </listitem>
    120143          </varlistentry>
     
    124147      </sect2>
    125148     
    126       <sect2 id="project_permission.introduction.checks">
     149      <sect2 id="project_permission.permissions.checks">
    127150        <title>How access permissions are checked</title>
    128151     
     
    130153          There are several ways that permission to access an item can
    131154          be granted to you. The list below is a description of how the
    132           permission checks are implemented in the core.
     155          permission checks are implemented in the BASE core:
    133156        </para>
    134157       
    135158        <orderedlist>
    136159          <listitem>
     160            <para>
    137161            Check if you are the root user. The root user has full
    138162            permission to everything and the permission check stops here.
    139           </listitem>
    140          
    141           <listitem>
    142             If you are a member of a role that gives you access to the
     163            </para>
     164          </listitem>
     165         
     166          <listitem>
     167            <para>
     168            Check if you are a member of a role that gives you access to the
    143169            item. Role-based permissions can only be specified based on
    144170            generic item types and is valid for all items of that type.
     
    146172            that can prevent a user from accessing any item. In that case,
    147173            the permission check stops here.
    148           </listitem>
    149          
    150           <listitem>
    151             If you are the owner of the item. As the owner you have full
     174            </para>
     175          </listitem>
     176         
     177          <listitem>
     178            <para>
     179            Check if you are the owner of the item. As the owner you have full
    152180            permission to the item and the permission check stops here.
    153           </listitem>
    154          
    155           <listitem>
    156             If you have been granted access to the item by the sharing system.
     181            </para>
     182          </listitem>
     183         
     184          <listitem>
     185            <para>
     186            Check if you have been granted access to the item by the sharing system.
    157187            The sharing system can grant access to individual users, groups of
    158188            users and to projects. We recommend that you always use projects
    159189            to share your items.
     190            </para>
    160191          </listitem>
    161192         
     
    168199            <itemizedlist>
    169200              <listitem>
     201                <para>
    170202                News: You always have read access to news if today's date
    171203                falls between the start and end date of the news item.
     204                </para>
    172205              </listitem>
    173206           
    174207              <listitem>
     208                <para>
    175209                Groups: You have read access to all groups where you
    176210                are a member.
     211                </para>
    177212              </listitem>
    178213           
    179214              <listitem>
     215                <para>
    180216                Users: You have read permission to all users that are members
    181217                of at least one group where you also are a member. When a project
    182218                is active, you also have read permission to all users of
    183219                that project.
     220                </para>
    184221              </listitem>
    185222           
     
    195232        </orderedlist>
    196233      </sect2>
     234     
     235      <sect2 id="project_permission.permissions.plugins">
     236        <title>Plugin permissions</title>
     237       
     238        <para>
     239          Another aspect of the permission system is that plugins
     240          may also have permissions on their own. The default is that
     241          plugins run with the same permissions as the user that invoked
     242          the plugin has. Sometimes this can be seen as a security risk
     243          if the plugin is not trusted. A malicious plugin can, for example,
     244          delete the entire database if invoked by the root user.
     245        </para>
     246       
     247        <para>
     248          An administrator can choose to give a plugin only those
     249          permissions that is required to complete it's task. If the plugin
     250          permission system is enabled for a plugin the default is to deny
     251          all actions. Then, the administrator can give the plugin the same
     252          permissions as listed above. There is one additional twist to
     253          the plugin permission system. A permission can be granted regardless
     254          of if the user that invoked the plugin had the permission or not, or
     255          a permission can be granted only if the user also has the permission.
     256          The first case makes it possible to develop a plugin that allows
     257          users to do things that they normally don't have permission to do.
     258          The seconds case is the same as not using the plugin permission system,
     259          except that unspecified permissions are always denied when the
     260          plugin permission system is used.
     261        </para>
     262       
     263        <note>
     264          Plugin developers can supply information about
     265          the wanted permissions making it easy for the administrator to
     266          just check the permissions and accept them with just a single
     267          click if they make sense.
     268        </note>
     269       
     270        <para>
     271          See also TODO - link to chapter about plugins that is not yet written.
     272        </para>
     273       
     274      </sect2>
     275     
    197276    </sect1>
    198277   
     
    208287      <itemizedlist>
    209288        <listitem>
     289          <para>
    210290          They don't require an administrator to setup and
    211291          use. All regular users may create a project, add items
    212292          to it and share it with other users. You are in complete
    213           control of who gets access to it and which permission levels
    214           to use.
     293          control of who gets access to the project, the items it contains
     294          and which permission levels to use.
     295          </para>
    215296        </listitem>
    216297       
    217298        <listitem>
     299          <para>
    218300          All items in a project are treated as one collection. If a
    219301          new member joins the team, just give the new person access
    220302          to the project and that person will be able to access all
    221303          items in the project.
     304          </para>
    222305        </listitem>
    223306     
    224307        <listitem>
    225           Items are automatically added to the active project so
     308          <para>
     309          When you create new items, they are automatically added to the active
     310          project so
    226311          there is almost no need to share items manually. All
    227312          you have to remember is to set an active project, and
    228313          this is easy accessible from the
    229314          <link linkend="webclient.intro.menubar">menu bar</link>.
     315          </para>
    230316        </listitem>
    231317       
    232318        <listitem>
     319          <para>
    233320          Filter out items that you don't want to see. When you have set
    234321          an active project you may choose to only see items that are
    235322          part of that project and no other items
    236323          (<xref linkend="webclient.itemlist.presets"/>).
     324          </para>
    237325        </listitem>
    238326       
    239327        <listitem>
     328          <para>
    240329          It's easy to share multiple items between projects. Items
    241330          may be part of more than one project. If you create a new
     
    243332          some or all of the existing items to the new project from one
    244333          central place, the <guilabel>Items</guilabel> tab on the project's
    245           view page.
     334          single-item view.
     335          </para>
    246336        </listitem>
    247337     
     
    275365     
    276366        <sect3 id="project_permission.projects.active.set">
    277           <title>Setting the active project</title>
     367          <title>Selecting an active project</title>
    278368         
    279369          <para>
    280370            Since it important to always have an active project
    281             there are several ways to make a project to become
     371            there are several ways to make a project
    282372            the active one.
    283373          </para>
     
    285375          <itemizedlist>
    286376            <listitem>
     377              <para>
    287378              The easiest way and the one you will probably
    288379              use most of the time is to use the
    289380              <link linkend="webclient.intro.menubar">menu bar</link> shortcut.
    290               Look in the menu for the project icon (<inlinemediaobject>
     381              Look in the menu for the project icon (<guiicon><inlinemediaobject>
    291382              <imageobject><imagedata fileref="figures/project.gif" format="GIF" /></imageobject>
    292               </inlinemediaobject>). Next to it, the name of the active project
     383              </inlinemediaobject></guiicon>). Next to it, the name of the active project
    293384              is displayed. If you see <guilabel>- none -</guilabel> here, it
    294385              means that no project is active. Click on the icon or project name
     
    296387              project. If another project is already active it will automatically
    297388              be unactivated.
    298             </listitem>
    299          
    300             <listitem>
     389              </para>
     390            </listitem>
     391         
     392            <listitem>
     393              <para>
    301394              Use the <menuchoice><guimenu>File</guimenu>
    302395              <guisubmenu>Select project</guisubmenu></menuchoice>
    303396              menu and select the project from the submenu that opens
    304397              up.
    305             </listitem>
    306            
    307             <listitem>
     398              </para>
     399            </listitem>
     400           
     401            <listitem>
     402              <para>
    308403              Go to the <link linkend="webclient.intro.homepage">homepage</link>
    309404              using the <menuchoice><guimenu>View</guimenu>
    310405              <guisubmenu>Home</guisubmenu></menuchoice> menu and select
    311406              a project from the list displayed there.
     407              </para>
    312408            </listitem>
    313409          </itemizedlist>
     
    340436        <orderedlist>
    341437          <listitem>
    342             Navigate to the single-item view page of your project
     438            <para>
     439            Navigate to the single-item view of your project
    343440            from the <menuchoice><guimenu>View</guimenu>
    344441            <guisubmenu>Projects</guisubmenu></menuchoice> list.
    345           </listitem>
    346          
    347           <listitem>
     442            </para>
     443          </listitem>
     444         
     445          <listitem>
     446            <para>
    348447            Click on the <guibutton>Edit&hellip;</guibutton>
    349448            button to open the <guilabel>Edit project</guilabel>
    350449            dialog.
    351           </listitem>
    352          
    353           <listitem>
     450            </para>
     451          </listitem>
     452         
     453          <listitem>
     454            <para>
    354455            Switch to the <guilabel>Members tab</guilabel>. From this
    355456            page you can add and remove users and change the access levels
    356457            of existing ones.
     458            </para>
    357459          </listitem>
    358460        </orderedlist>
     
    434536                button. Unless you are an administrator, the popup window
    435537                will only list users that are members of at least one of the
    436                 groups where you also are a memberm. It will not list users that
     538                groups where you also are a member. It will not list users that
    437539                are already part of the project.
    438540                </para>
     
    447549                groups to the project. In the popup window, mark
    448550                one or more groups and click on the <guibutton>Ok</guibutton>
    449                 button. Groups that are already part of the project
    450                 are not displayed in the popup window. Unless you are
     551                button. Unless you are
    451552                an administrator, the popup window will only list groups
    452553                that you are a member of. It will not list groups that
     
    471572            Use the <guibutton>Save</guibutton> button to save your
    472573            changes or the <guibutton>Cancel</guibutton> button to
    473             clost the popup without saving.
     574            close the popup without saving.
    474575          </para>
    475576        </helptext>
     
    481582       
    482583        <para>
    483         TODO
    484         </para>
     584        If you go to the single-item view for a project you will find
     585        that there is an extra tab, <guilabel>Items</guilabel>, on that
     586        page. Clicking on that tab will display a page that is similar
     587        to a list view. However there are some differences:
     588        </para>
     589       
     590        <itemizedlist>
     591          <listitem>
     592            <para>
     593            The list is not limited to one type of item. It can display
     594            all items that are part of the project.
     595            </para>
     596          </listitem>
     597         
     598          <listitem>
     599            <para>
     600              It support only a limited set of columns (name, description and
     601              owner) since theese are the only properties that are commom
     602              among all items.
     603            </para>
     604          </listitem>
     605         
     606          <listitem>
     607            <para>
     608              The list can't be filtered (except by item type)
     609              or sorted. This is due to a limitation in the query system
     610              used to generate the list.
     611            </para>
     612          </listitem>
     613        </itemizedlist>
     614       
     615        <note>
     616          The list only works for the active project. For all other
     617          projects it will only display items that are owned by the
     618          logged in user.
     619        </note>
     620       
     621        <para>
     622          There are also several similarities:
     623        </para>
     624       
     625        <itemizedlist>
     626          <listitem>
     627            <para>
     628              It supports all of the regular multi-item
     629              operations such as delete, restore, share
     630              and take ownership.
     631            </para>
     632          </listitem>
     633         
     634          <listitem>
     635            <para>
     636              Clicking on the name of the item will take you to the
     637              single-item view of that item. Holding down <keycap>CTRL</keycap>,
     638              <keycap>ALT</keycap> or <keycap>SHIFT</keycap> while clicking,
     639              will open the edit popup.
     640            </para>
     641          </listitem>
     642        </itemizedlist>
     643       
     644        <tip>
     645          <para>
     646          This list is very useful when you are creating a
     647          new project, in which you want to reuse items from
     648          an old project.
     649          </para>
     650         
     651          <itemizedlist>
     652            <listitem>
     653              <para>
     654              Activate the old project and go to this view.
     655              </para>
     656            </listitem>
     657           
     658            <listitem>
     659              <para>
     660                Mark the checkbox for all items that you want to
     661                use in the new project.
     662              </para>
     663            </listitem>
     664           
     665            <listitem>
     666              <para>
     667                Click on the <guibutton>Share&hellip;</guibutton> button
     668                and share the items to the new project.
     669              </para>
     670            </listitem>
     671          </itemizedlist>
     672          <para>
     673            If you have more than one old project, repeat the
     674            above procedure.
     675          </para>
     676        </tip>
    485677       
    486678      </sect2>
Note: See TracChangeset for help on using the changeset viewer.