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

Last change on this file since 3791 was 3791, checked in by Martin Svensson, 15 years ago

Fixes #665 Links in the documentation

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 22.1 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: project_permission.xml 3791 2007-09-26 11:33:17Z martin $
7
8  Copyright (C) 2007 Jari Hakkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
9
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 2
16  of the License, or (at your option) any later version.
17
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22
23  You should have received a copy of the GNU General Public License
24  along with this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28
29<chapter id="project_permission">
30  <?dbhtml dir="project_permission"?>
31  <title>Projects and the permission system</title>
32    <sect1 id="project_permission.permissions">
33      <title>The permission system</title>
34      <para>
35        BASE is a multi-user environment that supports cooperation
36        between users while protecting all data against unauthorized
37        access or modification. To make this possible an elaborate
38        permission system has been developed that allows an user to
39        specify exactly the permission to give to other users and at the
40        same time makes it easy to handle the permissions of multiple
41        items with just a few interactions. For this to work smoothly there
42        are a few recommendations that all users should follow. The first
43        and most important recommendation is:
44      </para>
45     
46      <important>
47        <title>Always use a project!</title>
48        By collecting items in a project the life
49        will be a lot easier when you want to share your data with others.
50        This is because you can always treat all items in a project as one
51        collection and grant or revoke access to the project as a whole.
52      </important> 
53       
54      <sect2 id="project_permission.permissions.levels">
55        <title>Permission levels</title>
56       
57        <para>
58          Whenever you try to create or access existing items in BASE the core will
59          check that you have the proper permission to do so. There
60          are several permission levels:
61        </para>
62       
63        <variablelist>
64          <varlistentry>
65            <term>Read</term>
66            <listitem>
67              <para>
68              Permission to read information about the item, such
69              as the name and description.
70              </para>
71            </listitem>
72          </varlistentry>
73         
74          <varlistentry>
75            <term>Use</term>
76            <listitem>
77              <para>
78              Permission to use the information. In most cases this
79              means linking with other items. For example, if you have permission
80              to use a protocol you may specify that protocol as the extraction
81              protocol when creating an extract from a sample. In the case of plug-ins,
82              you need this permission to be able to execute them.
83              </para>
84            </listitem>
85          </varlistentry>
86         
87          <varlistentry>
88            <term>Write</term>
89            <listitem>
90              <para>
91              Permission to change information about the item.
92              </para>
93            </listitem>
94          </varlistentry>
95
96          <varlistentry>
97            <term>Delete</term>
98            <listitem>
99              <para>
100              Permission to delete the item.
101              </para>
102            </listitem>
103          </varlistentry>
104
105          <varlistentry>
106            <term>Change owner</term>
107            <listitem>
108              <para>
109                Permission to change the owner of an item. This is implemented as a
110                <synopsis>Take ownership</synopsis> function in the web client
111                (<xref linkend="webclient.items.takeownership" />), where you can
112                take the ownership of items that you do not already own.
113              </para>
114            </listitem>
115          </varlistentry>
116
117          <varlistentry>
118            <term>Change permissions</term>
119            <listitem>
120              <para>
121              Permission to change the permissions on the item.
122              </para>
123            </listitem>
124          </varlistentry>
125         
126          <varlistentry>
127            <term>Create</term>
128            <listitem>
129              <para>
130              Permission to create new items. This permission can only be
131              given to roles.
132              </para>
133            </listitem>
134          </varlistentry>
135          <varlistentry>
136            <term>Deny</term>
137            <listitem>
138              <para>
139              Deny all access to the item. This permission can only be given
140              to roles.
141              </para>
142            </listitem>
143          </varlistentry>
144     
145        </variablelist>
146        <note>
147          An user's permissions need to be reloaded for the permissions that have been
148          changed should take effect. This is done either manually with the menu choice
149          <menuchoice>
150            <guimenu>File</guimenu>
151            <guimenuitem>Reload permissions</guimenuitem>
152          </menuchoice>
153          or automatically next time the user logs in to BASE.
154        </note>
155
156      </sect2>
157     
158      <sect2 id="project_permission.permissions.checks">
159        <title>Getting access to an item</title>
160     
161        <para>
162          There are several ways that permission to access an item can
163          be granted to you. The list below is a description of how the
164          permission checks are implemented in the BASE core:
165        </para>
166       
167        <orderedlist>
168          <listitem>
169            <para>
170            Check if you are the root user. The root user has full
171            permission to everything and the permission check stops here.
172            </para>
173          </listitem>
174         
175          <listitem>
176            <para>
177            Check if you are a member of a role that gives you access to the
178            item. Role-based permissions can only be specified based on
179            generic item types and is valid for all items of that type.
180            The role-based permissions also include a special deny permission
181            that can prevents an user from accessing any item. In that case,
182            the permission check stops here.
183            </para>
184          </listitem>
185         
186          <listitem>
187            <para>
188            Check if you are the owner of the item. As the owner you have full
189            permission to the item and the permission check stops here.
190            </para>
191          </listitem>
192         
193          <listitem>
194            <para>
195            Check if you have been granted access to the item by the
196            sharing system ((cf. <xref linkend="webclient.items.share"/>).
197            The sharing system can grant access to individual users, groups of
198            users and to projects. We recommend that you always use projects
199            to share your items.
200            </para>
201          </listitem>
202         
203          <listitem>
204            <para>
205            Some items implement special permission checks.
206            For example:
207            </para>
208           
209            <itemizedlist>
210              <listitem>
211                <para>
212                News: You always have read access to news if today's date
213                falls between the start and end date of the news item.
214                </para>
215              </listitem>
216           
217              <listitem>
218                <para>
219                Groups: You have read access to all groups where you
220                are a member.
221                </para>
222              </listitem>
223           
224              <listitem>
225                <para>
226                Users: You have read permission to all users that are members
227                of at least one group where you also are a member. When a project
228                is active, you also have read permission to all users of
229                that project.
230                </para>
231              </listitem>
232           
233            </itemizedlist>
234           
235            <para>
236              There are more items with special permission checks but
237              we do not list those here.
238            </para>
239           
240          </listitem>
241         
242        </orderedlist>
243      </sect2>
244
245      <sect2 id="project_permission.permissions.plugins">
246        <title>Plug-in permissions</title>
247       
248        <para>
249          Another aspect of the permission system is that plug-ins
250          may also have permissions of their own. The default is that
251          plug-ins run with the same permissions as the user that invoked
252          the plug-in has. Sometimes this can be seen as a security risk
253          if the plug-in is not trusted. A malicious plug-in can, for example,
254          delete the entire database if invoked by the root user.
255        </para>
256       
257        <para>
258          An administrator can choose to give a plug-in only those
259          permissions that is required to complete it's task. If the plug-in
260          permission system is enabled for a plug-in the default is to deny
261          all actions. Then, the administrator can give the plug-in the same
262          permissions as listed above. There is one additional twist to
263          the plug-in permission system. A permission can be granted regardless
264          of if the user that invoked the plug-in had the permission or not, or
265          a permission can be granted only if the user also has the permission.
266          The first case makes it possible to develop a plug-in that allows
267          users to do things that they normally do not have permission to do.
268          The second case is the same as not using the plug-in permission system,
269          except that unspecified permissions are always denied when the
270          plug-in permission system is used.
271        </para>
272       
273        <note>
274          Plug-in developers can supply information about
275          the wanted permissions making it easy for the administrator to
276          just check the permissions and accept them with just a single
277          click if they make sense.
278        </note>
279       
280        <para>
281          See <xref linkend="plugins.permissions"/> for more information.
282        </para>
283       
284      </sect2>
285     
286    </sect1>
287   
288    <sect1 id="project_permission.projects">
289   
290      <title>Projects</title>
291     
292      <para>
293        Projects are an important part of the permission system for several
294        reasons:
295      </para>
296     
297      <itemizedlist>
298        <listitem>
299          <para>
300          They do not require an administrator to setup and
301          use. All regular users may create a project, add items
302          to it and share it with other users. You are in complete
303          control of who gets access to the project, the items it contains
304          and which permission levels to use.
305          </para>
306        </listitem>
307       
308        <listitem>
309          <para>
310          All items in a project are treated as one collection. If a
311          new member joins the team, just give the new person access
312          to the project and that person will be able to access all
313          items in the project.
314          </para>
315        </listitem>
316     
317        <listitem>
318          <para>
319          When you create new items, they are automatically added to the active
320          project so
321          there is almost no need to share items manually. All
322          you have to remember is to set an active project, and
323          this is easy accessible from the
324          <link linkend="webclient.intro.menubar">menu bar</link>.
325          </para>
326        </listitem>
327       
328        <listitem>
329          <para>
330          Filter out items that you do not want to see. When you have set
331          an active project you may choose to only see items that are
332          part of that project and no other items
333          (<xref linkend="webclient.itemlist.presets"/>).
334          </para>
335        </listitem>
336       
337        <listitem>
338          <para>
339          It's easy to share multiple items between projects. Items
340          may be part of more than one project. If you create a new
341          project that builds on a previous one you can easily share
342          some or all of the existing items to the new project from one
343          central place, the <guilabel>Items</guilabel> tab on the project's
344          single-item view.
345          </para>
346        </listitem>
347     
348      </itemizedlist>
349     
350   
351      <sect2 id="project_permission.projects.active">
352     
353        <title>The active project</title>
354       
355        <para>
356          The active project concept is central to the sharing system.
357          You should always, with few exceptions, have a project active
358          when you work with BASE. The most important reason is that
359          new items will automatically be included in the active project.
360          This considerably reduces the time needed for managing access
361          permissions. Without an active project you would have to manually
362          set the permission on all items you create. If you have hundreds
363          of items this is a time-consuming and boring task best to be
364          avoided.
365        </para>
366       
367        <para>
368          If you work with multiple projects you will probably find the
369          filtering function that hides items that are not part
370          of the active project to be useful. As a matter of fact, if you
371          try to access an item that is part of another (not active) project
372          you will get an error message saying that you do not have
373          permission to access the item (unless you are the owner).
374        </para>
375     
376        <sect3 id="project_permission.projects.active.set">
377          <title>Selecting an active project</title>
378         
379          <para>
380            Since it's important to always have an active project
381            there are several ways to make a project 
382            the active one.
383          </para>
384         
385          <itemizedlist>
386            <listitem>
387              <para>
388                The easiest way and the one you will probably use most of the time
389                is to use the menu bar shortcut. Look in the menu for the project
390                icon
391                (<guiicon>
392                  <inlinemediaobject>
393                    <imageobject>
394                      <imagedata fileref="figures/project.gif" format="GIF" />
395                    </imageobject>
396                  </inlinemediaobject>
397                </guiicon>).
398                Next to it, the name of the active project is displayed. If you see
399                <guilabel>- none -</guilabel>
400                here, it means that no project is active. Click on the icon or
401                project name to open a drop-down menu and select a project to set as
402                the active project. If another project is already active it will
403                automatically be inactivated.
404              </para>
405            </listitem>
406         
407            <listitem>
408              <para>
409              Use the <menuchoice><guimenu>File</guimenu>
410              <guisubmenu>Select project</guisubmenu></menuchoice>
411              menu and select the project from the submenu that opens
412              up.
413              </para>
414            </listitem>
415           
416            <listitem>
417              <para>
418              Go to the <link linkend="webclient.intro.homepage">homepage</link>
419              using the <menuchoice><guimenu>View</guimenu>
420              <guisubmenu>Home</guisubmenu></menuchoice> menu and select
421              a project from the list displayed there.
422              </para>
423            </listitem>
424          </itemizedlist>
425         
426          <note>
427            Only one project can be active at a time.
428          </note>
429         
430          <warning>
431            If you change the active project while viewing an item
432            that you no longer has access to in the context of the
433            new project an error message about missing permission
434            will be displayed. Unfortunately, this is all that is displayed
435            and it may be difficult to navigate to a working page again.
436            In the worst case, you may have to go to the login page and
437            login again.
438          </warning>
439         
440        </sect3>
441      </sect2>
442       
443      <sect2 id="project_permission.projects.share">
444        <title>How to give other users access to your project</title>
445       
446        <para>
447          First, you will need to open the <guilabel>Edit project</guilabel>
448          dialog. Here is how to do that:
449        </para>
450       
451        <orderedlist>
452          <listitem>
453            <para>
454            Navigate to the single-item view of your project
455            from the <menuchoice><guimenu>View</guimenu>
456            <guisubmenu>Projects</guisubmenu></menuchoice> list.
457            </para>
458          </listitem>
459         
460          <listitem>
461            <para>
462            Click on the &gbEdit;
463            button to open the <guilabel>Edit project</guilabel>
464            dialog.
465            </para>
466          </listitem>
467         
468          <listitem>
469            <para>
470            Switch to the <guilabel>Members tab</guilabel>. From this
471            page you can add and remove users and change the access levels
472            of existing ones.
473            </para>
474          </listitem>
475        </orderedlist>
476       
477        <figure id="project_permission.projects.members">
478          <title>Manage members of a project</title>
479          <screenshot>
480            <mediaobject>
481              <imageobject><imagedata fileref="figures/project_members.png" format="PNG" /></imageobject>
482            </mediaobject>
483          </screenshot>
484        </figure>
485       
486       
487        <helptext external_id="project.edit.members" title="Project members">
488         
489          <variablelist>
490            <varlistentry>
491              <term><guilabel>Members</guilabel></term>
492              <listitem>
493                <para>
494                The members list contains users
495                and groups that are already members of the project. The list
496                shows the name and the permission level. The permission level
497                uses a one-letter code as follows:
498                </para>
499                <itemizedlist>
500                <listitem><guilabel>R</guilabel> = Read</listitem>
501                <listitem><guilabel>U</guilabel> = Use</listitem>
502                <listitem><guilabel>W</guilabel> = Write</listitem>
503                <listitem><guilabel>D</guilabel> = Delete</listitem>
504                <listitem><guilabel>O</guilabel> = Take ownership</listitem>
505                <listitem><guilabel>P</guilabel> = Set permission</listitem>
506                </itemizedlist>
507              </listitem>
508            </varlistentry>
509           
510            <varlistentry>
511              <term><guilabel>Permissions</guilabel></term>
512              <listitem>
513                <para>
514                When you select an user or group in the
515                list the current permission will be checked. To change the
516                permissions just check the permissions you want to
517                grant or uncheck the permissions you want to revoke.
518                You may select more than one user and/or group
519                and change the permissions for all of them at once.
520                </para>
521               
522                <note>
523                In most cases, you should give the project members
524                <emphasis>use</emphasis> permission. This will allow an user
525                to use all items in the project as well as add new items to it.
526                If you give them write or delete permission they will be able
527                to modify or delete all items including those that they do not
528                own.
529                </note>
530               
531                <note>
532                The above note is not always true since the permission to
533                an item in the project also depends on the permission that
534                was set when adding the item to the project. The default
535                permission is <emphasis>delete</emphasis> and the above note
536                holds true. If the item's permission is manually changed to for
537                example, <emphasis>use</emphasis>, no project member can get
538                higher permission to the item.
539                </note>
540               
541              </listitem>
542            </varlistentry>
543           
544            <varlistentry>
545              <term><guibutton>Add users</guibutton></term>
546              <listitem>
547                <para>
548                Opens a popup window that allows you to add
549                users to the project. In the popup window, mark
550                one or more users and click on the &gbOk;
551                button. Unless you are an administrator, the popup window
552                will only list users that are members of at least one of the
553                groups where you also are a member. It will not list users that
554                are already part of the project.
555                </para>
556              </listitem>
557            </varlistentry>
558           
559            <varlistentry>
560              <term><guibutton>Add groups</guibutton></term>
561              <listitem>
562                <para>
563                Opens a popup window that allows you to add
564                groups to the project. In the popup window, mark
565                one or more groups and click on the &gbOk;
566                button. Unless you are
567                an administrator, the popup window will only list groups
568                that you are a member of. It will not list groups that
569                are already part of the project.
570                </para>
571              </listitem>
572            </varlistentry>
573           
574            <varlistentry>
575              <term>&gbRemove;</term>
576              <listitem>
577                <para>
578                Click on this button to remove the selected
579                users and/or groups from the project.
580                </para>
581              </listitem>   
582            </varlistentry>
583          </variablelist>
584         
585         
586          <para>
587            Use the &gbSave; button to save your
588            changes or the &gbCancel; button to
589            close the popup without saving.
590          </para>
591        </helptext>
592
593      </sect2>
594     
595      <sect2 id="project_permission.projects.items">
596        <title>Working with the items in the project</title>
597       
598        <para>
599        If you go to the single-item view for a project you will find
600        that there is an extra tab, <guilabel>Items</guilabel>, on that
601        page. Clicking on that tab will display a page that is similar
602        to a list view. However there are some differences:
603        </para>
604       
605        <itemizedlist>
606          <listitem>
607            <para>
608            The list is not limited to one type of item. It can display
609            all items that are part of the project.
610            </para>
611          </listitem>
612         
613          <listitem>
614            <para>
615              It support only a limited set of columns (name, description and
616              owner) since these are the only properties that are common
617              among all items.
618            </para>
619          </listitem>
620         
621          <listitem>
622            <para>
623              The list cannot be filtered (except by item type)
624              or sorted. This is due to a limitation in the query system
625              used to generate the list.
626            </para>
627          </listitem>
628        </itemizedlist>
629       
630        <note>
631          The list only works for the active project. For all other
632          projects it will only display items that are owned by the
633          logged in user.
634        </note>
635       
636        <para>
637          There are also several similarities:
638        </para>
639       
640        <itemizedlist>
641          <listitem>
642            <para>
643              It supports all of the regular multi-item
644              operations such as delete, restore, share
645              and take ownership.
646            </para>
647          </listitem>
648         
649          <listitem>
650            <para>
651              Clicking on the name of the item will take you to the
652              single-item view of that item. Holding down <keycap>CTRL</keycap>,
653              <keycap>ALT</keycap> or <keycap>SHIFT</keycap> while clicking,
654              will open the edit popup.
655            </para>
656          </listitem>
657        </itemizedlist>
658       
659        <tip>
660          <para>
661          This list is very useful when you are creating a
662          new project, in which you want to reuse items from
663          an old project.
664          </para>
665         
666          <itemizedlist>
667            <listitem>
668              <para>
669              Activate the old project and go to this view.
670              </para>
671            </listitem>
672           
673            <listitem>
674              <para>
675                Mark the checkbox for all items that you want to
676                use in the new project.
677              </para>
678            </listitem>
679           
680            <listitem>
681              <para>
682                Click on the &gbShare; button
683                and share the items to the new project.
684              </para>
685            </listitem>
686          </itemizedlist>
687          <para>
688            If you have more than one old project, repeat the
689            above procedure.
690          </para>
691        </tip>
692       
693      </sect2>
694   
695    </sect1>
696       
697</chapter>
Note: See TracBrowser for help on using the repository browser.