Chapter 17. JBoss Portal Identity Management

This chapter addresses identity management in JBoss Portal 2.6

17.1. Identity management API

Since JBoss Portal 2.6 there are 4 identity services and 2 identity related interfaces. The goal of having such a fine grained API is to enable flexible implementations based on different identity storage like relational databases or LDAP servers. The Membership service takes care of managing the relationship between user objects and role objects. The User Profile service is responsible for managing the profile of a user, it has database and LDAP implementations as well as a mode that combines data from both.
  • The org.jboss.portal.identity.User interface represents a user and exposes the following operations:
     /** The user identifier. */
     public Object getId();
    
     /** The user name. */
     public String getUserName();
    
     /** Set the password using proper encoding. */
     public void updatePassword(String password);
    
     /** Return true if the password is valid. */
     public boolean validatePassword(String password);
    

    Warning

    Important Note! The proper usage of getId() method is:
    // Always use it like this:
    user.getId().toString();
    
    // Do not use it like this:
    
    // We would get a Long object if we are using the database implementation
    (Long)user.getId();
    
    // We would get a String with an LDAP server
    (String)user.getId();
    
    This is because the ID value depends on the User implementation. It'll probably be String object with the LDAP implementation and a Long object with the database implementation but it could be something else if one has chosen to make its own implementation.
  • The org.jboss.portal.identity.Role interface represents a Role and exposes the following operations:
    /** The role identifier. */
    public Object getId();
    
    /** The role name used in security rules. This name can not be modified */
    public String getName();
    
    /** The role display name used on screens. This name can be modified */
    public String getDisplayName();
    
    /** */
    public void setDisplayName(String name);
    
  • The org.jboss.portal.identity.UserModule interface exposes operations for users management:
    /**Retrieve a user by its name.*/
    User findUserByUserName(String userName)
       throws IdentityException, IllegalArgumentException, NoSuchUserException;
    
    /**Retrieve a user by its id.*/
    User findUserById(Object id)
       throws IdentityException, IllegalArgumentException, NoSuchUserException;
    
    /**Retrieve a user by its id.*/
    User findUserById(String id)
       throws IdentityException, IllegalArgumentException, NoSuchUserException;
    
    /** Creates a new user with the specified name.*/
    User createUser(String userName, String password)
       throws IdentityException, IllegalArgumentException;
    
    /** Remove a user.*/
    void removeUser(Object id)
       throws IdentityException, IllegalArgumentException;
    
    /** Get a range of users.*/
    Set findUsers(int offset, int limit)
       throws IdentityException, IllegalArgumentException;
    
    /** Get a range of users.*/
    Set findUsersFilteredByUserName(String filter, int offset, int limit)
       throws IdentityException, IllegalArgumentException;
    
    /**Returns the number of users.*/
    int getUserCount() throws IdentityException, IllegalArgumentException;
    
  • The org.jboss.portal.identity.RoleModule interface exposes operations for roles management:
    /** Retrieves a role by its name*/
    Role findRoleByName(String name)
       throws IdentityException, IllegalArgumentException;
    
    /**Retrieve a collection of role from the role names.*/
    Set findRolesByNames(String[] names)
       throws IdentityException, IllegalArgumentException;
    
    /** Retrieves a role by its id.*/
    Role findRoleById(Object id)
       throws IdentityException, IllegalArgumentException;
    
    /** Retrieves a role by its id.*/
    Role findRoleById(String id)
       throws IdentityException, IllegalArgumentException;
    
    /** Create a new role with the specified name.*/
    Role createRole(String name, String displayName)
       throws IdentityException, IllegalArgumentException;
    
    /** Remove a role.*/
    void removeRole(Object id)
       throws IdentityException, IllegalArgumentException;
    
    /** Returns the number of roles. */
    int getRolesCount()
       throws IdentityException;
    
    /** Get all the roles */
    Set findRoles() throws IdentityException;
    
  • The MembershipModule interface exposes operations for obtaining or managing relationships between users and roles. The role of this service is to decouple relationship information from user and roles. Indeed while user role relationship is pretty straightforward with a relational database (using a many to many relationship with an intermediary table), with an LDAP server there a different ways to define relationships between users and roles.
    /** Return the set of role objects that a given user has.*/
    Set getRoles(User user) throws IdentityException, IllegalArgumentException;
    
    Set getUsers(Role role) throws IdentityException, IllegalArgumentException;
    
    /** Creates a relationship beetween a role and set of users. Other roles that have
        assotiontions with those users remain unaffected.*/
    void assignUsers(Role role, Set users) throws IdentityException, IllegalArgumentException;
    
    /** Creates a relationship beetween a user and set of roles. This operation will erase any
        other assotientions beetween the user and roles not specified in the provided set.*/
    void assignRoles(User user, Set roles) throws IdentityException, IllegalArgumentException;
    
    /** Returns role members based on rolename - depreciated method ethod here only
        for compatibility with old RoleModule interface */
    Set findRoleMembers(String roleName, int offset, int limit, String userNameFilter)
       throws IdentityException, IllegalArgumentException;
    
  • The UserProfileModule interface exposes operations to access and manage information stored in User profile:
    public Object getProperty(User user, String propertyName)
       throws IdentityException, IllegalArgumentException;
    
    public void setProperty(User user, String name, Object property)
       throws IdentityException, IllegalArgumentException;
    
    public Map getProperties(User user)
       throws IdentityException, IllegalArgumentException;
    
    public ProfileInfo getProfileInfo()
       throws IdentityException;
    

    Warning

    UserProfileModule.getProperty() method returns an Object. In most cases with DB backend it will always be String object. But normally you should check what object will be retrieved using getProfileInfo() method.
  • The ProfileInfo interface can be obtained using the UserProfileModule and exposes meta information of a profile:
    /** Returns a Map o PropertyInfo objects describing profile properties */
    public Map getPropertiesInfo();
    
    public PropertyInfo getPropertyInfo(String name);
    
  • PropertyInfo interface expose methods to obtain information about accessible property in User profile
    public static final String ACCESS_MODE_READ_ONLY = "read-only";
    public static final String ACCESS_MODE_READ_WRITE = "read-write";
    public static final String USAGE_MANDATORY = "mandatory";
    public static final String USAGE_OPTIONAL = "optional";
    public static final String MAPPING_DB_TYPE_COLUMN = "column";
    public static final String MAPPING_DB_TYPE_DYNAMIC = "dynamic";
    
    public String getName();
    
    public String getType();
    
    public String getAccessMode();
    
    public String getUsage();
    
    public LocalizedString getDisplayName();
    
    public LocalizedString getDescription();
    
    public String getMappingDBType();
    
    public String getMappingLDAPValue();
    
    public String getMappingDBValue();
    
    public boolean isMappedDB();
    
    public boolean isMappedLDAP();
    

