User Admin Developer Guide

Basic Principles

The User Admin service provides specific authentication and management of users. It is realized according to the OSGi User Admin Service specification. It arranges users in groups and stores user attributes, such as name, properties and credentials in a database, called "useradmin".

The service does not allow a user and a group to have one and the same name.

The main unit in the User Admin service is the org.osgi.service.useradmin.Roleobject. Generally, such an object represents a role that can be a user or a group. An org.osgi.service.useradmin.User object represents a user, and an org.osgi.service.useradmin.Group instance stands for a group.

The User Admin service restricts the access to user attributes, such as properties and credentials, by detecting the existence of an org.osgi.service.useradmin.UserAdminPermission with action that specifies the modification rights (in case framework security is on).

Credentials and properties of every user are stored in java.util.Dictionary objects. The keys in these objects are strings, and the values – strings or byte arrays. When assigning a new credential or property, a developer should comply with this format.

The example that follows creates a group called "OSGi" with two basic groups – "programmers" and "documentators". The "programmers" group contains the basic members "pascal_programmers" and "c_programmers" and the required member "java_programmers". The "documentators" group includes the "designers" required member – (R) and "programmers" as a basic member – (B). The following users are specified:

• programmers
  • java_programmers(R)
    • Jane
    • Peter
  • pascal_programmers(B)
    • John
  • c_programmers(B)
    • Jane
    • Peter
    • John
• documentators
  • designers(R)
    • Jane
    • George
  • programmers(B)

Next, the checkUsers method checks whether Peter owns the "documentators" and "programmers" roles.

Here is the example of using the User Admin service:

           . . .
public class UserAdminTest implements BundleActivator {
  private ServiceReference userAdmRef;
  private UserAdmin userAdm;

  public void start(BundleContext bc) throws BundleException {
    userAdmRef = bc.getServiceReference(UserAdmin.class.getName());
    userAdm = (UserAdmin) bc.getService(userAdmRef);

    Group server = (Group)userAdm.createRole("OSGi", Role.GROUP);

    // Forming "programmers"
    Group programmers = (Group)userAdm.createRole("programmers", Role.GROUP);
    Group jProgr = (Group)userAdm.createRole("java_programmers", Role.GROUP);
    Group cProgr = (Group)userAdm.createRole("c_programmers", Role.GROUP);
    programmers.addRequiredMember(jProgr);
    programmers.addMember(cProgr);
           . . .

    // Adding a programmer
    User peter = (User)userAdm.createRole("Peter", Role.USER);
    jProgr.addMember(peter);
    cProgr.addMember(peter);
           . . .

    // Forming "documentators"
    Group documentators = (Group)userAdm.createRole("documentators", Role.GROUP);
    documentators.addMember(jProgr);

    // Specifying user properties
    Dictionary props = peter.getProperties();
    props.put("Position", "Department Manager".getBytes());
    Dictionary creds = peter.getCredentials();
    creds.put("password", peter.getName().getBytes());
           . . .

    // Adding all users to "OSGi"
    server.addMember(documentators);
    server.addMember(programmers);

    // Authorizing created members
    checkUsers(documentators, peter);
    checkUsers(programmers, peter);
  }
           . . .
  public void checkUsers(Role role, User user) {
           . . .
    Authorization autho = userAdm.getAuthorization(user);
    boolean ok = autho.hasRole(role.getName());
    System.out.println("In group " + role.getName() + " ? " + ok);
           . . .
  }
}