From do-not-reply at jboss.org Sun Jan  8 20:32:32 2012
Content-Type: multipart/mixed; boundary="===============4962503347919191296=="
MIME-Version: 1.0
From: do-not-reply at jboss.org
To: gatein-commits at lists.jboss.org
Subject: [gatein-commits] gatein SVN: r8281 -
 epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity.
Date: Sun, 08 Jan 2012 20:32:32 -0500
Message-ID: <201201090132.q091WWCF024292@svn01.web.mwc.hst.phx2.redhat.com>

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

Author: smumford
Date: 2012-01-08 20:32:31 -0500 (Sun, 08 Jan 2012)
New Revision: 8281

Modified:
   epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIde=
ntity/AuthenticationAuthorizationOverview.xml
Log:
JBEPP-1468: Perfunctory edit of new Authorization content

Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/Authenticatio=
nAndIdentity/AuthenticationAuthorizationOverview.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
--- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndId=
entity/AuthenticationAuthorizationOverview.xml	2012-01-08 23:46:25 UTC (rev=
 8280)
+++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndId=
entity/AuthenticationAuthorizationOverview.xml	2012-01-09 01:32:31 UTC (rev=
 8281)
@@ -143,7 +143,7 @@
          <title>Login modules</title>
           =

          <para>
-            JBoss Enterprise Portal Platform uses its own security domain =
(<emphasis role=3D"bold">gatein-domain</emphasis>) with a set of predefined=
 login modules. Login module configuration for <emphasis>gatein-domain</emp=
hasis> is contained in the <file >deploy/gatein.ear/META-INF/gatein-jboss-b=
eans.xml</file> file.
+            JBoss Enterprise Portal Platform uses its own security domain =
(<emphasis role=3D"bold">gatein-domain</emphasis>) with a set of predefined=
 login modules. Login module configuration for <emphasis>gatein-domain</emp=
hasis> is contained in the <filename>deploy/gatein.ear/META-INF/gatein-jbos=
s-beans.xml</filename> file.
         </para>
         <para>
             Below is the default login modules stack:
@@ -187,7 +187,7 @@
          <itemizedlist>
             <listitem>
                <para>
-                  It is possible to log a user in through existing login m=
odules with their credentials (username: <literal>root</literal>/ password:=
 <literal>gtn</literal>, for example) but also with a WCI ticket (username:=
 <emphasis>root</literal>/password: <literal>wci-ticket-458791</literal>). =
The login modules stack supports both of these methods of authentication.
+                  It is possible to log a user in through existing login m=
odules with their credentials (username: <literal>root</literal>/ password:=
 <literal>gtn</literal>, for example) but also with a WCI ticket (username:=
 <literal>root</literal>/password: <literal>wci-ticket-458791</literal>). T=
he login modules stack supports both of these methods of authentication.
                </para>
             </listitem>
              =

@@ -272,7 +272,10 @@
                      <term>CustomMembershipLoginModule</term>
                          <listitem>
                              <para>
-                                 Special login module, which is disabled (=
commented) by default. It can be used to add user to some existing group du=
ring successful login of this user. Name of group is configurable and by de=
fault it's <emphasis>/platform/users</emphasis> group. Login module is comm=
ented because in normal environment, users are already in <emphasis>/platfo=
rm/users</emphasis> group. It's useful only for some special setups like re=
ad-only LDAP, where groups of ldap user are taken from ldap tree and so tha=
t users may not be in /platform/users group, which is needed for successful=
 authorization.
+                                 Special login module, which is disabled (=
commented) by default. It can be used to add user to some existing group du=
ring successful login of this user. Name of group is configurable, by defau=
lt it is <emphasis>/platform/users</emphasis> group.
+                            </para>
+                            <para>
+                                This login module is commented because in =
normal environment, users are already in <emphasis>/platform/users</emphasi=
s> group. It is useful only for some special setups like read-only LDAP, wh=
ere groups of ldap user are taken from ldap tree and so that users may not =
be in <emphasis>/platform/users</emphasis> group, which is needed for succe=
ssful authorization.
                              </para>
                          </listitem>
                  </varlistentry>
@@ -336,7 +339,7 @@
                <title>Authentication on application server level</title>
                 =

                <para>
