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

Author: smumford Date: 2012-01-08 18:45:52 -0500 (Sun, 08 Jan 2012) New Revision: 8279 Added: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml Log: JBEPP-1468: Adding new content files Added: 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 (rev 0) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2012-01-08 23:45:52 UTC (rev 8279) @@ -0,0 +1,707 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + <!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent"> + %BOOK_ENTITIES; + ]> + <section id="sect-Reference_Guide-Authentication_Authorization_Intro"> + <title>Authentication and Authorization intro</title> + + <section id="sect-Reference_Guide-Authentication_Authorization_Intro-Authentication"> + <title>Authentication Overview</title> + + <para> + Authentication in JBoss Enterprise Portal Platform is based on <ulink type="http" url="http://docs.oracle.com/javase/6/docs/technotes/guides/security/... and by default it is a standard J2EE FORM based authentication. + </para> + + <para> + JBoss Enterprise Portal Platform supports the following authentication methods: + </para> + + <itemizedlist> + <listitem> + <para> + J2EE FORM based authentication + </para> + </listitem> + + <listitem> + <para> + The <literal>RememberMe</literal> authentication method (wherein the user checks the <guilabel>Remember my login</guilabel> checkbox on the log in form). + </para> + </listitem> + + <listitem> + <para> + SSO server integration (CAS, JOSSO, OpenSSO). Refer to <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On" /> for more information. + </para> + </listitem> + + <listitem> + <para> + SPNEGO authentication with a Kerberos ticket. Refer to <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism" /> for more information. + </para> + </listitem> + + <listitem> + <para> + Cluster authentication with loadbalancer or with JBoss SSO valve. Refer to <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve" /> for more information. + </para> + </listitem> + </itemizedlist> + + <para> + Authentication workflow consists of HTTP requests and redirects which include handshakes. Source code related to authentication is partially included in the WCI module, as the authentication process differs on <ulink type="http" url="http://www.jcp.org/en/jsr/detail?id=154">Servlet 2.5</ulink> containers and <ulink type="http" url="http://www.jcp.org/en/jsr/detail?id=315">Servlet 3.0</ulink> containers. + </para> + + <para> + First you can see in <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> that authentication is triggered by accessing a secured URL: + </para> +<programlisting language="XML" role="XML"> +<![CDATA[ + <security-constraint> + <web-resource-collection> + <web-resource-name>user authentication</web-resource-name> + <url-pattern>/dologin</url-pattern> + <url-pattern>/private/*</url-pattern> + <url-pattern>/g/*</url-pattern> + <url-pattern>/u/*</url-pattern> + </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 some URLs (such as <ulink type="http" url="http://localhost:8080/portal/dologin">http://localhost:8080/portal/dologin</ulink>) will directly trigger J2EE authentication in the case that the user is not already logged in. + </para> + <para> + Access to this URL also means that the user needs to be in the JAAS group <emphasis>users</emphasis>, otherwise they can authenticate but will recieve an HTTP error; <emphasis>403 Forbidden</emphasis>, for example. + </para> + + <para> + In the next part of the file we can see that authentication is FORM based and it starts by redirection to <emphasis>/initiatelogin</emphasis> URL, which is actually mapped to <literal>InitiateLoginServlet</literal>. + </para> +<programlisting language="XML" role="XML"> +<![CDATA[ + <login-config> + <auth-method>FORM</auth-method> + <realm-name>gatein-domain</realm-name> + <form-login-config> + <form-login-page>/initiatelogin</form-login-page> + <form-error-page>/errorlogin</form-error-page> + </form-login-config> + </login-config> +]]> + </programlisting> + <para> + <literal>InitiateLoginServlet</literal> simply redirects user to login page placed in <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/login/jsp/login.jsp</filename>. + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/AuthenticationAndIdentity/Overview/loginScreen.png" format="PNG" align="center"/> + </imageobject> + + <imageobject role="fo"> + <imagedata fileref="images/AuthenticationAndIdentity/Overview/loginScreen.png" scalefit="1" format="PNG" align="center"/> + </imageobject> + </mediaobject> + </para> + + <para> + Changes to the appearance of this login page can be made in this JSP file. You can also change image or CSS placed in <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/login/skin</filename> . + </para> + + <para> + After a user submits the login form, they are redirected to the login URL; <ulink type="http" url="http://localhost:8080/portal/login?username=root&amp;password=gtn&amp;initialURI=/portal/classic">http://localhost:8080/portal/login?username=root&amp;password=gtn&amp;initialURI=/portal/private/classic</ulink>. + </para> + <para> + This URL is mapped to <literal>PortalLoginController</literal> servlet, which stores credentials and redirects again to <literal>InitiateLoginServlet</literal>, which performs a WCI login. + </para> + <para> + The WCI layer can recognize the current servlet container to determine if it is the old container with Servlet API 2.5 (JBoss 5, Tomcat 6) or the newer container with Servlet API 3.0 (JBoss 6, JBoss 7, Tomcat 7). + </para> + + <formalpara> + <title>Servlet 3.0</title> + <para> + The newer servlet API supports programmatic authentication by calling method <literal>HttpServletRequest.login(String username, String password)</literal>. This will directly call JAAS authentication without needing to perform any redirects. + </para> + </formalpara> + + <formalpara> + <title>Servlet 2.5</title> + <para> + The older API does not support programmatic authentication, so a redirection to a URL which will trigger JAAS authentication (such as; <ulink type="http" url="http://localhost:8080/portal/j_security_check?j_username=root&amp;j_password=wci-ticket-1385113882&amp;initialURI=/portal/private/classic/"></ulink>) is required. In this case, JAAS authentication is not triggered with a user password but with a WCI ticket which is created by <literal>InitiateLoginServlet</literal> during WCI login and saved into WCI <emphasis>TicketService</emphasis>. The purpose of this ticket is to avoid using a password during the URL redirection. + </para> + </formalpara> + </section> + + <section id="sect-Reference_Guide-Authentication_Authorization_Intro-LoginModules"> + <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. + </para> + <para> + Below is the default login modules stack: + </para> +<programlisting language="XML" role="XML"><![CDATA[ + <login-module code="org.gatein.wci.security.WCILoginModule" flag="optional"> + <module-option name="portalContainerName">portal</module-option> + <module-option name="realmName">gatein-domain</module-option> + </login-module> + <login-module code="org.exoplatform.web.security.PortalLoginModule" flag="required"> + <module-option name="portalContainerName">portal</module-option> + <module-option name="realmName">gatein-domain</module-option> + </login-module> + <login-module code="org.exoplatform.services.security.jaas.SharedStateLoginModule" flag="required"> + <module-option name="portalContainerName">portal</module-option> + <module-option name="realmName">gatein-domain</module-option> + </login-module> + + <!-- Uncomment this part to check on each login if user is member of "/platform/users" group and if not + create such membership --> + <!-- + <login-module code="org.exoplatform.services.organization.idm.CustomMembershipLoginModule" flag="required"> + <module-option name="portalContainerName">portal</module-option> + <module-option name="realmName">gatein-domain</module-option> + <module-option name="membershipType">member</module-option> + <module-option name="groupId">/platform/users</module-option> + </login-module> + --> + + <login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required"> + <module-option name="portalContainerName">portal</module-option> + <module-option name="realmName">gatein-domain</module-option> + </login-module>]]></programlisting> + <para> + New login modules can be added or the stack completely replaced with custom modules. + </para> + <para> + Some points to consider are: + </para> + + <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. + </para> + </listitem> + + <listitem> + <para> + Authentication through a WCI ticket is used for FORM based authentication in Servlet 2.5 containers (JBoss 5 or Tomcat 6). The majority of other cases (Servlet 3.0 login, JBoss SSO valve login, login through <ulink type="http" url="http://code.google.com/p/crsh/">Crash</ulink>;, BASIC authentication) are using an actual password. + </para> + </listitem> + + <listitem> + <para> + Authentication starts with the invocation of the <emphasis>login</emphasis> method on each login module. Once all <emphasis>login</emphasis> methods are invoked, then authentication continues by invoking the <emphasis>commit</emphasis> method on each login module. + </para> + <para> + Either method (<emphasis>login</emphasis> or <emphasis>commit</emphasis>) can throw <literal>LoginException</literal>. If this happens, the whole authentication process ends unsuccessfully, which in turn, invokes the <emphasis>abort</emphasis> method on each login module. + </para> + <para> + By returning "false" from the login method ensures that login module is ignored. This is not specific to JBoss Enterprise Portal Platform but generic to JAAS. More info about login modules in general can be found at <ulink type="http" url="http://docs.oracle.com/javase/6/docs/technotes/guides/security/...;. + </para> + </listitem> + </itemizedlist> + + <section id="sect-Authentication_Authorization_Intro-existingLM"> + <title>Existing login modules</title> + + <para> + Here is a brief description of existing login modules: + </para> + <variablelist> + <title>Modules</title> + <varlistentry> + <term>WCILoginModule</term> + <listitem> + <para> + This login module validates WCI login tickets and then finds the actual username and password of the user from WCI <emphasis>TicketService</emphasis>. It saves these details into <literal>sharedState</literal> map. The username is saved under the key <literal>javax.security.auth.login.name</literal> and the password is saved under the key <literal>javax.security.auth.login.password</literal>. + </para> + <note> + <title>Note</title> + <para> + If you trigger JAAS authentication with a literal username and password and not with a WCI ticket credential, the <literal>WCILoginModule</literal> throws a <literal>LoginException</literal>. However <literal>WCILoginModule</literal> is declared as "<emphasis>optional</emphasis>", meaning that a login failure in <literal>WCILoginModule</literal> is not a critical error to the full login process. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term>PortalLoginModule</term> + <listitem> + <para> + This login module is actually used mainly in cluster environments. It uses session replication between cluster nodes. After a successful authentication on cluster <emphasis>node1</emphasis> the <emphasis>commit</emphasis> method adds a flag (with the attribute <emphasis>AUTHENTICATED_CREDENTIALS</emphasis>) to the HTTP session and this flag can then be used to reauthenticate on <emphasis>node2</emphasis> when it executes method <emphasis>login</emphasis>. Refer to <xref linkend="sect-Authentication_Authorization_Intro-ClusterLogin" /> for more information. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>SharedStateLoginModule</term> + <listitem> + <para> + This login module triggers authentication using the <emphasis>Authenticator</emphasis> interface. It takes the username and password from the <literal>javax.security.auth.login.name</literal> and <literal>javax.security.auth.login.password</literal> attributes of the <literal>sharedState</literal> map. + </para> + <para> + Then it calls <literal>Authenticator.validateUser(Credential[] credentials)</literal>, which performs real authentication of username and password against OrganizationService and portal identity database. Result of successful authentication is object <emphasis>Identity</emphasis>, which is saved to sharedState map under key <literal>exo.security.identity</literal>. More info in <xref linkend="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor" />. + </para> + <para> + SharedStateLoginModule assumes that mentioned attributes for username and password are already placed in sharedState map, which was actually done by WCILoginModule. If attributes are not in sharedState map, SharedStateLoginModule is simply ignored (method "login" returns false). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>JbossLoginModule</term> + <listitem> + <para> + Previous login modules (like <literal>WCILoginModule</literal> and <literal>SharedStateLoginModule</literal>) are useful for authentication flow with WCI ticket. <literal>DefaultLoginModule</literal> (superclass of <literal>JbossLoginModule</literal>) is used for second case (authentication with real password instead of WCI ticket). + </para> + <para> + First it checks if Identity object has been already created and saved into <literal>sharedState</literal> map by <literal>SharedStateLoginModule</literal>. If not, then it means that WCI ticket authentication was not successful and so it tries to login with real password of user. It also uses <literal>Authentication.validateUser(Credential[] credentials)</literal> for authentication check. + </para> + <para> + In method <literal>JbossLoginModule.commit</literal>, we need to assign our Identity object to <literal>IdentityRegistry</literal>, which will be used later for authorization. We also need to create JAAS principals (<literal>UserPrincipal</literal> and <literal>RolesPrincipal</literal>) and assign them to our authenticated Subject. This is needed for JBoss AS server, so that it can properly recognize name of logged user and their role on JBoss AS level. + </para> + </listitem> + </varlistentry> + <varlistentry> + <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. + </para> + </listitem> + </varlistentry> + </variablelist> + + <section id="sect-Authentication_Authorization_Intro-LoginModuleLocations"> + <title>SVN location of login modules</title> + + <para> + Some modules are specific for portal, but some are used also by eXo JCR and so they are part of eXo core module. + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>PortalLoginModule</emphasis> - is located in JBoss Enterprise Portal Platform sources in <ulink type="http" url="http://anonsvn.jboss.org/repos/gatein/portal/trunk/component/we... + </para> + </listitem> + + <listitem> + <para> + <emphasis>SharedStateLoginModule, JbossLoginModule</emphasis> - these are located in eXo core sources in <ulink type="http" url="http://anonsvn.jboss.org/repos/exo-jcr/core/trunk/exo.core.comp... + </para> + </listitem> + + <listitem> + <para> + <emphasis>CustomMembershipLoginModule</emphasis> - located in JBoss Enterprise Portal Platform sources in module for identity integration - <ulink type="http" url="http://anonsvn.jboss.org/repos/gatein/portal/trunk/component/id... + </para> + </listitem> + </itemizedlist> + </section> + </section> +<!-- Ending section with existing login modules --> + <section id="sect-Authentication_Authorization_Intro-createNewLM"> + <title>Creating your own login module</title> + + <para> + Before creating your own login module, it is recommended that you study the source code of existing login modules to better understand the JAAS authentication process. You need to have good knowledge so that you can properly decide where your login module should be placed and if you need to replace some existing login modules or simply attach your own module to existing chain. + </para> + + <para> + We have actually two levels of authentication and overall result of JAAS authentication should properly handle both these cases: + </para> + + <itemizedlist> + <listitem> + <para> + Authentication on application server level + </para> + </listitem> + + <listitem> + <para> + Authentication on JBoss Enterprise Portal Platform level + </para> + </listitem> + </itemizedlist> + + <formalpara id="form-Authentication_Authorization_Intro-authenticationAppServerLevel"> + <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>. + </para> + </formalpara> + + <para> + 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 special algorithm from JBoss Enterprise Portal Platform memberships. See below in section with RolesExtractor. + </para> + + + <formalpara id="form-Authentication_Authorization_Intro-authenticationGateInServerLevel"> + <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. + </para> + </formalpara> + + <para> + So have this in mind, if you will extend or replace existing login modules. + </para> + </section> +<!-- Ending section with your own login module --> + <section id="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor"> + <title>Authenticator and RolesExtractor</title> + + <para> + Authenticator is important component in authentication process. Actually interface <emphasis>org.exoplatform.services.security.Authenticator</emphasis> looks like this: + </para> +<programlisting language="Java" role="Java"> +<![CDATA[ +public interface Authenticator +{ + + /** + * Authenticate user and return userId. + * + * @param credentials - list of users credentials (such as name/password, X509 + * certificate etc) + * @return userId + */ + String validateUser(Credential[] credentials) throws LoginException, Exception; + + /** + * @param userId. + * @return Identity + */ + Identity createIdentity(String userId) throws Exception; + +} + ]]> + </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 back username if credentials are correct. Otherwise LoginException 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 informations about single user like: + </para> + + <itemizedlist> + <listitem> + <para> + username + </para> + </listitem> + + <listitem> + <para> + set of Memberships (MembershipEntry objects) which user belongs to. <emphasis>Membership</emphasis> is object, which contains informations about <emphasis>membershipType</emphasis> (manager, member, validator, ... ) and about <emphasis>group</emphasis> (/platform/users, /platform/administrators, /partners, /organization/management/executiveBoard, ... ). + </para> + </listitem> + + <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: + </para> + </listitem> + </itemizedlist> +<programlisting language="Java" role="Java"> + <![CDATA[ +public interface RolesExtractor +{ + + /** + * Extracts J2EE roles from userId and|or groups the user belongs to both + * parameters may be null + * + * @param userId + * @param memberships + */ + Set<String> extractRoles(String userId, Set<MembershipEntry> memberships); +} + ]]> + </programlisting> + <para> + Default implementation <emphasis>DefaultRolesExtractorImpl</emphasis> is based on special algorithm, which uses name of role from the root of the group (for example for role "/organization/management/something" we have JAAS role "organization"). Only exception is group "platform" where we use 2nd level as name of group. For example from group "/platform/users" we have JAAS role "users". + </para> + + <para> + <emphasis role="bold">Example: </emphasis> We have user <emphasis>root</emphasis>, which has memberships <emphasis>member:/platform/users</emphasis>, <emphasis>manager:/platform/administrators</emphasis>, <emphasis>validator:/platform/managers</emphasis>, <emphasis>member:/partners</emphasis>, <emphasis>member:/customers/acme</emphasis>, <emphasis>member:/organization/management/board</emphasis>. In this case we will have JAAS roles: <emphasis>users</emphasis>, <emphasis>administrators</emphasis>, <emphasis>managers</emphasis>, <emphasis>partners</emphasis>, <emphasis>customers</emphasis>, <emphasis>organization</emphasis>. + </para> + + <para> + Default implementation of Authenticator is <emphasis>OrganizationAuthenticatorImpl</emphasis>, which is implementation based on <emphasis>OrganizationService</emphasis>. See <xref linkend="sect-Reference_Guide-Organization_API"/> . + </para> + + <para> + You can override default implementation of mentioned interfaces Authenticator and RolesExtractor if default behaviour is not suitable for your needs. Consult documentation of <emphasis>eXo kernel</emphasis> for more info. + </para> + </section> +<!-- Ending section Authenticator and RolesExtractor --> + </section> +<!-- Ending section with login modules --> + <section id="sect-Authentication_Authorization_Intro-differentAuthWorkflows"> + <title>Different authentication workflows</title> + + <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication"> + <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. + </para> + + <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication-howDoesItWork"> + <title>How does it work</title> + + <itemizedlist> + <listitem> + <para> + User checks the checkbox "Remember my login" on login screen of JBoss Enterprise Portal Platform . Then he submit 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 + </para> + </listitem> + + <listitem> + <para> + Request is processed by PortalLoginController servlet. Servlet obtains instance of <emphasis>RemindPasswordTokenService</emphasis> and save 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. + </para> + </listitem> + </itemizedlist> + </section> + + <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication-reauthentication"> + <title>Reauthentication</title> + + <itemizedlist> + <listitem> + <para> + After some time, user wants to reauthenticate. Let's assume that his HTTP Session is already expired but his RememberMe cookie is still active. + </para> + </listitem> + + <listitem> + <para> + User send HTTP request to some portal page (ie. <emphasis>http://localhost:8080/portal/classic</emphasis> ). + </para> + </listitem> + + <listitem> + <para> + There is special HTTP Filter <emphasis role="bold">RememberMeFilter</emphasis> configured in web.xml, which checks rememberme cookie and then it retrieves credentials of user from RemindPasswordTokenService. Now filter redirects request to PortalLoginController and authentication process goes in same way as for normal FORM based authentication. + </para> + </listitem> + </itemizedlist> + </section> + + <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication-RemindPasswordTokenService"> + <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" /> + </para> + + <para> + Another thing is that you can encrypt passwords before store them into JCR. More info is in section <xref linkend="sect-Reference_Guide-Authentication_and_Identity-Password_Encryption" />. + </para> + </section> + </section> + + <section id="sect-Authentication_Authorization_Intro-BASICAuthentication"> + <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: + </para> +<programlisting language="XML" role="XML"> + <![CDATA[ +<!-- + <login-config> + <auth-method>FORM</auth-method> + <realm-name>gatein-domain</realm-name> + <form-login-config> + <form-login-page>/initiatelogin</form-login-page> + <form-error-page>/errorlogin</form-error-page> + </form-login-config> + </login-config> +--> + <login-config> + <auth-method>BASIC</auth-method> + <realm-name>gatein-domain</realm-name> + </login-config + ]]> + </programlisting> + <para> + In this case user will see login dialog from browser instead of JBoss Enterprise Portal Platform login.jsp page. JAAS authentication will be performed with real credentials of user (ie. <emphasis>root</emphasis>/<emphasis>gtn</emphasis>). WCI ticket is not used with BASIC authentication. + </para> + </section> + + <section id="sect-Authentication_Authorization_Intro-ClusterLogin"> + <title>Cluster login</title> + + <para> + JBoss Enterprise Portal Platform supports automatic login propagation in cluster environment. Cluster login relies on HTTP session replication. It's useful for situations like this: + </para> + + <procedure> + <step> + <para> + You have Apache loadbalancer and two portal nodes <emphasis>node1</emphasis> and <emphasis>node2</emphasis> + </para> + </step> + + <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). + </para> + </step> + + <step> + <para> + User login on loadbalancer (which is redirected to node1) + </para> + </step> + + <step> + <para> + node1 is killed + </para> + </step> + + <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. + </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. + </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. + </para> + </note> + + <para> + There is also possibility for integration with JBoss clustered SSO valve (See <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve" />). + </para> + </section> + + <section id="sect-Authentication_Authorization_Intro-SSOLogin"> + <title>SSO login</title> + + <para> + JBoss Enterprise Portal Platform also supports integration with couple of well-known SSO frameworks (CAS, JOSSO, OpenSSO). When user wants login, he is not redirected to portal login form but to SSO server login form. After successful login with SSO server, he gains ticket represented by special cookie (name of cookie differs for each SSO server). Then user is redirected back to JBoss Enterprise Portal Platform, where we need to perform agent validation of SSO ticket against SSO server. We still need to create Identity object and bind it to IdentityRegistry (this is same as in default authentication), which is done thanks to Authenticator component. + </para> + + <para> + In other words, you need to ensure that users, which are logged successfuly through SSO, needs to be also in JBoss Enterprise Portal Platform identity database because SSO server is used only for authentication, but authorization is handled completely by JBoss Enterprise Portal Platform, which assumes that user exists in portal DB. If users are not in DB, Identity object won't be created and you will have 403 Forbidden errors even if you authenticate successfuly. For details about SSO integration, see <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On" />. + </para> + + <para> + Same applies for SPNEGO authentication (See <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"/>). In this case, you need to ensure that your Kerberos users are also created in JBoss Enterprise Portal Platform database. + </para> + </section> + </section> +<!-- Ending section different authentication workflows --> + <section id="sect-Authentication_Authorization_Intro-authorization"> + <title>Authorization overview</title> + + <para> + In previous section, we learned about JAAS authentication and about login modules. So we know that result of authentication are: + </para> + + <itemizedlist> + <listitem> + <para> + JAAS Subject with principals for username (UserPrincipal) and for JAAS roles (RolesPrincipal). + </para> + </listitem> + + <listitem> + <para> + Identity object, which encapsulates username, all memberships and all JAAS roles. This Identity object is bound to IdentityRegistry component. + </para> + </listitem> + </itemizedlist> + + <para> + Authorization in JBoss Enterprise Portal Platform actually happens on two levels: + </para> + + <section id="sect-Authentication_Authorization_Intro-servletContainerAuthorization"> + <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>: + </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. + </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. + </para> + </section> + + <section id="sect-Authentication_Authorization_Intro-gateInAuthorization"> + <title>Portal level authorization</title> + + <para> + Second round of authorization is based on component <emphasis role="bold">UserACL</emphasis> (See <xref linkend="chap-Reference_Guide-Portal_Default_Permission_Configuration" />). We can declare access and edit permissions for portals, pages and/or portlets. UserACL is then used to check if our user has particular permissions to access or edit specified resource. Important object with informations about roles of our user is mentioned <emphasis>Identity</emphasis> object created during JAAS authentication. + </para> + + <para> + Authorization on portal level looks like this: + </para> + + <itemizedlist> + <listitem> + <para> + user send HTTP request to some URL in portal + </para> + </listitem> + + <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>. + </para> + </listitem> + + <listitem> + <para> + SetCurrentIdentityFilter reads username of current user from <emphasis>HttpServletRequest.getRemoteUser()</emphasis>. Then it looks for Identity of this user in IdentityRegistry, where Identity has been saved during authentication. Found Identity is then encapsulated into <emphasis role="bold">ConversationState</emphasis> object and bound into ThreadLocal variable. + </para> + </listitem> + + <listitem> + <para> + UserACL is able to obtain Identity of current user from method <emphasis>UserACL.getIdentity()</emphasis>, which simply calls <emphasis>ConversationState.getCurrent().getIdentity()</emphasis> for find current Identity bound to ThreadLocal. Now UserACL has identity of user and so that it can performs any security checks. + </para> + </listitem> + </itemizedlist> + </section> + </section> +<!-- Ending section Authorization overview --> + </section> Added: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml 2012-01-08 23:45:52 UTC (rev 8279) @@ -0,0 +1,77 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Book_Name.ent"> +%BOOK_ENTITIES; +]> + + <section id="sect-Reference_Guide-Authentication_and_Identity-Password_Encryption"> + <title>Password Encryption</title> + <!-- The warning and first listitem below were relocated from sect-Reference_Guide-Authentication_Token_Configuration as security and plain-text password issues were being expanded on (from JBEPP-610) --> <warning> + <title>Username and passwords stored in clear text</title> + <para> + The <emphasis>Remember Me</emphasis> feature of JBoss Enterprise Portal Platform uses a token mechanism to be able to authenticate returning users without requiring an explicit login. However, to be able to authenticate these users, the token needs to store the username and password in clear text in the JCR. + </para> + + </warning> + <para> + Administrators have two options available to ameliorate this risk: + </para> + <orderedlist> + <listitem> + <para> + The <emphasis>Remember Me</emphasis> feature can be disabled by removing the corresponding checkbox in: <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/login/jsp/login.jsp</filename> and <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl</filename>. + </para> + + </listitem> + <listitem> + <para> + Passwords can be encoded prior to being saved to the JCR. This option requires administrators to provide a custom subclass of <parameter>org.exoplatform.web.security.security.AbstractCodec</parameter> and set up a codec implementation with <parameter>CookieTokenService</parameter>: + </para> + <procedure id="proc-Reference_Guide-Password_Encryption-Encrypt_Password_in_JCR"> + <title>Encrypt Password in JCR</title> + <step> + <para> + Create a javaclass similar to: + </para> + +<programlisting language="Java" role="Java"><xi:include href="../../extras/Authentication_Identity/ExampleCodec.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Compile the class and package it into a jar file. For this example we will call the jar file <filename>codec-example.jar</filename>. + </para> + + </step> + <step> + <para> + Create a <filename>conf/portal/configuration.xml</filename> file within the <filename>codec-example.jar</filename> similar to the example below. This allows the portal kernel to find and use the new codec implementation. + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity/configuration.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Deploy the <filename>codec-example.jar</filename> into your <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/lib/</filename> directory. + </para> + + </step> + <step> + <para> + Start (or restart) your JBoss Enterprise Portal Platform. + </para> + <para> + Any passwords written to the JCR will now be encoded and not plain text. + </para> + + </step> + + </procedure> + + + </listitem> + + </orderedlist> + +</section> \ No newline at end of file