3:39 p.m.
Author: anil.saldhana(a)jboss.com
Date: 2009-01-30 16:39:15 -0500 (Fri, 30 Jan 2009)
New Revision: 267
Added:
identity-federation/trunk/doc/DeveloperGuide/
identity-federation/trunk/doc/DeveloperGuide/pom.xml
identity-federation/trunk/doc/DeveloperGuide/src/
identity-federation/trunk/doc/DeveloperGuide/src/main/
identity-federation/trunk/doc/DeveloperGuide/src/main/docbook/
identity-federation/trunk/doc/DeveloperGuide/src/main/docbook/Author_Group.xml
identity-federation/trunk/doc/DeveloperGuide/src/main/docbook/DeveloperGuide.xml
identity-federation/trunk/doc/UserGuide/
identity-federation/trunk/doc/UserGuide/pom.xml
identity-federation/trunk/doc/UserGuide/src/
identity-federation/trunk/doc/UserGuide/src/main/
identity-federation/trunk/doc/UserGuide/src/main/docbook/
identity-federation/trunk/doc/UserGuide/src/main/docbook/Author_Group.xml
identity-federation/trunk/doc/UserGuide/src/main/docbook/UserGuide.xml
identity-federation/trunk/doc/UserGuide/src/main/docbook/images/
identity-federation/trunk/doc/UserGuide/src/main/docbook/images/HubNSpokeArchitecture.png
identity-federation/trunk/doc/pom.xml
Modified:
identity-federation/trunk/pom.xml
Log:
add the doc stuff
Added: identity-federation/trunk/doc/DeveloperGuide/pom.xml
===================================================================
--- identity-federation/trunk/doc/DeveloperGuide/pom.xml (rev 0)
+++ identity-federation/trunk/doc/DeveloperGuide/pom.xml 2009-01-30 21:39:15 UTC (rev
267)
@@ -0,0 +1,81 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>org.jboss.identity.federation</groupId>
+ <artifactId>Developer-Guide-${translation}</artifactId>
+ <version>1.0.0-SNAPSHOT</version>
+ <packaging>jdocbook</packaging>
+ <name>Developer Guide (${translation})</name>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jdocbook-plugin</artifactId>
+ <version>2.0.0</version>
+ <extensions>true</extensions>
+ <dependencies>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-docbook-xslt</artifactId>
+ <version>1.1.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-jdocbook-style</artifactId>
+ <version>1.1.0</version>
+ <type>jdocbook-style</type>
+ </dependency>
+ </dependencies>
+ <configuration>
+
<sourceDocumentName>DeveloperGuide.xml</sourceDocumentName>
+ <imageResource>
+ <directory>${basedir}/src/main/docbook</directory>
+ <includes>
+ <include>${basedir}/../images/*.png</include>
+ </includes>
+ </imageResource>
+ <!--<cssResource>
+ <directory>src/main/css</directory>
+ </cssResource>-->
+ <formats>
+ <format>
+ <formatName>pdf</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
+ <finalName>DeveloperGuide.pdf</finalName>
+ </format>
+ <format>
+ <formatName>html</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ <format>
+ <formatName>html_single</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ <format>
+ <formatName>eclipse</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/eclipse.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ </formats>
+ <options>
+ <xincludeSupported>true</xincludeSupported>
+ <xmlTransformerType>saxon</xmlTransformerType>
+ <!-- needed for uri-resolvers; can be ommitted if using
'current' uri scheme -->
+ <!-- could also locate the docbook dependency and inspect
its version... -->
+ <docbookVersion>1.72.0</docbookVersion>
+ </options>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+ <properties>
+ <translation>en-US</translation>
+ </properties>
+</project>
Added: identity-federation/trunk/doc/DeveloperGuide/src/main/docbook/Author_Group.xml
===================================================================
--- identity-federation/trunk/doc/DeveloperGuide/src/main/docbook/Author_Group.xml
(rev 0)
+++
identity-federation/trunk/doc/DeveloperGuide/src/main/docbook/Author_Group.xml 2009-01-30
21:39:15 UTC (rev 267)
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<authorgroup>
+ <corpauthor>Anil Saldhana</corpauthor>
+</authorgroup>
Added: identity-federation/trunk/doc/DeveloperGuide/src/main/docbook/DeveloperGuide.xml
===================================================================
--- identity-federation/trunk/doc/DeveloperGuide/src/main/docbook/DeveloperGuide.xml
(rev 0)
+++
identity-federation/trunk/doc/DeveloperGuide/src/main/docbook/DeveloperGuide.xml 2009-01-30
21:39:15 UTC (rev 267)
@@ -0,0 +1,474 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!ENTITY % RH-ENTITIES SYSTEM "Common_Config/rh-entities.ent">
+]>
+<book>
+ <bookinfo>
+ <title>JBoss Identity Federation</title>
+
+ <subtitle>Developer Guide</subtitle>
+
+ <xi:include href="Author_Group.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <releaseinfo>
+ 1.0.0.alpha1.
+ </releaseinfo>
+
+ </bookinfo>
+
+ <preface>
+ <title>What this Book Covers</title>
+
+ <para>This book aims to help you become familiar with JBoss Identity
+ Federation in order that you can use it to develop your own Federated
+ Identity based services or applications.</para>
+
+ <para>Part I 'Getting Started' introduces the federated identity
+ technologies that are provided in this product.</para>
+
+ <para>Part II 'Simple Usage' takes a look at the use cases that you
can
+ implement that meets majority of requirements.</para>
+
+ <para>Part III 'Advanced Usage' goes on to look at how you can add
+ advanced features to your use cases such as trust management and XML
+ Digital Signatures.</para>
+ </preface>
+
+ <part>
+ <title>Getting Started</title>
+
+ <chapter id="overview">
+ <title>Introduction</title>
+
+ <para>JBoss Identity Federation allows you to implement SAML v2.0 based
+ services and applications. It also has support for Oasis WS-Trust based
+ applications.</para>
+
+ <para>With JBoss Identity Federation, you have the following
+ features.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>SAML v2 and WS-Trust v1.3 Object Model.</para>
+ </listitem>
+
+ <listitem>
+ <para>SAML v2 Identity API.</para>
+ </listitem>
+
+ <listitem>
+ <para>SAML v2 HTTP/Redirect Binding Support for JBoss and
+ Tomcat.</para>
+ </listitem>
+
+ <listitem>
+ <para>SAML v2 HTTP/Redirect Binding Support for JBoss and Tomcat
+ with XML Signature Support.</para>
+ </listitem>
+
+ <listitem>
+ <para>WS-Trust Security Token Service (STS).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The SAML v2 specification provides multiple profiles and bindings.
+ In this version of the product, we provide support for web browser based
+ single sign on (SSO) via HTTP/Redirect Binding. </para>
+
+ <para>An user/developer is free to implement the other profiles and
+ bindings using the object model provided in this product.</para>
+ </chapter>
+
+ <chapter>
+ <title>Simple Usage</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
+ and Single Sign-On (SSO) for applications).</para>
+
+ <section>
+ <title>Identity API for SAML v2</title>
+ <note>
+ <para>Use SAML2Request API class for creating SAML request
objects.</para>
+ <para>Use SAML2Response API class for creating SAML response
objects.</para>
+ </note>
+ <para>The following examples displays usage of the API provided in
+ the Identity Federation product.
+ </para>
+ <para>The SAML2Request API class can be used to create SAML2 requests
+ and convert it into XML and back using the marshall or unmarshall methods.
+ </para>
+ <programlisting>
+ import org.jboss.identity.federation.api.saml.v2.request.SAML2Request;
+ import org.jboss.identity.federation.saml.v2.protocol.LogoutRequestType;
+
+ SAML2Request saml2Request = new SAML2Request();
+
+ //We will create an AuthnRequest
+ AuthnRequestType authnRequest = request.createAuthnRequestType(
+ id, "http://sp", "http://idp", "http://sp");
+
+ //Now marshall the request into a byte array based output stream
+ ByteArrayOutputStream baos = new ByteArrayOutputStream();
+ request.marshall(authnRequest, baos);
+ request.marshall(authnRequest, System.out); //To Console
+
+ //Assume that we have an inputstream where we get the SAML feed
+ InputStream is = new ByteArrayInputStream(baos.toCharArray());
+ authnRequest = saml2Request.unmarshall(is);
+
+ //We will create a log out request
+ LogoutRequestType lrt =
saml2Request.createLogoutRequest("http://idp");
+ </programlisting>
+ <para>SAML2Response API class can be used to create SAML2 response objects
+ as well as marshall and unmarshall to xml and back.
+ </para>
+ <programlisting>
+ import org.jboss.identity.federation.api.saml.v2.request.SAML2Response;
+
+ SAML2Response saml2Response = new SAML2Response();
+ saml2Response.createTimedConditions(assertion, this.assertionValidity)
+
+ //IssuerInfoHolder is a class for information on the Issuer of SAML Assertions
+ IssuerInfoHolder issuerHolder = new IssuerInfoHolder("http://idp");
+ issuerHolder.setStatusCode(JBossSAMLURIConstants.STATUS_SUCCESS.get());
+
+ //IDPInfoHolder is a class for information on the Identity Provider
+ IDPInfoHolder idp = new IDPInfoHolder();
+ idp.setNameIDFormatValue(IDGenerator.create());
+
+ //SPInfoHolder is a class for information on the Service Provider
+
+ ResponseType rt = JBossSAMLAuthnResponseFactory.createResponseType(
+ "response111",
+ new SPInfoHolder(), idp, issuerHolder);
+
+ ByteArrayOutputStream baos = new ByteArrayOutputStream();
+ saml2Response.marshall(rt, baos);
+ </programlisting>
+ </section>
+
+ <section> <!-- Section: SAML HTTP/Redirect Binding -->
+ <title>SAML v2 HTTP/Redirect Binding</title>
+ <para>This section will talk about the configuration information to
+ support the HTTP/Redirect binding which will provide centralized
+ identity services as well as web SSO for your applications.
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="../../../../images/HubNSpokeArchitecture.png" format="PNG"
+ contentwidth="6in" contentdepth="6in"/>
+ </imageobject>
+ <caption align="right">
+ <para>
+ <emphasis role="bold">Hub and Spoke Architecture for the
SAML v2 based Web SSO</emphasis>
+ </para>
+ </caption>
+ </mediaobject>
+ <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.
+ </para>
+ </note>
+
+
+ <section><!-- Section on configuring the Identity Provider -->
+ <title>Configuring the Identity Provider (IDP) </title>
+
+ <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>
+
+ <para>The IDP can be a JBoss Application Server or a Tomcat instance.
+ </para>
+ <para>
+ You need to configure a web application as the Identity provider.
+ </para>
+
+
+ <section><!-- Section on configuring web app security -->
+ <title>Configure the web application security for the IDP</title>
+ <para>The web application needs to have FORM or BASIC based security
enabled in its web.xml.
+ We recommend the use of FORM based web application security as it gives you
the ability to
+ customize the login page.</para>
+ <para>The web.xml needs to have a configuration such as the following:
+ </para>
+ <programlisting role="XML">
+ <?xml version="1.0" encoding="ISO-8859-1"?>
+<web-app xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
+ version="2.5">
+
+ <display-name>IDP</display-name>
+ <description>IDP</description>
+
+ <!-- Define a security constraint that gives unlimited access to images
-->
+ <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>Images</web-resource-name>
+ <url-pattern>/images/*</url-pattern>
+ </web-resource-collection>
+ </security-constraint>
+
+ <!-- Define a Security Constraint on this Application -->
+ <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>IDP</web-resource-name>
+ <url-pattern>/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>manager</role-name>
+ </auth-constraint>
+ </security-constraint>
+
+ <!-- Define the Login Configuration for this Application -->
+ <login-config>
+ <auth-method>FORM</auth-method>
+ <realm-name>IDP Application</realm-name>
+ <form-login-config>
+ <form-login-page>/jsp/login.jsp</form-login-page>
+
<form-error-page>/jsp/loginerror.jsp</form-error-page>
+ </form-login-config>
+ </login-config>
+
+ <!-- Security roles referenced by this web application -->
+ <security-role>
+ <description>
+ The role that is required to log in to the IDP Application
+ </description>
+ <role-name>manager</role-name>
+ </security-role>
+</web-app>
+ </programlisting>
+
+
+ <note>
+ <para> Remember to configure the realm or login modules for your IDP as
per the Tomcat or
+ JBoss AS documentation on "securing your web application".
+ </para>
+ <ulink
url="http://tomcat.apache.org/tomcat-6.0-doc/realm-howto.html"&...
Realm</ulink>
+ and
+ <ulink url="http://jboss.org/community/docs/DOC-10760">JBoss
AS Security</ulink>
+ </note>
+
+
+ </section> <!-- Section on configuring web app security - IDP -->
+
+
+ <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.IDPRedirectValve"
+ />
+ </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</IdentityURL>
+ </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>
+ </section><!-- End Section: Configure IDFed Config File - IDP -->
+
+ </section> <!-- End Section on configuring the Identity Provider -->
+
+
+ <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><!-- Section on configuring web app security -->
+ <title>Configure the web application security for the SP</title>
+ <para>The web application needs to have FORM based security enabled in
its web.xml.
+ </para>
+ <para>The web.xml needs to have a configuration such as the following:
+ </para>
+
+ <programlisting role="XML">
+
+ <?xml version="1.0" encoding="ISO-8859-1"?>
+<web-app xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
+ version="2.5">
+
+ <display-name>Test SALES Application</display-name>
+ <description>
+ Just a Test SP
+ </description>
+
+ <!-- Define a Security Constraint on this Application -->
+ <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>SALES
Application</web-resource-name>
+ <url-pattern>/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>manager</role-name>
+ </auth-constraint>
+ </security-constraint>
+
+ <!-- Define a security constraint that gives unlimted access to freezone
-->
+ <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>freezone</web-resource-name>
+ <url-pattern>/freezone/*</url-pattern>
+ </web-resource-collection>
+ </security-constraint>
+
+ <!-- Define the Login Configuration for this Application -->
+ <login-config>
+ <auth-method>FORM</auth-method>
+ <realm-name>Tomcat SALES Application</realm-name>
+ <form-login-config>
+ <form-login-page>/jsp/login.jsp</form-login-page>
+
<form-error-page>/jsp/loginerror.jsp</form-error-page>
+ </form-login-config>
+ </login-config>
+
+ <!-- Security roles referenced by this web application -->
+ <security-role>
+ <description>
+ The role that is required to log in to the SP Application
+ </description>
+ <role-name>manager</role-name>
+ </security-role>
+</web-app>
+
+ </programlisting>
+
+ <warning>
+ <para>
+ The SP web application should be configured with FORM based authentication.
+ </para>
+ </warning>
+
+ </section> <!-- Section on configuring web app security - SP -->
+
+
+ <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.SPRedirectFormAuthenticator"
+ />
+ </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 - SP -->
+ <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
+ SP web application</para>
+
+ <programlisting role="xml">
+
+ <JBossSP
xmlns="urn:jboss:identity-federation:config:1.0">
+
<IdentityURL>http://localhost:8080/idp</IdentityURL>
+
<ServiceURL>http://localhost:8080/sales</ServiceURL>
+ </JBossSP>
+
+ </programlisting>
+
+ <para>
+ In this configuration file, we define the URLs for the service provider and
+ the identity provider.
+ </para>
+ </section><!-- End Section: Configure IDFed Config File - SP -->
+
+ </section><!-- End Section:configure the SP -->
+
+ </section><!-- End Section: SAML HTTP/Redirect Binding -->
+ </chapter>
+ </part>
+</book>
Added: identity-federation/trunk/doc/UserGuide/pom.xml
===================================================================
--- identity-federation/trunk/doc/UserGuide/pom.xml (rev 0)
+++ identity-federation/trunk/doc/UserGuide/pom.xml 2009-01-30 21:39:15 UTC (rev 267)
@@ -0,0 +1,81 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>org.jboss.identity.federation</groupId>
+ <artifactId>User-Guide-${translation}</artifactId>
+ <version>1.0.0-SNAPSHOT</version>
+ <packaging>jdocbook</packaging>
+ <name>User Guide (${translation})</name>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jdocbook-plugin</artifactId>
+ <version>2.0.0</version>
+ <extensions>true</extensions>
+ <dependencies>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-docbook-xslt</artifactId>
+ <version>1.1.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-jdocbook-style</artifactId>
+ <version>1.1.0</version>
+ <type>jdocbook-style</type>
+ </dependency>
+ </dependencies>
+ <configuration>
+ <sourceDocumentName>UserGuide.xml</sourceDocumentName>
+ <imageResource>
+ <directory>${basedir}/src/main/docbook</directory>
+ <includes>
+ <include>${basedir}/../images/*.png</include>
+ </includes>
+ </imageResource>
+ <!--<cssResource>
+ <directory>src/main/css</directory>
+ </cssResource>-->
+ <formats>
+ <format>
+ <formatName>pdf</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
+ <finalName>UserGuide.pdf</finalName>
+ </format>
+ <format>
+ <formatName>html</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ <format>
+ <formatName>html_single</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ <format>
+ <formatName>eclipse</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/eclipse.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ </formats>
+ <options>
+ <xincludeSupported>true</xincludeSupported>
+ <xmlTransformerType>saxon</xmlTransformerType>
+ <!-- needed for uri-resolvers; can be ommitted if using
'current' uri scheme -->
+ <!-- could also locate the docbook dependency and inspect
its version... -->
+ <docbookVersion>1.72.0</docbookVersion>
+ </options>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+ <properties>
+ <translation>en-US</translation>
+ </properties>
+</project>
Added: identity-federation/trunk/doc/UserGuide/src/main/docbook/Author_Group.xml
===================================================================
--- identity-federation/trunk/doc/UserGuide/src/main/docbook/Author_Group.xml
(rev 0)
+++ identity-federation/trunk/doc/UserGuide/src/main/docbook/Author_Group.xml 2009-01-30
21:39:15 UTC (rev 267)
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<authorgroup>
+ <corpauthor>Anil Saldhana</corpauthor>
+</authorgroup>
Added: identity-federation/trunk/doc/UserGuide/src/main/docbook/UserGuide.xml
===================================================================
--- identity-federation/trunk/doc/UserGuide/src/main/docbook/UserGuide.xml
(rev 0)
+++ identity-federation/trunk/doc/UserGuide/src/main/docbook/UserGuide.xml 2009-01-30
21:39:15 UTC (rev 267)
@@ -0,0 +1,397 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!ENTITY % RH-ENTITIES SYSTEM "Common_Config/rh-entities.ent">
+]>
+<book>
+ <bookinfo>
+ <title>JBoss Identity Federation</title>
+
+ <subtitle>User Guide</subtitle>
+
+ <xi:include href="Author_Group.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <releaseinfo>
+ 1.0.0.alpha1.
+ </releaseinfo>
+
+
+ </bookinfo>
+
+ <preface>
+ <title>What this Book Covers</title>
+
+ <para>This book aims to help you become familiar with JBoss Identity
+ Federation in order that you can use it to build your own Federated
+ Identity based services or applications.</para>
+
+ <para>Part I 'Getting Started' introduces the federated identity
+ technologies that are provided in this product.</para>
+
+ <para>Part II 'Simple Usage' describes SAML v2 Web Browser based
+ Single Sign On (SSO).</para>
+
+ <para>Part III 'Advanced Usage' describes SAML v2 Web Browser based SSO
+ with advanced features such as Trust Management and XML
+ Digital Signatures.</para>
+ </preface>
+
+ <part>
+ <title>Getting Started</title>
+
+ <chapter id="overview">
+ <title>Introduction</title>
+
+ <para>JBoss Identity Federation allows you to implement SAML v2.0 based
+ services and applications. It also has support for Oasis WS-Trust based
+ applications (which is under development).</para>
+
+ <para>With JBoss Identity Federation, you have the following
+ features.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>SAML v2 Web Browser SSO (HTTP/Redirect Binding) Support for
+ JBoss Application Server and Apache Tomcat.</para>
+ </listitem>
+
+ <listitem>
+ <para>SAML v2 Web Browser SSO (HTTP/Redirect Binding) Support for
+ JBoss Application Server and Apache Tomcat
+ with XML Signature Support.</para>
+ </listitem>
+ </itemizedlist>
+
+ </chapter>
+
+ <chapter>
+ <title>Simple Usage</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
+ and Single Sign-On (SSO) for applications).</para>
+
+ <section> <!-- Section: SAML HTTP/Redirect Binding -->
+ <title>SAML v2 based Web SSO</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.
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="../../../../images/HubNSpokeArchitecture.png" format="PNG"
+ contentwidth="6in" contentdepth="6in"/>
+ </imageobject>
+ <caption align="right">
+ <para>
+ <emphasis role="bold">Hub and Spoke Architecture for the
SAML v2 based Web SSO</emphasis>
+ </para>
+ </caption>
+ </mediaobject>
+ <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.
+ </para>
+ </note>
+
+
+ <section><!-- Section on configuring the Identity Provider -->
+ <title>Configuring the Identity Provider (IDP) </title>
+
+ <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>
+
+ <para>The IDP can be a JBoss Application Server or a Tomcat instance.
+ </para>
+ <para>
+ You need to configure a web application as the Identity provider.
+ </para>
+
+
+ <section><!-- Section on configuring web app security -->
+ <title>Configure the web application security for the IDP</title>
+ <para>The web application needs to have FORM or BASIC based security
enabled in its web.xml.
+ We recommend the use of FORM based web application security as it gives you
the ability to
+ customize the login page.</para>
+ <para>The web.xml needs to have a configuration such as the following:
+ </para>
+ <programlisting role="XML">
+ <?xml version="1.0" encoding="ISO-8859-1"?>
+<web-app xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
+ version="2.5">
+
+ <display-name>IDP</display-name>
+ <description>IDP</description>
+
+ <!-- Define a security constraint that gives unlimited access to images
-->
+ <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>Images</web-resource-name>
+ <url-pattern>/images/*</url-pattern>
+ </web-resource-collection>
+ </security-constraint>
+
+ <!-- Define a Security Constraint on this Application -->
+ <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>IDP</web-resource-name>
+ <url-pattern>/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>manager</role-name>
+ </auth-constraint>
+ </security-constraint>
+
+ <!-- Define the Login Configuration for this Application -->
+ <login-config>
+ <auth-method>FORM</auth-method>
+ <realm-name>IDP Application</realm-name>
+ <form-login-config>
+ <form-login-page>/jsp/login.jsp</form-login-page>
+
<form-error-page>/jsp/loginerror.jsp</form-error-page>
+ </form-login-config>
+ </login-config>
+
+ <!-- Security roles referenced by this web application -->
+ <security-role>
+ <description>
+ The role that is required to log in to the IDP Application
+ </description>
+ <role-name>manager</role-name>
+ </security-role>
+</web-app>
+ </programlisting>
+
+
+ <note>
+ <para> Remember to configure the realm or login modules for your IDP as
per the Tomcat or
+ JBoss AS documentation on "securing your web application".
+ </para>
+ <ulink
url="http://tomcat.apache.org/tomcat-6.0-doc/realm-howto.html"&...
Realm</ulink>
+ and
+ <ulink url="http://jboss.org/community/docs/DOC-10760">JBoss
AS Security</ulink>
+ </note>
+
+
+ </section> <!-- Section on configuring web app security - IDP -->
+
+
+ <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.IDPRedirectValve"
+ />
+ </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</IdentityURL>
+ </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>
+ </section><!-- End Section: Configure IDFed Config File - IDP -->
+
+ </section> <!-- End Section on configuring the Identity Provider -->
+
+
+ <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><!-- Section on configuring web app security -->
+ <title>Configure the web application security for the SP</title>
+ <para>The web application needs to have FORM based security enabled in
its web.xml.
+ </para>
+ <para>The web.xml needs to have a configuration such as the following:
+ </para>
+
+ <programlisting role="XML">
+
+ <?xml version="1.0" encoding="ISO-8859-1"?>
+<web-app xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
+ version="2.5">
+
+ <display-name>Test SALES Application</display-name>
+ <description>
+ Just a Test SP
+ </description>
+
+ <!-- Define a Security Constraint on this Application -->
+ <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>SALES
Application</web-resource-name>
+ <url-pattern>/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>manager</role-name>
+ </auth-constraint>
+ </security-constraint>
+
+ <!-- Define a security constraint that gives unlimted access to freezone
-->
+ <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>freezone</web-resource-name>
+ <url-pattern>/freezone/*</url-pattern>
+ </web-resource-collection>
+ </security-constraint>
+
+ <!-- Define the Login Configuration for this Application -->
+ <login-config>
+ <auth-method>FORM</auth-method>
+ <realm-name>Tomcat SALES Application</realm-name>
+ <form-login-config>
+ <form-login-page>/jsp/login.jsp</form-login-page>
+
<form-error-page>/jsp/loginerror.jsp</form-error-page>
+ </form-login-config>
+ </login-config>
+
+ <!-- Security roles referenced by this web application -->
+ <security-role>
+ <description>
+ The role that is required to log in to the SP Application
+ </description>
+ <role-name>manager</role-name>
+ </security-role>
+</web-app>
+
+ </programlisting>
+
+ <warning>
+ <para>
+ The SP web application should be configured with FORM based authentication.
+ </para>
+ </warning>
+
+ </section> <!-- Section on configuring web app security - SP -->
+
+
+ <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.SPRedirectFormAuthenticator"
+ />
+ </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 - SP -->
+ <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
+ SP web application</para>
+
+ <programlisting role="xml">
+
+ <JBossSP
xmlns="urn:jboss:identity-federation:config:1.0">
+
<IdentityURL>http://localhost:8080/idp</IdentityURL>
+
<ServiceURL>http://localhost:8080/sales</ServiceURL>
+ </JBossSP>
+
+ </programlisting>
+
+ <para>
+ In this configuration file, we define the URLs for the service provider and
+ the identity provider.
+ </para>
+ </section><!-- End Section: Configure IDFed Config File - SP -->
+
+ </section><!-- End Section:configure the SP -->
+
+ </section><!-- End Section: SAML HTTP/Redirect Binding -->
+ </chapter>
+ </part>
+</book>
Added:
identity-federation/trunk/doc/UserGuide/src/main/docbook/images/HubNSpokeArchitecture.png
===================================================================
(Binary files differ)
Property changes on:
identity-federation/trunk/doc/UserGuide/src/main/docbook/images/HubNSpokeArchitecture.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: identity-federation/trunk/doc/pom.xml
===================================================================
--- identity-federation/trunk/doc/pom.xml (rev 0)
+++ identity-federation/trunk/doc/pom.xml 2009-01-30 21:39:15 UTC (rev 267)
@@ -0,0 +1,20 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd">
+ <parent>
+ <groupId>org.jboss.identity</groupId>
+ <artifactId>jboss-identity-fed-parent</artifactId>
+ <version>1.0.0-SNAPSHOT</version>
+ <relativePath>../parent</relativePath>
+ </parent>
+
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.jboss.identity.federation.docs</groupId>
+ <artifactId>jboss-identity-federation-docs</artifactId>
+ <packaging>pom</packaging>
+ <name>JBoss Identity Federation Docs</name>
+ <url>http://www.jboss.com/products/jbossidentity</url>
+ <description>JBoss Identity Federation Documentation</description>
+ <modules>
+ <module>UserGuide</module>
+ <module>DeveloperGuide</module>
+ </modules>
+</project>
Modified: identity-federation/trunk/pom.xml
===================================================================
--- identity-federation/trunk/pom.xml 2009-01-30 21:20:07 UTC (rev 266)
+++ identity-federation/trunk/pom.xml 2009-01-30 21:39:15 UTC (rev 267)
@@ -20,6 +20,7 @@
<module>identity-fed-core</module>
<module>identity-fed-api</module>
<module>identity-bindings</module>
+ <module>doc</module>
<module>assembly</module>
</modules>
</project>