User Admin Extension

The User Admin Extension bundle delivers functionality additional to User Admin Bundle, for management of groups and users.

Contents:

• Bundle Information
  • Bundle JAR
  • Import
  • Export
• Overview
• Services
  • Simple Login
  • Pluggable Commands
• Console Commands
• Configuration
  • Visual Administration
    • Viewing Existing Roles
    • Managing Roles
    • Management Tasks
  • System Properties
• Troubleshooting
• References

Bundle Information

Bundle JAR

The JAR file of the User Admin Extension bundle is usradmex.jar and is located in the bundles directory.

Import

Export

The UserAdmin Extension bundle exports the com.prosyst.mbs.services.useradmin package, which holds interfaces providing functionality additional to the OSGi defined role based authorization system.

Overview

The User Admin Extension bundle provides functionality specific for the ProSyst implementation of the UserAdmin service defined by the OSGi specification. It registers two services - a Simple Login service and a Pluggable Commands service. The first provides methods for easier user authorization and the second allows user management through the framework console.

When the User Admin Extension bundle is started, it gets a reference to the User Admin service of the User Admin Bundle and generates an initial roles structure as follows:

• administration
  • admin

The "administration" group holds roles with administrative rights. The admin user represents the default user role for this group. This user can create other users and assign to them the necessary rights. The password of admin is recorded as a credential, named password, with admin value. The creation of this initial administrator user is controlled by two system properties - mbs.useradmin.default.username, mbs.useradmin.default.password, described the "System Properties" section.

In case the User Admin service is not registered, a user can login as anonymous. This is possible only if the mbs.useradmin.anonymousConnect system property is true, and the user name is null or an empty String. In case the system property is set to false, on attempt to login, a java.lang.Exception is thrown.

Services

Simple Login

The Simple Login service supports user login to the ProSyst mBS framework and therefore, it is a simple mechanism for authentication to the framework's user management system. After a user successfully logs in, bundles can examine its authorization parameters. The Simple Login service is represented by the com.prosyst.mbs.services.useradmin.SimpleLogin interface. Authorization for this service is delivered by com.prosyst.mbs.services.useradmin.Authorization which extends the org.osgi.service.useradmin.Authorization. In addition to checking the roles of a requester, it allows user logout.

Note: To enable login of miscellaneous users, framework administrators should assign passwords to them as credentials.

Note: Developers can retrieve the format of the password credential from the SimpleLogin.PASSWORD field. The username property is accessible through SimpleLogin.USERNAME.

The code snippet that follows logs in the initial user admin and checks whether it owns the "administration" role.

                      . . .
  BundleContext bc;
  String userName = "admin";
  String password = "admin";
                      . . .
  ServiceReference sLoginRef = bc.getServiceReference(SimpleLogin.class.getName());
  SimpleLogin sLogin = (SimpleLogin) bc.getService(sLoginRef);
  Authorization autho = sLogin.login(userName, password);
  boolean okFlag = autho.hasRole("administration");  

  if(okFlag) {
    System.out.println("The user is an administrator!"); 
  }

  autho.logout();

The Simple Login service also allows developers to pass authorization information to bundles that restrict the access to their resources. A carrier of such information can be a data stream or a thread. By using the service, you can attach an Authorization object to an intermediary object that will handle it from the User Admin Extension bundle to another application. The methods you can use for associating Authorization objects are getAuthorization and setAuthorization.

The functionality of the services and utilities above can be accessed partially over PMP. Remote PMP Services can refer to and invoke only the methods of the com.prosyst.mbs.services.useradmin.UserAdminRemote interface, implemented by the Simple Login service object.

Pluggable Commands

The User Admin Extension bundle registers a PluggableCommands service under the com.prosyst.util.pcommands.PluggableCommands interface, which adds the ua console command group. See below the description of the commands.

Console Commands

Configuration

Visual Administration

