This page describes an older version of the product. The latest stable version is 14.2.

Directory Management


The directory provides the means for managing users and roles. User and role information stored in a persistent storage need to be accessed for authentication purposes and for management (adding/modifying,associating, etc.).

security-seq5.PNG

The SecurityManager access the directory for authenticating the user. The authentication process retrieves the user credentials and permissions. On the other hand, you need some tool to access the directory for managing the users/roles. It can be as simple as SQL statements modifying records in a database.

Our default file-based security implementation uses a local file. Using the UI with the default security, you can add, modify, associate, remove users and roles which are saved to this local file. The UI calls upon the DirectoryManager implementation to perform these actions.

In general, if you are using the UI and the default file-based security than you probably don’t need this API. If you need a command line tool to manage the users/roles you will probably need to write code either calling the default DirectoryManager implementation or write a custom implementation all together.

Accessing the directory

The directory has clear distinction between user management and role management. For each there is an associated authority that can be granted to a user. For example, you may grant a user an authority to manage users but at the same time deny role management.

The default user which can access the default file-based security implementation is admin/admin. Note that this is specific to the implementation. You can remove admin after first log-in to the directory, but make sure to declare a new user with MANAGE_USERS and/or MANAGE_ROLES authorities.

User Management

The DirectoryManager interface provides a means to managing users using the UserManager API. Access should be granted only to users with MANAGE_USERS authority.

The UserManager interface has simple methods for declaring users:

public interface UserManager {
    ...
    void createUser(UserDetails)
    UserDetails getUser(String)
    void deleteUser(String)
    void updateUser(UserDetails)
    ...
}

Role Management

The DirectoryManage interface provides a means to managing roles using the RoleManager API. Access should be granted only to users with MANAGE_ROLES authority.

The RoleManager interface has simple methods for declaring roles:

public interface RoleManager {
    ...
    createRole(RoleDetails)
    RoleDetails getRole(String)
    deleteRole(String)
    updateRole(RoleDetails)
    ...
}

Using the API

The directory manager is accessible via the SecurityManager. In our default implementation, the user admin/admin has both MANAGE_USERS and MANAGE_ROLES. We will use this user to gain access to the directory manager. Also, we have two default implementations User and Role implementing UserDetails and RoleDetails respectively.

Properties securityProperties = new Properties();
SecurityManager securityManager = SecurityFactory.createSecurityManager(securityProperties);

DirectoryManager directoryManager = securityManager.createDirectoryManager(new User("admin", "admin"));

We can now add a new user using the UserManager API. “Alice” will be added with READ authority for class “eg.ClassA”.

UserManager userManager = directoryManager.getUserManager();

userManager.createUser(new User("alice", "password",
        new SpaceAuthority(SpacePrivilege.READ, new ClassFilter("eg.ClassA"))
    ));

A role can be declared using the RoleManager API. The “author” role will be added with READ, WRITE, TAKE authorities for class “eg.ClassA”.

RoleManager roleManager = directoryManager.getRoleManager();

roleManager.createRole(new Role("author",
        new SpaceAuthority(SpacePrivilege.READ, new ClassFilter("eg.ClassA")),
        new SpaceAuthority(SpacePrivilege.WRITE, new ClassFilter("eg.ClassA")),
        new SpaceAuthority(SpacePrivilege.TAKE, new ClassFilter("eg.ClassA"))
    ));

We can assign this role to user “bob”.

userManager.createUser(new User("bob", "password",
        new RoleAuthority("author")
    ));

The ClassFilter is one of the restrictive filters available. There is also a RegexFilter, PackageFilter, etc. A handy utility is the wildcard expression converter which converts a string expression to a filter. This is used by the UI dialog when creating filters.

userManager.createUser(new User("carol", "password",
        new SpaceAuthority(SpacePrivilege.READ,
                WildcardExpressionToFilterConverter.convert(
                        "eg.Class*", true))
    ));