From do-not-reply at jboss.org Sun Mar 3 22:54:54 2013 Content-Type: multipart/mixed; boundary="===============1155873338034822369==" MIME-Version: 1.0 From: do-not-reply at jboss.org To: gatein-commits at lists.jboss.org Subject: [gatein-commits] gatein SVN: r9193 - in epp/docs/branches/6.0/Reference_Guide/en-US: modules/AuthenticationAndIdentity and 1 other directory. Date: Sun, 03 Mar 2013 22:54:54 -0500 Message-ID: <201303040354.r243ss41028599@svn01.web.mwc.hst.phx2.redhat.com> --===============1155873338034822369== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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/AuthenticationAndIde= ntity/AuthenticationAuthorizationOverview.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIde= ntity/BackendConfiguration.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIde= ntity/PasswordEncryption.xml Log: Incremented pubsnumber to get book re-Brew-ed Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.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/6.0/Reference_Guide/en-US/Revision_History.xml 2013-0= 3-03 15:57:47 UTC (rev 9192) +++ epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2013-0= 3-04 03:54:54 UTC (rev 9193) @@ -7,7 +7,21 @@ Revision History - + + 6.0.0-55 + Mon Mar 4 2013 + + Russell + Dickenson + + + + + BZ#911516 - Incorporated new QE Review comments. + + + + 6.0.0-54 Mon Mar 4 2013 Modified: epp/docs/branches/6.0/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/6.0/Reference_Guide/en-US/modules/AuthenticationAndId= entity/AuthenticationAuthorizationOverview.xml 2013-03-03 15:57:47 UTC (rev= 9192) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndId= entity/AuthenticationAuthorizationOverview.xml 2013-03-04 03:54:54 UTC (rev= 9193) @@ -49,7 +49,7 @@ Authentication workflow consists of HTTP requests and redirect= s which include handshakes. Currently only Servlet 3.0 containers are suppo= rted, so authentication is triggered programmatically from Servlet API. - In JPP_DIST/gatein/gatein.e= ar/portal.war/WEB-INF/web.xml, authentication is triggered by ac= cessing a secured URL /dologin: + In JPP_DIST/gatein/gatein.e= ar/portal.war/WEB-INF/web.xml, authentication is triggered by ac= cessing a secured URL /dologin: <security-constraint> @@ -66,7 +66,8 @@ <transport-guarantee>NONE</transport-guarantee> </user-data-constraint> </web-resource-collection> -</security-constraint> +</security-constraint> + This means that access to URLs (such as http://localhost:8080/portal/do= login) will directly trigger J2EE authentication in the case that t= he user is not already logged in. @@ -158,7 +159,7 @@ JBossAS7LoginModule - Most important login module, which is normally used to perf= orm the whole authentication by itself. First it checks if Identity object = has been already created and saved into sharedState map by previous login m= odules (like SSODelegateLoginModule, CustomMembershipLoginModule or SharedS= tateLoginModule). If not, it triggers real authentication of user with usag= e of Authenticator interface and it will use Authentication.valid= ateUser(Credential[] credentials) which performs real authentica= tion of username and password against OrganizationService and portal identi= ty database. See for details about Authenticator and about = Identity objects. + 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 previ= ous 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 A= uthentication.validateUser(Credential[] credentials) which perfo= rms real authentication of username and password against OrganizationServic= e and the portal identity database. See for details about A= uthenticator and about Identity objects. In the JBossAS7LoginModule.commit m= ethod, 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. @@ -175,7 +176,7 @@ Special login module, which can be used to add a user to e= xisting groups during a successful login of this user. The group name is co= nfigurable and by default is /platform/users group. This login module is no= t used because in normal environment, users are already in the /platform/us= ers group. It is useful only for some special setups like read-only LDAP, w= here 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 authori= zation. - Note that the CustomMembershipLoginModule can't be the= first login module in the LoginModule chain because it assumes that the Id= entity object is already available in shared state. So there are two possib= le 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 int= o shared state. Those login modules can be InitSharedStateLoginMo= dule and SharedStateLoginModule. For an SSO= case, you can add CustomMembershipLoginModule between= SSODelegateLoginModule and JBossAS7LoginModule. + Note that the CustomMembershipLoginModule cannot be the fir= st login module in the LoginModule chain because it assumes that the Identi= ty object is already available in the shared state. So there are two possib= le 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 int= o shared state. Those login modules can be InitSharedStateLoginMo= dule and SharedStateLoginModule. For an SSO= case, you can add CustomMembershipLoginModule between= SSODelegateLoginModule and JBossAS7LoginModule. @@ -191,7 +192,7 @@ SharedStateLoginModule - It reads username and password from sharedState map fr= om attributes javax.security.auth.login.name and javax.security.auth.login.password. Then it calls Authenticator= .validateUser(Credential[] credentials), to perform authentication of usern= ame and password against OrganizationService and portal identity database. = Result of successful authentication is Identity object, which is saved to s= haredState map. + It reads the username and password from sharedState ma= p from attributes javax.security.auth.login.name and javax.security.auth.login.password. Then it calls Authentic= ator.validateUser(Credential[] credentials), to perform authentication of u= sername and password against OrganizationService and portal identity databa= se. The result of successful authentication is an Identity object, which is= saved to the sharedState map. @@ -265,11 +266,11 @@ Authentication on Application Server Level - Application server needs to properly recognize that user is succ= essfully logged and it has his JAAS roles assigned. Unfortunately this part= is not standardized and is specific for each aaplication server. For examp= le in JBoss Enterprise Application, you need to ensure that JAAS Subject ha= s an assigned UserPrincipal with username and also a RolesPrincipal, which = contains a list of JAAS roles. This part is actually done in JbossAS7= LoginModule.commit(). In Tomcat, for example, this flow is little di= fferent, which means Tomcat has it is own TomcatLoginModule. + Application server needs to properly recognize that the user is = successfully logged and it has their JAAS roles assigned. Unfortunately thi= s 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 RolesPr= incipal, which contains a list of JAAS roles. This part is actually done in= JBossAS7LoginModule.commit(). In Tomcat, for example, this fl= ow is little different, which means Tomcat has it is own TomcatLog= inModule. - After successful authentication, user needs to be at least in JAAS= role "users" because this role is declared in web.xml<= /filename> as you saw above. JAAS roles are extracted by special algorithm = from JBoss Portal Platform memberships. See below in section with RolesExtr= actor. + After successful authentication, user needs to be at least in JAAS= role users because this role is declared in web.xml as you saw above. JAAS roles are extracted by speci= al algorithm from JBoss Portal Platform memberships. See below in section w= ith RolesExtractor. Authentication on JBoss Portal Platform Level @@ -307,20 +308,20 @@ ]]> - Method validateUser is used to check w= hether given credentials (username and password) are really valid. So it pe= rforms real authentication. It returns a username if the credentials are co= rrect. Otherwise LoginException is thrown. + Method validateUser is used to authent= icate the given credentials (username and password). It returns a username = if the credentials are correct, otherwise a LoginException<= /computeroutput> is thrown. - Method createIdentity is used to creat= e instance of object org.exoplatform.services.security.Identity, which encapsulates all important information about a single user: + Method createIdentity is used to creat= e an instance of object org.exoplatform.services.security.Identit= y, which encapsulates all important information about a single u= ser: - username + Username - set of Memberships (MembershipEntry objects) which us= er has. Membership is object, which contains informati= on about membershipType (manager, member, validator, .= .. ) and about group (/platform/users, /platform/admin= istrators, /partners, /organization/management/executiveBoard, ... ). + Set of Memberships (MembershipEntry objects) associat= ed with the user. Membership = is an object, which contains information about membershipType (manager, member, validator, ... ) and about group (/platform/users, /platform/administrators, /partners, /organization/m= anagement/executiveBoard, ... ). @@ -386,24 +387,24 @@
RememberMe Authentication - In default login dialog, you can notice that there is "= ;Remember my login" checkbox, which users can use to persist their log= in 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 Remember my logi= n checkbox, which persist a user's login on their workstation. The= default validity period of the RememberMe cookie = is one day, so a user can be logged for a whole day before needing to re-au= thenticate. The validity period is configurable.
How It Works - User checks the checkbox "Remember my login&q= uot; on login screen of JBoss Portal Platform . Then submits the form. + User checks the checkbox RememberMe on the login screen of JBoss Portal Platform, then submits the f= orm. - HTTP request like is sent to server. This is n= ot 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 is sent to the server. = This is not a HTTP GET request and the parameters are not encoded in the UR= L. The login form is submitted in a HTTP POST request to the /portal/login = URL. - Request is processed by PortalLoginController serv= let. The servlet obtains instance of RemindPasswordTokenService and saves user credentials into JCR. It generates and returns spe= cial token (key) for later use. Then it creates cookie called Rem= emberMe and use returned token as value of cookie. + Request is processed by PortalLoginController serv= let. The servlet obtains an instance of RemindPasswordTokenServic= e and saves user credentials into JCR. It generates and returns = special token (key) for later use, then creates a cookie called R= ememberMe and uses the returned token as the cookie's value. Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/Authenticatio= nAndIdentity/BackendConfiguration.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/6.0/Reference_Guide/en-US/modules/AuthenticationAndId= entity/BackendConfiguration.xml 2013-03-03 15:57:47 UTC (rev 9192) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndId= entity/BackendConfiguration.xml 2013-03-04 03:54:54 UTC (rev 9193) @@ -393,7 +393,7 @@ Configuration Files The main configuration file is - JPP_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/organizatio= n/idm-configuration.xml + JPP_HOME/gatein/gatein.ear/port= al.war/WEB-INF/conf/organization/idm-configuration.xml : @@ -540,12 +540,12 @@ defaultGroupType - The name of the PicketLink IDM GroupType that will be used to = store groups. The default is'GTN_GROUP_TYPE'. + The name of the PicketLink IDM GroupType that will be used to = store groups. The default is GTN_GROUP_TYPE. - rootGroupName The name of the PicketLink IDM Grou= p that will be used as a root parent. The default is 'GTN_ROOT_G= ROUP'. + rootGroupName The name of the PicketLink IDM Grou= p that will be used as a root parent. The default is GTN_ROOT_GROUP. Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/Authenticatio= nAndIdentity/PasswordEncryption.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/6.0/Reference_Guide/en-US/modules/AuthenticationAndId= entity/PasswordEncryption.xml 2013-03-03 15:57:47 UTC (rev 9192) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndId= entity/PasswordEncryption.xml 2013-03-04 03:54:54 UTC (rev 9193) @@ -16,17 +16,17 @@ Default implementation of CredentialEncoder - is using password hashing with MD5 algorithm and storing those MD5 h= ashes in database. It does not use any salting of passwords. This is not sa= fest solution, but it'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 h= ashes in database. It does not use any salting of passwords. This is not sa= fest solution, but it is backward compatible with previous releases of JBos= s Portal Platform before version 6, where MD5 password hashing was the only= possible encoding form. So if you migrate from older release of JBoss Port= al Platform, your users will still be able to authenticate. 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.
Choosing CredentialEncoder Implementation -The implementation of CredentialEncoder is configured in file JPP_HO= ME/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/picketlink-idm/pi= cketlink-idm-config.xml. Usually the most important options are the = options of the idm_portal realm starting with credential= Encoder prefix. Possible implementations are HashingEncoder, Databas= eReadingSaltEncoder, and FileReadingSaltEncoder. +The implementation of CredentialEncoder is configured in file JPP_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf= /organization/picketlink-idm/picketlink-idm-config.xml. Usually = the most important options are the options of the idm_portal r= ealm starting with credentialEncoder prefix. Possible implemen= tations are HashingEncoder, DatabaseReadingSaltEncoder, and FileReadingSalt= Encoder.
HashingEncoder - This is the default choice. It uses only hashing of password= s with MD5 algorithm without salting. As mentioned previously, it is not th= e safest solution but it's backward compatible with the previous JBoss= Portal Platform releases, so there are no issues with database migration. = Configuration looks like this: + This is the default choice. It uses only hashing of password= s with MD5 algorithm without salting. As mentioned previously, it is not th= e safest solution but it is backward compatible with the previous JBoss Por= tal Platform releases, so there are no issues with database migration. Conf= iguration looks like this: <option> @@ -42,7 +42,7 @@
DatabaseReadingSaltEncoder - This implementation provides salting of password in addition= to hashing. The salt is unique for each user, so it's much more compl= icated 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 o= f salt ensures that all users have different salts, so even if two users ha= ve the same password, the encoded password in database will be different fo= r them. Here is configuration example, which is using SHA-256 algorithm for= hashing (more secure than MD5) and algorithm SHA1PRNG for generation of ra= ndom salts. + This implementation provides salting of password in addition= to hashing. The salt is unique for each user, so it is much more complicat= ed to decrypt password via brute force, if an attacker steals encoded passw= ords from your database. The salt is generated randomly for each user and s= tored 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 h= ashing (more secure than MD5) and algorithm SHA1PRNG for generation of rand= om salts. <option> @@ -63,7 +63,7 @@
FileReadingSaltEncoder - The FileReadingSaltEncoder also uses hashing and salting, so it&= apos;s similar to the previous encoder. But it's theoretically even mo= re secure, because salts are not stored in PicketLink IDM database together= with passwords. Salt of each user is generated from saltPrefix and user's username. And saltPrefix 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 secur= e, because salts are not stored in the PicketLink IDM database together wit= h passwords. Salt of each user is generated from saltPrefix and user's username. And saltPrefix is read from some file in your file system. Conf= iguration can look like this: @@ -82,15 +82,15 @@ - Please note that specified file /salt/mysalt.txt mu= st 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 a4564dac2aasddsklklkajdgnioiow. + Please note that specified file /salt/mysalt.txt mu= st 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 u= ser of your operating syste,. The content of the file can be a random phras= e, such as: a4564dac2aasddsklklkajdgnioiow. -So the FileReadingSaltEncoderis probably the most secure of a= ll options, but in addition to DatabaseReadingSaltEncoder, you= need to set the file with salt. + The FileReadingSaltEncoderis probably the most secu= re of all options, but in addition to DatabaseReadingSaltEncoder, you need to set the file with salt. Important - The CredentialEncoder from above is actually used= only for encoding of passwords in PicketLink IDM database. It's not u= sed for LDAP. PicketLink IDM LDAP implementation (LDAPIdentityStore) 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 DatabaseReadingSaltEncoder implementation). + The CredentialEncoder from above is actually used= only for encoding of passwords in PicketLink IDM database. It is not used = for LDAP. PicketLink IDM LDAP implementation (LDAPIdentityStore) sends passwords to the LDAP server in plain form, because password encod= ing is usually provided by LDAP server itself. For example OpenDS 2 is usin= g SHA1 based hashing of passwords with random generation of user salt (so a= ctually something similar to our DatabaseReadingSaltEncoder im= plementation).
--===============1155873338034822369==--