The AccessTab and Permission Management

  Meta::

     Valid for:  Silva 0.9.3, Zope 2.6.2, Python 2.1.3
     Authors:    kit blake
                 Clemens Klein-Robbenhaar 
                 Jan-Wijbrand Kolman
                 Martijn Faassen
     Email:      kitblake+infrae.com
                 robbenhaar+espresto.com
                 jw+infrae.com
     CVS:        $Revision: 1.16 $ $Date: 2003/11/12 21:12:24 $

  This document describes permission management within the Silva
  environment, including instructions for the AccessTab of the SMI (Silva
  Management Interface).

  Silva comes with an advanced user management system. For users who have
  been granted access, the system allows control of what actions they are
  allowed to perform, as well on which objects they are allowed to perform
  those actions.

  The Roles concept

    To manage user activity, Silva uses a roles approach. Roles group
    related actions together: if a role is granted to a user, the user
    is allowed to perform the actions of this role. Silva has five
    built-in roles: Manager, ChiefEditor, Editor, Author, and
    Reader. Additionally, there are a number of Viewer roles (Viewer,
    Viewer + and Viewer ++) to restrict access to published content to
    authenticated users. See <a href="#restrictions">Access
    Restrictions</a> below.

    The setup allows responsibility (read: work) to be delegated so it
    cascades down the hierarchy of the organization. A Manager creates
    a few Chief Editors, a Chief Editor creates a number of Editors,
    Authors, Readers, and so on. Hundreds of users can be managed this
    way in a scalable way; there is no need for a single person
    bottleneck for both publication of documents or role assignment.

    A user can have different roles in different locations within
    Silva content. A user could be a Chief Editor in one area but only
    a Reader in another. A user can even be a Manager somewhere but
    have no access, not even viewing access to published information,
    in another area.

    The Silva roles and their privileges are:

    - A **Reader** is allowed to:

      - read and preview content objects.

      - copy content to the clipboard. This is useful if a user is an
        Author elsewhere and wants to (ghost) copy content.

    - An **Author** is allowed to:

      - create, edit, and delete unpublished content objects,
        (see "ContentsTab":../ContentsTab/).

      - request approval for publication for content (see
        "PublishTab":../PublishTab/).

      - revoke approval of previously approved (but not published)
        content.

      - create a new editable version of already published content
        (see "PublishTab":../PublishTab/) to prepare new content. This
        new version can however not be published without Editor
        approval.

    - An **Editor** is allowed to:

      - approve and publish content, e.g. make it available for the public.

      - define and change the time frame within which content will be
        published.

      - close published content.

      - delete published content, i.e. close the content and delete it
        (see "PublishTab":../PublishTab/).

    - A **Chief Editor** is allowed to:

      - grant/revoke roles from/to users and groups, including the
        Editor, Author and Reader roles. This way a Chief Editor is
        allowed to create new Editors, Author and Readers in
        particular locations.

      - create and edit groups.

    - A **Manager** (has the same rights as a Zope manager): 

      - A manager can create new Chief Editors and other Managers by
        assigning those roles to users in a location.

      - This role is allowed to do lower level operations via the Zope
        Management Interface, like add layout page templates or create
        external sources.

    Silva roles are in a hierarchy, i.e. the Manager can play the
    ChiefEditor role, who can play an Editor role, etc.

    - The **Viewer** role can be used to create a closed off
      (Intranet) area within a Silva site. In order to view published
      content in that area visitors must have the Viewer role or
      higher assigned to them in this area. Typically for easier
      management a viewer role is assigned to a group of users
      instead, and then all members of this group are allowed to enter
      this area.

      Sometimes, a section of a site that is already restricted to
      people with the Viewer role there needs to be restricted to a
      subset of people again. This can be done by using the **Viewer
      +** and **Viewer ++** roles, so up to two levels of more
      restricted access is possible.

  Structuring access by Folder/Publication

    Role assignment works following the principle of acquisition, where
    objects inherit characteristics from their physical parents. An
    example of this can also be seen in the presentation of a Silva
    website; a branch of a site can have a different layout and style.
    When the style in a branch is altered, the new presentation is
    automatically acquired by all items in the branch.

    Silva's role assignment works the same way. Roles do not have to be
    granted to an user per document (unless desired) but can be granted
    in a folder, which affects all items therein, including documents and
    underlying folders.

    If somebody is given a role in a container, it is not possible to
    withdraw that role on a lower level. This should be
    kept in mind when setting up the publication tree structure. 

    If Authors should not be able to edit each other's content, they
    should be assigned roles in different branches of the tree. If on
    the other hand an Author needs access to the whole tree this is
    possible as well; a Chief Editor with rights on the top of the
    tree can assign the Author role to someone in the top of the Silva
    tree (Silva root).

  Setting up users to Silva can find them

    It is the task of a site manager to set up Silva and its
    users. Chief Editors are able to assign roles to users known by
    the system, but are not able to create the users themselves.

    In a simple Silva setup, users are created and deleted in the
    standard Zope user folder ('acl_users') by a site manager with
    Zope management access.

    When creating users in 'acl_users', do **not** assign them a role
    there. Assigning a role there would result in them having this
    role throughout the Silva instance, which is usually not the
    intent. In addition, there is no way to manage this setting from
    within the Silva user interface, only from the Zope management
    Interface.

    In more sophisticated Silva setups other user folders can be used,
    for instance the LDAPUserFolder
    "LDAPUserFolder":http://www.dataflake.org/software/ldapuserfolder
    Using a Silva extension a site manager can set up Silva so that it
    retrieves users and user information from an external LDAP server.
    This way it is possible to work with very large quantities of
    users. See the "SiteManager":SiteManager document for more
    information.

  Managing roles

    An user is not allowed to enter the Silva environment or perform
    any actions in the SMI unless the user has the appropriate role
    assigned for the location the user wants to access.  Managing such
    role assignments is described in this section. Only Chief Editors
    and Managers are allowed to manage role assignments, in the
    AccessTab.
  
    Looking up a user

      In order to add a role to a user, the first task is to select
      the user so that a role can be assigned to them. This is done
      in the lookup screen.

      Go to the access tab and click the |_lookup users_| button in
      the top right, in the user clipboard. This brings you to the
      user lookup screen where users can be selected to place on the
      clipboard.

      In the user search area, type the name or part of the name of
      the user you want to find and click the |_search_| button
      (alt-s). The system will now list all users which match, with
      some extra information like an email address if available.

      Select the users you want to assign roles to during this session
      using the checkbox in front of their name, and click the |_add
      to clipboard_| button. The selected users will now appear in the
      user clipboard area to the right.

      You can now repeat this action and look up more users if
      desired, until all the users you want to assign roles to later
      are on the clipboard.

      The next step is to press the |_use clipboard_| button in the
      user clipboard area. You will now be returned to the Access tab,
      with the selected users on your clipboard.

      You are now ready to assign roles to the users on your
      clipboard. 

      The clipboard contents will be kept around until you log
      out. You can use therefore use the same clipboard to assign a
      number of roles to a number of users in different locations. It
      is also possible to remove users from the clipboard in the
      lookup screen, by using the |_remove user_| button (alt-r) in
      the user clipboard.

    Assigning roles to users on the clipboard

      Select the user you want to assign a role to in user the
      clipboard area to in the right column of the Access tab. It is
      also possible to select multiple users by using the shift or
      control keys when making the selection.
      
      When you are ready with the selection, select the role you want
      to assign to the user(s) in the drop down list at the bottom of
      the user clipboard. Press the |_assign_| button next to the role
      selection list.

      You are now done assigning the role. You can repeat this step
      for other users on the clipboard if desired.

    Assigning roles to a user with previously assigned roles

      Users which already have roles assigned to them, possibly higher
      up in the site, will be listed in the user roles area in the
      middle column of the Access tab. Roles assigned in a container
      higher up in the site will be listed in the &#8220roles defined
      above" column of the user roles area.

      You can assign more roles to such users by selecting the
      checkbox in front of their user name. You can select multiple
      users if you want to assign the same role to them at once.

      Then, select the role in the drop down list at the bottom of the
      user roles area. Press the |_assign_role_| button next to the
      drop down list.

      You are now done assigning the roles to existing users.

    Revoking roles from users

      Again, go to the user roles area in the middle column of the Access
      tab.

      You can only remove roles from users in the location where this
      role has been assigned to them. If the role has been assigned
      higher up it is not possible to remove the role in the lower
      location. If you have the right access, you can go up to the
      Access tab of the container using the up arrow in the tab or by
      using the sidebar, until you reach the point where the role is
      assigned.

      You can revoke a role by using the checkboxes in the &#8220roles
      defined here" column. After selecting the roles you want
      to revoke, click the |_revoke role_| button below the checkboxes
      in the bottom right area of the user roles area.

      You are now done revoking the roles. If you revoke all roles
      from a particular user, the user won't be shown anymore in the
      user roles area.
      
  Groups

    Silva also offers the ability to group users together and assign a
    role to a whole group at once. This means whenever a group has a
    role in a location and a user is a member of that group, the user
    will also have this role. The group system can be used to manage
    small groups of Authors and Editors, but is particularly useful
    when managing the Viewer role, in which case groups could have a
    large amount of members.

    Managing the role assignments of groups is done in much the same
    way as managing the role assignments of users. The only difference
    is that groups are not looked up in a separate screen; they are
    always available in the groups list in the right colum of the
    Access tab.

    If Silva has been connected to LDAP, group membership membership
    information can be configured to be retrieved from an LDAP server.
    This is allows the reuse of groups defined centrally on such a
    server, and this can scale to many users and large groups.

    Silva supports a number of different kinds of groups:

    Normal Groups

      Normal Groups are made out of users. These users are stored in
      Zope directly by Silva.

    Virtual Groups

      Virtual Groups are composed of other groups. Only if a user is
      in *all* groups the Virtual Group is made of he will be in the
      Virtual Group and thus gain the roles assigned to this group.

    IP Groups

      IP Groups specify a range of IP addresses. IP Groups determine
      membership based on the IP address of the computer the user is
      using. This way, a user can be given a role only if the user has
      a particular type of IP address.

      This way it is for instance possible to give all users accessing
      Silva from your local network, intranet or campus network a
      particular role. This is in particularly useful when using the
      Viewer role to restrict access; an area of the site could be
      closed for all users but those on a certain network.

      Using a virtual group you could even require someone is in a
      particular networked as well as being in another group in order
      to gain access.

      Note that protecting access based on IP address is only a
      minimal security measure. The inherent weaknesses of the
      underlying IP protocol does not allow strong identification of
      users.

      Using IP groups also may not work in all setups of Silva, as
      proxy servers could be in play.

   External groups

      In addition to the three built-in groups, it is possible for
      group membership information to be retrieved from an external
      source like LDAP. In this case the group cannot be managed from
      Silva directly, but is available nonetheless to assign roles to.

  Pending requests for roles 

   The Membership system in Silva allows users to request roles at 
   specific locations. If the Email Service is activated, Chief
   Editors are notified about a request with an email that includes a
   link to the AccessTab (otherwise the request just appears in the
   AccessTab at that location). Requests are listed in the
   "Pending requests for roles" table. To process a
   request:

   - Place a check in the user's checkbox

   - Click the appropriate button. 

   The user will be informed by email if the Email Service is active,
   otherwise they will just be granted access. 

  Public Access Restrictions

    The previous section has discussed how to assign roles to users
    and groups of users. The roles Reader, Author, Editor, Chief
    Editor or Manager are used to give people abilities in to manage
    content using Silva. In contrast, the roles Viewer, Viewer + and
    Viewer ++ are used to restrict access to the published areas of
    the site: they are used to give people the right to *view* the
    content managed with Silva.

    Using public access restrictions it is possible to close to the
    general public a certain area of the site managed with Silva.
    Only people with a viewing role assigned to them are then allowed
    to log in and view these parts of the site. Restricting access can
    be used to put some small areas of the site (even single
    documents) behind a login, or alternatively to construct a large
    intranet area (possibly the entire site).
 
    Just giving someone the Viewer role won't close off any area of
    the site. In order to make use of viewing role assignments, an
    area of the site needs to be restricted for users without this
    role. This can be done using the "Public view access
    restrictions&8221; area below the group management section of the
    Access tab.

    By default, the Silva root container has no public access
    restrictions but is "Open to the public"; this means
    everybody can view the contents of the Silva root without having
    to log in.

    Before any action has been taken to change it, the public access
    restriction of all other objects in the tree will also be acquired
    from above, just like role assignments. This means that the whole
    site will be public to the world.

    It possible to restrict access to a container to people who have a
    certain minimum viewing role. People who don't have this role
    assigned to them (either directly or through group membership)
    won't have access to the object then. Restricting access is done
    by selecting the role by which the area should be restricted and
    clicking the |_set restriction_| button. The restriction will now
    be visible in the public view access restrictions area and will be
    acquired to underlying objects which don't set their own
    restrictions.
  
    Once an access restriction is in place, it is impossible to open
    underlying objects to the public again, though it *is* possible to
    change an underlying object to a lighter restriction (i.e. Viewer
    role needed instead of Viewer +).

    If after a restriction has been set it is decided to go back to
    acquiring the access restriction from the container above, thus
    lifting any special restrictions in this location, this can be set
    by clicking the |_acquire restriction_| button. This button only
    appears when indeed an access restriction has been set locally.

    The possible restrictions are as follows:

       * Anonymous -- 
         This restriction is in fact the lack of all restrictions;
         anyone can see this part of the tree. It is only available if
         there are no restrictions higher up. In that case, pressing
         the 'acquire restriction' button will in fact have the same
         effect.

       * Authenticated -- 
         Only allow viewing by people who can log in (and make them
         log in to view). The person logged in does not necessarily
         have to have any roles assigned to them anywhere. This can be
         used to restrict access only to known users (those who have a
         login with this Silva).

       * Viewer --
         Only allow access to people who have the viewer role or higher.

       * Viewer + --
         Only allow access to people who have the Viewer + role or higher.
     
       * Viewer ++ --
         Only allow access to people who have the Viewer ++ role or higher.

  List user email addresses

    It is sometimes useful to get a list of all email addresses of
    users who have been assigned roles below a certain point in the
    tree, in order to mail them.

    - Click the |_list_email_addresses_| button.

    - In the subscreen a list appears, formatted so it can be copied and
    pasted into an email "To:" field.

    Note that for large sites this collecting all email addresses can
    take a long time and be processor intensive.
    
<br />
Copyright &copy; 2002, 2003 Infrae. All rights reserved.<br />
See also "LICENSE.txt":license.txt
