3:04 p.m.
Author: anil.saldhana(a)jboss.com
Date: 2009-02-02 16:04:42 -0500 (Mon, 02 Feb 2009)
New Revision: 272
Modified:
identity-federation/trunk/doc/UserGuide/src/main/docbook/UserGuide.xml
Log:
userguide
Modified: identity-federation/trunk/doc/UserGuide/src/main/docbook/UserGuide.xml
===================================================================
--- identity-federation/trunk/doc/UserGuide/src/main/docbook/UserGuide.xml 2009-02-02
13:39:43 UTC (rev 271)
+++ identity-federation/trunk/doc/UserGuide/src/main/docbook/UserGuide.xml 2009-02-02
21:04:42 UTC (rev 272)
@@ -27,7 +27,8 @@
Identity based services or applications.</para>
<para>Part I 'Getting Started' introduces the federated identity
- technologies that are provided in this product.</para>
+ technologies that are provided in this product. It also indicates
+ the libraries required for the installation.</para>
<para>Part II 'Simple Usage' describes SAML v2 Web Browser based
Single Sign On (SSO).</para>
@@ -35,6 +36,10 @@
<para>Part III 'Advanced Usage' describes SAML v2 Web Browser based SSO
with advanced features such as Trust Management and XML
Digital Signatures.</para>
+
+ <para>Part IV 'Trouble Shooting' section describes some basic
+ troubleshooting tips when things do not work the way they were intended.
+ </para>
</preface>
<part>
@@ -64,10 +69,51 @@
</itemizedlist>
</chapter>
+
+ <chapter id="installation">
+ <title>Installation</title>
+ <para>
+ JBoss Identity Federation requires the following libraries
+ to be either downloaded separately or as part of the Java JDK
+ or as part of JBoss Application Server.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para> JBoss Identity Federation Library
+ </para>
+ </listitem>
+ <listitem>
+ <para> JBoss XACML Library (jboss-xacml.jar and jboss-sunxacml.jar)
+ </para>
+ </listitem>
+ <listitem>
+ <para> JAXB V2 Library
+ </para>
+ </listitem>
+ <listitem>
+ <para> STAX API Library (a dependency for JAXB2)
+ </para>
+ </listitem>
+ <listitem>
+ <para> Activation API Library (a dependency for JAXB2)
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <tip>
+ <title>Location for downloading the jars</title>
+ <para>
+ <ulink url="http://repository.jboss.org/maven2">JBoss Maven
Repository</ulink>
+ </para>
+ </tip>
+ </chapter>
+ </part>
+
+ <part>
+ <title>Simple Usage</title>
- <chapter>
- <title>Simple Usage</title>
-
+ <chapter>
+ <title>Web Single Sign On (SSO)</title>
<para>In this chapter, we will look at usage of JBoss Identity
Federation to help you obtain a platform to implement federated identity
based services (including centralized identity services
@@ -392,6 +438,362 @@
</section><!-- End Section:configure the SP -->
</section><!-- End Section: SAML HTTP/Redirect Binding -->
- </chapter>
+ </chapter>
</part>
-</book>
+
+ <part> <!-- Advanced Usage -->
+ <title>Advanced Usage (Trust Management)</title>
+ <chapter> <!-- Web SSO (XML Signature Support) -->
+ <title>Web SSO - XML Signature Support</title>
+ <para>
+ In this chapter, we describe the configuration for Web SSO with XML Signature
Support.
+ </para>
+ <section> <!-- Configuring the IDP -->
+ <title>Configuring the Identity Provider</title>
+ <para>
+ The IDP needs to be configured to provide Web SSO with XML Signature Support.
+ </para>
+
+ <note>
+ <title>Check list for configuring the IDP</title>
+ <orderedlist>
+ <listitem>Configure the IDP as a secure web application.
+ </listitem>
+ <listitem>Configure the web.xml to either allow FORM or BASIC
authentication.
+ </listitem>
+ <listitem>Configure the context.xml for IDP valves.
+ </listitem>
+ <listitem>Configure the jboss-idfed.xml for IDP configuration.
+ </listitem>
+ </orderedlist>
+ </note>
+
+ <section> <!-- Configure the IDP web.xml security-->
+ <title>Configure the IDP Web Application Security</title>
+ <warning>
+ <title>Configure the web application security for IDP</title>
+ <para> Follow the web.xml security configuration for the IDP from the
previous section
+ "Simple Usage".
+ </para>
+ </warning>
+ </section>
+
+ <section> <!-- Configure the IDP Valves -->
+ <title>Configure the IDP Valves</title>
+ <para> Create a <emphasis
role="italic">context.xml</emphasis> file for configuring
+ the valves for the IDP.
+ </para>
+ <para> The context.xml file should look like:
+ </para>
+ <programlisting role="xml">
+ <Context>
+ <Valve
+ className
+
="org.jboss.identity.federation.bindings.tomcat.idp.IDPRedirectWithSignatureValve"
+ />
+ </Context>
+ </programlisting>
+
+ <note>
+ <para>If the IDP is running in Apache Tomcat, then place the
context.xml in
+ <emphasis role="bold">META-INF</emphasis> of your IDP
web application.
+ </para>
+ </note>
+
+ <note>
+ <para> If the IDP is running in JBoss Application Server, then place
the context.xml in
+ <emphasis role="bold">WEB-INF</emphasis> of your IDP
web application.
+ </para>
+ </note>
+
+ </section> <!-- Section: configure IDP valves -->
+
+ <section> <!-- Section: Configure IDFed Config File - IDP -->
+ <title>Configure the JBoss Identity Federation configuration file
(jboss-idfed.xml)</title>
+ <para>Configure <emphasis
role="italic">jboss-idfed.xml</emphasis> in WEB-INF of your
+ IDP web application</para>
+ <programlisting role="xml">
+ <JBossIDP xmlns="urn:jboss:identity-federation:config:1.0"
>
+
<IdentityURL>http://localhost:8080/idp-sig</IdentityURL>
+ <Trust>
+
<Domains>localhost,jboss.com,jboss.org</Domains>
+ </Trust>
+ <KeyProvider
+
ClassName="org.jboss.identity.federation.bindings.tomcat.KeyStoreKeyManager">
+ <Auth Key="KeyStoreURL"
Value="jbid_test_keystore.jks" />
+ <Auth Key="KeyStorePass" Value="store123"
/>
+ <Auth Key="SigningKeyPass" Value="test123"
/>
+ <Auth Key="SigningKeyAlias"
Value="servercert" />
+ <ValidatingAlias Key="localhost"
Value="servercert"/>
+ <ValidatingAlias Key="127.0.0.1"
Value="servercert"/>
+ </KeyProvider>
+ </JBossIDP>
+ </programlisting>
+
+ <para>In this configuration file, you are providing the URL of your
IDP.
+ This is the URL that gets added as the issuer in the outgoing SAML2
assertions
+ to the Service Providers.
+ </para>
+ <para>
+ Additionally, you can configure the <emphasis
role="italic">Trust</emphasis>
+ element to indicate which domains the IDP trusts.
+ </para>
+ <para>
+ You can configure a <emphasis
role="bold">TrustKeyManager</emphasis>
+ implementation for the Signing (Private) Key and the Validating (Public) Key
+ information. In this example, we have used the
+ <emphasis role="bold">KeyStoreKeyManager</emphasis>
that
+ stores the keys in a Java KeyStore. The <emphasis
role="italic">Auth</emphasis>
+ element define the key value pair needed to authenticate against the
+ <emphasis role="bold">TrustKeyManager</emphasis>
implementation. The
+ <emphasis role="italic">ValidatingAlias</emphasis> is a
map of the domains
+ that need to be validated against an alias where the public key of the
domains
+ are stored.
+ </para>
+ </section><!-- End Section: Configure IDFed Config File - IDP -->
+
+ </section> <!-- End Section: configuring the IDP -->
+
+
+ <section> <!-- Section:configure the SP -->
+ <title>Configure the Service Provider (SP)</title>
+ <note>
+ <title>Check List for configuring the Service Provider.
+ </title>
+ <orderedlist>
+ <listitem>Configure the SP as a secure FORM authentication based web
application.
+ </listitem>
+ <listitem>Configure the web.xml of the SP web application.
+ </listitem>
+ <listitem>Configure the context.xml for the SP valves.
+ </listitem>
+ <listitem>Configure the jboss-idfed.xml for the SP configuration.
+ </listitem>
+ </orderedlist>
+ </note>
+
+ <para>The SP can be a JBoss Application Server or a Tomcat instance.
+ </para>
+ <para>
+ You need to configure a web application as the Service Provider(SP).
+ </para>
+
+ <section> <!-- Configure the SP web.xml security-->
+ <title>Configure the SP Web Application Security</title>
+ <warning>
+ <title>Configure the web application security for SP</title>
+ <para> Follow the web.xml security configuration for the SP from the
previous section
+ "Simple Usage".
+ </para>
+ </warning>
+ </section> <!-- End: Configure SP web.xml security -->
+
+ <section> <!-- Configure the SP Valves -->
+ <title>Configure the SP Valves</title>
+ <para> Create a <emphasis
role="italic">context.xml</emphasis> file for configuring
+ the valves for the SP.
+ </para>
+ <para> The context.xml file should look like:
+ </para>
+ <programlisting role="xml">
+
+ <Context>
+ <Valve
+ className=
+
"org.jboss.identity.federation.bindings.tomcat.sp.SPRedirectSignatureFormAuthenticator"
+ />
+ </Context>
+
+ </programlisting>
+
+ <note>
+ <para>If the SP is running in Apache Tomcat, then place the
context.xml in
+ <emphasis role="bold">META-INF</emphasis> of your SP
web application.
+ </para>
+ </note>
+
+ <note>
+ <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>
+
+ </section> <!-- Section: configure SP valves -->
+
+ <section> <!-- Section: Configure IDFed Config File - IDP -->
+ <title>Configure the JBoss Identity Federation configuration file
(jboss-idfed.xml)</title>
+ <para>Configure <emphasis
role="italic">jboss-idfed.xml</emphasis> in WEB-INF of your
+ IDP web application</para>
+ <programlisting role="xml">
+ <JBossIDP xmlns="urn:jboss:identity-federation:config:1.0"
>
+
<IdentityURL>http://localhost:8080/idp-sig</IdentityURL>
+ <Trust>
+
<Domains>localhost,jboss.com,jboss.org</Domains>
+ </Trust>
+ <KeyProvider
+
ClassName="org.jboss.identity.federation.bindings.tomcat.KeyStoreKeyManager">
+ <Auth Key="KeyStoreURL"
Value="jbid_test_keystore.jks" />
+ <Auth Key="KeyStorePass" Value="store123"
/>
+ <Auth Key="SigningKeyPass" Value="test123"
/>
+ <Auth Key="SigningKeyAlias"
Value="servercert" />
+ <ValidatingAlias Key="localhost"
Value="servercert"/>
+ <ValidatingAlias Key="127.0.0.1"
Value="servercert"/>
+ </KeyProvider>
+ </JBossIDP>
+ </programlisting>
+
+ <para>In this configuration file, we define the URLs for the service
provider and
+ the identity provider.
+ </para>
+ <para>
+ Additionally, you can configure the <emphasis
role="italic">Trust</emphasis>
+ element to indicate which domains the SP trusts.
+ </para>
+ <para>
+ You can configure a <emphasis
role="bold">TrustKeyManager</emphasis>
+ implementation for the Signing (Private) Key and the Validating (Public) Key
+ information. In this example, we have used the
+ <emphasis role="bold">KeyStoreKeyManager</emphasis>
that
+ stores the keys in a Java KeyStore. The <emphasis
role="italic">Auth</emphasis>
+ element define the key value pair needed to authenticate against the
+ <emphasis role="bold">TrustKeyManager</emphasis>
implementation. The
+ <emphasis role="italic">ValidatingAlias</emphasis> is a
map of the domains
+ that need to be validated against an alias where the public key of the
domains
+ are stored.
+ </para>
+ </section><!-- End Section: Configure IDFed Config File - SP -->
+
+ </section> <!-- End: Configure the SP -->
+
+ </chapter> <!-- Web SSO (XML Signature Support) -->
+ </part> <!-- End Section: Advanced Usage -->
+
+ <part> <!-- Troubleshooting -->
+ <title>Troubleshooting</title>
+ <chapter id="logging">
+ <section>
+ <title>Configuring Logging</title>
+ <para>
+ JBoss Identity Federation uses Apache log4j as the logging framework.
+ </para>
+ <section><!-- Logging:Tomcat -->
+ <title> Configuring Logging on Apache Tomcat</title>
+ <warning>
+ <title>Log4J jars and xml file</title>
+ <para>
+ Add a log4j.jar (from the Apache log4j Distribution) into the lib
directory of
+ tomcat 6.x or server/lib of tomcat 5.5.x
+ </para>
+ <para> Also add a log4j.xml as shown below to the lib directory.
+ </para>
+ </warning>
+
+ <programlisting role="xml">
+ <?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
+
+<!-- =====================================================================
-->
+<!--
-->
+<!-- Log4j Configuration
-->
+<!--
-->
+<!-- =====================================================================
-->
+
+<!--
+ | For more configuration information and examples see the Jakarta Log4j
+ | owebsite: http://jakarta.apache.org/log4j
+ -->
+
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/"
debug="false">
+
+ <!-- ================================= -->
+ <!-- Preserve messages in a local file -->
+ <!-- ================================= -->
+
+ <!-- A time/date based rolling appender -->
+ <appender name="FILE"
class="org.apache.log4j.DailyRollingFileAppender">
+ <param name="File" value="../logs/server.log"/>
+ <param name="Append" value="false"/>
+ <!--
+ Set the threshold via a system property. Note this is parsed by log4j,
+ so the full JBoss system property format is not supported; e.g.
+ setting a default via ${jboss.server.log.threshold:WARN} will not work.
+ -->
+ <param name="Threshold" value="TRACE"/>
+
+ <!-- Rollover at midnight each day -->
+ <param name="DatePattern"
value="'.'yyyy-MM-dd"/>
+
+ <!-- Rollover at the top of each hour
+ <param name="DatePattern"
value="'.'yyyy-MM-dd-HH"/>
+ -->
+
+ <layout class="org.apache.log4j.PatternLayout">
+ <!-- The default pattern: Date Priority [Category] (Thread) Message\n
-->
+ <param name="ConversionPattern" value="%d %-5p [%c] (%t)
%m%n"/>
+
+ <!-- The full pattern: Date MS Priority [Category] (Thread:NDC)
Message\n
+ <param name="ConversionPattern" value="%d %-5r %-5p [%c]
(%t:%x) %m%n"/>
+ -->
+ </layout>
+ </appender>
+
+ <!-- ============================== -->
+ <!-- Append messages to the console -->
+ <!-- ============================== -->
+
+ <appender name="CONSOLE"
class="org.apache.log4j.ConsoleAppender">
+ <param name="Target" value="System.out"/>
+ <param name="Threshold" value="INFO"/>
+
+ <layout class="org.apache.log4j.PatternLayout">
+ <!-- The default pattern: Date Priority [Category] Message\n -->
+ <param name="ConversionPattern" value="%d{ABSOLUTE} %-5p
[%c{1}] %m%n"/>
+ </layout>
+ </appender>
+
+ <!-- ================ -->
+ <!-- Limit categories -->
+ <!-- ================ -->
+
+ <!-- Limit the org.apache category to INFO as its DEBUG is verbose -->
+ <category name="org.apache">
+ <priority value="TRACE"/>
+ </category>
+ <category name="org.jboss">
+ <priority value="TRACE"/>
+ </category>
+
+ <!-- Setup the Root category -->
+ <!-- ======================= -->
+
+ <root>
+ <appender-ref ref="CONSOLE"/>
+ <appender-ref ref="FILE"/>
+ </root>
+
+</log4j:configuration>
+
+ </programlisting>
+ <tip>
+ <title>Location of the generated log file</title>
+ <para>
+ The generated log file will be server.log in the logs directory.
+ </para>
+ </tip>
+
+ </section> <!-- End: Logging Tomcat -->
+
+ <section> <!-- Logging JBoss -->
+ <title>Configuring logging in JBoss</title>
+ <para>
+ You can configure log4j in the conf directory of your JBoss server (default,
all etc)
+ </para>
+ <tip>
+ <para> Please refer to JBoss AS documentation on
logging.</para>
+ </tip>
+ </section><!-- End: Logging JBoss -->
+
+ </section> <!-- Configuring logging -->
+ </chapter>
+ </part>
+</book>
\ No newline at end of file