10:43 p.m.
Author: smumford
Date: 2012-12-11 23:43:37 -0500 (Tue, 11 Dec 2012)
New Revision: 8989
Added:
epp/docs/branches/6.0/Reference_Guide/en-US/images/AuthenticationAndIdentity/SSO/josso.png
Modified:
epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml
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/Revision_History.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2012-12-12 04:09:24
UTC (rev 8988)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2012-12-12 04:43:37
UTC (rev 8989)
@@ -312,7 +312,7 @@
</author>
<revdescription>
<simplelist>
- <member>BZ#865640 - Amended the JOSSO wording in <xref
linkend="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-JOSSO_server"/>
to clarify that Red Hat does not support JOSSO server, but offers integration with the
server. </member>
+ <member>BZ#865640 - Amended the JOSSO wording to clarify that Red Hat
does not support JOSSO server, but offers integration with the server. </member>
</simplelist>
</revdescription>
</revision>
Added:
epp/docs/branches/6.0/Reference_Guide/en-US/images/AuthenticationAndIdentity/SSO/josso.png
===================================================================
(Binary files differ)
Property changes on:
epp/docs/branches/6.0/Reference_Guide/en-US/images/AuthenticationAndIdentity/SSO/josso.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
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:09:24 UTC (rev 8988)
+++
epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-12-12
04:43:37 UTC (rev 8989)
@@ -1,4 +1,5 @@
<?xml version='1.0' encoding='UTF-8'?>
+<!-- This document was created with Syntext Serna Free. -->
<!DOCTYPE chapter 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;
@@ -686,7 +687,7 @@
</section>
<section
id="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project">
- <title>Java Open Single Sign-On Project</title>
+ <title><remark>BZ#856430</remark>Java Open Single Sign-On
Project</title>
<para>
Configuring JOSSO for JBoss Enterprise Application Platform requires an
Apache server instance to host JOSSO. JBoss Enterprise Application Platform communicates
with the JOSSO Apache instance through the single sign-on plug-in.
@@ -704,6 +705,242 @@
After completing all procedures in this section, all links redirecting to the
user authentication pages will redirect to the JOSSO centralized authentication form.
</para>
+ <section>
+ <title>Authentication Process</title>
+
+ <para>
+ The login workflow for JOSSO is quite similar to that used for CAS
authentications (specific details can be found in <xref
linkend="sect-CAS-Authentication_Process"/>).
+ </para>
+
+ <para>
+ Essentially, after a user clicks to sign in they are redirected to the
JOSSO login screen, where they supply the appropriate credentials. They are then
redirected back to the Portal.
+ </para>
+
+ <para>
+ The <systemitem>JOSSOAgent</systemitem> component performs a
validation of the ticket with the JOSSO server via a back channel after the
<systemitem>InitiateLoginFilter</systemitem> has delegated the
<parameter> josso_assertion_id </parameter> request to it. The JOSSO agent and
JOSSO server communicate via web services.
+ </para>
+
+ <para>
+ After a successful validation, the user identity is successfully
established and the user is logged into the requested Portal.
+ </para>
+
+ <para>
+ On logout, <systemitem>JOSSOLogoutFilter</systemitem> performs
a logout on both the Portal and the JOSSO server (similar to the process for CAS).
+ </para>
+
+ <para>
+ While the authentication plugin (which is able to send REST requests to
the portal, receive the response, and authenticate the user on the JOSSO side) is
supported, this support is only for JOSSO 1.8 (not JOSSO 2.2 at this release).
+ </para>
+
+ <para>
+ In this example, we will assume again that JBoss Portal Platform will be
running on JBoss Enterprise Application Platform 6 using port <emphasis
role="italics">localhost:8080</emphasis> and that the JOSSO server will
be running on Tomcat, using <emphasis
role="italics">localhost:8888</emphasis>.
+ </para>
+
+ <note>
+ <para>
+ There are differences between various JOSSO minor versions (especially
betweeen JOSSO versions 1.8.1 and 1.8.2) so instructions will be slightly different
between various versions. This will be pointed in text in more details.
+ </para>
+ </note>
+ </section>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <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>
+ </listitem>
+ </itemizedlist>
+ </step>
+
+ <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>
+
+ <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>.
+ </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>
+<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.josso.agent.config.file=sso/josso/1.8/josso-agent-config.xml
+gatein.sso.josso.properties.file=file:${jboss.home.dir}/standalone/configuration/gatein/configuration.properties
+gatein.sso.josso.host=localhost:8888
+gatein.sso.josso.base.url=http://${gatein.sso.josso.host}/josso/signon
+gatein.sso.server.url=${gatein.sso.josso.base.url}/login.do
+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.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>
+
+ <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>
+
+ <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><version></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>
+<!-- Old JOSSO content replaced by action prompted by BZ#856430
+
<procedure
id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-JOSSO_server">
<title>Download and extract JOSSO server</title>
@@ -883,6 +1120,7 @@
<programlisting language="XML" role="XML"><xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"
href="../../extras/Authentication_Identity_SSO/default115.xml"
parse="text"/></programlisting>
</step>
</procedure>
+ </section> -->
</section>
<section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenSSO">
@@ -1827,7 +2065,7 @@
<sso cache-container="web" cache-name="sso"
reauthenticate="true" />
]]></programlisting>
<para>
- The <literal>true</literal> value ensures that
reauthentication with user credentials will be performed against the web application's
security domain in each HTTP request. This will enforce creation of a new principal with
updated roles for the web application. As user credentials are used for authentication in
this case, it is required that the same user credentials exist in both the web application
and the JBoss Portal Platform instance.
+ The <literal>true</literal> value ensures that
reauthentication with user credentials will be performed against the web
application's security domain in each HTTP request. This will enforce creation of
a new principal with updated roles for the web application. As user credentials are used
for authentication in this case, it is required that the same user credentials exist in
both the web application and the JBoss Portal Platform instance.
</para>
</section>
</section>