From portal-commits at lists.jboss.org Tue Jan 30 17:33:12 2007
Content-Type: multipart/mixed; boundary="===============0503837634035200752=="
MIME-Version: 1.0
From: portal-commits at lists.jboss.org
To: portal-commits at lists.jboss.org
Subject: [portal-commits] JBoss Portal SVN: r6128 -
 docs/trunk/referenceGuide/en/modules.
Date: Tue, 30 Jan 2007 17:33:12 -0500
Message-ID: <E1HC1XM-000845-4U@committer01.frg.pub.inap.atl.jboss.com>

--===============0503837634035200752==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- docs/trunk/referenceGuide/en/modules/authentication.xml	               =
         (rev 0)
+++ docs/trunk/referenceGuide/en/modules/authentication.xml	2007-01-30 22:3=
3:11 UTC (rev 6128)
@@ -0,0 +1,12 @@
+<chapter id=3D"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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- docs/trunk/referenceGuide/en/modules/identity.xml	                     =
   (rev 0)
+++ docs/trunk/referenceGuide/en/modules/identity.xml	2007-01-30 22:33:11 U=
TC (rev 6128)
@@ -0,0 +1,410 @@
+<chapter id=3D"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=3D"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 underlayi=
ng 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=3D"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 implementat=
ion. It'll probably be String in LDAP and Long
+                    in Hibernate but it can be anything else...
+
+                </warning>
+            </listitem>
+            <listitem>
+                <para>
+                    <emphasis role=3D"bold">Role</emphasis>
+                    interface which exposes such operations on
+                    <emphasis role=3D"bold">User</emphasis>
+                    object:
+                </para>
+                <programlisting>
+                    <![CDATA[
+                /** The role identifier. */
+                public Object getId();
+
+                /** The role name used in security rules. This name can no=
t be modified */
+                public String getName();
+
+                /** The role display name used on screens. This name can b=
e modified */
+                public String getDisplayName();
+
+                /** */
+                public void setDisplayName(String name);
+                ]]>
+                </programlisting>
+            </listitem>
+            <listitem>
+                <para>
+                    <emphasis role=3D"bold">UserModule</emphasis>
+                    interface which exposes operations for users management
+                </para>
+                <programlisting>
+                    <![CDATA[
+                /**Retrieve a user by its name.*/
+                User findUserByUserName(String userName) throws IdentityEx=
ception, IllegalArgumentException, NoSuchUserException;
+
+                /**Retrieve a user by its id.*/
+                User findUserById(Object id) throws IdentityException, Ill=
egalArgumentException, NoSuchUserException;
+
+                /**Retrieve a user by its id.*/
+                User findUserById(String id) throws IdentityException, Ill=
egalArgumentException, NoSuchUserException;
+
+                /** Creates a new user with the specified name.*/
+                User createUser(String userName, String password) throws I=
dentityException, IllegalArgumentException;
+
+                /** Remove a user.*/
+                void removeUser(Object id) throws IdentityException, Illeg=
alArgumentException;
+
+                /** Get a range of users.*/
+                Set findUsers(int offset, int limit) throws IdentityExcept=
ion, 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, IllegalArgume=
ntException;
+                ]]>
+                </programlisting>
+            </listitem>
+            <listitem>
+                <para>
+                    <emphasis role=3D"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 IdentityExcept=
ion, IllegalArgumentException;
+
+                /** Retrieves a role by its id.*/
+                Role findRoleById(Object id) throws IdentityException, Ill=
egalArgumentException;
+
+                /** Retrieves a role by its id.*/
+                Role findRoleById(String id) throws IdentityException, Ill=
egalArgumentException;
+
+                /** Create a new role with the specified name.*/
+                Role createRole(String name, String displayName) throws Id=
entityException, IllegalArgumentException;
+
+                /** Remove a role.*/
+                void removeRole(Object id) throws IdentityException, Illeg=
alArgumentException;
+
+                /** Returns the number of roles. */
+                int getRolesCount() throws IdentityException;
+
+                /** Get all the roles */
+                Set findRoles() throws IdentityException;/** Retrieves a r=
ole by its name*/
+                Role findRoleByName(String name) throws IdentityException,=
 IllegalArgumentException;
