BaBar Database Authorization API and Authorization Management Utility

Version 1.0

Igor A.Gaponenko1

September 26, 1997

1. Introduction.

The document describes the BaBar database authorization facility.

The primary goal of developing the authorization facility was to provide the Bdb data access classes with authorization information about users and groups. Currently this information is used to control the update-mode access of the Bdb users to the particular resources of the database.

The facility to be described in this document is made from three components:

The authorization API
The authorization database
The management utility BdbAuthCmd

The authorization programming interface (authorization API) has been built into existing BaBar database access software and is not normally visible to the regular users. The database access software uses this API code as a sort of "internal fire-wall service" in order to check if a particular Bdb user has the privileges to make updates to a specific database of the Bdb federation database.

The authorization information itself is also kept in the BaBar database. This part of the database is called "authorization database". A significant part of the authorization API aims to maintain this information.

The authorization database as of their current implementation contains three independent collections of the authorization information - one per domain: "Conditions", "Events" and "Online". All of these collections are maintained independently of each other.

Each collection has two lists of interrelated records: users and groups. A user is assumed to be "real" UNIX user. Users are known to the authorization database by their names. A user record contains a list of information describing the user's rights as well as their membership in various groups.

The groups are not necessarily the same as the UNIX groups and are just the abstract organizations constructed to share the resources between their members.

The subsequent document section describes in more details the semantics of user and group and their relations to each other in the context of the authorization database. Further information on how these users and groups map to the whole BaBar database structure may be found at [1].

This document describes also a specially developed UNIX utility BdbAuthCmd providing a simple command-line style interface to those management API.

2. Users, groups and domains in the authorization database.

2.1 Users

There are four types of users in the database:

simple user
group member
group manager
system manager

The last three categories of users are just the variations of the "simple user" possessing update-mode access to their associated (context dependent) resources of the BaBar database resources as well as additional authorization management privileges.

By default all of these users have free read-mode access to any part of the BaBar database, including the authorization database.

In particularly any user is allowed to request the following information from the authorization database:

wether he or she is authorized on the given authorization level
the registration data of any of existing (known to the database) users, including user's privileges, creation date and description.
the registration data of any of existing groups
a list of all the known users
a list of all the known groups
a list of users within any group
a list of groups a user being a member of

The users are known to the authorization database by their UNIX name (not UID!).

The database keeps also additional information about each user, such as registration date and a user description string.

2.1.1 Simple user.

The simple users may have update-mode access to their private database files only and no more else. As to the BaBar database access mode this corresponds to the so called "User-level" [see Reference]. The simple users do not possess any management privileges.

2.1.2 Group member.

A group member is a user having update-mode access to their group database files ("Group-level" access) and to their private files as well. This kind of users also does not possess any management privileges.

Any user may be a member of more then one group simultaneously.

2.1.3 Group manager.

One special subclass of the group members is known as a group manager. As to their data access rights this user has the same privileges as the normal group member of the same group. The only difference is that it possesses additional group-scope management privileges. These privileges allow to:

include new users into their group
exclude existing group members from their group

The only restriction when performing these operations is that a group manager can include in their group only those users that are already known to the authorization database. And vice versa - having excluded from a particular group a user stays in the database (probably as a member of other groups, simple user or even as a system manager).

There may be zero, one or more group managers in a group. In a case when there are not any group managers in a particular group, the group management actions are performed by any of the system managers (see later).

2.1.4 System manager.

These users have the update access to any database file within their domain. This corresponds to so called "System" authorization level access.

The system managers have all the management privileges allowing them:

add a new user to the database
remove any existing user from the database (including himself)
change the privileges of any user (including their own)
perform the group management actions within any group
create new groups
delete existing groups
initialize the internal structure of the authorization database within their domain

There may be more then zero, one or more system managers in a particular database domain. The situation when there are zero system managers in the database is considered to be an accidental one, but it is still allowed in the current implementation of the authorization API.

2.2 Groups

The group in the context of the BaBar authorization database means a collection of users cooperating to share the common resources of the database. In principle the groups may be empty.

The groups are known to the authorization database by their names. These names do not necessarily have a direct relation to the UNIX groups.

The database keeps also additional information about each group, such as registration date and a group description string.

2.2.1 Default group.

There is one group having a special meaning - "Global". This is so called default group. All the users without any exception are the members of this group.

The default group is maintained automatically. This group can not be neither deleted nor created. There is no way neither to explicitly add nor to remove a users to or from this group. This is why this group can not have the group managers. Users are included or excluded to or from the group as they added or removed to or from the authorization database.

2.3 Domains

The domain in the context of the BaBar authorization database means a logically independent collection of users and groups records.

The following groups are defined in the current architecture of the BaBar database:

Conditions
Events
Online

3. Authorization API.

