[portal-commits] JBoss Portal SVN: r6128 - docs/trunk/referenceGuide/en/modules.
portal-commits at lists.jboss.org
portal-commits at lists.jboss.org
Tue Jan 30 17:33:12 EST 2007
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>
More information about the portal-commits
mailing list