Author: rdickens Date: 2013-01-10 20:32:39 -0500 (Thu, 10 Jan 2013) New Revision: 9043 Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml Log: Updated content to Confluence wiki version 14 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-01-11 01:32:21 UTC (rev 9042) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2013-01-11 01:32:39 UTC (rev 9043) @@ -5,6 +5,11 @@ ]> <chapter id="sect-Reference_Guide-Authentication_Authorization_Intro"> <title>Authentication and Authorization intro</title> + <remark> + ======================================================= + NOTE: Content updated to wiki version 4 (11 Jan 2013) + =======================================================</remark> + <section id="sect-Reference_Guide-Authentication_Authorization_Intro-Authentication"> <title>Authentication Overview</title> <para> @@ -25,54 +30,62 @@ </para> </listitem> <listitem> + <remark>FIXME: Correct the following link</remark> <para> - SSO server integration (CAS, JOSSO, OpenSSO). Refer to <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On"/> for more information. + SSO server integration (CAS, JOSSO, OpenSSO). Refer to ** xref linkend="sect-Reference_Guide-SSO_Single_Sign_On"/ for more information. </para> </listitem> <listitem> + <remark>FIXME: Correct the following link</remark> <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. + 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> + <remark>FIXME: Fix the following link</remark> + SAML2 based authentication. Refer to ** xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-SAML2"/ for more information. + </para> + </listitem> + <listitem> <para> Cluster authentication with load balancer or with JBoss SSO valve. Refer to <xref linkend="sect-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 url="http://www.jcp.org/en/jsr/detail?id=154" type="http">Servlet 2.5</ulink> containers and <ulink url="http://www.jcp.org/en/jsr/detail?id=315" type="http">Servlet 3.0</ulink> containers. + 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> - First you can see in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> that authentication is triggered by accessing a secured URL: + First you can see in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/portal.war/WEB-INF/web.xml</filename> that authentication is triggered by accessing a secured URL <systemitem>_/dologin_</systemitem>: </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> + <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> + </web-resource-collection> + </security-constraint> ]]> </programlisting> <para> - This means that access to some 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. + 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> <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 receive an HTTP error; <emphasis>403 Forbidden</emphasis>, for example. + 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 receive 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>. + In the next part of the file we can see that authentication is FORM based and it starts by redirection to <emphasis>/login</emphasis> URL, which is mapped to <literal>LoginServlet</literal>. </para> <programlisting language="XML" role="XML"> <![CDATA[ @@ -80,14 +93,14 @@ <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-page>/login</form-login-page> + <form-error-page>/login</form-error-page> </form-login-config> </login-config> ]]> </programlisting> <para> - <literal>InitiateLoginServlet</literal> simply redirects user to login page placed in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/login/jsp/login.jsp</filename>. + <literal>LoginServlet</literal> redirects the user to the login page placed in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/portal.war/login/jsp/login.jsp</filename>. <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/AuthenticationAndIdentity/Overview/loginScreen.png" format="PNG"/> @@ -98,96 +111,50 @@ </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>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/login/skin</filename> . + Changes to the appearance of this login page can be made in this JSP file. Alternatively you can create an extension and override this page via extension if you don't want to edit it directly. You can also change images or CSS placed in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/login/skin</filename> . </para> <para> - After a user submits the login form, they are redirected to the login URL; <ulink url="http://localhost:8080/portal/login?username=root&amp;password=gtn&amp;initialURI=/portal/classic" type="http">http://localhost:8080/portal/login?username=root&amp;password=gtn&amp;initialURI=/portal/private/classic</ulink>. + After a user submits the login form, they are redirected to the login URL: <ulink url="http://localhost:8080/portal/login?username=root&amp;password=gtn&amp;initialURI=/portal/classic" type="http">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. + 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> - <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 url="http://localhost:8080/portal/j_security_check?j_username=root&amp;j_password=wci-ticket-1385113882&amp;initialURI=/portal/private/classic/" type="http"/>) 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-Authentication_Authorization_Intro-Login_Modules"> <title>Login modules</title> <para> -JBoss Portal Platform uses its own security domain (<emphasis role="bold">gatein-domain</emphasis>) with a set of predefined login modules. Login module configuration for <emphasis>gatein-domain</emphasis> is contained in the <filename>deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> file. +From the WCI servlet API login, the user is redirected to JAAS authentication. JBoss Portal Platform uses its own security domain (<emphasis role="bold">gatein-domain</emphasis>) with a set of predefined login modules. Login module configuration for <emphasis>gatein-domain</emphasis> is contained in the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> file. </para> <para> Below is the default login modules stack: </para> + <remark> + QUESTION: Does the reference below "JBossAS7LoginModule" need to be changed? + </remark> <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> +<security-domain name="gatein-domain" cache-type="default"> + <authentication> + <login-module code="org.gatein.sso.integration.SSODelegateLoginModule" flag="required"> + <module-option name="enabled" value="${gatein.sso.login.module.enabled}" /> + <module-option name="delegateClassName" value="${gatein.sso.login.module.class}" /> + <module-option name="portalContainerName" value="portal" /> + <module-option name="realmName" value="gatein-domain" /> + <module-option name="password-stacking" value="useFirstPass" /> + </login-module> + <login-module code="org.exoplatform.services.security.j2ee.JBossAS7LoginModule" flag="required"> + <module-option name="portalContainerName" value="portal"/> + <module-option name="realmName" value="gatein-domain"/> + </login-module> + </authentication> +</security-domain>]]> + </programlisting> <para> - New login modules can be added or the stack completely replaced with custom modules. - </para> + New login modules can be added or the stack completely replaced with custom modules. + </para> + <remark>QUESTION: Should the following reference be to official Red Hat documentation instead of Oracle's?</remark> <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: <literal>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 url="http://code.google.com/p/crsh/" type="http">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 &quot;false&quot; from the login method ensures that login module is ignored. This is not specific to JBoss Portal Platform but generic to JAAS. More info about login modules in general can be found at <ulink url="http://docs.oracle.com/javase/6/docs/technotes/guides/security/... type="http"/>. - </para> - </listitem> - </itemizedlist> + Authentication starts with the login method of each login module being invoked. After all login methods are invoked, the authentication is continued by invoking the commit method on each login module. Both login and commit methods can throw LoginException. If it happens, then the whole authentication ends unsuccessfully, which in turn invokes the abort method on each login module. By returning "false" from the login method, you can ensure that the login module is ignored. This is not specific to JBoss Portal Platform but it is generic to JAAS. Refer to <ulink type="http" url="http://docs.oracle.com/javase/6/docs/technotes/guides/security/... here for more information about login modules in general. + </para> <section id="sect-Authentication_Authorization_Intro-existingLM"> <title>Existing login modules</title> <para> @@ -196,98 +163,116 @@ <variablelist> <title>Modules</title> <varlistentry> - <term>WCILoginModule</term> + <term>SSODelegateLoginModule</term> <listitem> + <remark>FIXME: Fix the link to the relevant CAS section</remark> <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 &quot;<emphasis>optional</emphasis>&quot;, meaning that a login failure in <literal>WCILoginModule</literal> is not a critical error to the full login process. - </para> - </note> + It's useful only if SSO authentication is enabled (disabled by default. It can be enabled through properties in configuration.properties file and in this case it delegates the work to another real login module for SSO integration. If SSO is disabled, SSODelegateLoginModule is simply ignored. See ** xref linkend="Central Authentication Service (CAS)#Configuration"/ properties details for more details. If SSO is used and SSO authentication succeed, the special Identity object will be created and saved into shared state map (Map, which is shared between all login modules), so that this Identity object can be used by JBossAS7LoginModule or other login modules in the JAAS chain. + </para> </listitem> </varlistentry> <varlistentry> - <term>PortalLoginModule</term> + <term>JBossAS7LoginModule</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 re-authenticate on <emphasis>node2</emphasis> when it executes method <emphasis>login</emphasis>. Refer to <xref linkend="sect-Authentication_Authorization_Intro-ClusterLogin"/> for more information. - </para> + Most important login module, which is normally used to perform 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 Authentication.validateUser(Credential[] credentials) 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. In the JbossAS7LoginModule.commit method, the Identity object is registered to IdentityRegistry, which will be used later for authorization. Also some JAAS principals (UserPrincipal and RolesPrincipal) and assigned to our authenticated Subject. Thi! s is needed for JBoss AS server, so that it can properly recognize the name of the logged user and its roles on an JBoss AS level. + </para> </listitem> </varlistentry> + </variablelist> + + <para> + Some other login modules are not active by default, but can be added them if you find them useful. + </para> + + <variablelist> <varlistentry> - <term>SharedStateLoginModule</term> + <term>CustomMembershipLoginModule</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> + 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> - 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 &quot;login&quot; returns false). - </para> + Note that the CustomMembershipLoginModule can'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 an non-SSO case, you may need to chain this LM with other login modules, which can be used to establish Identity and add it into shared state. Those LM can be InitSharedStateLoginModule and SharedStateLoginModule. For an SSO case, you can add CustomMembershipLoginModule between SSODelegateLoginModule and JBossAS7LoginModule. + </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> + <term>InitSharedStateLoginModule</term> + <listitem> + <para> + It can read credentials from JAAS callback and add them into shared state. It's intended to be used in JAAS chain before SharedStateLoginModule + </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, by default it is <emphasis>/platform/users</emphasis> group. - </para> - <para> - This login module is commented because in normal environment, users are already in <emphasis>/platform/users</emphasis> group. It is useful only for some special setups like read-only LDAP, where groups of ldap user are taken from ldap tree and so that users may not be in <emphasis>/platform/users</emphasis> group, which is needed for successful authorization. - </para> - </listitem> + <term>SharedStateLoginModule</term> + <listitem> + <para> + It reads username and password from sharedState map from attributes javax.security.auth.login.name and javax.security.auth.login.password. 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 object Identity, which is saved to sharedState map. + </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 Portal Platform sources in <ulink url="http://anonsvn.jboss.org/repos/gatein/portal/trunk/component/we... type="http">http://anonsvn.jboss.org/repos/gatein/portal/tru... - </para> - </listitem> - <listitem> - <para> - <emphasis>SharedStateLoginModule, JbossLoginModule</emphasis> - these are located in eXo core sources in <ulink url="http://anonsvn.jboss.org/repos/exo-jcr/core/trunk/exo.core.comp... type="http">http://anonsvn.jboss.org/repos/exo-jcr/core/trun... - </para> - </listitem> - <listitem> - <para> - <emphasis>CustomMembershipLoginModule</emphasis> - located in JBoss Portal Platform sources in module for identity integration - <ulink url="http://anonsvn.jboss.org/repos/gatein/portal/trunk/component/id... type="http">http://anonsvn.jboss.org/repos/gatein/portal/tru... - </para> - </listitem> - </itemizedlist> - </section> + + <para> + Configuration example with CustomMembershipLoginModule and disabled SSO: + </para> + <programlisting language="XML" role="XML"><![CDATA[ + <login-module code="org.exoplatform.web.security.InitSharedStateLoginModule" flag="required"> + <module-option name="portalContainerName" value="portal"/> + <module-option name="realmName" value="gatein-domain"/> + </login-module> + <login-module code="org.exoplatform.services.security.jaas.SharedStateLoginModule" flag="required"> + <module-option name="portalContainerName" value="portal"/> + <module-option name="realmName" value="gatein-domain"/> + </login-module> + <login-module code="org.exoplatform.services.organization.idm.CustomMembershipLoginModule" flag="required"> + <module-option name="portalContainerName" value="portal"/> + <module-option name="realmName" value="gatein-domain"/> + <module-option name="membershipType" value="member" /> + <module-option name="groupId" value="/platform/users" /> + </login-module> + <login-module code="org.exoplatform.services.security.j2ee.JBossAS7LoginModule" flag="required"> + <module-option name="portalContainerName" value="portal"/> + <module-option name="realmName" value="gatein-domain"/> + </login-module>]]> + </programlisting> + + <para> + And a configuration example with enabled SSO: + </para> + + <programlisting language="XML" role="XML"><![CDATA[ + <login-module code="org.gatein.sso.integration.SSODelegateLoginModule" flag="required"> + <module-option name="enabled" value="${gatein.sso.login.module.enabled}" /> + <module-option name="delegateClassName" value="${gatein.sso.login.module.class}" /> + <module-option name="portalContainerName" value="portal" /> + <module-option name="realmName" value="gatein-domain" /> + <module-option name="password-stacking" value="useFirstPass" /> + </login-module> + <login-module code="org.exoplatform.services.organization.idm.CustomMembershipLoginModule" flag="required"> + <module-option name="portalContainerName" value="portal"/> + <module-option name="realmName" value="gatein-domain"/> + <module-option name="membershipType" value="member" /> + <module-option name="groupId" value="/platform/users" /> + </login-module> + <login-module code="org.exoplatform.services.security.j2ee.JBossAS7LoginModule" flag="required"> + <module-option name="portalContainerName" value="portal"/> + <module-option name="realmName" value="gatein-domain"/> + </login-module>]]> + </programlisting> + + </section> -<!-- Ending section with existing login modules --> <section id="sect-Authentication_Authorization_Intro-createNewLM"> +<!-- 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. + 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 the existing chain. </para> <para> - We have actually two levels of authentication and overall result of JAAS authentication should properly handle both these cases: + There are two levels of authentication and the overall result of JAAS authentication should properly handle both these cases: </para> <itemizedlist> <listitem> @@ -304,27 +289,26 @@ <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 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 &quot;Roles&quot; and it contains list of JAAS roles. This part is actually done in <code>JbossLoginModule.commit()</code>. In Tomcat, this flow is little different, which means Tomcat has it is own <literal>TomcatLoginModule</literal>. - </para> + <remark>QUESTION: Should the following reference to Tomcat be removed?</remark> + Application server needs to properly recognize that user is successfully 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 &quot;Roles&quot; and it contains list of JAAS roles. This part is actually done in <code>JbossLoginModule.commit()</code>. In Tomcat, this flow is little different, which means Tomcat has it is own <literal>TomcatLoginModule</literal>. + </para> </formalpara> <para> - After successful authentication, user needs to be at least in JAAS role &quot;users&quot; because this role is declared in web.xml as you saw above. JAAS roles are extracted by special algorithm from JBoss Portal Platform memberships. See below in section with RolesExtractor. - </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. + </para> <formalpara id="form-Authentication_Authorization_Intro-authenticationGateInServerLevel"> <title>Authentication on JBoss Portal Platform level</title> <para> - Login process needs to create special object <literal>org.exoplatform.services.security.Identity</literal> and register this object into JBoss Portal Platform component <literal>IdentityRegistry</literal>. This Identity object should encapsulate username of authenticated user, Memberships of this user and also JAAS roles. Identity object can be easily created with interface <literal>Authenticator</literal> as can be seen below. - </para> + The login process needs to create a special object <literal>org.exoplatform.services.security.Identity</literal> and register this object into JBoss Portal Platform component <literal>IdentityRegistry</literal>. The Identity object should encapsulate the username of the authenticated user, memberships of this user and JAAS roles. The Identity object can be easily created with interface <literal>Authenticator</literal> as shown 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"> +<!-- 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> + Authenticator is an important component in the authentication process. The interface <emphasis>org.exoplatform.services.security.Authenticator</emphasis> looks like this: + </para> <programlisting language="Java" role="Java"> <![CDATA[ public interface Authenticator @@ -352,7 +336,7 @@ 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 information about single user like: + 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: </para> <itemizedlist> <listitem> @@ -367,10 +351,13 @@ </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: + 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. </para> </listitem> </itemizedlist> + <para> + RolesExtractor interface looks like this: + </para> <programlisting language="Java" role="Java"> <![CDATA[ public interface RolesExtractor @@ -388,7 +375,7 @@ ]]> </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 &quot;/organization/management/something&quot; we have JAAS role &quot;organization&quot;). Only exception is group &quot;platform&quot; where we use second level as name of group. For example from group &quot;/platform/users&quot; we have JAAS role &quot;users&quot;. + Default implementation <emphasis>DefaultRolesExtractorImpl</emphasis> is based on a special algorithm, which uses the name of the role from the root of the group (for example for role &quot;/organization/management/something&quot; we have JAAS role &quot;organization&quot;). The only exception is the &quot;platform&quot; group where we use second level as the name of the group. For example from group &quot;/platform/users&quot; we have JAAS role &quot;users&quot;. </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>. @@ -396,6 +383,7 @@ <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> + <remark>FIXME: Change the following reference to eXo kernel</remark> <para> You can override default implementation of mentioned interfaces Authenticator and RolesExtractor if default behavior is not suitable for your needs. Consult documentation of <emphasis>eXo kernel</emphasis> for more info. </para> @@ -433,17 +421,17 @@ <itemizedlist> <listitem> <para> - After some time, user wants to re-authenticate. Let&apos;s assume that his HTTP Session is already expired but his RememberMe cookie is still active. + After some time, the user wants to re-authenticate. It is assumed 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 (<ulink url="http://localhost:8080/portal/classic"/>). + The user sends the HTTP request to some portal pages (for example, <ulink url="http://localhost:8080/portal/classic"/>). </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. + There is a special HTTP Filter <emphasis role="bold">RememberMeFilter</emphasis> configured in web.xml, which checks the 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> @@ -451,101 +439,17 @@ <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication-RemindPasswordTokenService"> <title>RemindPasswordTokenService</title> <para> - This is special service used during RememberMe authentication workflow. It is configurable in file <filename>deploy/gatein.ear/02portal.war/WEB-INF/conf/common/remindpwd-configuration.xml</filename> . For more info, look at section <xref linkend="sect-Reference_Guide-Authentication_Token_Configuration"/> + This is a special service used during the RememberMe authentication workflow. It is configurable in the file <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/common/remindpwd-configuration.xml</filename> . For more info, look at section <xref linkend="sect-Reference_Guide-Authentication_Token_Configuration"/> </para> <para> - 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"/>. + You can encrypt passwords before storing them in 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 Portal Platform is using FORM based authentication by default but it is not a problem with switch to different authentication type like BASIC. Only needed thing is to configure it properly in <filename>deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> like this: - </para> - <programlisting language="XML" role="XML"> - <![CDATA[ -<!-- - <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 Portal Platform login.jsp page. JAAS authentication will be performed with real credentials of user (<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 Portal Platform supports automatic login propagation in cluster environment. Cluster login relies on HTTP session replication. It&apos;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 <emphasis>node1</emphasis>. All his requests will be then processed on <emphasis>node1</emphasis> (sticky session). - </para> - </step> - <step> - <para> - User login on loadbalancer (which is redirected to <emphasis>node1</emphasis>) - </para> - </step> - <step> - <para> - node1 is killed - </para> - </step> - <step> - <para> - User will send another HTTP request. He will now be redirected to <emphasis>node2</emphasis> because <emphasis>node1</emphasis> is killed. Now user will be automatically logged on <emphasis>node2</emphasis> as well thanks to session replication, because he still has same HTTP session, which was replicated from <emphasis>node1</emphasis> to <emphasis>node2</emphasis>. So end user shouldn&apos;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 <emphasis>node2</emphasis> is working thanks to servlet filter <emphasis>ClusteredSSOFilter</emphasis>, which is able to automatically trigger programmatic authentication. - </para> - <note> - <title>Note</title> - <para> - <literal>ClusteredSSOFilter</literal> is using proprietary JBossWeb API for trigger programmatic authentication and so it is working only on JBoss AS. It is not working on other servers like Tomcat or Jetty. - </para> - </note> - <para> - There is also possibility for integration with JBoss clustered SSO valve (See <xref linkend="sect-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 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 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 successfully through SSO, needs to be also in JBoss Portal Platform identity database because SSO server is used only for authentication, but authorization is handled completely by JBoss Portal Platform, which assumes that user exists in portal DB. If users are not in DB, Identity object won&apos;t be created and you will have 403 Forbidden errors even if you authenticate successfully. 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 Portal Platform </para> - </section> - </section> -<!-- Ending section different authentication workflows --> <section id="sect-Authentication_Authorization_Intro-authorization"> + <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: + In the previous section, you learned about JAAS authentication and about login modules. So you know the result of authentication, including: </para> <itemizedlist> <listitem> @@ -571,17 +475,18 @@ <auth-constraint> <role-name>users</role-name> </auth-constraint>]]></programlisting> + <remark>FIXME: correct the link to 'Login modules'</remark> <para> - This actually means that our user needs to be in JBoss Portal Platform role <emphasis>/platform/users</emphasis> (For details see <xref linkend="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor"/>). In other words, if we successfully authenticate but our user is not in group <emphasis>/platform/users</emphasis>, then it means that he is not in JAAS role <emphasis>users</emphasis>, which in next turn means that he will have authorization error <emphasis role="bold">403 Forbidden</emphasis> thrown by servlet container. + This actually means that our user needs to be in JBoss Portal Platform role <emphasis>/platform/users</emphasis> (For details see <xref linkend="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor"/>). In other words, if we successfully authenticate but our user is not in group <emphasis>/platform/users</emphasis>, then it means that he is not in JAAS role <emphasis>users</emphasis>, which in turn means that they will have authorization error <emphasis role="bold">403 Forbidden</emphasis> thrown by servlet container. For example in LDAP setup, your users may not be in /platform/users by default, but you can use CustomMembershipLoginModule to fix this problem. For details see ** Login modules**. </para> <para> - You can change the behavior and possibly add some more <emphasis>auth-constraint</emphasis> elements into <filename>web.xml</filename>. However this protection of resources based on web.xml is not standard JBoss Portal Platform way and it is mentioned here mainly for illustration purposes. + You can change the behavior and possibly add some more <emphasis>auth-constraint</emphasis> elements into <filename>web.xml</filename>. However this protection of resources based on web.xml is not standard JBoss Portal Platform method and is 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 information about roles of our user is mentioned <emphasis>Identity</emphasis> object created during JAAS authentication. + The second round of authorization is based on the component <emphasis role="bold">UserACL</emphasis> (See <xref linkend="chap-Reference_Guide-Portal_Default_Permission_Configuration"/>). You 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 resources. An important object containing information about the roles of our user is the <emphasis>Identity</emphasis> object created during JAAS authentication. </para> <para> Authorization on portal level looks like this: @@ -589,25 +494,26 @@ <itemizedlist> <listitem> <para> - user send HTTP request to some URL in portal + The user sends a HTTP request to some URLs in portal; </para> </listitem> <listitem> <para> - HTTP request is processed through <literal>SetCurrentIdentityFilter</literal>, which is declared in <filename>deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename>. + The HTTP request is processed through <literal>SetCurrentIdentityFilter</literal>, which is declared in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename>. </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. + 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. The Identity found is then encapsulated into a <emphasis role="bold">ConversationState</emphasis> object and bound into the 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. + UserACL is able to obtain Identity of current user from method <emphasis>UserACL.getIdentity()</emphasis>, which simply calls <emphasis>ConversationState.getCurrent().getIdentity()</emphasis> to find the current Identity bound to ThreadLocal. Now the UserACL has the identity of the user and can perform any security checks. </para> </listitem> </itemizedlist> </section> </section> + </section> <!-- Ending section Authorization overview --></chapter>