The authorization API is a part of the BdbApplication package and is available to their users through a singleton class BdbAuth.

This class definition must be included into your program via:

#include <BdbApplication/BdbAuth.hh>

A pointer to the singleton may be obtained via:

BdbAuth* theAuth = BdbAuth:instance( );

This will automatically instantiate an object of this class if this has not been done yet. The class constructor is private and can't be called directly from user's code.

Current section gives a comprehensive description on how to use the class methods.

All the methods drop onto three categories:

Informational (see subsection 3.2). These methods allow to retrieve the authorization information from the database. The methods of this group do not change the authorization database contents.
Users and groups management (see subsection 3.3). These methods will change the database contents.
Transactions management (see subsection 3.4). This is an optional group of methods aimed at the management of the Objectivity/DB transactions, if it is not provided by your application itself.

3.1 General notes on the methods invocation.

3.1.1 Errors handling.

Most of the methods of the authorization API are designed to return a simple logical value of d_Boolean. The meaning of the return value is just to indicate wether a requested operation was successive or not. More detailed information about errors is printed onto the standard output stream in the following format:

"BdbAuth[<domain>] <severity level>::<message>"

Where:

domain - is the domain name ("Conditions", "Events", or "Online"). If the message is not associated to any of the existing domains and has a common nature (database access problem, bad parameters, etc.), then this field will be empty.
severity level - indicates how serious a message is ("fatal", "error", "warning", or just "message").
message - is a message body.

3.1.2 The parameters.

Most of the singleton's methods require to specify a BaBar database domain as a parameter. This parameter has a type of d_ULong. In the current implementation the parameter may take one of the following values:

BdbDomain::Conditions

BdbDomain::Events

BdbDomain::Online

Another important parameter is so called authorization level. This parameter also has a type of d_ULong. The following values are valid:

BdbDomain::System

BdbDomain::Group

BdbDomain::User

The mentioned above parameters are checked internally for the correct range. If not, then a corresponding output message is generated and a false value is returned.

All the character strings passed as the parameters to the API methods must be the NULL-terminated strings. All the methods make their local copies of the strings.

3.2 Retrieving the information from the authorization database.

The database operations listed in this subsections require read-only access to the authorization database.

3.2.1 Checking for a user's authorization level.

METHOD:

d_Boolean BdbAuth::isAuthorized( d_ULong theDomain,

d_ULong theAuthLevel = BdbDomain::User,

const char* theAuthName = NULL );

PARAMETERS:

theDomain - BaBar database domain selector
theAuthLevel - Authorization level selector
theAuthName - Authorization name (depends on the authorization level)

DESCRIPTION:

This method allows to check wether a user calling for this method is authorized to get update access to the database on a specified authorization level.

In the current implementation the theAuthName parameter makes no sense for any authorization level except the "Group" one. In this case a group name must be supplied.

3.2.2 Obtaining user information.

METHODS:

d_Boolean BdbAuth::isSystemManager( d_ULong theDomain,

const char* theUserName );

d_Boolean BdbAuth::isGroupManager( d_ULong theDomain,

const char* theUserName,

const char* theGroupName );

d_Boolean BdbAuth::isGroupMember( d_ULong theDomain,

const char* theUserName,

const char* theGroupName );

const char* BdbAuth::getUserDescription( d_ULong theDomain,

const char* theUserName );

const char* BdbAuth::getUserCreated( d_ULong theDomain,

const char* theUserName );

PARAMETERS:

theDomain - BaBar database domain selector
theUserName - a valid user name
theGroupName - a valid group name

DESCRIPTION:

The first three methods are intended to check if the specified user is a system manager of a particular domain, or is a group manager of a particular group, or is just a member of a particular group. The positive answer corresponds to the true value upon the methods completion.

The getUserDescription method returns back a user description.

The getUserCreated returns back a string representation of the date when the user was registered in the given domain. The string has the following format:

"Sep 15 22:22 1997"

The pointers returned upon the successful completion of these methods point to the virtual addresses in the Objectivity/DB kernel cash. These strings must be immediately copied into the internal store of the caller's code.

If the functions are failed for some reason the NULL pointers are returned.

3.2.3 Obtaining group information.

METHODS:

const char* BdbAuth::getGroupDescription( d_ULong theDomain,

const char* theGroupName );

const char* BdbAuth::getGroupCreated( d_ULong theDomain,

const char* theGroupName );

PARAMETERS:

theDomain - BaBar database domain selector
theGroupName - a valid group name

DESCRIPTION:

The getGroupDescription method returns back a group description.

The getGroupCreated returns back a string representation of the date when the group was registered in the given domain. The string has the following format:

"Sep 15 22:22 1997"

If the functions are failed for some reason the NULL pointers are returned.

3.2.4 Traversing the users collections.

