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

Author: smumford Date: 2012-12-12 00:37:16 -0500 (Wed, 12 Dec 2012) New Revision: 8990 Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml Log: BZ856430: First edit of new JOSSO content from docs.jboss.org Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-12-12 04:43:37 UTC (rev 8989) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-12-12 05:37:16 UTC (rev 8990) @@ -646,7 +646,7 @@ Jasig CAS uses Apache Maven to build the <filename>cas.war</filename> file. Follow the instructions to produce this file, and deploy it to the Apache Tomcat server. </para> - <procedure> + <procedure id="sect-Deploying_CAS_on _Tomcat"> <title>Building CAS, and Deploying to Tomcat</title> <step> @@ -743,120 +743,113 @@ </note> </section> - <section id="sid-55477376_JOSSO-ObtainingJOSSO"> - <title>Obtaining JOSSO</title> + <section> + <title>JOSSO 1.8</title> - <para> - JOSSO can be downloaded from <ulink url="http://sourceforge.net/projects/josso/files/"/> . Use the package that embeds Apache Tomcat. - </para> + <section id="sid-55477376_JOSSO-ObtainingJOSSO"> + <title>Obtaining JOSSO</title> + + <para> + JOSSO can be downloaded from <ulink url="http://sourceforge.net/projects/josso/files/"/> . Use the package that embeds Apache Tomcat. + </para> + + <para> + Once downloaded, extract the package into what will be called <replaceable>JOSSO_HOME</replaceable> in this example. + </para> + </section> - <para> - Once downloaded, extract the package into what will be called <replaceable>JOSSO_HOME</replaceable> in this example. - </para> - </section> - - <section id="sid-55477376_JOSSO-JOSSOserver"> - <title>JOSSO server</title> - - <para> - This section describes how to set up the JOSSO server to authenticate against the JBoss Portal Platform using the REST authentication plugin. In this example, the JOSSO server will be installed on Tomcat. - </para> - - <procedure> - <step> - <para> - <emphasis role="bold">Optional:</emphasis> To use the SSO authentication plugin with JOSSO (not-mandatory but recommended. See <xref linkend="sect-CAS-Authentication_Process"/> for details): - </para> + <section id="sid-55477376_JOSSO-JOSSOserver"> + <title>JOSSO server</title> + + <para> + This section describes how to set up the JOSSO server to authenticate against the JBoss Portal Platform using the REST authentication plugin. In this example, the JOSSO server will be installed on Tomcat. + </para> + + <procedure> + <step> + <para> + <emphasis role="bold">Optional:</emphasis> To use the SSO authentication plugin with JOSSO (not-mandatory but recommended. See <xref linkend="sect-CAS-Authentication_Process"/> for details): + </para> + + <para> + Copy the files from <filename>SSO_HOME/josso/josso-<replaceable>&lt;version&gt;</replaceable>/plugin</filename> into the Tomcat directory (<replaceable>JOSSO_HOME</replaceable>). (<replaceable>SSO_HOME</replaceable> points to directory with JBoss Portal Platform as mentioned in <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On"/>) + </para> + + <para> + This action will replace some, and add other, JAR files to the <filename>JOSSO_HOME/webapps/josso/WEB-INF/lib</filename> directory. + </para> + + <itemizedlist> + <listitem> + <para> + <filename>JOSSO_HOME/lib/josso-gateway-config.xml</filename> + </para> + </listitem> + + <listitem> + <para> + <filename>JOSSO_HOME/lib/josso-gateway-gatein-stores.xml</filename> + </para> + </listitem> + + <listitem> + <para> + <filename>JOSSO_HOME/webapps/josso/WEB-INF/classes/gatein.properties</filename> + </para> + + <para> + This file may need to be reconfigured according to your JBoss Portal Platform environment (you need to use the host and port of your JBoss Portal Platform instance as this will be used by the Authentication plugin to send REST requests over HTTP). + </para> + </listitem> + </itemizedlist> + </step> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">JOSSO 1.8.1:</emphasis> Copy the files from <filename>SSO_HOME/josso/josso-181/plugin</filename> into the Tomcat directory (<replaceable>JOSSO_HOME</replaceable>). (<replaceable>SSO_HOME</replaceable> points to directory with JBoss Portal Platform as mentioned in <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On"/>) - </para> - </listitem> + <step> + <para> + Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and replace the <literal>8080</literal> port to <literal>8888</literal> to change the default Tomcat port and avoid a conflict with the default JBoss Portal Platform port (for testing purposes). + </para> - <listitem> - <para> - <emphasis role="bold">JOSSO 1.8.2:</emphasis> Copy the files from <filename>SSO_HOME/josso/josso-182/plugin</filename> into the Tomcat directory (<replaceable>JOSSO_HOME</replaceable>). - </para> + <note> + <title>Port Conflicts</title> <para> - This action will replace some, and add other, JAR files to the <filename>JOSSO_HOME/webapps/josso/WEB-INF/lib</filename> directory. + If JBoss Portal Platform is running on the same machine as Tomcat, other ports need to be changed in addition to <literal>8080</literal> to avoid port conflicts. They can be changed to any free port. For example, you can change the admin port from <literal>8005</literal> to <literal>8805</literal>, and AJP port from <literal>8009</literal> to <literal>8809</literal>. </para> + </note> + </step> + + <step> + <para> + Tomcat should now allow access to <uri>http://localhost:8888/josso/signon/login.do</uri>. However, if you are using SSO Authentication plugin, the login will not be available at this stage as your JBoss Portal Platform is not yet set up. + </para> + + <figure> + <title/> - <itemizedlist> - <listitem> - <para> - <filename>JOSSO_HOME/lib/josso-gateway-config.xml</filename> - </para> - </listitem> - - <listitem> - <para> - <filename>JOSSO_HOME/lib/josso-gateway-gatein-stores.xml</filename> - </para> - </listitem> - - <listitem> - <para> - <filename>JOSSO_HOME/webapps/josso/WEB-INF/classes/gatein.properties</filename> - </para> - - <para> - This file may need to be reconfigured according to your JBoss Portal Platform environment (you need to use the host and port of your JBoss Portal Platform instance as this will be used by the Authentication plugin to send REST requests over HTTP). - </para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </step> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/AuthenticationAndIdentity/SSO/josso.png" format="PNG"/> + </imageobject> + </mediaobject> + </figure> + </step> + </procedure> + </section> + + <section id="sid-55477376_JOSSO-SetuptheJOSSOclient"> + <title>JOSSO client</title> - <step> - <para> - Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and replace the <literal>8080</literal> port to <literal>8888</literal> to change the default Tomcat port and avoid a conflict with the default JBoss Portal Platform port (for testing purposes). - </para> - - <note> - <title>Port Conflicts</title> + <procedure> + <step> + <para> + Some of the configuration properties in <filename>JBOSS_HOME/standalone/configuration/gatein/configuration.properties</filename> need to be set on the client server. + </para> <para> - If JBoss Portal Platform is running on the same machine as Tomcat, other ports need to be changed in addition to <literal>8080</literal> to avoid port conflicts. They can be changed to any free port. For example, you can change the admin port from <literal>8005</literal> to <literal>8805</literal>, and AJP port from <literal>8009</literal> to <literal>8809</literal>. + Locate the <literal>#SSO</literal> section of the file and edit it to match the sample below: </para> - </note> - </step> - - <step> - <para> - Tomcat should now allow access to <uri>http://localhost:8888/josso/signon/login.do</uri>. However, if you are using SSO Authentication plugin, the login will not be available at this stage as your JBoss Portal Platform is not yet set up. - </para> - - <figure> - <title/> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/AuthenticationAndIdentity/SSO/josso.png" format="PNG"/> - </imageobject> - </mediaobject> - </figure> - </step> - </procedure> - </section> - - <section id="sid-55477376_JOSSO-SetuptheJOSSOclient"> - <title>JOSSO client</title> - - <procedure> - <step> - <para> - Some of the configuration properties in <filename>JBOSS_HOME/standalone/configuration/gatein/configuration.properties</filename> need to be set on the client server. - </para> - - <para> - Locate the <literal>#SSO</literal> section of the file and edit it to match the sample below: - </para> - - <informalexample> + <informalexample> <programlisting> #SSO gatein.sso.enabled=true @@ -873,71 +866,378 @@ gatein.sso.filter.logout.url=${gatein.sso.josso.base.url}/logout.do gatein.sso.filter.login.sso.url=${gatein.sso.server.url}?josso_back_to=${gatein.sso.portal.url}/@@portal.container.name@(a)/initiatessologin </programlisting> - </informalexample> + </informalexample> + + <para> + Most of the properties are described in <xref linkend="sect-CAS_Configuring_the_Platform"/>. + </para> + + <para> + Some of the properites differ for JOSSO: + </para> + + <itemizedlist> + <listitem> + <para> + The Logout filter is <code>org.gatein.sso.agent.filter.JOSSOLogoutFilter</code>. + </para> + </listitem> + + <listitem> + <para> + <code>gatein.sso.josso.host</code> points to the location of the JOSSO server. + </para> + </listitem> + + <listitem> + <para> + <code>gatein.sso.portal.url</code> must be changed if you intend to access JBoss Portal Platform on any URL other than <emphasis role="italics">localhost:8080</emphasis>. + </para> + </listitem> + + <listitem> + <para> + The <code>gatein.sso.josso.agent.config.file</code> property points to the location of the Agent configuration file, which is relative to classpath. Therefore the agent file location is actually located at <filename>JBOSS_HOME/gatein/gatein.ear/portal.war/WEB-INF/classes/sso/josso/1.8/josso-agent-config.xml</filename>. + </para> + + <para> + In the majority of cases, nothing in this file will need to be configured beyond the defaults. + </para> + </listitem> + </itemizedlist> + </step> - <para> - Most of the properties are described in <xref linkend="sect-CAS_Configuring_the_Platform"/>. - </para> + <step> + <para> + JOSSO has some specific dependencies, which differ between various versions. The original <code>org.gatein.sso</code> SSO module must be replaced with one appropriate for your version of JOSSO. The alternate modules are available in the JOSSO download. + </para> + + <substeps> + <step> + <para> + Delete the <filename>JBOSS_HOME/modules/org/gatein/sso</filename> directory. + </para> + </step> + + <step> + <para> + Copy the <filename>SSO_HOME/josso/gatein-josso-<replaceable>&lt;version&gt;</replaceable>/modules/org/gatein/sso</filename> directory into <filename>JBOSS_HOME/modules/org/gatein/</filename>. + </para> + </step> + </substeps> + </step> + </procedure> + + <para> + From now on, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form. If you set Authentication plugin for JOSSO, you can login with JBoss Portal Platform credentials (like john/gtn) on JOSSO side. + </para> + </section> + </section> + + <section> + <title>JOSSO 2.2</title> + + <para> + JOSSO 2.2 takes a different approach to SSO than JOSSO 1.8. It is designed to allow users to create their own SSO environment by modelling it in flash web application called <emphasis role="strong">atricore-console</emphasis>. + </para> + + <para> + Unfortunately this make it more difficult to use the SSO Authentication plugin as it's not easily possible to configure an existing JOSSO 2.2 environment via Spring XML files. Using the AuthenticationPlugin with JOSSO 2.2 is not supported. + </para> + + <section id="sid-55477376_JOSSO-JOSSO2.2serversetup"> + <title>JOSSO 2.2 server setup</title> + + <para> + You can downloaded JOSSO 2.2.0 from <ulink url="http://www.josso.org">JOSSO site</ulink> and follow the instructions from the JOSSO 2 quickstart in <ulink url="http://www.josso.org/confluence/display/JOSSO1/JOSSO2+Quick+sta... . + </para> + + <para> + After unzipping the download and running the JOSSO, you can access the <application>atricore</application> console at <uri>http://server.local.network:8081/atricore-console</uri> (<emphasis>server.local.network</emphasis> is the virtual host defined in <filename>/etc/hosts</filename>). + </para> + + <procedure> + <step> + <para> + Login to the portal as <literal>admin/admin</literal>. + </para> + </step> - <para> - Some of the properites differ for JOSSO: - </para> + <step> + <para> + Create a new empty <emphasis role="italics">Identity appliance</emphasis> with the following details: + </para> + + <itemizedlist> + <listitem> + <para> + Name: <emphasis role="italics">MYFIRSTIA</emphasis> + </para> + </listitem> + + <listitem> + <para> + Realm name: <emphasis role="italics">com.mycompany.myrealm</emphasis> + </para> + </listitem> + + <listitem> + <para> + Appliance location: <emphasis role="italics"> <uri>http://server.local.network:8081</uri> </emphasis> + </para> + </listitem> + </itemizedlist> + </step> - <itemizedlist> - <listitem> - <para> - The Logout filter is <code>org.gatein.sso.agent.filter.JOSSOLogoutFilter</code>. - </para> - </listitem> + <step> + <para> + Create a new Identity provider named <emphasis role="italics">AcmeIDP</emphasis> (use the default settings) + </para> - <listitem> + <figure> + <title>Identity Provider configuration</title> + + <mediaobject> + <imageobject> + <imagedata fileref="author/download/attachments/55477376/josso22-acmeidp.png"/> + </imageobject> + </mediaobject> + </figure> + </step> + + <step> + <para> + Create an Identity vault <emphasis role="italics">IDPUsers</emphasis> and connect it with <emphasis role="italics">AcmeIDP</emphasis> via <emphasis role="italics">Identity lookup</emphasis> connection. + </para> + </step> + + <step> + <para> + Create a Service provider called <emphasis role="italics">SP1</emphasis> but let the hosts to be on <emphasis role="italics">server.local.network:8081</emphasis>. + </para> + + <figure> + <title>Service Provider configuration</title> + + <mediaobject> + <imageobject> + <imagedata fileref="author/download/attachments/55477376/josso22-sp1.png"/> + </imageobject> + </mediaobject> + </figure> + </step> + + <step> + <para> + Create an Identity vault <emphasis role="italics">SP1Users</emphasis> and wire it with SP1 via <emphasis role="italics">Identity lookup</emphasis> connection. + </para> + </step> + + <step> + <para> + Create empty temporary directory <filename>/tmp/tomcat7</filename> and then in the <application>atricore</application> console create new Execution environment of type <emphasis role="italics">Tomcat</emphasis> with the following parameters: + </para> + + <itemizedlist> + <listitem> + <para> + Name: <emphasis role="italics">SP1EE</emphasis> + </para> + </listitem> + + <listitem> + <para> + Version: <emphasis role="italics">7.0.x</emphasis> + </para> + </listitem> + + <listitem> + <para> + Target host: <emphasis role="italics">Local</emphasis> + </para> + </listitem> + + <listitem> + <para> + Install home: <emphasis role="italics">/tmp/tomcat7</emphasis> (Directory <code>/tmp/tomcat7</code> must exists, but it could be empty directory without any tomcat presented as we do not overwrite existing setup or install demo apps). + </para> + </listitem> + </itemizedlist> + + <figure> + <title>SP Execution Environment configuration</title> + + <mediaobject> + <imageobject> + <imagedata fileref="author/download/attachments/55477376/josso22-sp1ee.png"/> + </imageobject> + </mediaobject> + </figure> + </step> + + <step> + <para> + Wire <emphasis role="italics">SP1</emphasis> and <emphasis role="italics">SP1EE</emphasis> via an <emphasis role="italics">Activation</emphasis> connection. + </para> + + <para> + <remark>Docs note: I don't even know what this sentence is trying to say.</remark> Left default values of parameters instead of parameter <emphasis role="italics">Partner application location</emphasis> needs to be configured to <ulink url="http://localhost:8080/portal"/> + </para> + </step> + + <step> + <para> + Wire <emphasis role="italics">SP1</emphasis> and <emphasis role="italics">AcmeIDP</emphasis> via <emphasis role="italics">Federated connection</emphasis>. + </para> + </step> + + <step> + <para> + Click <guilabel>Save</guilabel> and save this model. + </para> + + <figure> + <title>Overview with SP connection details</title> + + <mediaobject> + <imageobject> + <imagedata fileref="author/download/attachments/55477376/josso22-connection.png"/> + </imageobject> + </mediaobject> + </figure> + </step> + + <step> + <para> + Go to the <emphasis role="italics">Identity appliance lifecycle management</emphasis> tab and go through lifecycle of Identity appliance (<menuchoice><guimenuitem>Saved</guimenuitem><guimenuitem>Staged</guimenuitem><guimenuitem>Deployed</guimenuitem><guimenuitem>Started</guimenuitem></menuchoice>) as suggested in the quickstart. + </para> + </step> + + <step> + <para> + Go to the <emphasis role="italics">Account &amp; Entitlement management</emphasis> tab and create users. Users must be created this way because REST callbacks to the Portal are not supported in this release. + </para> + + <para> + This example will create the following user/password accounts: <literal>john</literal>/<literal>password</literal>, <literal>root</literal>/<literal>password</literal> and <literal>demo</literal>/<literal>password</literal>. + </para> + </step> + </procedure> + </section> + + <section id="sid-55477376_JOSSO-JOSSOclientsetup"> + <title>JOSSO client setup</title> + + <para> + This section assumes that all relevant configurations were made as described in <xref linkend="sid-55477376_JOSSO-JOSSO2.2serversetup"/>. + </para> + + <procedure> + <step> + <para> + Assuming again that you have JBoss Portal Platform running on JBoss Enterprise Platform 6, you need to change some of the properties in the SSO sections of <filename>JBOSS_HOME/standalone/configuration/gatein/configuration.properties</filename> to match those below: + </para> + + <informalexample> +<programlisting> +# SSO +gatein.sso.enabled=true +gatein.sso.callback.enabled=${gatein.sso.enabled} +gatein.sso.login.module.enabled=${gatein.sso.enabled} +gatein.sso.login.module.class=org.gatein.sso.agent.login.SSOLoginModule +gatein.sso.filter.initiatelogin.enabled=false +gatein.sso.filter.initiatelogin.josso2.enabled=true +gatein.sso.josso.agent.config.file=sso/josso/2.2/josso-agent-config.xml +gatein.sso.josso.properties.file=file:${jboss.home.dir}/standalone/configuration/gatein/configuration.properties +gatein.sso.portal.url=http://localhost:8080 +gatein.sso.filter.logout.class=org.gatein.sso.agent.filter.JOSSOLogoutFilter +gatein.sso.filter.logout.url= +gatein.sso.josso.host=server.local.network:8081 +gatein.sso.server.url=http://${gatein.sso.josso.host} +gatein.sso.josso.identityApplianceId=MYFIRSTIA +gatein.sso.josso.partnerAppId=SP1 +gatein.sso.josso.partnerAppPoint=SP1EE +gatein.sso.filter.login.sso.url=${gatein.sso.server.url}/IDBUS/${gatein.sso.josso.identityApplianceId}/${gatein.sso.josso.partnerAppPoint}/JOSSO/SSO/REDIR?josso_back_to=${gatein.sso.portal.url}/@@portal.container.name@(a)/josso_security_check&amp;amp;josso_partnerapp_id=${gatein.sso.josso.partnerAppId} +</programlisting> + </informalexample> + + <para> + Note that <code>gatein.sso.filter.logout.url</code> is empty now as the logout URL will be obtained from JOSSO agent configuration in file <filename>JBOSS_HOME/gatein/gatein.ear/portal.war/WEB-INF/classes/sso/josso/2.2/josso-agent-config.xml</filename>. + </para> + </step> + + <step> + <para> + Update Sthe SO module in EAP 6 : + </para> + + <substeps> + <step> + <para> + Delete the <filename>JBOSS_HOME/modules/org/gatein/sso</filename> directory. + </para> + </step> + + <step> + <para> + Copy the <filename>GATEIN_SSO_HOME/josso/gatein-josso-182/modules/org/gatein/sso into JBOSS_HOME/modules/org/gatein/</filename> directory. + </para> + </step> + </substeps> + </step> + + <substeps> + <step> <para> - <code>gatein.sso.josso.host</code> points to the location of the JOSSO server. + Start the Portal. </para> - </listitem> - - <listitem> + <para> - <code>gatein.sso.portal.url</code> must be changed if you intend to access JBoss Portal Platform on any URL other than <emphasis role="italics">localhost:8080</emphasis>. + Access <uri>http://localhost:8080/portal</uri> and click <emphasis role="italics">Sign in</emphasis>. </para> - </listitem> - - <listitem> + <para> - The <code>gatein.sso.josso.agent.config.file</code> property points to the location of the Agent configuration file, which is relative to classpath. Therefore the agent file location is actually located at <filename>JBOSS_HOME/gatein/gatein.ear/portal.war/WEB-INF/classes/sso/josso/1.8/josso-agent-config.xml</filename>. + You will be redirected to JOSSO, but you will need to login with the username/password account created via the JOSSO console (for example <literal>john</literal>/<literal>password</literal>) as REST callbacks are not supported. </para> <para> - In the majority of cases, nothing in this file will need to be configured beyond the defaults. + After a successful login to JOSSO, you will be redirected to the Portal as <literal>john</literal>. </para> - </listitem> - </itemizedlist> - </step> + </step> + </substeps> + </procedure> + </section> + </section> + + <section> + <title>Setup with portal on Tomcat</title> + + <para> + If you have JBoss Portal Platform on Tomcat 7 and you want to configure it for SSO against JOSSO you must complete the following additional steps: + </para> + + <procedure> + <title></title> <step> <para> - JOSSO has some specific dependencies, which differ between various versions. The original <code>org.gatein.sso</code> SSO module must be replaced with one appropriate for your version of JOSSO. The alternate modules are available in the JOSSO download. + Add <code>ServletAccessValve</code> into <filename>server.xml</filename> (as was done to set up CAS single sign-on). </para> - <substeps> - <step> - <para> - Delete the <filename>JBOSS_HOME/modules/org/gatein/sso</filename> directory. - </para> - </step> - - <step> - <para> - Copy the <filename>SSO_HOME/josso/gatein-josso-<replaceable>&lt;version&gt;</replaceable>/modules/org/gatein/sso</filename> directory into <filename>JBOSS_HOME/modules/org/gatein/</filename>. - </para> - </step> - </substeps> + <para> + Refer to <xref linkend="sect-Deploying_CAS_on _Tomcat"/> for more details. + </para> </step> + + <step> + <para> + Copy the JAR files for the appropriate JOSSO version from <filename>GATEIN_SSO_HOME/josso/gatein-josso-<replaceable>&lt;version&gt;</replaceable>/modules/org/gatein/sso/main into JBOSS_HOME/lib/</filename>. + </para> + <para> + Use <replaceable>gatein-josso-181</replaceable> if you are on JOSSO 1.8.1 or older or <replaceable>gatein-josso-182</replaceable> if you are on JOSSO 1.8.2 or newer or on JOSSO 2.2. + </para> + </step> </procedure> - - <para> - From now on, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form. If you set Authentication plugin for JOSSO, you can login with JBoss Portal Platform credentials (like john/gtn) on JOSSO side. - </para> </section> <!-- Old JOSSO content replaced by action prompted by BZ#856430