The User Admin Extension bundle provides a custom property editor for configuration of roles - groups and users, through mConsole application. The editor offers to administrators a user-friendly interface to create and remove new users and groups and modify their relationships.

To activate the property editor of the User Admin Extension bundle:

1. Start the ProSyst mBS.
2. Start mConsole and connect to the server.
3. To load the property editor, locate the osgi/User Admin Extension node in the bundle tree, and unfold it to see the User Admin Configuration.

Initially, the "administration" group and the admin user are displayed because they are automatically created at bundle's startup.

The following topics are discussed in the current chapter:

• Viewing Existing Roles
  • Roles Panel
    • List View
    • Tree View
  • Info Panel
    • Membership Panel
      • User Membership
      • Group Members
    • Properties Panel
• Managing Roles
  • Tree View
  • List View
    • Users
    • Groups
• Management Tasks
• Create User
• Create Group
• Add an Existing User to a Group
• Add Existing Group as a Member
• Cancel User Membership
• Cancel Group Membership
• Destroy a User
• Destroy a Group

Viewing Existing Roles

The property editor is separated into two main panels - a Roles panel to the left, where all roles are listed - in tree or list view, according to the current settings, and an Info panel to the right, where details about the currently selected role are displayed.

Figure 1: The Custom Property Editor of the User Admin Extension Bundle - List View

Figure 2: Tree View

Roles Panel. There are two views of the property editor - as a tree and as a list, which are relevant to the left pane only. The view is controlled by the leftmost button at the bottom, which toggles its name according to the current view - to List View when the roles are displayed as a tree and Tree View otherwise. To refresh the user tree, mainly if some users are added by another server administrator or by a bundle in a program way, use the Refresh button.

• In List view Users and Groups are displayed in two separate panes to the left - Users at the top and Groups at the bottom.
• In Tree view, groups are arranged according to their membership. A group is displayed as a subnode to all of the groups it is a member of. If a group isn't a member of any other group, then it is displayed as a root node on the first level. Basic groups are marked byicon, required groups - by, and users - by.

  Note: Users, which are not members of any group, are not displayed.

The property editor allows creating loops of membership. For example: if the group java_programmers is a member of the group mBServer and also has this group as a member, then a membership loop is present. In tree view this case is presented as one of the groups is added as a leaf node and no members of it are displayed, because it is already present up in the tree, where all of its members are listed.

Figure 3: Membership Loop

Note: Though creating membership loops is allowed, it is strongly recommended loops of required members to be avoided. Users, that are members of groups that participate in a loop of required members, never have access when membership in one of this groups is required.

Info Panel. The right pane, which is also separated in two, displays details about the item selected in the left. The top panel shows details about its membership, and the lower - its properties.

• Membership Panel
  • When a user is selected, the top pane to the right displays Membership of this user - all groups in which this user participates, are listed. The user itself and the role user.anyone are also present, because membership is according to roles, and every user is a member of itself as a role and to the role user.anyone.
  • When a group is selected, the panel label changes to Members. All roles that are members of the group are displayed. Basic groups are marked by icon, required groups - by, and users - by.
• Properties Panel. The lower right pane displays properties of the selected role. Both users and groups may have properties. Users always have at least one property - username. You may use this panel to manage user or group properties. If you want to remove a property, just select it and hit Remove. To add a new property, use the Add button and you will be prompted to enter a new key-value pair in the following dialog:
  
  
  Figure 4: Adding a Custom Property to a User.

Managing Roles

Role management is performed in the left, Roles panel. The way of management depends on the selected view. In both views you may use the provided buttons or the pop-up menu.

Tree View. Six buttons are available on the top of the Roles panel in tree view.