Use an iterator class UsersItr, defined as a nested class within a class of BdbAuth, in order to traverse the collections of users. The iterator itself must be instantiated in the following way:

BdbAuth::UsersItr ui;

There are two collections of users that may be traversed by the iterator:

all the users within a domain
all the members of a particular group

METHODS:

d_Boolean BdbAuth::UsersItr::selectAll( d_ULong theDomain );

d_Boolean BdbAuth::UsersItr::selectGroup( d_ULong theDomain,

const char* theGroupName );

d_Boolean BdbAuth::UsersItr::next( );

char* BdbAuth::UsersItr::current( );

PARAMETERS:

theDomain - BaBar database domain selector
theGroupName - a valid group name

DESCRIPTION:

The methods of selectAll and selectGroup select a collection of users. Call for a member function of selectAll allows to traverse all the users within a domain. Call for a member function of selectGroup allows to traverse all the members of a particular group.

The method of next is used to point an iterator to the next element in a selected collection of users. This method must be invoked prior to make any attempts to obtain the data. The return value of false normally means that no more data are available. The false will also be returned when the iterator was not properly initialized by calling to the one of the described above methods: selectAll and selectGroup.

The name of the currently pointed by the iterator user is available by a call to the method of current. This method returns a pointer to a character string allocated in the dynamic memory. The string must be explicitly deleted after use to prevent the memory leaks.

See the "live" examples below how to use this kind of iterator.

EXAMPLES:

// ==================================================================

// Two functions are defined in this file:

// listAllUsers( ) - prints all the known users within a domain.

// listInGroup( ) - prints all the known users within a group.

// It's assumed that Objectivity/DB transaction is already started.

// ==================================================================

...

#include <BdbApplication/BdbAuth.hh>

...

static int listAllUsers( )

{

BdbAuth::UsersItr ui;

char* user;

// -- Initialize the iterator to list ALL the known users --

if( ui.selectAll( BdbDomain::Conditions )) {

cout << "MyApp: Failed to select all the users" << endl;

return 0;

}

// -- Fetch user names one by one and print them to the --

// -- standard output --

// -- NOTE: Do not forget to delete the string. --

while( ui.next( )) {

user = ui.current( );

cout << user << endl;

delete [] user;

}

return 1;

}

...

static int listInGroup( )

{

BdbAuth::UsersItr ui;

char* user;

// -- Initialize the iterator to list a group members --

if( ui.selectGroup( BdbDomain::Conditions, "Global" )) {

cout << "MyApp: Failed to select a group members" << endl;

return 0;

}

// -- Fetch user names one by one and print them to the --

// -- standard output --

// -- NOTE: Do not forget to delete the string. --

while( ui.next( )) {

user = ui.current( );

cout << user << endl;

delete [] user;

}

return 1;

}

...

3.2.5 Traversing the groups collections.

Use an iterator class GroupsItr, defined as a nested class within a class of BdbAuth, in order to traverse the collections of groups. The iterator itself must be instantiated in the following way:

BdbAuth::GroupsItr gi;

There are two collections of groups that may be traversed by the iterator:

all the groups within a domain
all the groups a particular user belongs to

METHODS:

d_Boolean BdbAuth::GroupsItr::selectAll( d_ULong theDomain );

d_Boolean BdbAuth::GroupsItr::selectUser( d_ULong theDomain,

const char* theUserName );

d_Boolean BdbAuth::GroupsItr::next( );

char* BdbAuth::GroupsItr::current( );

PARAMETERS:

theDomain - BaBar database domain selector
theUserName - a valid user name

DESCRIPTION:

The methods of selectAll and selectUser select a collection of groups. Call for a member function of selectAll allows to traverse all the groups within a domain. Calling to a member function of selectUser allows to traverse all the groups a particular user belongs to.

The method of next is used to point an iterator to the next element in a selected collection of groups. This method must be invoked prior to make any attempts to obtain the data. The return value of false normally means that no more data are available. The false will also be returned when the iterator was not properly initialized by calling to the one of the described above methods: selectAll and selectUser.

The name of the currently pointed by the iterator group is available by a call to the method of current. This method returns a pointer to a character string allocated in the dynamic memory. The string must be explicitly deleted after use to prevent the memory leaks.

See the "live" examples below how to use this kind of iterator.

EXAMPLES:

// =====================================================================

// Two functions are defined in this file:

// listAllGroups( ) - prints all the known groups within a domain.

// listMembership( ) - prints a particular user's membership.

// It's assumed that Objectivity/DB transaction is already started.

// =====================================================================

...

#include <BdbApplication/BdbAuth.hh>

...

static int listAllGroups( )

