source: trunk/doc/src/docbook/user/project_permission.xml @ 5782

Last change on this file since 5782 was 5782, checked in by Nicklas Nordborg, 10 years ago

References #1590: Documentation cleanup

Restructured documentation to generate shorter filenames.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 27.5 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 5782 2011-10-04 13:43:16Z nicklas $
7
8  Copyright (C) 2007 Jari Häkkinen, 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 3
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 BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
26
27<chapter id="project_permission">
28  <?dbhtml dir="projects" filename="index.html" ?>
29  <title>Projects and the permission system</title>
30    <sect1 id="project_permission.permissions">
31      <?dbhtml filename="permissions.html" ?>
32      <title>The permission system</title>
33      <para>
34        BASE is a multi-user environment that supports cooperation
35        between users while protecting all data against unauthorized
36        access or modification. To make this possible an elaborate
37        permission system has been developed that allows an user to
38        specify exactly the permission to give to other users and at the
39        same time makes it easy to handle the permissions of multiple
40        items with just a few interactions. For this to work smoothly there
41        are a few recommendations that all users should follow. The first
42        and most important recommendation is:
43      </para>
44     
45      <important>
46        <title>Always use a project!</title>
47        By collecting items in a project the life
48        will be a lot easier when you want to share your data with others.
49        This is because you can always treat all items in a project as one
50        collection and grant or revoke access to the project as a whole.
51      </important> 
52       
53      <sect2 id="project_permission.permissions.levels">
54        <title>Permission levels</title>
55       
56        <para>
57          Whenever you try to create or access existing items in BASE the core will
58          check that you have the proper permission to do so. There
59          are several permission levels:
60        </para>
61       
62        <variablelist>
63          <varlistentry>
64            <term>Read</term>
65            <listitem>
66              <para>
67              Permission to read information about the item, such
68              as the name and description.
69              </para>
70            </listitem>
71          </varlistentry>
72         
73          <varlistentry>
74            <term>Use</term>
75            <listitem>
76              <para>
77              Permission to use the information. In most cases this
78              means linking with other items. For example, if you have permission
79              to use a protocol you may specify that protocol as the extraction
80              protocol when creating an extract from a sample. In the case of plug-ins,
81              you need this permission to be able to execute them.
82              </para>
83            </listitem>
84          </varlistentry>
85         
86          <varlistentry>
87            <term>Write</term>
88            <listitem>
89              <para>
90              Permission to change information about the item.
91              </para>
92            </listitem>
93          </varlistentry>
94
95          <varlistentry>
96            <term>Delete</term>
97            <listitem>
98              <para>
99              Permission to delete the item.
100              </para>
101            </listitem>
102          </varlistentry>
103
104          <varlistentry>
105            <term>Change owner</term>
106            <listitem>
107              <para>
108                Permission to change the owner of an item. This is implemented as a
109                <guilabel>Set owner</guilabel> function in the web client
110                (<xref linkend="webclient.items.changeowner" />), where you can
111                change the owner of items that you have permission to do so on.
112              </para>
113            </listitem>
114          </varlistentry>
115
116          <varlistentry>
117            <term>Change permissions</term>
118            <listitem>
119              <para>
120              Permission to change the permissions on the item.
121              </para>
122            </listitem>
123          </varlistentry>
124         
125          <varlistentry>
126            <term>Create</term>
127            <listitem>
128              <para>
129              Permission to create new items. This permission can only be
130              given to roles.
131              </para>
132            </listitem>
133          </varlistentry>
134          <varlistentry>
135            <term>Deny</term>
136            <listitem>
137              <para>
138              Deny all access to the item. This permission can only be given
139              to roles.
140              </para>
141            </listitem>
142          </varlistentry>
143     
144        </variablelist>
145        <note>
146          A user's permissions need to be reloaded for the permissions that have been
147          changed should take effect. This is done either manually with the menu choice
148          <menuchoice>
149            <guimenu>BASE</guimenu>
150            <guimenuitem>Reload permissions</guimenuitem>
151          </menuchoice>
152          or automatically next time the user logs in to BASE.
153        </note>
154
155      </sect2>
156     
157      <sect2 id="project_permission.permissions.checks">
158        <title>Getting access to an item</title>
159     
160        <para>
161          There are several ways that permission to access an item can
162          be granted to you. The list below is a description of how the
163          permission checks are implemented in the BASE core:
164        </para>
165       
166        <orderedlist>
167          <listitem>
168            <para>
169            Check if you are the root user. The root user has full
170            permission to everything and the permission check stops here.
171            </para>
172          </listitem>
173         
174          <listitem>
175            <para>
176            Check if you are a member of a role that gives you access to the
177            item. Role-based permissions can only be specified based on
178            generic item types and is valid for all items of that type.
179            The role-based permissions also include a special deny permission
180            that can prevents a user from accessing any item. In that case,
181            the permission check stops here.
182            </para>
183          </listitem>
184         
185          <listitem>
186            <para>
187            Check if you are the owner of the item. As the owner you have full
188            permission to the item and the permission check stops here.
189            </para>
190          </listitem>
191         
192          <listitem>
193            <para>
194            Check if you have been granted access to the item by the
195            sharing system (cf. <xref linkend="webclient.items.share"/>).
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 share group
226                membership with, excluding the <emphasis>Everyone</emphasis> group.
227                When a project is active, you also have read permission to all
228                users that are members of that project.
229                </para>
230              </listitem>
231           
232            </itemizedlist>
233           
234            <para>
235              There are more items with special permission checks but
236              we do not list those here.
237            </para>
238           
239          </listitem>
240         
241        </orderedlist>
242      </sect2>
243
244      <sect2 id="project_permission.permissions.plugins">
245        <title>Plug-in permissions</title>
246       
247        <para>
248          Another aspect of the permission system is that plug-ins
249          may also have permissions of their own. The default is that
250          plug-ins run with the same permissions as the user that invoked
251          the plug-in has. Sometimes this can be seen as a security risk
252          if the plug-in is not trusted. A malicious plug-in can, for example,
253          delete the entire database if invoked by the root user.
254        </para>
255       
256        <para>
257          An administrator can choose to give a plug-in only those
258          permissions that is required to complete it's task. If the plug-in
259          permission system is enabled for a plug-in the default is to deny
260          all actions. Then, the administrator can give the plug-in the same
261          permissions as listed above. There is one additional twist to
262          the plug-in permission system. A permission can be granted regardless
263          of if the user that invoked the plug-in had the permission or not, or
264          a permission can be granted only if the user also has the permission.
265          The first case makes it possible to develop a plug-in that allows
266          users to do things that they normally do not have permission to do.
267          The second case is the same as not using the plug-in permission system,
268          except that unspecified permissions are always denied when the
269          plug-in permission system is used.
270        </para>
271       
272        <note>
273          Plug-in developers can supply information about
274          the wanted permissions making it easy for the administrator to
275          just check the permissions and accept them with just a single
276          click if they make sense.
277        </note>
278       
279        <para>
280          See <xref linkend="plugins.permissions"/> for more information.
281        </para>
282       
283      </sect2>
284     
285    </sect1>
286   
287    <sect1 id="project_permission.projects">
288      <?dbhtml filename="projects.html" ?>
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 shared
320          using the settings from the active project. There is almost no
321          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 shared using the settings in
360          the active project. This considerably reduces
361          the time needed for managing access permissions. Without an
362          active project you would have to manually
363          set the permission on all items you create. If you have hundreds
364          of items this is a time-consuming and boring task best to be
365          avoided.
366        </para>
367       
368        <para>
369          If you work with multiple projects you will probably find the
370          filtering function that hides items that are not part
371          of the active project to be useful. As a matter of fact, if you
372          try to access an item that is part of another (not active) project
373          you will get an error message saying that you do not have
374          permission to access the item (unless you are the owner).
375        </para>
376     
377        <sect3 id="project_permission.projects.active.set">
378          <title>Selecting an active project</title>
379         
380          <para>
381            Since it's important to always have an active project
382            there are several ways to make a project 
383            the active one.
384          </para>
385         
386          <itemizedlist>
387            <listitem>
388              <para>
389                The easiest way and the one you will probably use most of the time
390                is to use the menu bar shortcut. Look in the menu for the project
391                icon
392                (<guiicon>
393                  <inlinemediaobject>
394                    <imageobject>
395                      <imagedata fileref="figures/project.gif" format="GIF" />
396                    </imageobject>
397                  </inlinemediaobject>
398                </guiicon>).
399                Next to it, the name of the active project is displayed. If you see
400                <guiicon>
401                  <inlinemediaobject>
402                    <imageobject>
403                      <imagedata fileref="figures/no_active_project.gif" format="GIF" />
404                    </imageobject>
405                  </inlinemediaobject>
406                </guiicon>
407                <guilabel>- no active project -</guilabel>
408                here, it means that you have not selected a project to work in. Click on the icon or
409                project name to open a drop-down menu and select a project to set as
410                the active project. If another project is already active it will
411                automatically be inactivated.
412              </para>
413              <para>
414                The most recently used projects are listed first, then the list is filled with the
415                rest of your projects up to a maximum of 15. If you have more projects an option to
416                display the remaining projects is activated.
417              </para>
418              <tip>
419                <para>
420                The sort order of the non-recent projects is the same as the sort order on the
421                projects list page. If you, for example, want to sort the newest
422                project first, select to sort by the <guilabel>Registered</guilabel> 
423                column in descending order on the list page. The menu will automatically
424                use the same order.
425                </para>
426              </tip>
427            </listitem>
428         
429            <listitem>
430              <para>
431              Use the <menuchoice><guimenu>BASE</guimenu>
432              <guisubmenu>Select project</guisubmenu></menuchoice>
433              menu and select the project from the submenu that opens
434              up.
435              </para>
436            </listitem>
437           
438            <listitem>
439              <para>
440              Go to the <link linkend="webclient.intro.homepage">homepage</link>
441              using the <menuchoice><guimenu>View</guimenu>
442              <guisubmenu>Home</guisubmenu></menuchoice> menu and select
443              a project from the list displayed there.
444              </para>
445            </listitem>
446          </itemizedlist>
447         
448          <note>
449            Only one project can be active at a time.
450          </note>
451         
452          <warning>
453            If you change the active project while viewing an item
454            that you no longer has access to in the context of the
455            new project an error message about missing permission
456            will be displayed. Unfortunately, this is all that is displayed
457            and it may be difficult to navigate to a working page again.
458            In the worst case, you may have to go to the login page and
459            login again.
460          </warning>
461         
462        </sect3>
463
464        <sect3 id="project_permission.projects.active.autopermissions">
465          <title>Default permissions for the active project</title>
466         
467          <para>
468            When a project is active all new items you create are automatically
469            shared using the settings from the active project. If the active project
470            has a permission template the permissions from the template are copied
471            to the new item. If the project doesn't have a permission template, the
472            new item is shared to the active project with the configured default
473            level. By default, projects doesn't have a permission template
474            and the default permissions are set to
475            <emphasis>read</emphasis>, <emphasis>use</emphasis>,
476            <emphasis>write</emphasis> and <emphasis>delete</emphasis>. It is
477            possible to change the default permission level by modifying the
478            settings for the project. Simply open the edit-view page for the project
479            and select the permissions you want and save. From now on, all new
480            items will be shared with the specified permissions. Items that are
481            already in the project are not affected by the change.
482          </para>
483        </sect3>
484
485      </sect2>
486       
487      <sect2 id="project_permission.projects.share">
488        <title>How to give other users access to your project</title>
489       
490        <para>
491          First, you will need to open the <guilabel>Edit project</guilabel>
492          dialog. Here is how to do that:
493        </para>
494       
495        <orderedlist>
496          <listitem>
497            <para>
498            Navigate to the single-item view of your project
499            from the <menuchoice><guimenu>View</guimenu>
500            <guisubmenu>Projects</guisubmenu></menuchoice> list.
501            </para>
502          </listitem>
503         
504          <listitem>
505            <para>
506            Click on the &gbEdit;
507            button to open the <guilabel>Edit project</guilabel>
508            dialog.
509            </para>
510          </listitem>
511         
512          <listitem>
513            <para>
514            Switch to the <guilabel>Members tab</guilabel>. From this
515            page you can add and remove users and change the access levels
516            of existing ones.
517            </para>
518          </listitem>
519        </orderedlist>
520       
521        <figure id="project_permission.projects.members">
522          <title>Manage members of a project</title>
523          <screenshot>
524            <mediaobject>
525              <imageobject><imagedata fileref="figures/project_members.png" format="PNG" /></imageobject>
526            </mediaobject>
527          </screenshot>
528        </figure>
529       
530       
531        <helptext external_id="project.edit.members" title="Project members">
532         
533          <variablelist>
534            <varlistentry>
535              <term><guilabel>Members</guilabel></term>
536              <listitem>
537                <para>
538                The members list contains users
539                and groups that are already members of the project. The list
540                shows the name and the permission level. The permission level
541                uses a one-letter code as follows:
542                </para>
543                <itemizedlist>
544                <listitem><guilabel>R</guilabel> = Read</listitem>
545                <listitem><guilabel>U</guilabel> = Use</listitem>
546                <listitem><guilabel>W</guilabel> = Write</listitem>
547                <listitem><guilabel>D</guilabel> = Delete</listitem>
548                <listitem><guilabel>O</guilabel> = Set owner</listitem>
549                <listitem><guilabel>P</guilabel> = Set permission</listitem>
550                </itemizedlist>
551              </listitem>
552            </varlistentry>
553           
554            <varlistentry>
555              <term><guilabel>Permissions</guilabel></term>
556              <listitem>
557                <para>
558                When you select an user or group in the
559                list the current permission will be checked. To change the
560                permissions just check the permissions you want to
561                grant or uncheck the permissions you want to revoke.
562                You may select more than one user and/or group
563                and change the permissions for all of them at once.
564                </para>
565               
566                <note>
567                In most cases, you should give the project members
568                <emphasis>use</emphasis> permission. This will allow an user
569                to use all items in the project as well as add new items to it.
570                If you give them write or delete permission they will be able
571                to modify or delete all items including those that they do not
572                own.
573                </note>
574               
575                <note>
576                The above note is not always true since the permission to
577                an item in the project also depends on the permission that
578                was set when adding the item to the project. The default
579                permission is <emphasis>delete</emphasis> and the above note
580                holds true. If the item's permission is manually changed to for
581                example, <emphasis>use</emphasis>, no project member can get
582                higher permission to the item.
583                </note>
584               
585              </listitem>
586            </varlistentry>
587           
588            <varlistentry>
589              <term><guibutton>Add users</guibutton></term>
590              <listitem>
591                <para>
592                Opens a popup window that allows you to add
593                users to the project. In the popup window, mark
594                one or more users and click on the &gbOk;
595                button. The popup window will only list users that you have
596                permission to read. Unless you are an administrator, this
597                usually means that you can only see users that:
598                </para>
599                <itemizedlist>
600                  <listitem>
601                    <para>
602                    you share group memberships with
603                    (the <emphasis>Everyone</emphasis> group doesn't count)
604                    </para>
605                  </listitem>
606                  <listitem>
607                    <para>
608                    are members of the currently active project, if any.
609                    </para>
610                  </listitem>
611                </itemizedlist>
612                <para>
613                Users that already have access to the project are not included in the
614                list. If you don't see a user that you want to add to the project,
615                you'll need to talk to an administrator for setting up the proper
616                group membership.
617                </para>
618              </listitem>
619            </varlistentry>
620           
621            <varlistentry>
622              <term><guibutton>Add groups</guibutton></term>
623              <listitem>
624                <para>
625                Opens a popup window that allows you to add
626                groups to the project. In the popup window, mark
627                one or more groups and click on the &gbOk;
628                button. Unless you are
629                an administrator, the popup window will only list groups
630                that you are a member of. It will not list groups that
631                are already part of the project.
632                </para>
633              </listitem>
634            </varlistentry>
635           
636            <varlistentry>
637              <term>&gbRemove;</term>
638              <listitem>
639                <para>
640                Click on this button to remove the selected
641                users and/or groups from the project.
642                </para>
643              </listitem>   
644            </varlistentry>
645          </variablelist>
646         
647         
648          <para>
649            Use the &gbSave; button to save your
650            changes or the &gbCancel; button to
651            close the popup without saving.
652          </para>
653        </helptext>
654
655      </sect2>
656     
657      <sect2 id ="project_permissions.project.defaults">
658        <title>Default items</title>
659       
660        <para>TODO</para>
661       
662      </sect2>
663     
664      <sect2 id="project_permission.projects.items">
665        <title>Working with the items in the project</title>
666       
667        <para>
668        If you go to the single-item view for a project you will find
669        that there is an extra tab, <guilabel>Items</guilabel>, on that
670        page.
671        <figure id="project_permission.images.projecttabs">
672          <title/>
673          <screenshot>
674            <mediaobject>
675              <imageobject><imagedata fileref="figures/project_tabs.png" format="PNG" /></imageobject>
676            </mediaobject>
677          </screenshot>
678        </figure>
679        Clicking on that tab will display a page that is similar
680        to a list view. However there are some differences:
681        </para>
682       
683        <itemizedlist>
684          <listitem>
685            <para>
686            The list is not limited to one type of item. It can display
687            all items that are part of the project.
688            </para>
689          </listitem>
690         
691          <listitem>
692            <para>
693              It support only a limited set of columns (id, name, description and
694              owner) since these are the only properties that are common
695              among all items.
696            </para>
697          </listitem>
698         
699          <listitem>
700            <para>
701              The list cannot be sorted. This is due to a limitation in the
702              query system used to generate the list.
703            </para>
704          </listitem>
705        </itemizedlist>
706       
707        <note>
708          The list only works for the active project. For all other
709          projects it will only display items that are owned by the
710          logged in user.
711        </note>
712       
713        <para>
714          There are also several similarities:
715        </para>
716       
717        <itemizedlist>
718          <listitem>
719            <para>
720              It supports all of the regular multi-item
721              operations such as delete, restore, share
722              and change owner.
723            </para>
724          </listitem>
725         
726          <listitem>
727            <para>
728              Clicking on the name of the item will take you to the
729              single-item view of that item. Holding down <keycap>CTRL</keycap>,
730              <keycap>ALT</keycap> or <keycap>SHIFT</keycap> while clicking,
731              will open the edit popup.
732            </para>
733          </listitem>
734        </itemizedlist>
735       
736        <tip>
737          <para>
738          This list is very useful when you are creating a
739          new project, in which you want to reuse items from
740          an old project.
741          </para>
742         
743          <itemizedlist>
744            <listitem>
745              <para>
746              Activate the old project and go to this view.
747              </para>
748            </listitem>
749           
750            <listitem>
751              <para>
752                Mark the checkbox for all items that you want to
753                use in the new project.
754              </para>
755            </listitem>
756           
757            <listitem>
758              <para>
759                Click on the &gbShare; button
760                and share the items to the new project.
761              </para>
762            </listitem>
763          </itemizedlist>
764          <para>
765            If you have more than one old project, repeat the
766            above procedure.
767          </para>
768        </tip>
769       
770      </sect2>
771   
772    </sect1>
773   
774    <sect1 id="project_permission.templates">
775      <?dbhtml filename="templates.html" ?>
776      <title>Permission templates</title>
777   
778      <para>
779        A <emphasis>permission template</emphasis> is a pre-defined set of permissions
780        for users, groups and/or projects. The template makes it easy to quickly share
781        items to multiple users, groups and projects, possible with different permissions
782        for everyone. There are three major use-cases were permission templates are useful:
783      </para>
784     
785      <itemizedlist>
786        <listitem>
787          <para>
788          A permission template can be associated with project. When the project is selected
789          as the active project, the permissions from the template are copied to any new items
790          that are created. Note that the new items may or may not be shared with the active
791          project, depending on the settings in the permission template.
792          </para>
793        </listitem>
794        <listitem>
795          <para>
796          Permission templates can be selected in the <link linkend="webclient.items.share">share dialog</link>,
797          making it easier to manually share items to multiple users,
798          groups and projects in just a few clicks.
799          </para>
800        </listitem>
801        <listitem>
802          <para>
803          Permission templates can be used with some batch item importers, making it easier
804          for administrators which only needs a single data file even if the data belong to
805          different projects.
806          </para>
807        </listitem>
808      </itemizedlist>
809     
810      <para>
811        Permission templates are managed from the <menuchoice><guimenu>View</guimenu>
812        <guisubmenu>Permission templates</guisubmenu></menuchoice> menu. The template is
813        a very simple item that only has a name (required) and a description (optional).
814        We recommend that the names of the templates are kept unique, but this is not
815        enforced by BASE. To assign permissions to the template use the
816        <guibutton>Set permissions</guibutton> button. This is the same dialog as the
817        <link linkend="webclient.items.share">share dialog</link>.
818      </para>
819     
820      <note>
821        <title>Permissions are copied</title>
822        <para>
823        When a permission template is used the permissions are <emphasis>copied</emphasis>
824        to the items. Modifications to the template that are made afterwards doesn't
825        affect the permissions for the items on which the template was used.
826        </para>
827      </note>
828    </sect1>
829</chapter>
Note: See TracBrowser for help on using the repository browser.