17.1.1. How to obtain identity modules services ?

The advocated way to get a reference to the identity modules is by using JNDI:
import org.jboss.portal.identity.UserModule;
import org.jboss.portal.identity.RoleModule;
import org.jboss.portal.identity.MembershipModule;
import org.jboss.portal.identity.UserProfileModule;

[...]

(UserModule)new InitialContext().lookup("java:portal/UserModule");
(RoleModule)new InitialContext().lookup("java:portal/RoleModule");
(MembershipModule)new InitialContext().lookup("java:portal/MembershipModule");
(UserProfileModule)new InitialContext().lookup("java:portal/UserProfileModule");
Another way to do this is, if you are familiar with JBoss Microkernel architecture is to get the IdentityServiceController mbean. You may want to inject it into your services like this:
<depends optional-attribute-name="IdentityServiceController" proxy-type="attribute">
   portal:service=Module,type=IdentityServiceController
</depends>
or simply obtain in your code by doing a lookup using the portal:service=Module,type=IdentityServiceController name. Please refer to the JBoss Application Server documentation if you want to learn more about service MBeans. Once you obtained the object you can use it:
(UserModule)identityServiceController.getIdentityContext()
            .getObject(IdentityContext.TYPE_USER_MODULE);

(RoleModule)identityServiceController.getIdentityContext()
            .getObject(IdentityContext.TYPE_ROLE_MODULE);

(MembershipModule)identityServiceController.getIdentityContext()
            .getObject(IdentityContext.TYPE_MEMBERSHIP_MODULE);

(UserProfileModule)identityServiceController.getIdentityContext()
            .getObject(IdentityContext.TYPE_USER_PROFILE_MODULE);

17.1.2. API changes since 2.4

Because in JBoss Portal 2.4 there were only UserModule , RoleModule , User and Role interfaces some API usages changed. Here are the most important changes you will need to apply to your code while migrating your application to 2.6:
  • For the User interface:
    // Instead of: user.getEnabled()
    userProfileModule.getProperty(user, User.INFO_USER_ENABLED);
    
    // Instead of: user.setEnabled(value)
    userProfileModule.setProperty(user, User.INFO_USER_ENABLED, value);
    
    // In a similar way you should change rest of methods that are missing in User interface
    // in 2.6 by the call to the UserProfileModule
    
    // Instead of: user.getProperties()
    userProfileModule.getProperties(user);
    
    // Instead of: user.getGivenName()
    userProfileModule.getProperty(user, User.INFO_USER_NAME_GIVEN);
    
    // Instead of: user.getFamilyName()
    userProfileModule.getProperty(user, User.INFO_USER_NAME_FAMILY);
    
    // Instead of: user.getRealEmail()
    userProfileModule.getProperty(user, User.INFO_USER_EMAIL_REAL);
    
    // Instead of: user.getFakeEmail()
    userProfileModule.getProperty(user, User.INFO_USER_EMAIL_FAKE);
    
    // Instead of: user.getRegistrationDate()
    userProfileModule.getProperty(user, User.INFO_USER_REGISTRATION_DATE);
    
    // Instead of: user.getViewRealEmail()
    userProfileModule.getProperty(user, User.INFO_USER_VIEW_EMAIL_VIEW_REAL);
    
    // Instead of: user.getPreferredLocale()
    userProfileModule.getProperty(user, User.INFO_USER_LOCALE);
    
    // Instead of: user.getSignature()
    userProfileModule.getProperty(user, User.INFO_USER_SIGNATURE);
    
    // Instead of: user.getLastVisitDate()
    userProfileModule.getProperty(user, User.INFO_USER_LAST_LOGIN_DATE);
  • The RoleModule interface:
    // Instead of
    // RoleModule.findRoleMembers(String roleName, int offset, int limit, String userNameFilter)
    //    throws IdentityException;
    membershipModule.findRoleMembers(String roleName, int offset, int limit,
                                                      String userNameFilter)
    
    // Instead of
    // RoleModule.setRoles(User user, Set roles) throws IdentityException;
    membershipModule.assignRoles(User user, Set roles)
    
    // Instead of
    // RoleModule.getRoles(User user) throws IdentityException;
    membershipModule.getRoles(User user)