[gatein-commits] gatein SVN: r9193 - in epp/docs/branches/6.0/Reference_Guide/en-US: modules/AuthenticationAndIdentity and 1 other directory.

Author: rdickens Date: 2013-03-03 22:54:54 -0500 (Sun, 03 Mar 2013) New Revision: 9193 Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/BackendConfiguration.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml Log: Incremented pubsnumber to get book re-Brew-ed Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2013-03-03 15:57:47 UTC (rev 9192) +++ epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2013-03-04 03:54:54 UTC (rev 9193) @@ -7,7 +7,21 @@ <title>Revision History</title> <simpara> <revhistory> - <revision> + <revision> + <revnumber>6.0.0-55</revnumber> + <date>Mon Mar 4 2013</date> + <author> + <firstname>Russell</firstname> + <surname>Dickenson</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>BZ#911516 - Incorporated new QE Review comments.</member> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>6.0.0-54</revnumber> <date>Mon Mar 4 2013</date> <author> 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-03 15:57:47 UTC (rev 9192) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2013-03-04 03:54:54 UTC (rev 9193) @@ -49,7 +49,7 @@ <para> Authentication workflow consists of HTTP requests and redirects which include handshakes. Currently only Servlet 3.0 containers are supported, so authentication is triggered programmatically from Servlet API. </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>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; @@ -66,7 +66,8 @@ &lt;transport-guarantee&gt;NONE&lt;/transport-guarantee&gt; &lt;/user-data-constraint&gt; &lt;/web-resource-collection&gt; -&lt;/security-constraint&gt; </programlisting> +&lt;/security-constraint&gt; +</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> @@ -158,7 +159,7 @@ <term>JBossAS7LoginModule</term> <listitem> <para> - Most important login module, which is normally used to perform the whole authentication by itself. First it checks if Identity object has been already created and saved into sharedState map by previous login modules (like SSODelegateLoginModule, CustomMembershipLoginModule or SharedStateLoginModule). If not, it triggers real authentication of user with usage of Authenticator interface and it will use <filename>Authentication.validateUser(Credential[] credentials)</filename> which performs real authentication of username and password against OrganizationService and portal identity database. See <xref linkend="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor"/> for details about Authenticator and about Identity objects. </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. </para> </listitem> @@ -175,7 +176,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 can&apos;t be the first login module in the LoginModule chain because it assumes that the Identity object is already available in 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 <filename>InitSharedStateLoginModule</filename> and <filename>SharedStateLoginModule</filename>. For an SSO case, you can add <filename>CustomMembershipLoginModule</filename> between <filename>SSODelegateLoginModule</filename> and JBossAS7LoginModule. </para> </listitem> </varlistentry> @@ -191,7 +192,7 @@ <term>SharedStateLoginModule</term> <listitem> <para> - It reads username and password from sharedState map from attributes <literal>javax.security.auth.login.name</literal> and <literal>javax.security.auth.login.password</literal>. Then it calls Authenticator.validateUser(Credential[] credentials), to perform authentication of username and password against OrganizationService and portal identity database. Result of successful authentication is Identity object, which is saved to sharedState map. + It reads the username and password from sharedState map from attributes <literal>javax.security.auth.login.name</literal> and <literal>javax.security.auth.login.password</literal>. Then it calls Authenticator.validateUser(Credential[] credentials), to perform authentication of username and password against OrganizationService and portal identity database. The result of successful authentication is an Identity object, which is saved to the sharedState map. </para> </listitem> </varlistentry> @@ -265,11 +266,11 @@ <formalpara id="form-Authentication_Authorization_Intro-authenticationAppServerLevel"> <title>Authentication on Application Server Level</title> <para> - Application server needs to properly recognize that user is successfully logged and it has his JAAS roles assigned. Unfortunately this part is not standardized and is specific for each aaplication server. For example in JBoss Enterprise Application, you need to ensure that JAAS Subject has an assigned UserPrincipal with username and also a RolesPrincipal, which contains a list of JAAS roles. This part is actually done in <code>JbossAS7LoginModule.commit()</code>. In Tomcat, for example, this flow is little different, which means Tomcat has it is own <literal>TomcatLoginModule</literal>. + Application server needs to properly recognize that the user is successfully logged and it has their JAAS roles assigned. Unfortunately this part is not standardized and is specific for each aaplication server. For example in JBoss Enterprise Application Platform, you need to ensure that JAAS Subject has an assigned UserPrincipal with username and also a RolesPrincipal, which contains a list of JAAS roles. This part is actually done in <code>JBossAS7LoginModule.commit()</code>. In Tomcat, for example, this flow is little different, which means Tomcat has it is own <literal>TomcatLoginModule</literal>. </para> </formalpara> <para> - After successful authentication, user needs to be at least in JAAS role &quot;users&quot; because this role is declared in <filename>web.xml</filename> as you saw above. JAAS roles are extracted by special algorithm from JBoss Portal Platform memberships. See below in section with RolesExtractor. + After successful authentication, user needs to be at least in JAAS role <systemitem>users</systemitem> because this role is declared in <filename>web.xml</filename> as you saw above. JAAS roles are extracted by special algorithm from JBoss Portal Platform memberships. See below in section with RolesExtractor. </para> <formalpara id="form-Authentication_Authorization_Intro-authenticationGateInServerLevel"> <title>Authentication on JBoss Portal Platform Level</title> @@ -307,20 +308,20 @@ ]]> </programlisting> <para> - Method <emphasis>validateUser</emphasis> is used to check whether given credentials (username and password) are really valid. So it performs real authentication. It returns a username if the credentials are correct. Otherwise LoginException is thrown. + Method <emphasis>validateUser</emphasis> is used to authenticate the given credentials (username and password). It returns a username if the credentials are correct, otherwise a <computeroutput>LoginException</computeroutput> is thrown. </para> <para> - Method <emphasis>createIdentity</emphasis> is used to create instance of object <emphasis>org.exoplatform.services.security.Identity</emphasis>, which encapsulates all important information about a single user: + Method <emphasis>createIdentity</emphasis> is used to create an instance of object <emphasis>org.exoplatform.services.security.Identity</emphasis>, which encapsulates all important information about a single user: </para> <itemizedlist> <listitem> <para> - username + Username </para> </listitem> <listitem> <para> - set of Memberships (MembershipEntry objects) which user has. <emphasis>Membership</emphasis> is object, which contains information about <emphasis>membershipType</emphasis> (manager, member, validator, ... ) and about <emphasis>group</emphasis> (/platform/users, /platform/administrators, /partners, /organization/management/executiveBoard, ... ). + Set of Memberships (MembershipEntry objects) associated with the <systemitem>user</systemitem>. <emphasis>Membership</emphasis> is an object, which contains information about <emphasis>membershipType</emphasis> (manager, member, validator, ... ) and about <emphasis>group</emphasis> (/platform/users, /platform/administrators, /partners, /organization/management/executiveBoard, ... ). </para> </listitem> <listitem> @@ -386,24 +387,24 @@ <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication"> <title>RememberMe Authentication</title> <para> - In default login dialog, you can notice that there is &quot;Remember my login&quot; 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 re-authenticate. + In the default login dialog is the <screen>Remember my login</screen> checkbox, which persist a user's login on their workstation. The default validity period of the <systemitem>RememberMe</systemitem> cookie is one day, so a user can be logged for a whole day before needing to re-authenticate. The validity period is configurable. </para> <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication-howDoesItWork"> <title>How It Works</title> <itemizedlist> <listitem> <para> - User checks the checkbox &quot;Remember my login&quot; on login screen of JBoss Portal Platform . Then submits the form. + User checks the checkbox <systemitem>RememberMe</systemitem> on the login screen of JBoss Portal Platform, then submits the form. </para> </listitem> <listitem> <para> - HTTP request like <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 server. This is not a HTTP GET request and the parameters are not encoded in URL. The login form is submitted in a HTTP POST request to the /portal/login URL. + 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. </para> </listitem> <listitem> <para> - Request is processed by PortalLoginController servlet. The servlet obtains instance of <emphasis>RemindPasswordTokenService</emphasis> and saves user credentials into JCR. It generates and returns special token (key) for later use. Then it creates cookie called <emphasis>RememberMe</emphasis> and use returned token as value of cookie. + Request is processed by PortalLoginController servlet. The servlet obtains an instance of <emphasis>RemindPasswordTokenService</emphasis> and saves user credentials into JCR. It generates and returns special token (key) for later use, then creates a cookie called <emphasis>RememberMe</emphasis> and uses the returned token as the cookie's value. </para> </listitem> </itemizedlist> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/BackendConfiguration.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/BackendConfiguration.xml 2013-03-03 15:57:47 UTC (rev 9192) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/BackendConfiguration.xml 2013-03-04 03:54:54 UTC (rev 9193) @@ -393,7 +393,7 @@ <title>Configuration Files</title> <para> The main configuration file is - <code>JPP_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/idm-configuration.xml</code> + <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/idm-configuration.xml</filename> : </para> <informalexample> @@ -540,12 +540,12 @@ <listitem> <para> <code>defaultGroupType</code> - The name of the PicketLink IDM GroupType that will be used to store groups. The default is<code>&apos;GTN_GROUP_TYPE&apos;</code>. + The name of the PicketLink IDM GroupType that will be used to store groups. The default is <code>GTN_GROUP_TYPE</code>. </para> </listitem> <listitem> <para> - <code>rootGroupName</code> The name of the PicketLink IDM Group that will be used as a root parent. The default is <code>&apos;GTN_ROOT_GROUP&apos;</code>. + <code>rootGroupName</code> The name of the PicketLink IDM Group that will be used as a root parent. The default is <code>GTN_ROOT_GROUP</code>. </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-03 15:57:47 UTC (rev 9192) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml 2013-03-04 03:54:54 UTC (rev 9193) @@ -16,17 +16,17 @@ <para> Default implementation of <code>CredentialEncoder</code> - is using password hashing with MD5 algorithm and storing those MD5 hashes in database. It does not use any salting of passwords. This is not safest solution, but it&apos;s backward compatible with previous releases of JBoss Portal Platform before version 6, where MD5 password hashing was the only possible encoding form. So if you migrate from older release of JBoss Portal Platform, your users will still be able to authenticate. + is using password hashing with MD5 algorithm and storing those MD5 hashes in database. It does not use any salting of passwords. This is not safest solution, but it is backward compatible with previous releases of JBoss Portal Platform before version 6, where MD5 password hashing was the only possible encoding form. So if you migrate from older release of JBoss Portal Platform, your users will still be able to authenticate. </para> <para>However if you are starting from a fresh database (no migration from previous JBoss Portal Platform release), you may increase security by using better hashing algorithm and especially by enabling password salting. See below for details.</para> <section id="sid-54264610_PasswordEncryption-ChoosingCredentialEncoderimplementation"> <title>Choosing CredentialEncoder Implementation</title> <para> -The implementation of CredentialEncoder is configured in file <code>JPP_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/picketlink-idm/picketlink-idm-config.xml</code>. Usually the most important options are the options of the <code>idm_portal</code> realm starting with <code>credentialEncoder</code> prefix. Possible implementations are HashingEncoder, DatabaseReadingSaltEncoder, and FileReadingSaltEncoder. +The implementation of CredentialEncoder is configured in file <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/picketlink-idm/picketlink-idm-config.xml</filename>. Usually the most important options are the options of the <code>idm_portal</code> realm starting with <code>credentialEncoder</code> prefix. Possible implementations are HashingEncoder, DatabaseReadingSaltEncoder, and FileReadingSaltEncoder. </para> <section id="sid-54264610_PasswordEncryption-HashingEncoder"> <title>HashingEncoder</title> - <para>This is the default choice. It uses only hashing of passwords with MD5 algorithm without salting. As mentioned previously, it is not the safest solution but it&apos;s backward compatible with the previous JBoss Portal Platform releases, so there are no issues with database migration. Configuration looks like this:</para> + <para>This is the default choice. It uses only hashing of passwords with MD5 algorithm without salting. As mentioned previously, it is not the safest solution but it is backward compatible with the previous JBoss Portal Platform releases, so there are no issues with database migration. Configuration looks like this:</para> <informalexample> <programlisting> &lt;option&gt; @@ -42,7 +42,7 @@ </section> <section id="sid-54264610_PasswordEncryption-DatabaseReadingSaltEncoder"> <title>DatabaseReadingSaltEncoder</title> - <para>This implementation provides salting of password in addition to hashing. The salt is unique for each user, so it&apos;s much more complicated to decrypt password via brute force, if some attacker steals encoded passwords from your database. The salt is generated randomly for each user and stored in PicketLink IDM database as an attribute. Random generation of salt ensures that all users have different salts, so even if two users have the same password, the encoded password in database will be different for them. Here is configuration example, which is using SHA-256 algorithm for hashing (more secure than MD5) and algorithm SHA1PRNG for generation of random salts.</para> + <para>This implementation provides salting of password in addition to hashing. The salt is unique for each user, so it is much more complicated to decrypt password via brute force, if an attacker steals encoded passwords from your database. The salt is generated randomly for each user and stored in the PicketLink IDM database as an attribute. Random generation of salt ensures that all users have different salts, so even if two users have the same password, the encoded password in database will be different for them. Here is configuration example, which is using SHA-256 algorithm for hashing (more secure than MD5) and algorithm SHA1PRNG for generation of random salts.</para> <informalexample> <programlisting> &lt;option&gt; @@ -63,7 +63,7 @@ <section id="sid-54264610_PasswordEncryption-FileReadingSaltEncoder"> <title>FileReadingSaltEncoder</title> <para> - The FileReadingSaltEncoder also uses hashing and salting, so it&apos;s similar to the previous encoder. But it&apos;s theoretically even more secure, because salts are not stored in PicketLink IDM database together with passwords. Salt of each user is generated from <emphasis role="italics">saltPrefix</emphasis> and user&apos;s username. And <emphasis role="italics">saltPrefix</emphasis> is read from some file in your file system. Configuration can look like this: + The FileReadingSaltEncoder also uses hashing and salting, so it is similar to the previous encoder. But it is theoretically even more secure, because salts are not stored in the PicketLink IDM database together with passwords. Salt of each user is generated from <emphasis role="italics">saltPrefix</emphasis> and user&apos;s username. And <emphasis role="italics">saltPrefix</emphasis> is read from some file in your file system. Configuration can look like this: </para> <informalexample> <programlisting> @@ -82,15 +82,15 @@ </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 readable by every user of your OS. 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 syste,. The content of the file can be a random phrase, such as: <emphasis role="italics">a4564dac2aasddsklklkajdgnioiow</emphasis>. </para> <para> -So 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. + 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. </para> <important> <title>Important</title> <para> - The <code>CredentialEncoder</code> from above is actually used only for encoding of passwords in PicketLink IDM database. It&apos;s not used for LDAP. PicketLink IDM LDAP implementation (<code>LDAPIdentityStore</code>) is sending passwords to LDAP server in plain form, because password encoding is usually provided by LDAP server itself. For example OpenDS 2 is using SHA1 based hashing of passwords with random generation of user salt (so actually something similar to our <code>DatabaseReadingSaltEncoder</code> implementation). + The <code>CredentialEncoder</code> from above is actually used only for encoding of passwords in PicketLink IDM database. It is not used for LDAP. PicketLink IDM LDAP implementation (<code>LDAPIdentityStore</code>) sends passwords to the LDAP server in plain form, because password encoding is usually provided by LDAP server itself. For example OpenDS 2 is using SHA1 based hashing of passwords with random generation of user salt (so actually something similar to our <code>DatabaseReadingSaltEncoder</code> implementation). </para> </important> </section>