[portal-commits] JBoss Portal SVN: r6128 - docs/trunk/referenceGuide/en/modules.

Author: bdaw Date: 2007-01-30 17:33:11 -0500 (Tue, 30 Jan 2007) New Revision: 6128 Added: docs/trunk/referenceGuide/en/modules/authentication.xml docs/trunk/referenceGuide/en/modules/identity.xml docs/trunk/referenceGuide/en/modules/sso.xml Log: some initial work on identity, and placeholders for authentication and sso chapters Added: docs/trunk/referenceGuide/en/modules/authentication.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/authentication.xml (rev 0) +++ docs/trunk/referenceGuide/en/modules/authentication.xml 2007-01-30 22:33:11 UTC (rev 6128) @@ -0,0 +1,12 @@ +<chapter id="authentication"> + <chapterinfo> + <author> + <firstname>Boleslaw</firstname> + <surname>Dawidowicz</surname> + <email>boleslaw.dawidowicz at jboss dot com</email> + </author> + </chapterinfo> + <title>Authentication</title> + <para>This chapter describes authentication mechanisms in JBoss Portal</para> + +</chapter> Added: docs/trunk/referenceGuide/en/modules/identity.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/identity.xml (rev 0) +++ docs/trunk/referenceGuide/en/modules/identity.xml 2007-01-30 22:33:11 UTC (rev 6128) @@ -0,0 +1,410 @@ +<chapter id="identity"> + <chapterinfo> + <author> + <firstname>Boleslaw</firstname> + <surname>Dawidowicz</surname> + <email>boleslaw.dawidowicz at jboss dot com</email> + </author> + </chapterinfo> + <title>JBoss Portal Identity management</title> + <para>This chapter addresses identity management in JBoss Portal 2.6</para> + <sect1 id="management_api"> + <title>Identity management API</title> + <para>In JBoss Portal currently there are 4 identity modules and 2 identity reletad objects. The goal about + having such wide API is to + enable flexible implementations related to different underlaying technologies like RDBS or LDAP. With such + data storage mechanisms things like + User/Role relationship are defined in slightly different way. Another thing is User Profile where + information about user can be grabbed from database + column or LDAP entry or even mixed. + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">User</emphasis> + interface which exposes such operations on User object: + </para> + <programlisting> + <![CDATA[ + /** 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); + ]]> + </programlisting> + <warning> + Important Note!!! Proper usage of getId() method is: + <programlisting> + <![CDATA[ + //Always use it like this: + user.getId().toString() + + //NEVER use it like this: + (Long)user.getId() + (String)user.getId() + ]]> + </programlisting> + This is because of that ID depends on User implementation. It'll probably be String in LDAP and Long + in Hibernate but it can be anything else... + + </warning> + </listitem> + <listitem> + <para> + <emphasis role="bold">Role</emphasis> + interface which exposes such operations on + <emphasis role="bold">User</emphasis> + object: + </para> + <programlisting> + <![CDATA[ + /** 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); + ]]> + </programlisting> + </listitem> + <listitem> + <para> + <emphasis role="bold">UserModule</emphasis> + interface which exposes operations for users management + </para> + <programlisting> + <![CDATA[ + /**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; + ]]> + </programlisting> + </listitem> + <listitem> + <para> + <emphasis role="bold">RoleModule</emphasis> + interface which exposes operations for roles management + </para> + <programlisting> + <![CDATA[ + /** 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;/** 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; + ]]> + </programlisting> + </listitem> + <listitem> + <para> + <emphasis role="bold">MembershipModule</emphasis> + interface which exposes operations for obtaining or defining relationship beetween users and roles. + The role of this module is to + decouple relationship information from user and roles. Whith different implementations definition of + such relationship can be specified on different sides. + With Relational DB it's quite simple, but in LDAP there are several ways to store such information. + Role of this module is to bring flexibility + in defining contract beetween user and role. + </para> + <programlisting> + <![CDATA[ + /** 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; + ]]> + </programlisting> + </listitem> + <listitem> + <para> + <emphasis role="bold">UserProfileModule</emphasis> + interface which exposes operations to access informations stored in User profile. + </para> + <programlisting> + <![CDATA[ + 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; + ]]> + </programlisting> + <warning> + UserProfileModule?.getProperty() method returns Object. + In most cases with DB backend it will always be String object. But normally you should check what + object will be retreived using getProfileInfo() method. + </warning> + </listitem> + <listitem> + <para> + <emphasis role="bold">ProfileInfo</emphasis> + interface which can be obtained using + <emphasis role="bold">UserProfileModule</emphasis> + and exposes information about User profile properties that are accessible: + </para> + <programlisting> + <![CDATA[ + /** Returns a Map o PropertyInfo objects describing profile properties */ + public Map getPropertiesInfo(); + + public PropertyInfo getPropertyInfo(String name); + ]]> + </programlisting> + </listitem> + <listitem> + <para> + <emphasis role="bold">PropertyInfo</emphasis> + interface expose methods to obtain information about accessible property in User profile + </para> + <programlisting> + <![CDATA[ + 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(); + ]]> + </programlisting> + </listitem> + + </itemizedlist> + + <sect2> + <title>Way to access identity modules</title> + <para> + The best way to access identity modules is by using JNDI: + </para> + <programlisting> + 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"); + + </programlisting> + <para> + Another way to do this is, if you are fimiliar with JBoss Mikrokernel architecture is by obtaining + <emphasis role="bold">IdentityServiceController</emphasis> + mbean. You may want to inject it into your mbean like this: + </para> + <programlisting> + <![CDATA[<depends optional-attribute-name="IdentityServiceController" proxy-type="attribute">portal:service=Module,type=IdentityServiceController</depends>]]> + </programlisting> + <para> + or simply obtain in your code using + <emphasis role="bold">portal:service=Module,type=IdentityServiceController</emphasis> + name. Please refer to JBoss Application Server documentation if you want to learn more + about MBeans. Once you obtained the object you can use it: + </para> + + <programlisting> + (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); + </programlisting> + + </sect2> + <sect2> + <title>API changes since 2.4</title> + <para>Because in JBoss Portal 2.4 there were only + <emphasis role="bold">UserModule</emphasis> + , + <emphasis role="bold">RoleModule</emphasis> + , + <emphasis role="bold">User</emphasis> + and + <emphasis role="bold">Role</emphasis> + interfaces some API usages changed. Here are the most important changes you will need to aply to your + code + while migrating your aplication to 2.6: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">User</emphasis> + interface + </para> + <programlisting> + <![CDATA[ + //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 the 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); + + ]]> + </programlisting> + </listitem> + <listitem> + <para> + <emphasis role="bold">RoleModule</emphasis> + interface + </para> + <programlisting> + <![CDATA[ + //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) + + ]]> + </programlisting> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + +</chapter> Added: docs/trunk/referenceGuide/en/modules/sso.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/sso.xml (rev 0) +++ docs/trunk/referenceGuide/en/modules/sso.xml 2007-01-30 22:33:11 UTC (rev 6128) @@ -0,0 +1,13 @@ +<chapter id="sso"> + <chapterinfo> + <author> + <firstname>Boleslaw</firstname> + <surname>Dawidowicz</surname> + <email>boleslaw.dawidowicz at jboss dot com</email> + </author> + </chapterinfo> + <title>Authentication</title> + <para>This chapter describes how to setup SSO in JBoss Portal</para> + + +</chapter>