[gatein-commits] gatein SVN: r9196 - epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity.

Author: smumford Date: 2013-03-05 22:27:32 -0500 (Tue, 05 Mar 2013) New Revision: 9196 Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml Log: BZ#911516: Committing comment 16 changes Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2013-03-06 01:20:50 UTC (rev 9195) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2013-03-06 03:27:32 UTC (rev 9196) @@ -51,23 +51,20 @@ </para> <para>In <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/web.xml</filename>, authentication is triggered by accessing a secured URL <systemitem>/dologin</systemitem>: </para> - <programlisting language="XML"> -&lt;security-constraint&gt; - &lt;web-resource-collection&gt; - &lt;web-resource-name&gt;user authentication&lt;/web-resource-name&gt; - &lt;url-pattern&gt;/dologin&lt;/url-pattern&gt; - &lt;http-method&gt;POST&lt;/http-method&gt; - &lt;http-method&gt;GET&lt;/http-method&gt; - &lt;/web-resource-collection&gt; - &lt;auth-constraint&gt; - &lt;role-name&gt;users&lt;/role-name&gt; - &lt;/auth-constraint&gt; - &lt;user-data-constraint&gt; - &lt;transport-guarantee&gt;NONE&lt;/transport-guarantee&gt; - &lt;/user-data-constraint&gt; - &lt;/web-resource-collection&gt; -&lt;/security-constraint&gt; -</programlisting> + <programlisting language="XML"><![CDATA[<security-constraint> + <web-resource-collection> + <web-resource-name>user authentication</web-resource-name> + <url-pattern>/dologin</url-pattern> + <http-method>POST</http-method> + <http-method>GET</http-method> + </web-resource-collection> + <auth-constraint> + <role-name>users</role-name> + </auth-constraint> + <user-data-constraint> + <transport-guarantee>NONE</transport-guarantee> + </user-data-constraint> +</security-constraint>]]></programlisting> <para> This means that access to URLs (such as <ulink url="http://localhost:8080/portal/dologin" type="http">http://localhost:8080/portal/dologin</ulink>) will directly trigger J2EE authentication in the case that the user is not already logged in. </para> @@ -105,9 +102,6 @@ <para> After a user submits the login form, the LoginServlet will store credentials and trigger WCI login, which delegates to Servlet API (method HttpServletRequest.login(String username, String password) available in Servlet 3.0) and additionally triggers WCI Authentication listeners. Login through Servlet API delegates to JAAS. </para> - <para> - This URL is mapped to <literal>LoginServlet</literal> servlet, which stores credentials and redirects again to <literal>LoginServlet</literal>. LoginServlet triggers WCI login, which delegates to Servlet API (method HttpServletRequest.login(String username, String password) available in Servlet 3.0) and additionally triggers WCI Authentication listeners. Login through Servlet API delegates to JAAS. - </para> </section> <section id="sect-Authentication_Authorization_Intro-Login_Modules"> <title>Login Modules</title> @@ -159,8 +153,8 @@ <term>JBossAS7LoginModule</term> <listitem> <para> - The most important login module, which is normally used to perform the whole authentication by itself. First it checks if an Identity object has been already created and saved into the sharedState map by previous login modules (like SSODelegateLoginModule, CustomMembershipLoginModule or SharedStateLoginModule). If not, it triggers real authentication of the user with usage of the Authenticator interface and it will use <filename>Authentication.validateUser(Credential[] credentials)</filename> which performs real authentication of username and password against OrganizationService and the portal identity database. See <xref linkend="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor"/> for details about Authenticator and about Identity objects. </para> - <para>In the <filename>JBossAS7LoginModule.commit</filename> method, the Identity object is registered to IdentityRegistry, which will be used later for authorization. Also some JAAS principals (UserPrincipal and RolesPrincipal) are assigned to our authenticated Subject. This is needed for JBoss Enterprise Application server, so that it can properly recognize the name of the logged user and its roles on an application server level. + The most important login module, which is normally used to perform the whole authentication by itself. First it checks if an Identity object has been already created and saved into the sharedState map by previous login modules (like SSODelegateLoginModule, CustomMembershipLoginModule or SharedStateLoginModule). If not, it triggers real authentication of the user with usage of the Authenticator interface and it will use <literal>Authentication.validateUser(Credential[] credentials)</literal> which performs real authentication of username and password against OrganizationService and the portal identity database. See <xref linkend="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor"/> for details about Authenticator and about Identity objects. </para> + <para>In the <literal>JBossAS7LoginModule.commit</literal> method, the Identity object is registered to IdentityRegistry, which will be used later for authorization. Also some JAAS principals (UserPrincipal and RolesPrincipal) are assigned to our authenticated Subject. This is needed for JBoss Enterprise Application server, so that it can properly recognize the name of the logged user and its roles on an application server level. </para> </listitem> </varlistentry> @@ -176,7 +170,7 @@ Special login module, which can be used to add a user to existing groups during a successful login of this user. The group name is configurable and by default is /platform/users group. This login module is not used because in normal environment, users are already in the /platform/users group. It is useful only for some special setups like read-only LDAP, where groups of an LDAP user are taken from the LDAP tree so that users may not be in the /platform/users group, which is needed for successful authorization. </para> <para> - Note that the CustomMembershipLoginModule cannot be the first login module in the LoginModule chain because it assumes that the Identity object is already available in the shared state. So there are two possible cases. For a non-SSO case, you may need to chain this login module with other login modules, which can be used to establish Identity and add it into shared state. Those login modules can be <filename>InitSharedStateLoginModule</filename> and <filename>SharedStateLoginModule</filename>. For an SSO case, you can add <filename>CustomMembershipLoginModule</filename> between <filename>SSODelegateLoginModule</filename> and JBossAS7LoginModule. + Note that the CustomMembershipLoginModule cannot be the first login module in the LoginModule chain because it assumes that the Identity object is already available in the shared state. So there are two possible cases. For a non-SSO case, you may need to chain this login module with other login modules, which can be used to establish Identity and add it into shared state. Those login modules can be <literal>InitSharedStateLoginModule</literal> and <literal>SharedStateLoginModule</literal>. For an SSO case, you can add <literal>CustomMembershipLoginModule</literal> between <literal>SSODelegateLoginModule</literal> and <literal>JBossAS7LoginModule</literal>. </para> </listitem> </varlistentry> @@ -399,7 +393,7 @@ </listitem> <listitem> <para> - A HTTP request such as <ulink url="http://localhost:8080/portal/login?initialURI=/portal/classic&amp;amp;username=root&amp;amp;password=gtn&amp;amp;rememberme=true"/> is sent to the server. This is not a HTTP GET request and the parameters are not encoded in the URL. The login form is submitted in a HTTP POST request to the /portal/login URL. + Form data such as <literal>username</literal>, <literal>password</literal> and <literal>rememberme</literal> are sent in an HTTP POST request to the <uri>/portal/login</uri> URL, with the <literal>rememberme</literal> parameter set to true. </para> </listitem> <listitem> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml 2013-03-06 01:20:50 UTC (rev 9195) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml 2013-03-06 03:27:32 UTC (rev 9196) @@ -82,7 +82,7 @@ </programlisting> </informalexample> <para> - Please note that specified file <code>/salt/mysalt.txt</code> must exist and must be readable by user, which executed JBoss Portal Platform. The file should be properly secured so that it is not readable by every user of your operating syste,. The content of the file can be a random phrase, such as: <emphasis role="italics">a4564dac2aasddsklklkajdgnioiow</emphasis>. + Please note that specified file <code>/salt/mysalt.txt</code> must exist and must be readable by user, which executed JBoss Portal Platform. The file should be properly secured so that it is not readable by every user of your operating system. The content of the file can be a random phrase, such as: <emphasis role="italics">a4564dac2aasddsklklkajdgnioiow</emphasis>. </para> <para> The <code>FileReadingSaltEncoder</code>is probably the most secure of all options, but in addition to <code>DatabaseReadingSaltEncoder</code>, you need to set the file with salt.