{

BdbAuth::GroupsItr gi;

char* group;

// -- Initialize the iterator to list ALL the known groups --

if( gi.selectAll( BdbDomain::Conditions )) {

cout << "MyApp: Failed to select all the groups" << endl;

return 0;

}

// -- Fetch group names one by one and print them to the --

// -- standard output --

// -- NOTE: Do not forget to delete the string. --

while( gi.next( )) {

group = gi.current( );

cout << group << endl;

delete [] group;

}

return 1;

}

...

static int listMembership( )

{

BdbAuth::GroupsItr gi;

char* group;

// -- Initialize the iterator to list all groups --

// -- the user "root" belongs to. --

if( gi.selectUser( BdbDomain::Conditions, "root" )) {

cout << "MyApp: Failed to select a user's membership" << endl;

return 0;

}

// -- Fetch group names one by one and print them to the --

// -- standard output. --

// -- NOTE: Do not forget to delete the string. --

while( gi.next( )) {

group = gi.current( );

cout << group << endl;

delete [] group;

}

return 1;

}

...

3.3 Users, groups and domains management.

3.3.1 Add new user to the domain.

METHOD:

d_Boolean BdbAuth::createUser( d_ULong theDomain,

d_ULong theAuthLevel = BdbDomain::User,

const char* theUserName,

const char* theGroupName = NULL,

const char* theDescription = NULL );

PARAMETERS:

theDomain - BaBar database domain selector
theAuthLevel - Authorization level selector
theUserName - a user name
theGroupName - a group name (depends on the authorization level)
theDescription - user description (optional)

DESCRIPTION:

This method creates a new user record within a specified domain.

The new user is automatically placed into default "Global" group irrespective of the authorization level specified in the call to the method.

If the "System" authorization level is specified then the user is assigned as a system manager of this domain. In this case the theGroupName parameter is ignored.

If the "Group" authorization level is specified then the user is placed into a group specified by the theGroupName parameter. In this case the parameter of theGroupName must point to a valid non-NULL string, otherwise a call to the method will fail with a false value returned and corresponding message printed onto the standard output.

If the "User" authorization level is specified the theGroupName parameter is ignored.

A theDescription parameter is the optional one. It may contain any kind of information related to this user. This information is not used by the authorization API itself and is left to the authorization API users.

3.3.2 Delete a user from the domain.

METHOD:

d_Boolean BdbAuth::deleteUser( d_ULong theDomain,

const char* theUserName );

PARAMETERS:

theDomain - BaBar database domain selector
theUserName - a user name

DESCRIPTION:

This method completely removes specified user record from a domain. All the information associated with the user is lost in the authorization database.

All the references to the user are automatically removed from the groups this user was a member of.

WARNING

Do not remove yourself if you are the last system manager in this domain. Otherwise nobody will be able to maintain the domain.

3.3.3 Add new group to the domain.

METHOD:

d_Boolean BdbAuth::createGroup( d_ULong theDomain,

const char* theGroupName,

const char* theDescription = NULL );

PARAMETERS:

theDomain - BaBar database domain selector
theGroupName - a group name
theDescription - group description (optional)

DESCRIPTION:

This method creates a new group record within a specified domain.

A theDescription parameter is the optional one. It may contain any kind of information related to this group. This information is not used by the authorization API itself and is left to the authorization API users.

3.3.4 Delete a group from the domain.

METHOD:

d_Boolean BdbAuth::deleteGroup( d_ULong theDomain,

const char* theGroupName );

PARAMETERS:

theDomain - BaBar database domain selector
theGroupName - a group name

DESCRIPTION:

This method completely remove specified group record from a domain. All the information associated with the group is lost in the authorization database. All the group members are excluded from the group.

WARNING

You can not delete the default group "Global" in such a way. Any attempts to do it will produce an error status to be returned.

3.3.5 Assign/de-assign a user as a system manager.

METHOD:

d_Boolean BdbAuth::setSystemManager( d_ULong theDomain,

const char* theUserName,

d_Boolean onOff );

PARAMETERS:

theDomain - BaBar database domain selector
theUserName - a user name
onOff - new status of the user

DESCRIPTION:

This method changes the status of the specified user as a system manager of the domain. The new status is specified via a boolean variable of type d_Boolean. If the parameter onOff is set to true then the user will be assigned as a system manager.

The previous status of the user is never checked.

WARNING

Do not change your own status from the system manager to an ordinary user (or even group manager) if you are the last system manager in this domain. Otherwise nobody will be able to maintain the domain.

3.3.6 Assign/de-assign a user as a group manager.

METHOD:

d_Boolean BdbAuth::setGroupManager( d_ULong theDomain,

const char* theUserName,

const char* theGroupName,

d_Boolean onOff );

PARAMETERS:

theDomain - BaBar database domain selector
theUserName - a user name
theGroupName - a group name
onOff - new status of the user

DESCRIPTION:

This method changes the status of the specified user as a manager of the specified group. The new status is specified via a boolean variable of type d_Boolean. If the parameter onOff is set to true then the user will be assigned as the group manager.

This method checks the previous status of the user. If the onOff parameter does not change the current status of the user then false is returned.

3.3.7 Include a user into a group.

METHOD:

d_Boolean BdbAuth::includeUser( d_ULong theDomain,

const char* theUserName,

const char* theGroupName )

PARAMETERS:

theDomain - BaBar database domain selector
theUserName - a user name
theGroupName - a group name

DESCRIPTION:

This method makes a user a member of a specified group.

You can not include into default group "Global". This group is maintained in a special way.

3.3.8 Exclude a user from a group.

METHOD:

d_Boolean BdbAuth::excludeUser( d_ULong theDomain,

const char* theUserName,

const char* theGroupName );

PARAMETERS:

theDomain - BaBar database domain selector
theUserName - a user name
theGroupName - a group name

DESCRIPTION:

This method removes a user from a specified group even if the user was a manager of this group.

You can not exclude from default group "Global". This group is maintained in a special way.

3.3.9 Initialize an authorization domain.

METHOD:

d_Boolean BdbAuth::initialize( d_ULong theDomain );

PARAMETERS:

theDomain - BaBar database domain selector

DESCRIPTION:

This method must be the first one used after the authorization database or the federated database has been created. Another good reason to use this method is to destroy the existing information and start creating it from the scratch.

The method initializes the internal structure of the authorization database within specified domain. The method will perform the following sequence of actions:

All the existing contents of the authorization database domain will be completely destroyed.
The default group of "Global" will be created.
The only user having your UNIX name will be created.
The user will be included into default group as the group member.
This user will be assigned as a system manager of the domain.

If the authorization database does not exist on the moment when the method is called then:

The database file of "Authorization.xyz.DB" will be automatically created.
The database file will appear in the same directory where your "xyz.FDDB" is located.

When the authorization database domain is being initialized for the first time, then ANY user may perform this action. This user will be assigned as "initial system manager". This exact string will be used as the user description in the database.

WARNING

Be careful - this method will destroy all the existing authorization information within given domain.

3.3.10 Delete an authorization domain.

METHOD:

d_Boolean BdbAuth::deleteDomain( d_ULong theDomain );

PARAMETERS:

theDomain - BaBar database domain selector

DESCRIPTION:

The method completelly remove all the authorization information related to the specified domain from the authorization database.

3.4 Transactions management.

In addition to the API methods directly operating under the authorization database contents four additional methods have been added to the API. These methods aims at the Objectivity/DB transaction management if it is not provided by your application.

METHODS:

void BdbAuth::startUpdate( const char* theTag = NULL );

void BdbAuth::startRead( const char* theTag = NULL );

void BdbAuth::abort( );

void BdbAuth::commit( );

PARAMETERS:

theTag - a transaction tag

DESCRIPTION:

These transaction management methods are based at the ooSession class provided by the Objectivity. This class uses an environment variable of "OO_FD_BOOT" in order to locate a federated database boot file.

EXAMPLES:

// =====================================================================

// This example illustrates how to use the transaction management

// methods in your application in order to initialize the internal

// structure of the authorization database for the "Conditions" domain.

// The default group of "Global" will be created.

// The only user will be created - the one having your UNIX name.

// This user will possess the system management privileges.

// All the information previously stored in this authorization domain will

// be lost.

// NOTE: This operation is available only if you already have the system

// management privileges in this domain or if the domain is not

// initialized yet.

// =====================================================================

...

#include <BdbApplication/BdbAuth.hh>

...

main( )

{

BdbAuth* theAuth = BdbAuth::instance( );

...

theAuth->startUpdate( ); // Start Update-mode transaction.

theAuth->initialize( BdbDomain::Conditions );

theAuth->startCommit( ); // Commit the changes to the database.

...

}

...

4. Authorization management utility.

One possible way to maintain the authorization database contents is to use a specially designed utility BdbAuthCmd. This command line utility allows to get an easy interactive access to the full spectrum of management and browsing procedures provided by the API described in the previous section.

4.1 The general notes on the input syntax.

Since the most of the authorization API methods return a boolean value to indicate the result of an operation, the utility is designed to propagate this status back to your shell. The conventions on return status applied here are the following:

0 - means that an operation has completed successfully.
1 - indicates an error. The corresponding message explaining error reason is printed via the standard output stream. See the section 3.1.1 for the format of this message.

For some of the complex services provided by the utility, such as users and groups listings, there is no direct mapping of one-to-one to the authorization API methods. In this case the utility will always return success status code.

The utility recognizes the following syntax:

% BdbAuthCmd { help | <command-name> [par1] [par2] ... }

A list of all the commands recognized by the utility and their meaning can be obtained by typing:

