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

Last change on this file since 3329 was 3329, checked in by Nicklas Nordborg, 14 years ago

References #548: Write "Installing plug-ins" section

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 21.7 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 3329 2007-05-11 12:20:35Z 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 a 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 plugins,
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.
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       
147      </sect2>
148     
149      <sect2 id="project_permission.permissions.checks">
150        <title>How access permissions are checked</title>
151     
152        <para>
153          There are several ways that permission to access an item can
154          be granted to you. The list below is a description of how the
155          permission checks are implemented in the BASE core:
156        </para>
157       
158        <orderedlist>
159          <listitem>
160            <para>
161            Check if you are the root user. The root user has full
162            permission to everything and the permission check stops here.
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
169            item. Role-based permissions can only be specified based on
170            generic item types and is valid for all items of that type.
171            The role-based permissions also include a special deny permission
172            that can prevent a user from accessing any item. In that case,
173            the permission check stops here.
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
180            permission to the item and the permission check stops here.
181            </para>
182          </listitem>
183         
184          <listitem>
185            <para>
186            Check if you have been granted access to the item by the sharing system.
187            The sharing system can grant access to individual users, groups of
188            users and to projects. We recommend that you always use projects
189            to share your items.
190            </para>
191          </listitem>
192         
193          <listitem>
194            <para>
195            Some items implement special permission checks.
196            For example:
197            </para>
198           
199            <itemizedlist>
200              <listitem>
201                <para>
202                News: You always have read access to news if today's date
203                falls between the start and end date of the news item.
204                </para>
205              </listitem>
206           
207              <listitem>
208                <para>
209                Groups: You have read access to all groups where you
210                are a member.
211                </para>
212              </listitem>
213           
214              <listitem>
215                <para>
216                Users: You have read permission to all users that are members
217                of at least one group where you also are a member. When a project
218                is active, you also have read permission to all users of
219                that project.
220                </para>
221              </listitem>
222           
223            </itemizedlist>
224           
225            <para>
226              There are more items with special permission checks but
227              we don't list those here.
228            </para>
229           
230          </listitem>
231         
232        </orderedlist>
233      </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 <xref linkend="plugins.permissions"/> for more information.
272        </para>
273       
274      </sect2>
275     
276    </sect1>
277   
278    <sect1 id="project_permission.projects">
279   
280      <title>Projects</title>
281     
282      <para>
283        Projects are an important part of the permission system for several
284        reasons:
285      </para>
286     
287      <itemizedlist>
288        <listitem>
289          <para>
290          They don't require an administrator to setup and
291          use. All regular users may create a project, add items
292          to it and share it with other users. You are in complete
293          control of who gets access to the project, the items it contains
294          and which permission levels to use.
295          </para>
296        </listitem>
297       
298        <listitem>
299          <para>
300          All items in a project are treated as one collection. If a
301          new member joins the team, just give the new person access
302          to the project and that person will be able to access all
303          items in the project.
304          </para>
305        </listitem>
306     
307        <listitem>
308          <para>
309          When you create new items, they are automatically added to the active
310          project so
311          there is almost no need to share items manually. All
312          you have to remember is to set an active project, and
313          this is easy accessible from the
314          <link linkend="webclient.intro.menubar">menu bar</link>.
315          </para>
316        </listitem>
317       
318        <listitem>
319          <para>
320          Filter out items that you don't want to see. When you have set
321          an active project you may choose to only see items that are
322          part of that project and no other items
323          (<xref linkend="webclient.itemlist.presets"/>).
324          </para>
325        </listitem>
326       
327        <listitem>
328          <para>
329          It's easy to share multiple items between projects. Items
330          may be part of more than one project. If you create a new
331          project that builds on a previous one you can easily share
332          some or all of the existing items to the new project from one
333          central place, the <guilabel>Items</guilabel> tab on the project's
334          single-item view.
335          </para>
336        </listitem>
337     
338      </itemizedlist>
339     
340   
341      <sect2 id="project_permission.projects.active">
342     
343        <title>The active project</title>
344       
345        <para>
346          The active project concept is central to the sharing system.
347          You should always, with few exceptions, have a project active
348          when you work with BASE. The most important reason is that
349          new items will automatically be included in the active project.
350          This considerably reduces the time needed for managing access
351          permissions. Without an active project you would have to manually
352          set the permission on all items you create. If you have hundreds
353          of items this is a time-consuming and boring task best to be
354          avoided.
355        </para>
356       
357        <para>
358          If you work with multiple projects you will probably find the
359          filtering function that hides items that are not part
360          of the active project to be useful. As a matter of fact, if you
361          try to access an item that is part of another (not active) project
362          you will get an error message saying that you don't have
363          permission to access the item (unless you are the owner).
364        </para>
365     
366        <sect3 id="project_permission.projects.active.set">
367          <title>Selecting an active project</title>
368         
369          <para>
370            Since it important to always have an active project
371            there are several ways to make a project 
372            the active one.
373          </para>
374         
375          <itemizedlist>
376            <listitem>
377              <para>
378              The easiest way and the one you will probably
379              use most of the time is to use the
380              <link linkend="webclient.intro.menubar">menu bar</link> shortcut.
381              Look in the menu for the project icon (<guiicon><inlinemediaobject>
382              <imageobject><imagedata fileref="figures/project.gif" format="GIF" /></imageobject>
383              </inlinemediaobject></guiicon>). Next to it, the name of the active project
384              is displayed. If you see <guilabel>- none -</guilabel> here, it
385              means that no project is active. Click on the icon or project name
386              to open a drop-down menu and select a project to set as the active
387              project. If another project is already active it will automatically
388              be unactivated.
389              </para>
390            </listitem>
391         
392            <listitem>
393              <para>
394              Use the <menuchoice><guimenu>File</guimenu>
395              <guisubmenu>Select project</guisubmenu></menuchoice>
396              menu and select the project from the submenu that opens
397              up.
398              </para>
399            </listitem>
400           
401            <listitem>
402              <para>
403              Go to the <link linkend="webclient.intro.homepage">homepage</link>
404              using the <menuchoice><guimenu>View</guimenu>
405              <guisubmenu>Home</guisubmenu></menuchoice> menu and select
406              a project from the list displayed there.
407              </para>
408            </listitem>
409          </itemizedlist>
410         
411          <note>
412            Only one project can be active at a time.
413          </note>
414         
415          <warning>
416            If you change the active project while viewing an item
417            that you no longer has access to in the context of the
418            new project an error message about missing permission
419            will be displayed. Unfortunately, this is all that is displayed
420            and it may be difficult to navigate to a working page again.
421            In the worst case, you may have to go to the login page and
422            login again.
423          </warning>
424         
425        </sect3>
426      </sect2>
427       
428      <sect2 id="project_permission.projects.share">
429        <title>How to give other users access to your project</title>
430       
431        <para>
432          First, you will need to open the <guilabel>Edit project</guilabel>
433          dialog. Here is how to do that:
434        </para>
435       
436        <orderedlist>
437          <listitem>
438            <para>
439            Navigate to the single-item view of your project
440            from the <menuchoice><guimenu>View</guimenu>
441            <guisubmenu>Projects</guisubmenu></menuchoice> list.
442            </para>
443          </listitem>
444         
445          <listitem>
446            <para>
447            Click on the <guibutton>Edit&hellip;</guibutton>
448            button to open the <guilabel>Edit project</guilabel>
449            dialog.
450            </para>
451          </listitem>
452         
453          <listitem>
454            <para>
455            Switch to the <guilabel>Members tab</guilabel>. From this
456            page you can add and remove users and change the access levels
457            of existing ones.
458            </para>
459          </listitem>
460        </orderedlist>
461       
462        <figure id="project_permission.projects.members">
463          <title>Manage members of a project</title>
464          <screenshot>
465            <mediaobject>
466              <imageobject><imagedata fileref="figures/project_members.png" format="PNG" /></imageobject>
467            </mediaobject>
468          </screenshot>
469        </figure>
470       
471       
472        <helptext external_id="project.edit.members" title="Project members">
473         
474          <variablelist>
475            <varlistentry>
476              <term><guilabel>Members</guilabel></term>
477              <listitem>
478                <para>
479                The members list contains users
480                and groups that are already members of the project. The list
481                shows the name and the permission level. The permission level
482                uses a one-letter code as follows:
483                </para>
484                <itemizedlist>
485                <listitem><guilabel>R</guilabel> = Read</listitem>
486                <listitem><guilabel>U</guilabel> = Use</listitem>
487                <listitem><guilabel>W</guilabel> = Write</listitem>
488                <listitem><guilabel>D</guilabel> = Delete</listitem>
489                <listitem><guilabel>O</guilabel> = Take ownership</listitem>
490                <listitem><guilabel>P</guilabel> = Set permission</listitem>
491                </itemizedlist>
492              </listitem>
493            </varlistentry>
494           
495            <varlistentry>
496              <term><guilabel>Permissions</guilabel></term>
497              <listitem>
498                <para>
499                When you select a user or group in the
500                list the current permission will be checked. To change the
501                permissions just check the permissions you want to
502                grant or uncheck the permissions you want to revoke.
503                You may select more than one user and/or group
504                and change the permissions for all of them at once.
505                </para>
506               
507                <note>
508                In most cases, you should give the project members
509                <emphasis>use</emphasis> permission. This will allow a user
510                to use all items in the project as well as add new items to it.
511                If you give them write or delete permission they will be able
512                to modify or delete all items including those that they don't
513                own.
514                </note>
515               
516                <note>
517                The above note is not always true since the permission to
518                an item in the project also depends on the permission that
519                was set when adding the item to the project. The default
520                permission is <emphasis>delete</emphasis> and the above note
521                holds true. If the item's permission is manually changed to for
522                example, <emphasis>use</emphasis>, no project member can get
523                higher permission to the item.
524                </note>
525               
526              </listitem>
527            </varlistentry>
528           
529            <varlistentry>
530              <term><guibutton>Add users</guibutton></term>
531              <listitem>
532                <para>
533                Opens a popup window that allows you to add
534                users to the project. In the popup window, mark
535                one or more users and click on the <guibutton>Ok</guibutton>
536                button. Unless you are an administrator, the popup window
537                will only list users that are members of at least one of the
538                groups where you also are a member. It will not list users that
539                are already part of the project.
540                </para>
541              </listitem>
542            </varlistentry>
543           
544            <varlistentry>
545              <term><guibutton>Add groups</guibutton></term>
546              <listitem>
547                <para>
548                Opens a popup window that allows you to add
549                groups to the project. In the popup window, mark
550                one or more groups and click on the <guibutton>Ok</guibutton>
551                button. Unless you are
552                an administrator, the popup window will only list groups
553                that you are a member of. It will not list groups that
554                are already part of the project.
555                </para>
556              </listitem>
557            </varlistentry>
558           
559            <varlistentry>
560              <term><guibutton>Remove</guibutton></term>
561              <listitem>
562                <para>
563                Click on this button to remove the selected
564                users and/or groups from the project.
565                </para>
566              </listitem>   
567            </varlistentry>
568          </variablelist>
569         
570         
571          <para>
572            Use the <guibutton>Save</guibutton> button to save your
573            changes or the <guibutton>Cancel</guibutton> button to
574            close the popup without saving.
575          </para>
576        </helptext>
577
578      </sect2>
579     
580      <sect2 id="project_permission.projects.items">
581        <title>Working with the items in the project</title>
582       
583        <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>
677       
678      </sect2>
679   
680    </sect1>
681       
682</chapter>
Note: See TracBrowser for help on using the repository browser.