RBAC/Web Release 1.1
John Barkley, Tony Cincotta, Serban Gavrila
May 20, 1998

MailTo: RBAC/Web Team



Introduction

The software contained in this distribution is a work in progress and everything is subject to change. While we have done a considerable amount of testing, more testing is needed. Consequently, it is very likely that many bugs remain. Section RBAC/Web Installed Systems provides the operating systems and HTTP Servers we have used with this distribution. We have used Netscape Gold on the server and client side, Internet Explorer 4.01 on the client side, and an old version of Mosaic (i.e., before frames). The RBAC/Web Admin Tool requires frames. Please send your comments and suggestions to rbac@hissa.ncsl.nist.gov.

Contents of the Distribution

Of the deliverables described in the RBAC/Web Design Documentation, i.e., Database Definition, RBAC/Web Admin Tool, Database Server, API Library, CGI, and Session Manager, this distribution contains:
Database Definition
The RBAC/Web Database, with the exception of the active role sets, is made up of perl source files. These files are located in the RBAC/admin directory. They are: users, roles, assigned_roles, cardinality, dynamic_separation, static_separation. These files correspond to the data sets described in the Design Documentation. Active role sets are files of the form <user>.active_roles.

Admin Tool
The RBAC/Web Admin Tool in the distribution consists of three Perl scripts, about_users, about_roles, and about_graph, located in RBAC/ExamplesCGI/appl/cgi. The scripts use a few libraries of Perl subroutines located in RBAC/cgi/lib. The tool implements the following functions: add/remove users, add/remove roles, assign/de-assign roles to/from users, add/remove inheritance relation between two roles, establish/de-establish SSD and DSD relations between two roles. The execution of each administrative operation is preceded by a test of the RBAC/Web Database consistency and a test of the conditions associated with that operation assuring the preservation of the database consistency. If any of these tests fails, the administrative operation is not performed.

CGI (Solaris, preSolaris(SUNOS), & Linux)
The RBAC/Web CGI is complete. It is derived from source code available from the World Wide Web Consortium (W3) at: http://www.w3.org/

In the definition of HTTP 1.1, the semantics of PUT are pretty much "implementation defined". The RBAC/Web CGI implements two kinds of PUT. One where the resource addressed is simply replaced and one where the resouce addressed becomes the latest "version", i.e., the resouce addressed is renamed to an earlier version and the current version becomes that which was PUT. In the distribution as installed, the CGI is configured for the simple replacement PUT. The RBAC/Web CGI also permits a PUT to be passed to another CGI. The mlsput CGI in the RBAC_v1.1/RBAC/ExamplesCGI/appl/cgi directory is an example of such a PUT CGI.

Session Manager
The Session Manager in the distribution consists of the perl program login contained in the RBAC_v1.1/RBAC/cgi directory. This program is how the user establishes an RBAC Session. i.e., creates the active role set (<user>.active_roles) for the user.


Note:

The Session Manager in this distribution never removes active role sets. If a user closes their browser and then opens a new browser and does not run login, then that user will automatically be able to access files based on the active role set previously established. To change that active role set, the user must run login again. If properly configured, a user will only be able to access RBAC controlled files using the RBAC/Web CGI and only after having been authenticated.

It is possible to use this distribution without using the Session Manager assuming one does not use any of the role relationships: inheritance, and dynamic and static separation of duties. In an elementary RBAC system, a user only has assigned roles, those roles are the only ones that can become active, and every assigned role is always active. Thus, the Session Manager is not necessary. The active role sets for each user can be created with an editor and left permanently in place.

Documentation
Documentation for this distribution is available in the RBAC_v1.1/RBAC/DOCs directory. Included in that directory are this README.html file, the RBAC/Web Design Document, design.html, documentation for RBAC/Web CGI, CGI_Doc.html, and the user agreement, rbacweb.agreement. Please read the user agreement.

Demos and Examples
The RBAC_v1.1/RBAC/ExamplesCGI directory contain many examples of how this distribution of RBAC/Web may be used. The bank and MLS demos are in the RBAC_v1.1/RBAC/ExamplesCGI/appl directory. The RBAC_v1.1/RBAC/admin/users file contains the users defined in the demos. The password for each user is that user's name. The user admin is the user assigned the role role_admin, which is the required role for running the RBAC/Web Admin Tool. The other directories in the RBAC_v1.1/RBAC/ExamplesCGI directory contain tests specifically for the CGI. See the CGI Documentation in RBAC_v1.1/RBAC/DOCs/CGI_Doc.html.
This distribution of RBAC/Web is capable of supporting a domain concept. In this case, the concept of domain means a separately administered RBAC/Web Database. This is possible by installing this distribution of RBAC/Web in more than one location on a Web server. The distribution is small (less than 2 MB) and can be located in more than one place on a server. The distribution, in particularly the CGI, expects a specific directory structure under the directory RBAC and is capable of self-relocating by simply changing a few parameters. In particular, if the directory structure under RBAC is maintained and the RBAC directory structure is moved, the CGI need not be recompiled. Because an RBAC session is a file of the form: "<user>.active_roles", there is only one RBAC session per user per domain per server.