% BdbAuthCmd help

If you want to get more instructions on a particular command syntax specify a command-name without any parameters:

% BdbAuthCmd <command-name>

The precise syntax, meaning, and output of each command recognized by the utility will be described later in separate subsections.

4.1.1 The parameters.

There are two types of parameters recognized by the utility that have a fixed set of their values:

domain
authorization level

The domain is selected by their name that may have the following values:

"Conditions"
"Events"
"Online"

It is not necessarily to specify the full name of a domain - it's quite enough to print the first symbol only in order to avoid the ambiguity problem.

Therefor any name may be shortened to the first case-insensitive letter ("c", "C", "e", "E", "o", "O").

An authorization level is also selected by one of the following keywords:

"System"
"Group"
"User"

These keywords can also be shortened to the first case-insensitive letters ("s", "S", "g", "G", "u", "U").

4.2 Check for a user's authorization privileges.

SYNTAX:

% BdbAuthCmd isauth <domain> <auth-level> [<group-name>]

PARAMETERS:

domain - a domain name.
auth-level - an authorization level.
group-name - a group name. Depends on the authorization level.

DESCRIPTION:

This command has a direct mapping onto a corresponding authorization API method. See subsection 3.2.1 for the description.

The last parameter is mandatory for the "Group" authorization level and is ignored for the other levels.

EXAMPLES:

All of these commands will do the same for the domain of "Conditions":

% BdbAuthCmd isauth Conditions System anyuser

% BdbAuthCmd isauth Conditions Group anyuser anygroup

% BdbAuthCmd isauth Conditions User anyuser

4.3. Initialize a domain.

SYNTAX:

% BdbAuthCmd dinit <domain>

PARAMETERS:

domain - a domain name.

DESCRIPTION:

This command has a direct mapping onto a corresponding authorization API method. See subsection 3.3.9 for the description.

EXAMPLES:

All of these commands will do the same for the domain of "Conditions":

% BdbAuthCmd dinit Conditions

% BdbAuthCmd dinit Condi

% BdbAuthCmd dinit c

4.4 Delete all the authorization information in a domain.

SYNTAX:

% BdbAuthCmd ddelete <domain>

PARAMETERS:

domain - a domain name.

DESCRIPTION:

The command has a direct mapping onto a corresponding authorization API method. See subsection 3.3.10 for the description.

EXAMPLES:

The following command will destroy the authorization information at the domain "Events":

% BdbAuthCmd ddelete Events

4.5 Create a new user.

SYNTAX:

% BdbAuthCmd ucreate <domain> <auth-level> <user-name> [<group-name>] <descrip>

PARAMETERS:

domain - a domain name.
auth-level - an authorization level.
user-name - a user name.
group-name - a group name. Depends on the authorization level. See command description below.
descrip - a user description string.

DESCRIPTION:

This command has a direct mapping onto a corresponding authorization API method. See subsection 3.3.1 for the description.

The parameter of group-name is mandatory for the "Group" authorization level and must me omitted for the other levels.

EXAMPLES:

All of these commands will create "anyuser" with different privileges in different domains:

% BdbAuthCmd ucreate Conditions System anyuser "This is a new system manager"

% BdbAuthCmd ucreate Events Group anyuser anygroup "New member of the group"

% BdbAuthCmd ucreate Online User anyuser "Just a simple user"

4.6 Delete a user.

SYNTAX:

% BdbAuthCmd udelete <domain> <user-name>

PARAMETERS:

domain - a domain name.
user-name - a user name.

DESCRIPTION:

This command has a direct mapping onto a corresponding authorization API method. See subsection 3.3.2 for the description.

EXAMPLES:

The following commands will delete user "anyuser" from all the known domains:

% BdbAuthCmd udelete Conditions anyuser

% BdbAuthCmd udelete Events anyuser

% BdbAuthCmd udelete Online anyuser

4.7 Create a new group.

SYNTAX:

% BdbAuthCmd gcreate <domain> <group-name> <descrip>

PARAMETERS:

domain - a domain name.
group-name - a group name.
descrip - a group description string.

DESCRIPTION:

This command has a direct mapping onto a corresponding authorization API method. See subsection 3.3.3 for the description.

EXAMPLES:

All of these commands will create "NewGroup" at all the known domains:

% BdbAuthCmd gcreate Conditions NewGroup "This must be a perfect group"

% BdbAuthCmd gcreate Events NewGroup "But this one is better"

% BdbAuthCmd gcreate Online NewGroup "no more comments"

4.8 Delete a group.

SYNTAX:

% BdbAuthCmd gdelete <domain> <group-name>

PARAMETERS:

domain - a domain name.
group-name - a group name.

DESCRIPTION:

This command has a direct mapping onto a corresponding authorization API method. See subsection 3.3.4 for the description.