+
+                /**Retrieve a collection of role from the role names.*/
+                Set findRolesByNames(String[] names) throws IdentityExcept=
ion, IllegalArgumentException;
+
+                /** Retrieves a role by its id.*/
+                Role findRoleById(Object id) throws IdentityException, Ill=
egalArgumentException;
+
+                /** Retrieves a role by its id.*/
+                Role findRoleById(String id) throws IdentityException, Ill=
egalArgumentException;
+
+                /** Create a new role with the specified name.*/
+                Role createRole(String name, String displayName) throws Id=
entityException, IllegalArgumentException;
+
+                /** Remove a role.*/
+                void removeRole(Object id) throws IdentityException, Illeg=
alArgumentException;
+
+                /** Returns the number of roles. */
+                int getRolesCount() throws IdentityException;
+
+                /** Get all the roles */
+                Set findRoles() throws IdentityException;
+                ]]>
+                </programlisting>
+            </listitem>
+            <listitem>
+                <para>
+                    <emphasis role=3D"bold">MembershipModule</emphasis>
+                    interface which exposes operations for obtaining or de=
fining 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 ther=
e 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, IllegalA=
rgumentException;
+
+                Set getUsers(Role role) throws IdentityException, IllegalA=
rgumentException;
+
+                /** Creates a relationship beetween a role and set of user=
s. Other roles that have assotiontions with those users remain unaffected.*/
+                void assignUsers(Role role, Set users) throws IdentityExce=
ption, IllegalArgumentException;
+
+               /** Creates a relationship beetween a user and set of roles=
. This operation will erase any other assotientions beetween the user and r=
oles not specified in the provided set.*/
+               void assignRoles(User user, Set roles) throws IdentityExcep=
tion, IllegalArgumentException;
+
+               /** Returns role members based on rolename - depreciated me=
thod 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=3D"bold">UserProfileModule</emphasis>
+                    interface which exposes operations to access informati=
ons 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 pro=
perty) throws IdentityException, IllegalArgumentException;
+
+                public Map getProperties(User user) throws IdentityExcepti=
on, IllegalArgumentException;
+
+                public ProfileInfo getProfileInfo() throws IdentityExcepti=
on;
+                ]]>
+                </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=3D"bold">ProfileInfo</emphasis>
+                    interface which can be obtained using
+                    <emphasis role=3D"bold">UserProfileModule</emphasis>
+                    and exposes information about User profile properties =
that are accessible:
+                </para>
+                <programlisting>
+                    <![CDATA[
+                /** Returns a Map o PropertyInfo objects describing profil=
e properties */
+                public Map getPropertiesInfo();
+
+                public PropertyInfo getPropertyInfo(String name);
+                ]]>
+                </programlisting>
+            </listitem>
+            <listitem>
+                <para>
+                    <emphasis role=3D"bold">PropertyInfo</emphasis>
+                    interface expose methods to obtain information about a=
ccessible property in User profile
+                </para>
+                <programlisting>
+                    <![CDATA[
+                public static final String ACCESS_MODE_READ_ONLY =3D "read=
-only";
+                public static final String ACCESS_MODE_READ_WRITE =3D "rea=
d-write";
+                public static final String USAGE_MANDATORY =3D "mandatory";
+                public static final String USAGE_OPTIONAL =3D "optional";
+                public static final String MAPPING_DB_TYPE_COLUMN =3D "col=
umn";
+                public static final String MAPPING_DB_TYPE_DYNAMIC =3D "dy=
namic";
+
+                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/UserM=
odule");
+                (RoleModule)new InitialContext().lookup("java:portal/RoleM=
odule");
+                (MembershipModule)new InitialContext().lookup("java:portal=
/MembershipModule");
+                (UserProfileModule)new InitialContext().lookup("java:porta=
l/UserProfileModule");
+
+            </programlisting>
+            <para>
+                Another way to do this is, if you are fimiliar with JBoss =
Mikrokernel architecture is by obtaining
+                <emphasis role=3D"bold">IdentityServiceController</emphasi=
s>
+                mbean. You may want to inject it into your mbean like this:
+            </para>
+            <programlisting>
+                <![CDATA[<depends optional-attribute-name=3D"IdentityServi=
ceController" proxy-type=3D"attribute">portal:service=3DModule,type=3DIdent=
ityServiceController</depends>]]>
+            </programlisting>
+            <para>
+                or simply obtain in your code using
+                <emphasis role=3D"bold">portal:service=3DModule,type=3DIde=
ntityServiceController</emphasis>
+                name. Please refer to JBoss Application Server documentati=
on 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.getIdentityCon=
text().getObject(IdentityContext.TYPE_MEMBERSHIP_MODULE);
+                (UserProfileModule)identityServiceController.getIdentityCo=
ntext().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=3D"bold">UserModule</emphasis>
+                ,
+                <emphasis role=3D"bold">RoleModule</emphasis>
+                ,
+                <emphasis role=3D"bold">User</emphasis>
+                and
+                <emphasis role=3D"bold">Role</emphasis>
+                interfaces some API usages changed. Here are the most impo=
rtant changes you will need to aply to your
+                code
+                while migrating your aplication to 2.6:
+            </para>
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        <emphasis role=3D"bold">User</emphasis>
+                        interface
+                    </para>
+                    <programlisting>
+                        <![CDATA[
+                    //Instead of: user.getEnabled()
+                    userProfileModule.getProperty(user, User.INFO_USER_ENA=
BLED);
+
+                    //Instead of: user.setEnabled(value)
+                    userProfileModule.setProperty(user, User.INFO_USER_ENA=
BLED, value);
+
+                    In the similar way you should change rest of methods t=
hat are missing in User interface in 2.6 by the call to the UserProfileModu=
le?:
+
+                    //Instead of: user.getProperties()
+                    userProfileModule.getProperties(user);
+
+                    //Instead of: user.getGivenName()
+                    userProfileModule.getProperty(user, User.INFO_USER_NAM=
E_GIVEN);
+
+                    //Instead of: user.getFamilyName()
+                    userProfileModule.getProperty(user, User.INFO_USER_NAM=
E_FAMILY);
+
+                    //Instead of: user.getRealEmail()
+                    userProfileModule.getProperty(user, User.INFO_USER_EMA=
IL_REAL);
+
+                    //Instead of: user.getFakeEmail()
+                    userProfileModule.getProperty(user, User.INFO_USER_EMA=
IL_FAKE);
+
+                    //Instead of: user.getRegistrationDate()
+                    userProfileModule.getProperty(user, User.INFO_USER_REG=
ISTRATION_DATE);
+
+                    //Instead of: user.getViewRealEmail()
+                    userProfileModule.getProperty(user, User.INFO_USER_VIE=
W_EMAIL_VIEW_REAL);
+
+                    //Instead of: user.getPreferredLocale()
+                    userProfileModule.getProperty(user, User.INFO_USER_LOC=
ALE);
+
+                    //Instead of: user.getSignature()
+                    userProfileModule.getProperty(user, User.INFO_USER_SIG=
NATURE);
+
+                    //Instead of: user.getLastVisitDate()
+                    userProfileModule.getProperty(user, User.INFO_USER_LAS=
T_LOGIN_DATE);
+
+                ]]>
+                    </programlisting>
+                </listitem>
+                <listitem>
+                    <para>
+                        <emphasis role=3D"bold">RoleModule</emphasis>
+                        interface
+                    </para>
+                    <programlisting>
+                        <![CDATA[
+                    //Instead of
+                    //RoleModule.findRoleMembers(String roleName, int offs=
et, 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 Ide=
ntityException;
+                    membershipModule.assignRoles(User user, Set roles)
+
+                    //Instead of
+                    //RoleModule.getRoles(User user) throws IdentityExcept=
ion;
+                    membershipModule.getRoles(User user)
+
+                ]]>
+                    </programlisting>
+                </listitem>
+            </itemizedlist>
+        </sect2>
+    </sect1>
+   =

+
+</chapter>

Added: docs/trunk/referenceGuide/en/modules/sso.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- docs/trunk/referenceGuide/en/modules/sso.xml	                        (r=
ev 0)
+++ docs/trunk/referenceGuide/en/modules/sso.xml	2007-01-30 22:33:11 UTC (r=
ev 6128)
@@ -0,0 +1,13 @@
+<chapter id=3D"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>


--===============0503837634035200752==--