11:15 a.m.
Author: anil.saldhana(a)jboss.com
Date: 2009-12-17 12:15:36 -0500 (Thu, 17 Dec 2009)
New Revision: 1096
Modified:
identity-doc/trunk/UserGuide/src/main/docbook/UserGuide.xml
Log:
update doc
Modified: identity-doc/trunk/UserGuide/src/main/docbook/UserGuide.xml
===================================================================
--- identity-doc/trunk/UserGuide/src/main/docbook/UserGuide.xml 2009-12-16 19:15:22 UTC
(rev 1095)
+++ identity-doc/trunk/UserGuide/src/main/docbook/UserGuide.xml 2009-12-17 17:15:36 UTC
(rev 1096)
@@ -120,7 +120,7 @@
<tip>
<title>Location for downloading the jars</title>
<para>
- <ulink url="http://repository.jboss.org/maven2">JBoss Maven
Repository</ulink>
+ <ulink
url="http://repository.jboss.org/maven2/org/picketlink">Pick... - JBoss
Maven Repository</ulink>
</para>
</tip>
</chapter>
@@ -137,11 +137,11 @@
and Single Sign-On (SSO) for applications).</para>
<section> <!-- Section: SAML HTTP/Redirect Binding -->
- <title>SAML v2 based Web SSO</title>
+ <title>SAML v2 based Web SSO using HTTP/Redirect Binding</title>
<para>This section will talk about the configuration information to
support the SAML V2.0 based Web Single Sign On (SSO). The SAML profile
- that is implemented is the HTTP/Redirect binding with centralized
- identity services to enable web SSO for your applications.
+ has support for both the HTTP/POST and the HTTP/Redirect bindings
+ with centralized identity services to enable web SSO for your applications.
</para>
<mediaobject>
<imageobject>
@@ -154,14 +154,15 @@
</para>
</caption>
</mediaobject>
- <para>The architecture follows the Hub and Spoke architecture of Identity
Management.
+ <para>The architecture follows the Hub and Spoke architecture of Identity
+ Management.
An Identity Provider (IDP) acts as the central source (hub) for identity and role
information to all the applications (Service Providers/SP). The spokes are the
Service Providers (SP).
</para>
<note>
<para>The IDP and the SP can be a JBoss Application Server or a Tomcat
instance.
- Please note that the instructions for Tomcat and JBAS are different.
+ Please note that the instructions for Tomcat and JBAS have slight differences.
</para>
</note>
@@ -173,15 +174,30 @@
<title>Check list for configuring the IDP</title>
<orderedlist>
<listitem>
- <para>the IDP as a secure web application.</para>
+ <para>
+ The IDP as a secure web application.
+ </para>
</listitem>
<listitem>
- <para>Configure the web.xml to either allow FORM or BASIC
authentication. </para>
+ <para>
+ Configure the web.xml to either allow FORM or BASIC authentication.
+ </para>
</listitem>
- <listitem><para>Configure the context.xml for IDP
valves.</para>
+ <listitem>
+ <para>
+ Configure the context.xml for IDP valves.
+ </para>
</listitem>
- <listitem><para>Configure the picketlink-idfed.xml for IDP
configuration.</para>
+ <listitem>
+ <para>
+ Configure the picketlink-idfed.xml for IDP configuration.
+ </para>
</listitem>
+ <listitem>
+ <para>
+ Configure the picketlink-handlers.xml for IDP configuration.
+ </para>
+ </listitem>
</orderedlist>
</note>
@@ -299,7 +315,7 @@
IDP web application</para>
<programlisting role="xml">
<PicketLinkIDP
xmlns="urn:picketlink:identity-federation:config:1.0" >
-
<IdentityURL>http://localhost:8080/idp</IdentityURL>
+
<IdentityURL>http://localhost:8080/idp/</IdentityURL>
</PicketLinkIDP>
</programlisting>
@@ -309,6 +325,27 @@
</para>
</section><!-- End Section: Configure IDFed Config File - IDP -->
+ <section> <!-- Section: Configure IDFed Handler File - IDP -->
+ <title>
+ Configure the PicketLink Federation Handlers file (picketlink-handlers.xml)
+ </title>
+ <para>
+ Configure <emphasis
role="italic">picketlink-handlers.xml</emphasis>
+ in WEB-INF of your IDP web application
+ </para>
+ <programlisting role="xml">
+ <Handlers
xmlns="urn:picketlink:identity-federation:handler:config:1.0">
+<Handler
class="org.picketlink.identity.federation.web.handlers.saml2.SAML2IssuerTrustHandler"/>
+<Handler
class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler"/>
+<Handler
class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler"/>
+<Handler
class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler"/>
+</Handlers>
+ </programlisting>
+
+ <para>
+ Note the order of the handlers is important.
+ </para>
+ </section><!-- End Section: Configure IDFed Config File - IDP -->
</section> <!-- End Section on configuring the Identity Provider-->
@@ -332,6 +369,11 @@
<para>Configure the picketlink-idfed.xml for the SP
configuration.</para>
</listitem>
<listitem>
+ <para>
+ Configure the picketlink-handlers.xml for the SP configuration.
+ </para>
+ </listitem>
+ <listitem>
<para>Perform additional steps if the SP is running on JBoss
Application Server.</para>
</listitem>
</orderedlist>
@@ -447,8 +489,10 @@
<section> <!-- Section: Configure IDFed Config File - SP -->
<title>Configure the PicketLink Federation configuration file
(picketlink-idfed.xml)</title>
- <para>Configure <emphasis
role="italic">picketlink.xml</emphasis> in WEB-INF of your
- SP web application</para>
+ <para>
+ Configure <emphasis
role="italic">picketlink-idfed.xml</emphasis>
+ in WEB-INF of your SP web application
+ </para>
<programlisting role="xml">
@@ -464,6 +508,29 @@
the identity provider.
</para>
</section><!-- End Section: Configure IDFed Config File - SP -->
+
+ <section> <!-- Section: Configure IDFed Handlers File - SP -->
+ <title>
+ Configure the PicketLink Federation Handlers file (picketlink-handlers.xml)
+ </title>
+ <para>
+ Configure <emphasis
role="italic">picketlink-handlers.xml</emphasis>
+ in WEB-INF of your SP web application.
+ </para>
+
+ <programlisting role="xml">
+<Handlers
xmlns="urn:picketlink:identity-federation:handler:config:1.0">
+
+<Handler
class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler"/>
+
+<Handler
class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler"/>
+
+</Handlers>
+ </programlisting>
+
+ </section><!-- End Section: Configure IDFed Config File - SP -->
+
+
<section> <!-- Section: Additional steps for JBAS based SP -->
<title>Additional Steps for JBoss AS based SP</title>
@@ -508,6 +575,38 @@
</section><!-- End Section:configure the SP -->
</section><!-- End Section: SAML HTTP/Redirect Binding -->
+
+
+ <section> <!-- Section: SAML HTTP/POST Binding -->
+ <title>SAML v2 based Web SSO using HTTP/POST Binding</title>
+ <para>
+ In the previous section, we looked at the HTTP/Redirect Binding for obtaining
+ web browser based SSO. If you would like to utilize the HTTP/POST binding
+ which is the recommended binding, then configure the IDP as in the
+ HTTP/Redirect binding.
+ </para>
+ <para>
+ The configuration at the SP is identical to the HTTP/Redirect Binding except
+ that the context.xml at the SP looks as follows (change in the valve class):
+ </para>
+ <para>
+ The context.xml file should look like:
+ </para>
+ <programlisting role="xml">
+ <Context>
+ <Valve
+
className="org.picketlink.identity.federation.bindings.tomcat.sp.SPPostFormAuthenticator"
+ />
+ </Context>
+ </programlisting>
+
+ <warning>
+ <para>
+ Remember for the HTTP/POST Binding, the IDP configuration is exactly the same as
the HTTP/Redirect Binding. For the SP Configuration, there is a change in context.xml
only. The rest is the same as HTTP/Redirect binding.
+ </para>
+ </warning>
+
+ </section><!-- End Section: SAML HTTP/POST Binding -->
</chapter>
</part>
@@ -632,14 +731,28 @@
</title>
<orderedlist>
<listitem>
- <para>Configure the SP as a secure FORM authentication based web
application.</para>
+ <para>
+ Configure the SP as a secure FORM authentication based web
application.
+ </para>
</listitem>
- <listitem><para>Configure the web.xml of the SP web
application.</para>
+ <listitem>
+ <para>Configure the web.xml of the SP web
application.</para>
</listitem>
- <listitem><para>Configure the context.xml for the SP
valves.</para>
+ <listitem>
+ <para>
+ Configure the context.xml for the SP valves.
+ </para>
</listitem>
- <listitem><para>Configure the picketlink-idfed.xml for the SP
configuration.</para>
+ <listitem>
+ <para>
+ Configure the picketlink-idfed.xml for the SP configuration.
+ </para>
</listitem>
+ <listitem>
+ <para>
+ Configure the picketlink-handlers.xml for the SP configuration.
+ </para>
+ </listitem>
</orderedlist>
</note>
@@ -684,7 +797,9 @@
</note>
<note>
- <para> If the SP is running in JBoss Application Server, then place
the context.xml in
+ <para>
+ If the SP is running in JBoss Application Server, then place the
+ context.xml in
<emphasis role="bold">WEB-INF</emphasis> of your SP
web application.
</para>
</note>
@@ -693,8 +808,9 @@
<section> <!-- Section: Configure IDFed Config File - IDP -->
<title>Configure the PicketLink Federation configuration file
(picketlink-idfed.xml)</title>
- <para>Configure <emphasis
role="italic">picketlink-idfed.xml</emphasis> in WEB-INF of your
- IDP web application</para>
+ <para>Configure <emphasis
role="italic">picketlink-idfed.xml</emphasis>
+ in WEB-INF of your SP web application.
+ </para>
<programlisting role="xml">
<PicketLinkIDP
xmlns="urn:picketlink:identity-federation:config:1.0" >
<IdentityURL>http://localhost:8080/idp-sig</IdentityURL>
@@ -734,6 +850,17 @@
</para>
</section><!-- End Section: Configure IDFed Config File - SP -->
+ <section> <!-- Section: Configure handlers Config File - SP -->
+ <title>Configure the PicketLink Federation handlers file
(picketlink-handlers.xml)</title>
+ <para>
+ Configure <emphasis
role="italic">picketlink-handlers.xml</emphasis>
+ in WEB-INF of your SP web application
+ </para>
+ <para>
+ Please refer to the previous chapter for the handlers file.
+ </para>
+ </section><!-- End Section: Configure handlers Config File - SP
-->
+
</section> <!-- End: Configure the SP -->
</chapter> <!-- Web SSO (XML Signature Support) -->