EXAMPLES:

All of these commands will delete "ObsoleteGroup" from two domains:

% BdbAuthCmd gcreate Conditions ObsoleteGroup

% BdbAuthCmd gcreate Events ObsoleteGroup

4.9 Include a user into a group.

SYNTAX:

% BdbAuthCmd uinclude <domain> <user-name> <group-name>

PARAMETERS:

domain - a domain name.
user-name - a user name.
group-name - a group name.

DESCRIPTION:

This command has a direct mapping onto a corresponding authorization API method. See subsection 3.3.7 for the description.

EXAMPLES:

The following command will register already existing user "anyuser" as a member of "NewGroup" group:

% BdbAuthCmd uinclude Conditions anyuser NewGroup

4.10 Exclude a user from a group.

SYNTAX:

% BdbAuthCmd uexclude <domain> <user-name> <group-name>

PARAMETERS:

domain - a domain name.
user-name - a user name.
group-name - a group name.

DESCRIPTION:

This command has a direct mapping onto a corresponding authorization API method. See subsection 3.3.8 for the description.

EXAMPLES:

The following command will exclude already existing group member "anyuser" from the "ObsoleteGroup" group:

% BdbAuthCmd uexclude Conditions anyuser ObsoleteGroup

4.11 Assign/de-assign a user as a system manager of a domain.

SYNTAX:

% BdbAuthCmd setsysmgr <domain> <user-name> <yes-no>

PARAMETERS:

domain - a domain name.
user-name - a user name.
yes-no - new status of the user. The parameter can take one of two values: "Yes" or "No". The value of the parameter can be shortened to the first case-insensitive symbol. For example: "y", "Y". See the command description below for more details on the command usage.

DESCRIPTION:

This command has a direct mapping onto a corresponding authorization API method. See subsection 3.3.5 for the description.

The last parameter allows to toggle the existing user status. The value of this parameters is treated as the boolean one. So if the "Yes" value is specified, then the user will be assigned as a system manager of the specified domain.

This command does not check the previous status of the user.

EXAMPLES:

The following command will assign already existing user "anyuser" as a system manager at "Conditions" domain:

% BdbAuthCmd setsysmgr Conditions anyuser Yes

4.12 Assign/de-assign a user as a manager of a group.

SYNTAX:

% BdbAuthCmd setgrpmgr <domain> <user-name> <yes-no>

PARAMETERS:

domain - a domain name.
user-name - a user name.
group-name - a group name.
yes-no - new status of the user. The parameter can take one of two values: "Yes" or "No". The value of the parameter can be shortened to the first case-insensitive symbol. For example: "y", "Y". See the command description below for more details on the command usage.

DESCRIPTION:

This command has a direct mapping onto a corresponding authorization API method. See subsection 3.3.6 for the description.

This command makes a check for the previous status of the user before to change it to the new one. If the user already has desired status then the operation will fail with corresponding error message.

EXAMPLES:

The following command will assign already existing user "anyuser" as a group manager at "NewGroup" group:

% BdbAuthCmd setgrpmgr Conditions anyuser NewGroup Yes

4.13 Get a list of all the registered users at a domain.

SYNTAX:

% BdbAuthCmd lsusers <domain>

PARAMETERS:

domain - a domain name.

DESCRIPTION:

This command prints onto a standard output a list of all the users registered in the specified domain.

Each user record is shown at a separate line. The record contains the following fields:

user name
user privileges as a system manager:
"(SYS)" - is a system manager
"( )" - is not a system manager.
registration date and time
description string

At the end of the list the total number of found users is printed.

EXAMPLES:

The following command will print a list of the users at "Conditions" domain:

% BdbAuthCmd lsusers Conditions

This command might produce the following output:

####################################################

######## BaBar Database Authorization Manager ######

####################################################

Users in domain "Conditions" :

gapon (SYS) Sep 19 19:44 1997 initial system manager

pathfinder ( ) Sep 22 15:49 1997 *** now on Mars ***

Total of 2 users were found.

4.14 Get a list of all the registered groups at a domain.

SYNTAX:

% BdbAuthCmd lsgroups <domain>

PARAMETERS:

domain - a domain name.

DESCRIPTION:

This command prints onto a standard output a list of all the groups registered in the specified domain.

Each group record is shown at a separate line. The record contains the following fields:

group name
registration date and time
description string

At the end of the list the total number of found groups is printed.

EXAMPLES:

The following command will print a list of the groups at "Conditions" domain:

% BdbAuthCmd lsgroups Conditions

This command might produce the following output:

####################################################

######## BaBar Database Authorization Manager ######

####################################################

Groups in domain "Conditions" :

Global Sep 19 19:44 1997 default group

AnotherGroup Sep 19 19:44 1997 --

Virtual Sep 19 19:49 1997 meaningless group

