12:07 a.m.
Author: anil.saldhana(a)jboss.com
Date: 2009-02-02 01:07:32 -0500 (Mon, 02 Feb 2009)
New Revision: 270
Modified:
identity-federation/trunk/doc/DeveloperGuide/src/main/docbook/DeveloperGuide.xml
Log:
dev guide
Modified:
identity-federation/trunk/doc/DeveloperGuide/src/main/docbook/DeveloperGuide.xml
===================================================================
---
identity-federation/trunk/doc/DeveloperGuide/src/main/docbook/DeveloperGuide.xml 2009-01-30
22:38:30 UTC (rev 269)
+++
identity-federation/trunk/doc/DeveloperGuide/src/main/docbook/DeveloperGuide.xml 2009-02-02
06:07:32 UTC (rev 270)
@@ -3,7 +3,7 @@
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % RH-ENTITIES SYSTEM "Common_Config/rh-entities.ent">
]>
-<book>
+<book>
<bookinfo>
<title>JBoss Identity Federation</title>
@@ -19,7 +19,7 @@
</bookinfo>
<preface>
- <title>What this Book Covers</title>
+ <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
@@ -28,14 +28,12 @@
<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>
+ <para>Part II 'Developer Usage' takes a look at the API and Object
Model
+ available to you to create applications and services for your needs with
+ Federated Identity.
+ </para>
</preface>
-
+
<part>
<title>Getting Started</title>
@@ -44,10 +42,12 @@
<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>
+ applications.
+ </para>
<para>With JBoss Identity Federation, you have the following
- features.</para>
+ features.
+ </para>
<itemizedlist>
<listitem>
@@ -81,15 +81,12 @@
bindings using the object model provided in this product.</para>
</chapter>
- <chapter>
- <title>Simple Usage</title>
+ </part>
+
+ <part>
+ <title>Developer 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>
+ <chapter id="identity-api">
<title>Identity API for SAML v2</title>
<note>
<para>Use SAML2Request API class for creating SAML request
objects.</para>
@@ -149,326 +146,26 @@
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>
+ </chapter> <!-- End Section on Identity API Usage -->
+
+ <chapter id="jaxb-object-model"> <!-- Object Model -->
+ <title> JAXB2 Based Object Model for SAML and WS-Trust</title>
+ <para> JBoss Identity Federation contains an object model for SAMLv2 and
WS-Trust v1.3
+ applications. The object model is very useful for developers who want to build
advanced
+ applications that are not fully supported by the Identity API from the previous
section.
+ </para>
+ <tip>
+ <title>Object Model for SAML v2</title>
+ <para><emphasis
role="italic">org.jboss.identity.federation.saml.v2</emphasis> is
+ the package that contains the object model.</para>
+ </tip>
+ <tip>
+ <title>Object Model for WS-Trust v1.3</title>
+ <para><emphasis
role="italic">org.jboss.identity.federation.ws.trust</emphasis> is
+ the package that contains the object model.</para>
+ </tip>
+ </chapter>
</part>
+
+
</book>