RBAC/Web Installed Systems

This distribution has been installed and tested on:
SunOS 4.1.2 with NCSA HTTP Server 1.4.2
Solaris 2.5.1 with NCSA HTTP Server 1.4.2
Linux 2.0.27 with Apache HTTP Server 1.2.6
Thanks to Joerg Schreck (Joerg.Schreck@gmd.de) for initiating the use of RBAC/Web on Linux and his assistance with resolving conflicts that were present.
The directory tree RBAC_vi.1/RBAC/src provides the source to compile each of these systems. For the SunOS system, the file RBAC_v1.1/RBAC/src/Makefile must have the macro SYSTEM defined as PreSolaris. Compilation can be avoided, for these systems, by using the appropriate binary distribution nph-RBACcgi, which is available in RBAC_v1.1/binaries.

Installation Procedures

The distribution comes with two executables: nph-RBACcgi, the RBAC/Web CGI and DOT, a graph drawing filter from AT&T. DOT is used by the prototype RBAC/Web Admin Tool. Source code and documentation for GraphViz, the successor of DOT can be obtained via:
http://www.research.att.com/sw/tools/reuse/
The directory structure beginning at RBAC can be installed anywhere on Solaris system with an NCSA or Apache HTTP Server as follows:
  1. Untar the installation tar file:
    umask 0
    tar xf rbac_v1.1_dist.tar
    The topmost directory is named RBAC_v1.1. In that directory is this README.html file and rbacweb.agreement, the user agreement file for use of this software.

  2. As root, from the installed directory, run the script:
    ./RBAC_v1.1/SetProperOwner.sh <name_of_user_ID_of_http_server>
    This will set the proper ownership of directories and files needed by RBAC/Web CGI, the bank demo, and the MLS demo.

  3. Let <some_absolute_pathname>/RBAC_v1.1/RBAC be called <RBAC_root>. The path <RBAC_root> should be an absolute pathname, i.e., begin with a "/". Optionally, recursively copy the RBAC directory and its contents to some to some other <RBAC_root> maintaining the ownership of directories and files set by the SetProperOwner.sh script.

  4. In the NCSA or Apache HTTP Server configuration file srm.conf, add:
    ScriptAlias /RBAC/ <RBAC_root>/cgi/
    For NCSA:
    Alias /RBAC_DOCs/ <RBAC_root>/DOCs
    Alias /RBAC-CGI_src/ <RBAC_root>/src
    For Apache:
    Alias /RBAC_DOCs <RBAC_root>/DOCs
    Alias /RBAC-CGI_src <RBAC_root>/src
    As root, send a HUP signal to the HTTP Server to reload srm.conf.

  5. If a name other than "RBAC" (e.g., "RBAC_other") is used in the ScriptAlias above, then in <RBAC_root>/conf.sess, change:
    $RBAC_BASE_URL="http://$RBAC_SERVER/RBAC"; to
    $RBAC_BASE_URL="http://$RBAC_SERVER/RBAC_other";

    If a name other than "RBAC_DOCs" is used in the Alias above (e.g., "RBAC_DOCs_other"), then in <RBAC_root>/conf.cgi, change:

    docsURL /RBAC_DOCs to
    docsURL /RBAC_DOCs_other

    If a name other than "RBAC-CGI_src" is used in the Alias (e.g., "RBAC-CGI_src_other"), then in <RBAC_root>/conf.cgi, change:

    srcURL /RBAC-CGI_src to
    srcURL /RBAC-CGI_src_other


    Note:

    The <RBAC_root>/ExamplesCGI contains files, both documents and CGI scripts, whose access is controlled by RBAC/Web. Consequently, the HTTP Server administrator should not provide any Alias or ScriptAlias which permits access to the <RBAC_root>/ExamplesCGI directory or any of its contents by means of the HTTP Server directly. This caveat applies equally to any other files whose access is to be controlled by RBAC/Web.

  6. In <RBAC_root>/conf.cgi, changes are required to run the RBAC/Web demos.

    To run the bank and the MLS demos change:

    Pass /applData/* /export/RBAC_v1.1/RBAC/ExamplesCGI/appl/docs/* to
    Pass /applData/* <RBAC_root>/ExamplesCGI/appl/docs/*

    Exec /applCGI/* /export/RBAC_v1.1/RBAC/ExamplesCGI/appl/cgi/* to
    Exec /applCGI/* <RBAC_root>/ExamplesCGI/appl/cgi/*

    To run RBAC/Web CGI demos change:

    Pass /Example/* /export/RBAC_v1.1/RBAC/ExamplesCGI/* to
    Pass /Example/* <RBAC_root>/ExamplesCGI/*

    Exec /ExecTest/* /export/RBAC_v1.1/RBAC/ExamplesCGI/cgi/* to
    Exec /ExecTest/* <RBAC_root>/ExamplesCGI/cgi/*

    Pass /ExecTestPath/* /export/RBAC_v1.1/RBAC/ExamplesCGI/AddPathInfo/* to
    Pass /ExecTestPath/* <RBAC_root>/ExamplesCGI/AddPathInfo/*

  7. If the HTTP Server is using a port number other than the default, in order to run the bank and MLS demos, in <RBAC_root>/conf.sess, change:
    $RBAC_SERVER=$ENV{'SERVER_NAME'}; to
    $RBAC_SERVER="$ENV{'SERVER_NAME'}:$ENV{'SERVER_PORT'}";

  8. In the file <RBAC_root>/cgi/.htaccess change:
    AuthUserFile /export/RBAC_v1.1/RBAC/htpasswd to
    AuthUserFile <RBAC_root>/htpasswd

  9. For each perl source file located in:
    <RBAC_root>/cgi,
    <RBAC_root>/cgi/lib,
    <RBAC_root>/admin,
    <RBAC_root>/ExamplesCGI/cgi, and
    <RBAC_root>/ExamplesCGI/appl/cgi
    change the first line #!/usr/local/bin/perl to the location of perl. It may be possible to use softlinks so that these lines need not be changed.

  10. Establish <RBAC_root>/cgi/nph-RBACcgi by either copying the appropriate distribution file from RBAC_v1.1/binaries/YourSystem/nph-RBACcgi or compiling from the provided sources.

    To generate nph-RBACcgi from the sources, perform the following:

    cd <RBAC_root>/src
    Edit file Makefile:
    Establish value for WWW, which is the <RBAC_root> address.
    Establish value for INSTALL_DIR, which is <RBAC_root>/cgi.
    Select proper code line to use for value SYSTEM.
    make

  11. Start up a browser and clear any caches. It should now be possible to do:
    http://<your_server>/RBAC/login
    When an authentication prompt appears, enter one of the usernames in <RBAC_root>/admin/users file and that same name as the password.

Adding New Users and Roles

Before performing any administrative action, please read the RBAC/Web Database consistency requirements in the Design Documentation. This would help you to understand why some of your actions may come in conflict with those requirements.

To add a new user:

  1. login as admin, and then choose the role role_admin from the admin's menu. Now you're running the administrative tool. In the frame User Administration, write the new <username> in the topmost text field and then click on the Add User button. You can assign roles to the selected user using the Assign button and the assignable roles in the lower part of the frame. Note that some roles cannot be assigned because of the consistency requirements; the tool displays the reason in the lowermost list widget.

  2. Add <username> to <RBAC_root>/cgi/.htaccess and <username>'s password to <RBAC_root>/htpasswd according to HTTP Server instructions.

  3. Create the directory <username> in the <RBAC_root>/ExamplesCGI/appl/docs/tmp directory. Make this directory writable by the user ID of the HTTP Server process.

    Each user has a directory in the directory <RBAC_root>/ExamplesCGI/appl/docs/tmp. It contains temporary files accessible only by <username> in the role whose name is <username>. This "self" role is automatically generated by the login process and may also be used for discretionary access control. The "self" role does not appear in any of the files in <RBAC_root>/admin except for <username>.active_roles. Note that in the bank and MLS demos, the <username> item on the menu should return an error. Discretionary access control has not been implemented for these demos.

  4. In the <RBAC_root>/ExamplesCGI/appl/docs/tmp/<username> directory, create a .RBAC_acl file with the single line:
    *:GET:<username>
To add a new role:
Use the administrative tool. In the Role Administration frame, write the new <rolename> in the topmost text field, and press on the Add Role button. The role receives automatically an unlimited cardinality. You can change it, establish inherit, static separation, or dynamic separation relations between the new role and the old ones using appropriate selections and buttons.


MailTo: RBAC/Web Team