-                  Application server needs to properly recognize that user=
 is successfuly logged and it has assigned his JAAS roles. Unfortunately th=
is part is not standardized and is specific for each AS. For example in JBo=
ss AS, you need to ensure that JAAS Subject has assigned principal with use=
rname (UserPrincipal) and also RolesPrincipal, which has name "Roles" and i=
t contains list of JAAS roles. This part is actually done in <emphasis>Jbos=
sLoginModule.commit()</emphasis>. In Tomcat, this flow is little different,=
 which means Tomcat has it's own <emphasis>TomcatLoginModule</emphasis>.
+                  Application server needs to properly recognize that user=
 is successfuly logged and it has assigned his JAAS roles. Unfortunately th=
is part is not standardized and is specific for each AS. For example in JBo=
ss AS, you need to ensure that JAAS Subject has assigned principal with use=
rname (UserPrincipal) and also RolesPrincipal, which has name "Roles" and i=
t contains list of JAAS roles. This part is actually done in <code>JbossLog=
inModule.commit()</code>. In Tomcat, this flow is little different, which m=
eans Tomcat has it is own <literal>TomcatLoginModule</literal>.
                </para>
             </formalpara>
                            =

@@ -349,7 +352,7 @@
                <title>Authentication on JBoss Enterprise Portal Platform l=
evel</title>
                 =

                <para>
-                  Login process needs to create special object <emphasis r=
ole=3D"bold">org.exoplatform.services.security.Identity</emphasis> and regi=
ster this object into JBoss Enterprise Portal Platform component <emphasis =
role=3D"bold">IdentityRegistry</emphasis>. This Identity object should enca=
psulate username of authenticated user, Memberships of this user and also J=
AAS roles. Identity object can be easily created with interface <emphasis r=
ole=3D"bold">Authenticator</emphasis> as can be seen below.
+                  Login process needs to create special object <literal>or=
g.exoplatform.services.security.Identity</literal> and register this object=
 into JBoss Enterprise Portal Platform component <literal>IdentityRegistry<=
/literal>. This Identity object should encapsulate username of authenticate=
d user, Memberships of this user and also JAAS roles. Identity object can b=
e easily created with interface <literal>Authenticator</literal> as can be =
seen below.
                </para>
             </formalpara>
              =

@@ -410,7 +413,7 @@
                 =

                <listitem>
                   <para>
-                     set of Strings with JAAS roles of given user. JAAS ro=
les are simple Strings, which are mapped from MembershipEntry objects. Ther=
e is another special component <emphasis>org.exoplatform.services.security.=
RolesExtractor</emphasis>, which is used to map JAAS roles from MembershipE=
ntry objects. RolesExtractor interface looks like this:
+                     Set of Strings with JAAS roles of given user. JAAS ro=
les are simple Strings, which are mapped from MembershipEntry objects. Ther=
e is another special component <emphasis>org.exoplatform.services.security.=
RolesExtractor</emphasis>, which is used to map JAAS roles from MembershipE=
ntry objects. RolesExtractor interface looks like this:
                   </para>
                </listitem>
             </itemizedlist>
@@ -456,7 +459,7 @@
             <title>RememberMe authentication</title>
              =

             <para>
-               In default login dialog, you can notice that there is "Reme=
mber my login" checkbox, which users can use to persist their login on his =
workstation. Default validity period of RememberMe cookie is 1 day (it is c=
onfigurable), and so user can be logged for whole day before he need to rea=
uthenticate again with his credentials.
+               In default login dialog, you can notice that there is "Reme=
mber my login" checkbox, which users can use to persist their login on his =
workstation. Default validity period of RememberMe cookie is one day (it is=
 configurable), and so user can be logged for whole day before he need to r=
eauthenticate again with his credentials.
             </para>
              =

             <section id=3D"sect-Authentication_Authorization_Intro-Remembe=
rMeAuthentication-howDoesItWork">
@@ -465,13 +468,13 @@
                <itemizedlist>
                   <listitem>
                      <para>
-                        User checks the checkbox "Remember my login" on lo=
gin screen of JBoss Enterprise Portal Platform . Then he submit the form.
+                        User checks the checkbox "Remember my login" on lo=
gin screen of JBoss Enterprise Portal Platform . Then submits the form.
                      </para>
                   </listitem>
                    =

                   <listitem>
                      <para>