Icon Name Active Description Create new user Always. Opens a dialog box, where the properties of the new user must be entered. Add existing user Only when a group is selected. Opens a dialog box listing all existing users, thus allowing you to add the user as a member of the group, which was selected when the dialog was invoked. Remove user Only when a user is selected. Terminates the membership of this user, in the group. Create new group Always. Opens a dialog box, where properties of the new group must be added. Add existing group Only when a group is selected. Opens a dialog box, where all existing groups are listed. Groups may be added as required or basic members of the currently selected one. Remove group Only when a group is selected, which is a member of another group. The membership of the group in the one, represented by the parent node, is canceled.

These actions are available as commands in a pop-up menu, invoked on the subject node. The pop-up menu is identical for all nodes, only the activity of its items is different according to the selection.

Pop-up Menu Icon Name Active Analogous Button Description Create User Always. Create new user Creates a new user. Create Group Always. Create new group Creates a new group. Add User Group is selected. Add existing user Adds a user as a member to the selected group. Add Group Group is selected. Add existing group Adds a group as a member of the selected one. Remove When a role (user or group), member of another role, is selected. Remove user/ Remove group Removes the selected role from the membership list of the role, represented by the parent node. - Destroy Always. - After applying this command to a role, the role will no longer exist. - Change Password User is selected. - Issues a dialog for changing the user password.

List view. In list view user and group management is separated, the way their visual representation is. The buttons above the upper panel and the panel's pop-up menu control the users list. The bottom panel and the buttons above it, manage the groups. Both lists react to double click on a particular item, which action brings up a membership dialog.

Users:

Pop-up Menu Icon Name Description Add New User Creates a new user. Also available as a button. - Edit User Membership Opens a dialog box, in which the list of groups, where the user is a member, may be edited. Available at double click on the user entry. Destroy User Deletes the user from the user list. Available as a button. - Change Password Changes the user password.

Groups:

Pop-up Menu Icon Name Description Add New Group Creates a new group. Also available as a button. - Edit Members Allows adding/removing users/groups as members of this group. Available at double click on the group entry. Destroy Group Deletes the group from the group list. Available as a button.

Management Tasks

Create User. A user may be created in several ways:

• Tree View -> pop-up menu -> Create User.
• Tree View -> Create new user button.
• List View -> Users pane -> pop-up menu -> Add New User.
• List View -> Users pane -> Create new user button.

The following dialog box appears when a new user is being created:

The Create user dialog consists of two tabs. Only the User Name and password fields from the first tab are compulsory to be filled in.

• General tab.
  • User Name. Required. This field must contain the identifier, which the user will user when logging in.
  • Password and Confirm password. Required. These two fields must contain identical values. This is the password which the user will use for authentication when login in.
  • Membership. This panel contains a list of all currently existing groups. Each group is preceded by a check box. A selected check box, means that after creation, this user will be added as a member of the group.
• Personal Information tab. This tab contains miscellaneous information, which is optional, but may give more sophisticated information for user authentication. All of the values that are entered in the fields of this tab are added as properties of the specific user. You may also define other properties, using the Add button at the bottom of the tab. You are prompted to enter the new key-value pair in a dialog like the one displayed on Figure 4.

Create Group. A new group may be created in the following ways:

• Tree View -> pop-up menu -> Create Group.
• Tree View -> Create new group button.
• List View -> Groups pane -> pop-up menu -> Add New Group.
• List View -> Groups pane -> Create new group button.

When a new group is created, the following dialog must be filled in:

Figure 6: Creating a New Group

Enter the new Group Name and then optionally select which of the existing users should participate in the new group and to which of the groups the new one will be a basic and/or required member.

Add an Existing User to a Group. You can attach a user to many groups, as each group suggests a different level of authorization. In this way, the user obtains more roles for access to certain resources. To add an existing user as a member to an existing group, you may do the following:

• Tree View. Select the group, to which the user will be added and invoke either of:
  • pop-up menu -> Add User
  • Add existing user button
  The following dialog appears:
  
  
  Figure 7: Adding a User to a Group in Tree View
  
  In this dialog select the check box in front of the user.
