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

Last change on this file since 3423 was 3423, checked in by Nicklas Nordborg, 15 years ago

Fixed image scaling issues in the PDF version

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 22.2 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 3423 2007-05-31 11:53:55Z nicklas $
7
8  Copyright (C) Authors contributing to this file.
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
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>
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 sharing system.
196            The sharing system can grant access to individual users, groups of
197            users and to projects. We recommend that you always use projects
198            to share your items.
199            </para>
200          </listitem>
201         
202          <listitem>
203            <para>
204            Some items implement special permission checks.
205            For example:
206            </para>
207           
208            <itemizedlist>
209              <listitem>
210                <para>
211                News: You always have read access to news if today's date
212                falls between the start and end date of the news item.
213                </para>
214              </listitem>
215           
216              <listitem>
217                <para>
218                Groups: You have read access to all groups where you
219                are a member.
220                </para>
221              </listitem>
222           
223              <listitem>
224                <para>
225                Users: You have read permission to all users that are members
226                of at least one group where you also are a member. When a project
227                is active, you also have read permission to all users of
228                that project.
229                </para>
230              </listitem>
231           
232            </itemizedlist>
233           
234            <para>
235              There are more items with special permission checks but
236              we don't list those here.
237            </para>
238           
239          </listitem>
240         
241        </orderedlist>
242      </sect2>
243
244      <sect2 id="project_permission.permissions.share">
245        <title>Share an item to other users</title>
246       
247        <para>
248          This is described in <xref linkend="webclient.items.share" />.
249        </para>
250       
251      </sect2>
252
253      <sect2 id="project_permission.permissions.plugins">
254        <title>Plug-in permissions</title>
255       
256        <para>
257          Another aspect of the permission system is that plug-ins
258          may also have permissions of their own. The default is that
259          plug-ins run with the same permissions as the user that invoked
260          the plug-in has. Sometimes this can be seen as a security risk
261          if the plug-in is not trusted. A malicious plug-in can, for example,
262          delete the entire database if invoked by the root user.
263        </para>
264       
265        <para>
266          An administrator can choose to give a plug-in only those
267          permissions that is required to complete it's task. If the plug-in
268          permission system is enabled for a plug-in the default is to deny
269          all actions. Then, the administrator can give the plug-in the same
270          permissions as listed above. There is one additional twist to
271          the plug-in permission system. A permission can be granted regardless
272          of if the user that invoked the plug-in had the permission or not, or
273          a permission can be granted only if the user also has the permission.
274          The first case makes it possible to develop a plug-in that allows
275          users to do things that they normally don't have permission to do.
276          The second case is the same as not using the plug-in permission system,
277          except that unspecified permissions are always denied when the
278          plug-in permission system is used.
279        </para>
280       
281        <note>
282          Plug-in developers can supply information about
283          the wanted permissions making it easy for the administrator to
284          just check the permissions and accept them with just a single
285          click if they make sense.
286        </note>
287       
288        <para>
289          See <xref linkend="plugins.permissions"/> for more information.
290        </para>
291       
292      </sect2>
293     
294    </sect1>
295   
296    <sect1 id="project_permission.projects">
297   
298      <title>Projects</title>
299     
300      <para>
301        Projects are an important part of the permission system for several
302        reasons:
303      </para>
304     
305      <itemizedlist>
306        <listitem>
307          <para>
308          They don't require an administrator to setup and
309          use. All regular users may create a project, add items
310          to it and share it with other users. You are in complete
311          control of who gets access to the project, the items it contains
312          and which permission levels to use.
313          </para>
314        </listitem>
315       
316        <listitem>
317          <para>
318          All items in a project are treated as one collection. If a
319          new member joins the team, just give the new person access
320          to the project and that person will be able to access all
321          items in the project.
322          </para>
323        </listitem>
324     
325        <listitem>
326          <para>
327          When you create new items, they are automatically added to the active
328          project so
329          there is almost no need to share items manually. All
330          you have to remember is to set an active project, and
331          this is easy accessible from the
332          <link linkend="webclient.intro.menubar">menu bar</link>.
333          </para>
334        </listitem>
335       
336        <listitem>
337          <para>
338          Filter out items that you don't want to see. When you have set
339          an active project you may choose to only see items that are
340          part of that project and no other items
341          (<xref linkend="webclient.itemlist.presets"/>).
342          </para>
343        </listitem>
344       
345        <listitem>
346          <para>
347          It's easy to share multiple items between projects. Items
348          may be part of more than one project. If you create a new
349          project that builds on a previous one you can easily share
350          some or all of the existing items to the new project from one
351          central place, the <guilabel>Items</guilabel> tab on the project's
352          single-item view.
353          </para>
354        </listitem>
355     
356      </itemizedlist>
357     
358   
359      <sect2 id="project_permission.projects.active">
360     
361        <title>The active project</title>
362       
363        <para>
364          The active project concept is central to the sharing system.
365          You should always, with few exceptions, have a project active
366          when you work with BASE. The most important reason is that
367          new items will automatically be included in the active project.
368          This considerably reduces the time needed for managing access
369          permissions. Without an active project you would have to manually
370          set the permission on all items you create. If you have hundreds
371          of items this is a time-consuming and boring task best to be
372          avoided.
373        </para>
374       
375        <para>
376          If you work with multiple projects you will probably find the
377          filtering function that hides items that are not part
378          of the active project to be useful. As a matter of fact, if you
379          try to access an item that is part of another (not active) project
380          you will get an error message saying that you don't have
381          permission to access the item (unless you are the owner).
382        </para>
383     
384        <sect3 id="project_permission.projects.active.set">
385          <title>Selecting an active project</title>
386         
387          <para>
388            Since it's important to always have an active project
389            there are several ways to make a project 
390            the active one.
391          </para>
392         
393          <itemizedlist>
394            <listitem>
395              <para>
396              The easiest way and the one you will probably
397              use most of the time is to use the
398              <link linkend="webclient.intro.menubar">menu bar</link> shortcut.
399              Look in the menu for the project icon (<guiicon><inlinemediaobject>
400              <imageobject><imagedata fileref="figures/project.gif" format="GIF" /></imageobject>
401              </inlinemediaobject></guiicon>). Next to it, the name of the active project
402              is displayed. If you see <guilabel>- none -</guilabel> here, it
403              means that no project is active. Click on the icon or project name
404              to open a drop-down menu and select a project to set as the active
405              project. If another project is already active it will automatically
406              be unactivated.
407              </para>
408            </listitem>
409         
410            <listitem>
411              <para>
412              Use the <menuchoice><guimenu>File</guimenu>
413              <guisubmenu>Select project</guisubmenu></menuchoice>
414              menu and select the project from the submenu that opens
415              up.
416              </para>
417            </listitem>
418           
419            <listitem>
420              <para>
421              Go to the <link linkend="webclient.intro.homepage">homepage</link>
422              using the <menuchoice><guimenu>View</guimenu>
423              <guisubmenu>Home</guisubmenu></menuchoice> menu and select
424              a project from the list displayed there.
425              </para>
426            </listitem>
427          </itemizedlist>
428         
429          <note>
430            Only one project can be active at a time.
431          </note>
432         
433          <warning>
434            If you change the active project while viewing an item
435            that you no longer has access to in the context of the
436            new project an error message about missing permission
437            will be displayed. Unfortunately, this is all that is displayed
438            and it may be difficult to navigate to a working page again.
439            In the worst case, you may have to go to the login page and
440            login again.
441          </warning>
442         
443        </sect3>
444      </sect2>
445       
446      <sect2 id="project_permission.projects.share">
447        <title>How to give other users access to your project</title>
448       
449        <para>
450          First, you will need to open the <guilabel>Edit project</guilabel>
451          dialog. Here is how to do that:
452        </para>
453       
454        <orderedlist>
455          <listitem>
456            <para>
457            Navigate to the single-item view of your project
458            from the <menuchoice><guimenu>View</guimenu>
459            <guisubmenu>Projects</guisubmenu></menuchoice> list.
460            </para>
461          </listitem>
462         
463          <listitem>
464            <para>
465            Click on the &gbEdit;
466            button to open the <guilabel>Edit project</guilabel>
467            dialog.
468            </para>
469          </listitem>
470         
471          <listitem>
472            <para>
473            Switch to the <guilabel>Members tab</guilabel>. From this
474            page you can add and remove users and change the access levels
475            of existing ones.
476            </para>
477          </listitem>
478        </orderedlist>
479       
480        <figure id="project_permission.projects.members">
481          <title>Manage members of a project</title>
482          <screenshot>
483            <mediaobject>
484              <imageobject><imagedata fileref="figures/project_members.png" format="PNG" /></imageobject>
485            </mediaobject>
486          </screenshot>
487        </figure>
488       
489       
490        <helptext external_id="project.edit.members" title="Project members">
491         
492          <variablelist>
493            <varlistentry>
494              <term><guilabel>Members</guilabel></term>
495              <listitem>
496                <para>
497                The members list contains users
498                and groups that are already members of the project. The list
499                shows the name and the permission level. The permission level
500                uses a one-letter code as follows:
501                </para>
502                <itemizedlist>
503                <listitem><guilabel>R</guilabel> = Read</listitem>
504                <listitem><guilabel>U</guilabel> = Use</listitem>
505                <listitem><guilabel>W</guilabel> = Write</listitem>
506                <listitem><guilabel>D</guilabel> = Delete</listitem>
507                <listitem><guilabel>O</guilabel> = Take ownership</listitem>
508                <listitem><guilabel>P</guilabel> = Set permission</listitem>
509                </itemizedlist>
510              </listitem>
511            </varlistentry>
512           
513            <varlistentry>
514              <term><guilabel>Permissions</guilabel></term>
515              <listitem>
516                <para>
517                When you select an user or group in the
518                list the current permission will be checked. To change the
519                permissions just check the permissions you want to
520                grant or uncheck the permissions you want to revoke.
521                You may select more than one user and/or group
522                and change the permissions for all of them at once.
523                </para>
524               
525                <note>
526                In most cases, you should give the project members
527                <emphasis>use</emphasis> permission. This will allow an user
528                to use all items in the project as well as add new items to it.
529                If you give them write or delete permission they will be able
530                to modify or delete all items including those that they don't
531                own.
532                </note>
533               
534                <note>
535                The above note is not always true since the permission to
536                an item in the project also depends on the permission that
537                was set when adding the item to the project. The default
538                permission is <emphasis>delete</emphasis> and the above note
539                holds true. If the item's permission is manually changed to for
540                example, <emphasis>use</emphasis>, no project member can get
541                higher permission to the item.
542                </note>
543               
544              </listitem>
545            </varlistentry>
546           
547            <varlistentry>
548              <term><guibutton>Add users</guibutton></term>
549              <listitem>
550                <para>
551                Opens a popup window that allows you to add
552                users to the project. In the popup window, mark
553                one or more users and click on the &gbOk;
554                button. Unless you are an administrator, the popup window
555                will only list users that are members of at least one of the
556                groups where you also are a member. It will not list users that
557                are already part of the project.
558                </para>
559              </listitem>
560            </varlistentry>
561           
562            <varlistentry>
563              <term><guibutton>Add groups</guibutton></term>
564              <listitem>
565                <para>
566                Opens a popup window that allows you to add
567                groups to the project. In the popup window, mark
568                one or more groups and click on the &gbOk;
569                button. Unless you are
570                an administrator, the popup window will only list groups
571                that you are a member of. It will not list groups that
572                are already part of the project.
573                </para>
574              </listitem>
575            </varlistentry>
576           
577            <varlistentry>
578              <term>&gbRemove;</term>
579              <listitem>
580                <para>
581                Click on this button to remove the selected
582                users and/or groups from the project.
583                </para>
584              </listitem>   
585            </varlistentry>
586          </variablelist>
587         
588         
589          <para>
590            Use the &gbSave; button to save your
591            changes or the &gbCancel; button to
592            close the popup without saving.
593          </para>
594        </helptext>
595
596      </sect2>
597     
598      <sect2 id="project_permission.projects.items">
599        <title>Working with the items in the project</title>
600       
601        <para>
602        If you go to the single-item view for a project you will find
603        that there is an extra tab, <guilabel>Items</guilabel>, on that
604        page. Clicking on that tab will display a page that is similar
605        to a list view. However there are some differences:
606        </para>
607       
608        <itemizedlist>
609          <listitem>
610            <para>
611            The list is not limited to one type of item. It can display
612            all items that are part of the project.
613            </para>
614          </listitem>
615         
616          <listitem>
617            <para>
618              It support only a limited set of columns (name, description and
619              owner) since these are the only properties that are common
620              among all items.
621            </para>
622          </listitem>
623         
624          <listitem>
625            <para>
626              The list can't be filtered (except by item type)
627              or sorted. This is due to a limitation in the query system
628              used to generate the list.
629            </para>
630          </listitem>
631        </itemizedlist>
632       
633        <note>
634          The list only works for the active project. For all other
635          projects it will only display items that are owned by the
636          logged in user.
637        </note>
638       
639        <para>
640          There are also several similarities:
641        </para>
642       
643        <itemizedlist>
644          <listitem>
645            <para>
646              It supports all of the regular multi-item
647              operations such as delete, restore, share
648              and take ownership.
649            </para>
650          </listitem>
651         
652          <listitem>
653            <para>
654              Clicking on the name of the item will take you to the
655              single-item view of that item. Holding down <keycap>CTRL</keycap>,
656              <keycap>ALT</keycap> or <keycap>SHIFT</keycap> while clicking,
657              will open the edit popup.
658            </para>
659          </listitem>
660        </itemizedlist>
661       
662        <tip>
663          <para>
664          This list is very useful when you are creating a
665          new project, in which you want to reuse items from
666          an old project.
667          </para>
668         
669          <itemizedlist>
670            <listitem>
671              <para>
672              Activate the old project and go to this view.
673              </para>
674            </listitem>
675           
676            <listitem>
677              <para>
678                Mark the checkbox for all items that you want to
679                use in the new project.
680              </para>
681            </listitem>
682           
683            <listitem>
684              <para>
685                Click on the &gbShare; button
686                and share the items to the new project.
687              </para>
688            </listitem>
689          </itemizedlist>
690          <para>
691            If you have more than one old project, repeat the
692            above procedure.
693          </para>
694        </tip>
695       
696      </sect2>
697   
698    </sect1>
699       
700</chapter>
Note: See TracBrowser for help on using the repository browser.