Virtual_1 Sep 22 15:47 1997 just one more group

Total of 4 groups were found.

4.15 Get a list of groups where a user has a membership.

SYNTAX:

% BdbAuthCmd lsmembership <domain> <user-name>

PARAMETERS:

domain - a domain name.
user-name - a user name.

DESCRIPTION:

This command prints onto a standard output a list of all the groups a user is a member of.

Each group record is shown at a separate line. The record contains the following fields:

group name
registration date and time
description string

At the end of the list the total number of found groups is printed.

EXAMPLES:

The following command will print a list of the groups where the user "gapon" has a membership:

% BdbAuthCmd lsmembership Conditions gapon

This command might produce the following output:

####################################################

######## BaBar Database Authorization Manager ######

####################################################

Groups in domain "Conditions" related to user "gapon" :

Global Sep 19 19:44 1997 default group

Virtual_1 Sep 22 15:47 1997 just one more group

Total of 2 groups were found.

4.16 Get a list of a group members.

SYNTAX:

% BdbAuthCmd lsmembers <domain> <group-name>

PARAMETERS:

domain - a domain name.
group-name - a user name.

DESCRIPTION:

This command prints onto a standard output a list of all the users - members of a specified group.

Each user record is shown at a separate line. The record contains the following fields:

user name
user privileges as a system manager or/and a manager of this group:
"(SYS,GRP)" - is a system manager and a manager of the group.
"(SYS, )" - is a system manager.
"( ,GRP)" - is a manager of the group.
"( , )" - a simple member of the group.
registration date and time
description string

At the end of the list the total number of found users is printed.

EXAMPLES:

The following command will print a list of members of the group "Virtual_1":

% BdbAuthCmd lsmembers Conditions Virtual_1

This command might produce the following output:

####################################################

######## BaBar Database Authorization Manager ######

####################################################

Users in domain "Conditions" and group "Virtual_1" :

gapon (SYS, ) Sep 19 19:44 1997 initial system manager

pathfinder ( ,GRP) Sep 22 15:49 1997 *** just came back from Mars ***

explorer ( , ) Sep 24 21:01 1997 -- no comments --

Total of 2 users were found.

4.17 Print a list of known commands.

SYNTAX:

% BdbAuthCmd help

DESCRIPTION:

Prints a list of known commands along with their short description onto a standard output.

References

[1] "The Design of the BABAR Database Management System", David R.Quarrie, 26th March 1997, /BFROOT/doc/Computing/Databases/www/frames.htm

1. Introduction 1

2. Users, groups and domains in the authorization database 3

2.1 Users 3

2.1.1 Simple user 3

2.1.2 Group member 3

2.1.3 Group manager 4

2.1.4 System manager 4

2.2 Groups 4

2.2.1 Default group 5

2.3 Domains 5

3. Authorization API 6

3.1 General notes on the methods invocation 6

3.1.1 Errors handling 6

3.1.2 The parameters 7

3.2 Retrieving the information from the authorization database 8

3.2.1 Checking for a user's authorization level 8

3.2.2 Obtaining user information 8

3.2.3 Obtaining group information 9

3.2.4 Traversing the users collections 10

3.2.5 Traversing the groups collections 12

3.3 Users, groups and domains management 15

3.3.1 Add new user to the domain 15

3.3.2 Delete a user from the domain 15

3.3.3 Add new group to the domain 16

3.3.4 Delete a group from the domain 16

3.3.5 Assign/de-assign a user as a system manager 17

3.3.6 Assign/de-assign a user as a group manager 17

3.3.7 Include a user into a group 18

3.3.8 Exclude a user from a group 18

3.3.9 Initialize an authorization domain 19

3.3.10 Delete an authorization domain 20

3.4 Transactions management 21

4. Authorization management utility 23

4.1 The general notes on the input syntax 23

4.1.1 The parameters 23

4.2 Check for a user's authorization privileges 24

4.3. Initialize a domain 24

4.4 Delete all the authorization information in a domain 25

4.5 Create a new user 25

4.6 Delete a user 26

4.7 Create a new group 27

4.8 Delete a group 27

4.9 Include a user into a group 28

4.10 Exclude a user from a group 28

4.11 Assign/de-assign a user as a system manager of a domain 29

4.12 Assign/de-assign a user as a manager of a group 29

4.13 Get a list of all the registered users at a domain 30

4.14 Get a list of all the registered groups at a domain 31

4.15 Get a list of groups where a user has a membership 32

4.16 Get a list of a group members 33

4.17 Print a list of known commands 34

References 35

Table of contents 36

1. Budker Institute of Nuclear Physics (BINP), Novosibirsk, Russia,

e-mails: gapon@SLAC.Stanford.EDU, I.A.Gaponenko@inp.nsk.su