• List View.
  • Users panel. Select the user which will be added to the group and do one of the following:
    • double click on the user
    • select pop-up menu -> Edit user membership
    In the appearing dialog select the group of which the user will be a member:
    
    
    Figure 8: Edit User Memberships
    
  • Groups panel. Select the group, to which the user will be added and:
    • select pop-up menu -> Edit Members, or
    • double click it.
    The dialog that appears contains three panes. The topmost Users pane displays all currently existing users, and the ones that are currently members of the selected group, are preceded by selected check boxes. Select the check box in front of the user you wish to add as a member.
    
    
    Figure 9: Edit Group Members Dialog

Add Existing Group as a Member. To add group1 as a member of group2:

• Tree View. Select group2 and either:
  • click Add existing group button, or
  • select pop-up menu -> Add group.
  The Add Groups dialog appears:
  
  
  Figure 10: Add Groups Dialog
  
  All existing groups are listed both in the upper pane - Basic Members and in the lower - Required Members. Select the check box in front of group1, in the upper pane, if you want to add it as a basic member of group2 or in the lower, if you want group1 to be a required member of group2.
• List View. In the Groups pane select group2. Then either:
  • double click it, or
  • select Edit Members from the pop-up menu.
  The Edit Members dialog shown on Figure 9, appears. Check the box in front of group1 either in the Basic Members list, if you want it to be a basic member of group2, or in the Required Members list otherwise.

Cancel User Membership. To remove a user from the members list of a group you may:

• Tree View. Select the user where it appears as a subnode of the group in which you are about to cancel user's membership. Invoke:
  • Remove user button, or
  • pop-up menu -> Remove.
• List View.
  • Users panel. Select the user, whose membership you want to cancel and:
    • double click on it, or
    • invoke pop-up menu -> Edit user membership.
    In the Edit User Memberships dialog (see Figure 8) uncheck the check box in front of the group.
  • Groups panel. Select the group and:
    • double click it, or
    • select pop-up menu -> Edit Members.
    The Edit Members dialog, displayed on Figure 9, appears. Uncheck the check box in front of the user, whose membership you want to cancel.

Cancel Group Membership. To remove group1 from the members list of another group2, do one of the following:

• Tree View. Select group1, where it appears as a subnode of group2, and either:
  • Click the Remove group button, or
  • select pop-up menu -> Remove.
• List View. In the Groups panel, select the parent group, group2. Invoke the Edit Members dialog (available on Figure 9) by:
  • double click or
  • from the pop-up menu.
  Then locate group1 in the Basic Members pane and/or in the Required Members one and uncheck the check box(es) in front of it.

Destroy a User. When you destroy a user, it is deleted from the users database.

• Tree View. Select the user anywhere it appears in the tree, and select pop-up menu -> Destroy.
• List View. Select the user in the Users pane and:
  • press Destroy user button, or
  • invoke pop-up menu -> Destroy user.

Destroy a Group. To delete a group:

• Tree View. Select the group anywhere in the tree and invoke pop-up menu -> Destroy.
• List View. Select the group in the Groups pane and:
  • hit the Destroy group button, or
  • select pop-up menu -> Destroy Group.

System Properties

To use successfully the above system properties, you have to set them:

• In the default.prs file before the framework is started.
• At framework runtime through the set console command or the mConsole before the User Admin Extension bundle is started. Otherwise, you have to restart the bundle.

Troubleshooting

The User Admin Extension does not depend on the UserAdmin Bundle, but it uses the User Admin service. If the UserAdmin Bundle is not running in the framework, thus preventing the registration of the User Admin service, you can only log-in if the mbs.useradmin.anonymousConnect system property is set to true.

If you uninstall the User Admin Extension while in eager update mode, the PMP bundle also stops. Then, when you install the User Admin Extension again, you must start the PMP bundle manually. If you do not start it, you will not be able to log through remote applications, like mConsole.

References

• OSGi User Admin Service API.
• Simple Login Service API.
• User Admin Bundle Description.

OSGi Bundles