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/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml Log: JBEPP-1468: Perfunctory edit of new Authorization content Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2012-01-08 23:46:25 UTC (rev 8280) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/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="bold">gatein-domain</emphasis>) with a set of predefined login modules. Login module configuration for <emphasis>gatein-domain</emphasis> is contained in the <file >deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</file> file. + JBoss Enterprise Portal Platform uses its own security domain (<emphasis role="bold">gatein-domain</emphasis>) with a set of predefined login modules. Login module configuration for <emphasis>gatein-domain</emphasis> is contained in the <filename>deploy/gatein.ear/META-INF/gatein-jboss-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 modules 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 modules 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>). The 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 during successful login of this user. Name of group is configurable and by default it's <emphasis>/platform/users</emphasis> group. Login module is commented because in normal environment, users are already in <emphasis>/platform/users</emphasis> group. It's useful only for some special setups like read-only LDAP, where groups of ldap user are taken from ldap tree and so that 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 during successful login of this user. Name of group is configurable, by default 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</emphasis> group. It is useful only for some special setups like read-only LDAP, where 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 successful 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 this part is not standardized and is specific for each AS. For example in JBoss AS, you need to ensure that JAAS Subject has assigned principal with username (UserPrincipal) and also RolesPrincipal, which has name "Roles" and it contains list of JAAS roles. This part is actually done in <emphasis>JbossLoginModule.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 this part is not standardized and is specific for each AS. For example in JBoss AS, you need to ensure that JAAS Subject has assigned principal with username (UserPrincipal) and also RolesPrincipal, which has name "Roles" and it contains list of JAAS roles. This part is actually done in <code>JbossLoginModule.commit()</code>. In Tomcat, this flow is little different, which means Tomcat has it is own <literal>TomcatLoginModule</literal>. </para> </formalpara> @@ -349,7 +352,7 @@ <title>Authentication on JBoss Enterprise Portal Platform level</title> <para> - Login process needs to create special object <emphasis role="bold">org.exoplatform.services.security.Identity</emphasis> and register this object into JBoss Enterprise Portal Platform component <emphasis role="bold">IdentityRegistry</emphasis>. This Identity object should encapsulate username of authenticated user, Memberships of this user and also JAAS roles. Identity object can be easily created with interface <emphasis role="bold">Authenticator</emphasis> as can be seen below. + Login process needs to create special object <literal>org.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 authenticated user, Memberships of this user and also JAAS roles. Identity object can be 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 roles are simple Strings, which are mapped from MembershipEntry objects. There is another special component <emphasis>org.exoplatform.services.security.RolesExtractor</emphasis>, which is used to map JAAS roles from MembershipEntry objects. RolesExtractor interface looks like this: + Set of Strings with JAAS roles of given user. JAAS roles are simple Strings, which are mapped from MembershipEntry objects. There is another special component <emphasis>org.exoplatform.services.security.RolesExtractor</emphasis>, which is used to map JAAS roles from MembershipEntry 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 "Remember 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 configurable), and so user can be logged for whole day before he need to reauthenticate again with his credentials. + In default login dialog, you can notice that there is "Remember 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 reauthenticate again with his credentials. </para> <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication-howDoesItWork"> @@ -465,13 +468,13 @@ <itemizedlist> <listitem> <para> - User checks the checkbox "Remember my login" on login screen of JBoss Enterprise Portal Platform . Then he submit the form. + User checks the checkbox "Remember my login" on login screen of JBoss Enterprise Portal Platform . Then submits the form. </para> </listitem> <listitem> <para> - HTTP request like <emphasis>http://localhost:8080/portal/login?initialURI=/portal/classic&amp;username=root&amp;password=gtn&amp;rememberme=true</emphasis> is send to server + HTTP request like <uri>http://localhost:8080/portal/login?initialURI=/portal/classic&amp;username=root&amp;password=gtn&amp;rememberme=true</uri> is sent to server. </para> </listitem> @@ -495,7 +498,7 @@ <listitem> <para> - User send HTTP request to some portal page (ie. <emphasis>http://localhost:8080/portal/classic</emphasis> ). + User send HTTP request to some portal page (ie. <filename>http://localhost:8080/portal/classic</filename> ). </para> </listitem> @@ -511,7 +514,7 @@ <title>RemindPasswordTokenService</title> <para> - This is special service used during RememberMe authentication workflow. It's configurable in file <emphasis>deploy/gatein.ear/02portal.war/WEB-INF/conf/common/remindpwd-configuration.xml</emphasis> . For more info, look at section <xref linkend="sect-Reference_Guide-Authentication_Token_Configuration" /> + This is special service used during RememberMe authentication workflow. It is configurable in file <filename>deploy/gatein.ear/02portal.war/WEB-INF/conf/common/remindpwd-configuration.xml</filename> . For more info, look at section <xref linkend="sect-Reference_Guide-Authentication_Token_Configuration" /> </para> <para> @@ -524,7 +527,7 @@ <title>BASIC authentication</title> <para> - JBoss Enterprise Portal Platform is using FORM based authentication by default but it's not a problem with switch to different authentication type like BASIC. Only needed thing is to configure it properly in <emphasis>deploy/gatein.ear/02portal.war/WEB-INF/web.xml</emphasis> like this: + JBoss Enterprise Portal Platform is using FORM based authentication by default but it is not a problem with switch to different authentication type like BASIC. Only needed thing is to configure it properly in <filename>deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> like this: </para> <programlisting language="XML" role="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 (sticky session). + User will send request to loadbalancer and he will be redirected to <emphasis>node1</emphasis>. All his requests will be then processed on <emphasis>node1</emphasis> (sticky session). </para> </step> <step> <para> - User login on loadbalancer (which is redirected to node1) + User login on loadbalancer (which is redirected to <emphasis>node1</emphasis>) </para> </step> @@ -583,19 +586,19 @@ <step> <para> - User will send another HTTP request. He will now be redirected 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 shouldn't recognize any change even if his work is now done on different node of cluster. + User will send another HTTP request. He will now be redirected to <emphasis>node2</emphasis> because <emphasis>node1</emphasis> is killed. Now user will be automatically logged on <emphasis>node2</emphasis> as well thanks to session replication, because he still has same HTTP session, which was replicated from <emphasis>node1</emphasis> to <emphasis>node2</emphasis>. So end user shouldn't recognize any change even if his work is now done on different node of cluster. </para> </step> </procedure> <para> - This login workflow works thanks to <emphasis>PortalLoginModule</emphasis>, which is able to save special attribute into HTTP session as flag that user is already logged. Then reauthentication on node2 is working thanks to servlet filter <emphasis>ClusteredSSOFilter</emphasis>, which is able to automatically trigger programmatic authentication. + This login workflow works thanks to <emphasis>PortalLoginModule</emphasis>, which is able to save special attribute into HTTP session as flag that user is already logged. Then reauthentication on <emphasis>node2</emphasis> is working thanks to servlet filter <emphasis>ClusteredSSOFilter</emphasis>, which is able to automatically trigger programmatic authentication. </para> <note> <title>Note</title> <para> - ClusteredSSOFilter is using proprietary JBossWeb API for trigger programmatic authentication and so it's working only on JBoss AS. It is not working on other servers like Tomcat or Jetty. + <literal>ClusteredSSOFilter</literal> is using proprietary 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 authorization based on secured URL from <emphasis>web.xml</emphasis>. We saw above in web.xml snippet that secured URL are accessible only for users from role <emphasis>users</emphasis>: + First round of authorization is servlet container authorization based on secured URL from <filename>web.xml</filename>. We saw above in web.xml snippet that secured URL are accessible only for users from role <emphasis>users</emphasis>: </para> <programlisting language="XML" role="XML"><![CDATA[ <auth-constraint> <role-name>users</role-name> </auth-constraint>]]></programlisting> <para> - This actually means that our user needs to be in JBoss Enterprise Portal Platform role <emphasis>/platform/users</emphasis> (For details see <xref linkend="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor" />). In other words, if we successfuly authenticate but 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 will have authorization error <emphasis role="bold">403 Forbidden</emphasis> thrown by servlet container. + This actually means that our user needs to be in JBoss Enterprise Portal Platform role <emphasis>/platform/users</emphasis> (For details see <xref linkend="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor" />). In other words, if we successfuly authenticate but our user is not in group <emphasis>/platform/users</emphasis>, then it means that he is not in JAAS role <emphasis>users</emphasis>, which in next turn means that he will have authorization error <emphasis role="bold">403 Forbidden</emphasis> thrown by servlet container. </para> <para> - You can change the behaviour and possibly add some more <emphasis>auth-constraint</emphasis> elements into web.xml. However this protection 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 <emphasis>auth-constraint</emphasis> elements into <filename>web.xml</filename>. However this protection of resources based on web.xml is not standard JBoss Enterprise Portal Platform way and it is mentioned here mainly for illustration purposes. </para> </section> @@ -685,7 +688,7 @@ <listitem> <para> - HTTP request is processed through <emphasis role="bold">SetCurrentIdentityFilter</emphasis>, which is declared in <emphasis>deploy/gatein.ear/02portal.war/WEB-INF/web.xml</emphasis>. + HTTP request is processed through <literal>SetCurrentIdentityFilter</literal>, which is declared in <filename>deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename>. </para> </listitem>