-                        HTTP request like <emphasis>http://localhost:8080/=
portal/login?initialURI=3D/portal/classic&amp;username=3Droot&amp;password=
=3Dgtn&amp;rememberme=3Dtrue</emphasis> is send to server
+                        HTTP request like <uri>http://localhost:8080/porta=
l/login?initialURI=3D/portal/classic&amp;username=3Droot&amp;password=3Dgtn=
&amp;rememberme=3Dtrue</uri> is sent to server.
                      </para>
                   </listitem>
                    =

@@ -495,7 +498,7 @@
                    =

                   <listitem>
                      <para>
-                        User send HTTP request to some portal page (ie. <e=
mphasis>http://localhost:8080/portal/classic</emphasis> ).
+                        User send HTTP request to some portal page (ie. <f=
ilename>http://localhost:8080/portal/classic</filename> ).
                      </para>
                   </listitem>
                    =

@@ -511,7 +514,7 @@
                <title>RemindPasswordTokenService</title>
                 =

                <para>
-                  This is special service used during RememberMe authentic=
ation workflow. It's configurable in file <emphasis>deploy/gatein.ear/02por=
tal.war/WEB-INF/conf/common/remindpwd-configuration.xml</emphasis> . For mo=
re info, look at section <xref linkend=3D"sect-Reference_Guide-Authenticati=
on_Token_Configuration" />
+                  This is special service used during RememberMe authentic=
ation workflow. It is configurable in file <filename>deploy/gatein.ear/02po=
rtal.war/WEB-INF/conf/common/remindpwd-configuration.xml</filename> . For m=
ore info, look at section <xref linkend=3D"sect-Reference_Guide-Authenticat=
ion_Token_Configuration" />
                </para>
                 =

                <para>
@@ -524,7 +527,7 @@
             <title>BASIC authentication</title>
              =

             <para>
-               JBoss Enterprise Portal Platform is using FORM based authen=
tication by default but it's not a problem with switch to different authent=
ication type like BASIC. Only needed thing is to configure it properly in <=
emphasis>deploy/gatein.ear/02portal.war/WEB-INF/web.xml</emphasis> like thi=
s:
+               JBoss Enterprise Portal Platform is using FORM based authen=
tication by default but it is not a problem with switch to different authen=
tication type like BASIC. Only needed thing is to configure it properly in =
<filename>deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> like th=
is:
             </para>
 <programlisting language=3D"XML" role=3D"XML">
             <![CDATA[
@@ -565,13 +568,13 @@
                 =

                <step>
                   <para>
-                     User will send request to loadbalancer and he will be=
 redirected to node1. All his requests will be then processed on node1 (sti=
cky session).
+                     User will send request to loadbalancer and he will be=
 redirected to <emphasis>node1</emphasis>. All his requests will be then pr=
ocessed on <emphasis>node1</emphasis> (sticky session).
                   </para>
                </step>
                 =

                <step>
                   <para>
-                     User login on loadbalancer (which is redirected to no=
de1)
+                     User login on loadbalancer (which is redirected to <e=
mphasis>node1</emphasis>)
                   </para>
                </step>
                 =

@@ -583,19 +586,19 @@
                 =

                <step>
                   <para>
-                     User will send another HTTP request. He will now be r=
edirected to node2 because node1 is killed. Now user will be automatically =
logged on node2 as well thanks to session replication, because he still has=
 same HTTP session, which was replicated from node1 to node2. So end user s=
houldn't recognize any change even if his work is now done on different nod=
e of cluster.
+                     User will send another HTTP request. He will now be r=
edirected to <emphasis>node2</emphasis> because <emphasis>node1</emphasis> =
is killed. Now user will be automatically logged on <emphasis>node2</emphas=
is> as well thanks to session replication, because he still has same HTTP s=
ession, which was replicated from <emphasis>node1</emphasis> to <emphasis>n=
ode2</emphasis>. So end user shouldn't recognize any change even if his wor=
k is now done on different node of cluster.
                   </para>
                </step>
             </procedure>
              =

             <para>
-               This login workflow works thanks to <emphasis>PortalLoginMo=
dule</emphasis>, which is able to save special attribute into HTTP session =
as flag that user is already logged. Then reauthentication on node2 is work=
ing thanks to servlet filter <emphasis>ClusteredSSOFilter</emphasis>, which=
 is able to automatically trigger programmatic authentication.
+               This login workflow works thanks to <emphasis>PortalLoginMo=
dule</emphasis>, which is able to save special attribute into HTTP session =
as flag that user is already logged. Then reauthentication on <emphasis>nod=
e2</emphasis> is working thanks to servlet filter <emphasis>ClusteredSSOFil=
ter</emphasis>, which is able to automatically trigger programmatic authent=
ication.
             </para>
              =

             <note>
                 <title>Note</title>
                     <para>
-                        ClusteredSSOFilter is using proprietary JBossWeb A=
PI for trigger programmatic authentication and so it's working only on JBos=
s AS. It is not working on other servers like Tomcat or Jetty.
+                        <literal>ClusteredSSOFilter</literal> is using pro=
prietary JBossWeb API for trigger programmatic authentication and so it is =
working only on JBoss AS. It is not working on other servers like Tomcat or=
 Jetty.
                     </para>
             </note>
              =

@@ -650,18 +653,18 @@
             <title>Servlet container authorization</title>
              =

             <para>
-               First round of authorization is servlet container authoriza=
tion based on secured URL from <emphasis>web.xml</emphasis>. We saw above i=
n web.xml snippet that secured URL are accessible only for users from role =
<emphasis>users</emphasis>:
+               First round of authorization is servlet container authoriza=
tion based on secured URL from <filename>web.xml</filename>. We saw above i=
n web.xml snippet that secured URL are accessible only for users from role =
<emphasis>users</emphasis>:
             </para>
 <programlisting language=3D"XML" role=3D"XML"><![CDATA[
 <auth-constraint>
   <role-name>users</role-name>
 </auth-constraint>]]></programlisting>
             <para>
-               This actually means that our user needs to be in JBoss Ente=
rprise Portal Platform role <emphasis>/platform/users</emphasis> (For detai=
ls see <xref linkend=3D"sect-Authentication_Authorization_Intro-authenticat=
orAndRolesExtractor" />). In other words, if we successfuly authenticate bu=
t our user is not in group /platform/users, then it means that he is not in=
 JAAS role <emphasis>users</emphasis>, which in next turn means that he wil=
l have authorization error <emphasis role=3D"bold">403 Forbidden</emphasis>=
 thrown by servlet container.
+               This actually means that our user needs to be in JBoss Ente=
rprise Portal Platform role <emphasis>/platform/users</emphasis> (For detai=
ls see <xref linkend=3D"sect-Authentication_Authorization_Intro-authenticat=
orAndRolesExtractor" />). In other words, if we successfuly authenticate bu=
t our user is not in group <emphasis>/platform/users</emphasis>, then it me=
ans that he is not in JAAS role <emphasis>users</emphasis>, which in next t=
urn means that he will have authorization error <emphasis role=3D"bold">403=
 Forbidden</emphasis> thrown by servlet container.
             </para>
              =

             <para>
-               You can change the behaviour and possibly add some more <em=
phasis>auth-constraint</emphasis> elements into web.xml. However this prote=
ction of resources based on web.xml is not standard JBoss Enterprise Portal=
 Platform way and it's mentioned here mainly for illustration purposes.
+               You can change the behaviour and possibly add some more <em=
phasis>auth-constraint</emphasis> elements into <filename>web.xml</filename=
>. However this protection of resources based on web.xml is not standard JB=
oss Enterprise Portal Platform way and it is mentioned here mainly for illu=
stration purposes.
             </para>
          </section>
           =

@@ -685,7 +688,7 @@
                 =

                <listitem>
                   <para>
-                     HTTP request is processed through <emphasis role=3D"b=
old">SetCurrentIdentityFilter</emphasis>, which is declared in <emphasis>de=
ploy/gatein.ear/02portal.war/WEB-INF/web.xml</emphasis>.
+                     HTTP request is processed through <literal>SetCurrent=
IdentityFilter</literal>, which is declared in <filename>deploy/gatein.ear/=
02portal.war/WEB-INF/web.xml</filename>.
                   </para>
                </listitem>
                 =



--===============4962503347919191296==--