5:07 p.m.
Author: mstruk
Date: 2010-03-28 18:07:55 -0400 (Sun, 28 Mar 2010)
New Revision: 2377
Modified:
portal/trunk/docs/reference-guide/en/modules/SSO.xml
Log:
Reference guide edits - Chapter 3 - SSO
Modified: portal/trunk/docs/reference-guide/en/modules/SSO.xml
===================================================================
--- portal/trunk/docs/reference-guide/en/modules/SSO.xml 2010-03-28 16:47:47 UTC (rev
2376)
+++ portal/trunk/docs/reference-guide/en/modules/SSO.xml 2010-03-28 22:07:55 UTC (rev
2377)
@@ -8,7 +8,7 @@
<section id="sect-Reference_Guide-Single_Sign_On-Overview">
<title>Overview</title>
<para>
- &PRODUCT;, provides some form of Single Sign On
(<literal>SSO</literal>) as an integration and aggregation platform.
+ &PRODUCT; provides some form of Single Sign On
(<literal>SSO</literal>) as an integration and aggregation platform.
</para>
<para>
When logging into the portal users gain access to many systems through portlets using
a single identity. In many cases, however, the portal infrastructure must be integrated
with other SSO enabled systems. There are many different Identity Management solutions
available. In most cases each SSO framework provides a unique way to plug into a Java EE
application.
@@ -19,7 +19,7 @@
In this tutorial, the SSO server is installed in a Tomcat installation. Tomcat can be
obtained from <ulink type="http"
url="http://tomcat.apache.org">http://tomcat.apache.org</ulink>.
</para>
<para>
- All the packages required for setup can be found in a zip file located at:
<filename>http://repository.jboss.org/maven2/org/gatein/sso/sso-packagi...;.
In this document we will call $SSO_HOME the directory where the file is extracted.
+ All the packages required for setup can be found in a zip file located at: <ulink
type="http"
url="http://repository.jboss.org/maven2/org/gatein/sso/sso-packaging...;.
In this document we will call the directory where the file is extracted $GATEIN_SSO_HOME.
</para>
<para>
Users are advised to not run any portal extensions that could override the data when
manipulating the <filename>gatein.ear</filename> file directly.
@@ -57,10 +57,16 @@
<section id="sect-Reference_Guide-CAS_server-Modifying_CAS_server">
<title>Modifying CAS server</title>
<para>
- To configure the web archive as desired, it is simpler to directly modify the
sources.
+ To configure the web archive as desired, the simplest way is to make the necessary
changes directly in CAS codebase.
</para>
+ <note>
+ <para>
+ To complete these instructions, and perform the final build step, you
will need the Apache Maven 2.
+ You can get it <ulink type="http"
url="http://maven.apache.org/download.html">here</ulink>;.
+ </para>
+ </note>
<para>
- To change the authentication handler to use the portal authentication handler:
+ First, we need to change the default authentication handler with the one provided by
&PRODUCT;.
</para>
<para>
The CAS Server Plugin makes secure authentication callbacks to a RESTful service
installed on the remote GateIn server in order to authenticate a user.
@@ -107,7 +113,7 @@
</step>
<step>
<para>
- With the following (Make sure to set the host, port and context with the values
corresponding to your portal). Also available in
<filename>GATEIN_SSO/cas/plugin/WEB-INF/deployerConfigContext.xml</filename>.
+ With the following (Make sure to set the host, port and context with the values
corresponding to your portal). Also available in
<filename>GATEIN_SSO_HOME/cas/plugin/WEB-INF/deployerConfigContext.xml</filename>.
</para>
<para>
@@ -149,7 +155,7 @@
</step>
<step>
<para>
- Copy
<filename>GATEIN_SSO/cas/plugin/WEB-INF/lib/sso-cas-plugin-<VERSION>.jar</filename>
and
<filename>GATEIN_SSO/cas/plugin/WEB-INF/lib/commons-httpclient-<VERSION>.jar</filename>
into the
<filename>CAS_HOME/cas-server-webapp/src/main/webapp/WEB-INF/lib</filename>
created directory.
+ Copy
<filename>GATEIN_SSO_HOME/cas/plugin/WEB-INF/lib/sso-cas-plugin-<VERSION>.jar</filename>
and
<filename>GATEIN_SSO_HOME/cas/plugin/WEB-INF/lib/commons-httpclient-<VERSION>.jar</filename>
into the
<filename>CAS_HOME/cas-server-webapp/src/main/webapp/WEB-INF/lib</filename>
created directory.
</para>
</step>
<step>
@@ -160,7 +166,8 @@
Change the default port to avoid a conflict with the default &PRODUCT; (for
testing purposes). Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and
replace the 8080 port to 8888.
<note>
<para>
- If &PRODUCT; is running with Tomcat on the same machine the port 8005 should
be changed to something else to avoid port conflicts.
+ If &PRODUCT; is running on the same machine as Tomcat, other ports need to
be changed in addition to 8080 in order to avoid port conflicts.
+ They can be changed to any free port. For example, you can
change admin port from 8005 to 8805, and AJP port from 8009 to 8809.
</para>
</note>
</para>
@@ -195,7 +202,7 @@
<procedure>
<step>
<para>
- Copy all libraries from
<filename>GATEIN_SSO/cas/gatein.ear/lib</filename> into
<filename>JBOSS_HOME/server/default/deploy/gatein.ear/lib</filename> (Or in
Tomcat, into $<filename>GATEIN_HOME/lib</filename>)
+ Copy all libraries from
<filename>GATEIN_SSO_HOME/cas/gatein.ear/lib</filename> into
<filename>JBOSS_HOME/server/default/deploy/gatein.ear/lib</filename> (Or in
Tomcat, into $<filename>GATEIN_HOME/lib</filename>)
</para>
</step>
<step>
@@ -234,7 +241,7 @@
<procedure>
<step>
<para>
- Access &PRODUCT; (if the CAS server using Tomcat is still running) by going
to <ulink type="http"
url="http://localhost:8888/cas">http://localhost:8888/cas</ulink>.
+ Start (or restart) &PRODUCT;, and (assuming the CAS server on Tomcat is
running) direct your browser to <ulink type="http"
url="http://localhost:8888/cas">http://localhost:8888/cas</ulink>.
</para>
</step>
<step>
@@ -308,10 +315,10 @@
<section id="sect-Reference_Guide-Single_Sign_On-JOSSO">
<title>JOSSO</title>
<para>
- This Single Sign On plugin enables seamless integration between &PRODUCT; and the
JOSSO Single Sign On Framework. Details about OpenSSO can be found <ulink
url="http://www.ja-sig.org/products/cas/">here</ulink>;.
+ This Single Sign On plugin enables seamless integration between &PRODUCT; and the
JOSSO Single Sign On Framework. Details about JOSSO can be found <ulink
url="http://www.josso.org">here</ulink>.
</para>
<para>
- Setting up this integration happens in two distinct actions. The first part is
installing or configuring a JOSSO server and the second involves setting up the portal to
use the JOSSO server.
+ Setting up this integration involves two steps. The first step is to install or
configure a JOSSO server, and the second is to set up the portal to use the JOSSO server.
</para>
<section id="sect-Reference_Guide-JOSSO-JOSSO_server">
<title>JOSSO server</title>
@@ -324,7 +331,7 @@
<section id="sect-Reference_Guide-JOSSO_server-Obtaining_JOSSO">
<title>Obtaining JOSSO</title>
<para>
- JOSSO can be downloaded from <ulink type="http"
url="http://sourceforge.net/projects/josso/files/">http://so...;.
Use the package that embeds Apache Tomcat.
+ JOSSO can be downloaded from <ulink type="http"
url="http://sourceforge.net/projects/josso/files/">http://so...;.
Use the package that embeds Apache Tomcat. The integration was tested with JOSSO-1.8.1.
</para>
<para>
Once downloaded, extract the package into what will be called
<filename>JOSSO_HOME</filename> in this example.
@@ -336,7 +343,7 @@
<procedure>
<step>
<para>
- Copy the files from <filename>GATEIN_SSO/josso/plugin</filename> into
the Tomcat directory (<filename>JOSSO_HOME</filename>).
+ Copy the files from <filename>GATEIN_SSO_HOME/josso/plugin</filename>
into the Tomcat directory (<filename>JOSSO_HOME</filename>).
</para>
<para>
This action should replace or add the following files to the
<filename>JOSSO_HOME/webapps/josso/WEB-INF/lib</filename> directory:
@@ -370,7 +377,8 @@
<note>
<title>Port Conflicts</title>
<para>
- If &PRODUCT; is being on a machine with Tomcat, other ports will need to be
changed to avoid conflicts.
+ If &PRODUCT; is running on the same machine as Tomcat,
other ports need to be changed in addition to 8080 in order to avoid port conflicts.
+ They can be changed to any free port. For example, you can
change admin port from 8005 to 8805, and AJP port from 8009 to 8809.
</para>
</note>
</para>
@@ -395,9 +403,14 @@
<procedure>
<step>
<para>
- Copy the library files from
<filename>GATEIN_SS)/josso/gatein.ear/lib</filename> into
<filename>gatein.ear/lib</filename> (Or into
<filename>GATEIN_HOME/lib</filename> if &PRODUCT; is running in Tomcat)
+ Copy the library files from
<filename>GATEIN_SSO_HOME/josso/gatein.ear/lib</filename> into
<filename>gatein.ear/lib</filename> (or into
<filename>GATEIN_HOME/lib</filename> if &PRODUCT; is running in Tomcat)
</para>
</step>
+ <step>
+ <para>
+ Copy the file
<filename>GATEIN_SSO_HOME/josso/gatein.ear/portal.war/WEB-INF/classes/josso-agent-config.xml</filename>
into <filename>gatein.ear/02portal.war/WEB-INF/classes</filename> (or into
<filename>GATEIN_HOME/webapps/portal.war/WEB-INF/classes</filename>, or
<filename>GATEIN_HOME/conf</filename> if &PRODUCT; is running in Tomcat)
+ </para>
+ </step>
<step>
<itemizedlist>
<listitem>
@@ -433,7 +446,7 @@
<procedure>
<step>
<para>
- Start &PRODUCT; (assuming that the JOSSO server using Tomcat is running) by
going to <ulink type="http"
url="http://localhost:8888/josso/signon/login.do">http://localhost:8888/josso/signon/login.do</ulink>.
+ Start (or restart) &PRODUCT;, and (assuming the JOSSO server on Tomcat is
running) direct your browser to <ulink type="http"
url="http://localhost:8888/josso/signon/login.do">http://localhost:8888/josso/signon/login.do</ulink>.
</para>
</step>
<step>
@@ -489,7 +502,7 @@
<servlet-class>org.gatein.sso.agent.GenericSSOAgent</servlet-class>
<init-param>
<param-name>ssoServerUrl</param-name>
- <param-value>http://localhost:8888/cas</param-value>
+
<param-value>http://localhost:8888/josso/signon/login.do</param-value>
</init-param>
</servlet>
</programlisting>
@@ -514,15 +527,15 @@
This Single Sign On plugin enables seamless integration between &PRODUCT; and the
OpenSSO Single Sign On Framework. Details about OpenSSO can be found <ulink
url="https://opensso.dev.java.net/">here</ulink>;.
</para>
<para>
- Setting up this integration happens in two distinct actions. The first part is
installing or configuring an OpenSSO server and the second involves setting up the portal
to use the OpenSSO server.
+ Setting up this integration involves two steps. The first step is to install or
configure an OpenSSO server, and the second is to set up the portal to use the OpenSSO
server.
</para>
<section
id="sect-Reference_Guide-OpenSSO_The_Open_Web_SSO_project-OpenSSO_server">
<title>OpenSSO server</title>
<para>
- This section details setting up the OpenSSO server to authenticate against the
Enterprise Portal Platform login module.
+ This section details the setting up of OpenSSO server to authenticate against the
&PRODUCT; login module.
</para>
<para>
- In this example the JOSSO server will be installed on Tomcat.
+ In this example the OpenSSO server will be installed on Tomcat.
</para>
<section id="sect-Reference_Guide-OpenSSO_server-Obtaining_OpenSSO">
<title>Obtaining OpenSSO</title>
@@ -559,7 +572,8 @@
Change the default port to avoid a conflict with the default &PRODUCT; port
(for testing purposes). Do this by editing
<filename>TOMCAT_HOME/conf/server.xml</filename> and replacing the 8080 port
to 8888.
<note>
<para>
- If &PRODUCT; is running on the same machine as Tomcat, the port 8005 will
also need to be changed to avoid port conflicts.
+ If &PRODUCT; is running on the same machine as Tomcat,
other ports need to be changed in addition to 8080 in order to avoid port conflicts.
+ They can be changed to any free port. For example, you can
change admin port from 8005 to 8805, and AJP port from 8009 to 8809.
</para>
</note>
</para>
@@ -593,14 +607,15 @@
</step>
<step>
<para>
- Copy
<filename>GATEIN_SSO/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-<VERSION>.jar</filename>,
<filename>GATEIN_SSO/opensso/plugin/WEB-INF/lib/commons-httpclient-<VERSION>.jar</filename>,
and
<filename>GATEIN_SSO/opensso/plugin/WEB-INF/lib/commons-logging-<VERSION>.jar</filename>
into the Tomcat directory at
<filename>TOMCAT_HOME/webapps/opensso/WEB-INF/lib</filename>.
+ Copy
<filename>GATEIN_SSO_HOME/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-<VERSION>.jar</filename>,
<filename>GATEIN_SSO_HOME/opensso/plugin/WEB-INF/lib/commons-httpclient-<VERSION>.jar</filename>,
and
<filename>GATEIN_SSO_HOME/opensso/plugin/WEB-INF/lib/commons-logging-<VERSION>.jar</filename>
into the Tomcat directory at
<filename>TOMCAT_HOME/webapps/opensso/WEB-INF/lib</filename>.
</para>
</step>
<step>
<para>
- Copy
<filename>GATEIN_SSO/opensso/plugin/WEB-INF/classes/gatein.properties</filename>
into <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/classes</filename>
+ Copy
<filename>GATEIN_SSO_HOME/opensso/plugin/WEB-INF/classes/gatein.properties</filename>
into <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/classes</filename>
</para>
</step>
+
<step>
<para>
Tomcat should start and be able to access <ulink type="http"
url="http://localhost:8888/opensso/UI/Login?realm=gatein">http://localhost:8888/opensso/UI/Login?realm=gatein</ulink>.
Login will not be available at this point.
@@ -611,9 +626,54 @@
</imageobject>
</mediaobject>
</step>
- </procedure>
- </section>
+ </procedure>
+ <para>Configure "gatein" realm:</para>
+ <procedure>
+ <step>
+ <para>Direct your browser to <ulink type="http"
url="http://localhost:8888/opensso">http://localhost:8888/opensso</ulink></para>
+ </step>
+ <step>
+ <para>Create default configuration</para>
+ </step>
+ <step>
+ <para>Login as <literal>amadmin</literal> and then
go to tab "Configuration" -> tab "Authentication" -> link
"Core" ->
+ add new value and fill in the class name
"org.gatein.sso.opensso.plugin.AuthenticationPlugin".
+ This step is really important. Without it AuthenticationPlugin is
not available among other OpenSSO authentication modules.
+ </para>
+ </step>
+ <step>
+ <para>Go to tab "Access control" and create new realm
called "gatein".</para>
+ </step>
+ <step>
+ <para>Go to "gatein" realm and click on
"Authentication" tab. At the bottom in the section "Authentication
chaining" click on "ldapService".
+ Here change the selection from "Datastore", which is the
default module in the authentication chain, to "AuthenticationPlugin".
+ This enables authentication of "gatein" realm by using
GateIn REST service instead of the OpenSSO LDAP server.</para>
+ </step>
+ <step>
+ <para>
+ Go to "Advanced properties" and change UserProfile from
"Required" to "Dynamic". This step is needed
+ because &PRODUCT; users are not in OpenSSO Datastore (LDAP
server), so their profiles can't be obtained
+ if "Required" is active. By using "Dynamic" all
new users are automatically
+ created in OpenSSO datastore after successful authentication.
+ </para>
+ </step>
+ <step>
+ <para>
+ Increase the user privileges to allow REST access. Go to
"Access control" ->
+ Top level realm -> "Privileges" tab -> All
authenticated users, and check the last two checkboxes:
+ <itemizedlist>
+ <listitem><para>Read and write access only for policy
properties</para></listitem>
+ <listitem><para>Read and write access to all realm
and policy properties</para></listitem>
+ </itemizedlist>
+ </para>
+ </step>
+ <step>
+ <para>Do the same for "gatein" realm.</para>
+ </step>
+ </procedure>
+ <para>TODO: The above OpenSSO manual configuration could be replaced by
configuration files prepared in advance</para>
+ </section>
</section>
<section
id="sect-Reference_Guide-OpenSSO_The_Open_Web_SSO_project-Setup_the_OpenSSO_client">
@@ -621,7 +681,7 @@
<procedure>
<step>
<para>
- Copy all libraries from
<filename>GATEIN_SSO/opensso/gatein.ear/lib</filename> into
<filename>JBOSS_HOME/server/default/deploy/gatein.ear/lib</filename> (Or, in
Tomcat, into <filename>GATEIN_HOME/lib</filename>)
+ Copy all libraries from
<filename>GATEIN_SSO_HOME/opensso/gatein.ear/lib</filename> into
<filename>JBOSS_HOME/server/default/deploy/gatein.ear/lib</filename> (Or, in
Tomcat, into <filename>GATEIN_HOME/lib</filename>)
</para>
</step>
<step>