Author: bdaw
Date: 2007-03-13 09:19:38 -0400 (Tue, 13 Mar 2007)
New Revision: 6652
Modified:
docs/trunk/referenceGuide/en/modules/authentication.xml
docs/trunk/referenceGuide/en/modules/identity.xml
docs/trunk/referenceGuide/en/modules/ldap.xml
docs/trunk/referenceGuide/en/modules/sso.xml
Log:
some typos and tomcat sso howto
Modified: docs/trunk/referenceGuide/en/modules/authentication.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/authentication.xml 2007-03-13 11:45:23 UTC (rev
6651)
+++ docs/trunk/referenceGuide/en/modules/authentication.xml 2007-03-13 13:19:38 UTC (rev
6652)
@@ -53,7 +53,7 @@
<sect2>
<title>org.jboss.portal.identity.auth.DBIdentityLoginModule</title>
<para>This <emphasis>LoginModule</emphasis> implementation
extends JBossSX
<emphasis>org.jboss.security.auth.spi.DatabaseServerLoginModule</emphasis> and
can be
- used to authenicate against Database. The main purpose of this module is to be
configured directly against portal database (instead of using portal identity
+ used to authenticate against Database. The main purpose of this module is to be
configured directly against portal database (instead of using portal identity
modules like in IdentityLoginModule). So if you are using custom LoginModule
implementation you can place this module with "sufficient" flag. This can
be extremely useful. For example if you authenticate against LDAP server using
JBossSX <emphasis>LdapLoginModule</emphasis> you can
fallback to users present in portal database and not present in LDAP like
"admin" user. Please look into
Modified: docs/trunk/referenceGuide/en/modules/identity.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/identity.xml 2007-03-13 11:45:23 UTC (rev 6651)
+++ docs/trunk/referenceGuide/en/modules/identity.xml 2007-03-13 13:19:38 UTC (rev 6652)
@@ -373,11 +373,11 @@
<title>Identity configuration</title>
<para>At the beginning to understand identity configuration you need to
understand how it is designed to work in portal.
Different identity services like UserModule, RoleModule and etc are just plain
java classes that are instantiated and exposed
- by portal. So *example* UserModule service could be plain java bean object tha
will be:
+ by portal. So *example* UserModule service could be plain java bean object that
will be:
<itemizedlist>
- <listitem><emphasis
role="bold">Instantiated</emphasis> using relfection</listitem>
+ <listitem><emphasis
role="bold">Instantiated</emphasis> using reflection</listitem>
<listitem><emphasis
role="bold">Initialized/Started</emphasis> by invoking some
methods</listitem>
- <listitem><emphasis
role="bold">Registered/Exposed</emphasis> using JNDI and/or mbeans
(JBoss Mikrokernel) services, so
+ <listitem><emphasis
role="bold">Registered/Exposed</emphasis> using JNDI and/or mbeans
(JBoss Microkernel) services, so
other citizens of the portal can use it</listitem>
<listitem><emphasis
role="bold">Managed</emphasis> in the matter of lifecycle - so
it'll be stopped and unregistered during
portal shutdown</listitem>
@@ -387,11 +387,11 @@
custom ones - look on the methods that are leveraged by this
framework.</note>
</para>
<para>
- In JBoss Portal we provide very flexible configuration. It's very easy to
rearange and customize services,
+ In JBoss Portal we provide very flexible configuration. It's very easy to
rearrange and customize services,
provide and plug in own implementations, extend current ones or extend identity
model with own solutions using
provided configuration service.
</para>
- <para>To have the complete picture of the configuration of identity services
let's start from it's root
+ <para>To have the complete picture of the configuration of identity services
lets start from it's root
component. Whole configuration and setup of identity components is made by
<emphasis
role="bold">IdentityServiceController</emphasis>. It brings to life and
registers all other components
like UserModule, RoleModule, MembershipModule and UserProfileModule.
@@ -434,7 +434,7 @@
<emphasis
role="bold">DefaultConfigFile</emphasis> - defines location of
configuration file containing
default values. For each component defined in <emphasis
role="bold">ConfigFile</emphasis> IdentityServiceController
will look into this location to grab set of default options. This
simply makes the main configuration file
- simpler and shorter while still enabling more powerfull customization.
+ simpler and shorter while still enabling more powerful customization.
</para>
</listitem>
</itemizedlist>
@@ -470,7 +470,7 @@
<title>Datasources</title>
<para>This section defines datasource components. They will be
processed and instantiated before components in
<emphasis role="bold">Module</emphasis> section, so
they will be ready to serve them.</para>
- <note>This section isn't used whith Database configuration as in
JBoss Portal services exposing Hibernate
+ <note>This section isn't used with Database configuration as in
JBoss Portal services exposing Hibernate
are defined separately. It's used by LDAP configuration and we'll use
it as an example</note>
<programlisting><![CDATA[
<datasource>
@@ -502,7 +502,7 @@
<note>If you look into JBoss Portal configuration files you will find
that <![CDATA[<service-name/> and <class/>]]>
are specified in <emphasis
role="bold">DefaultConfigFile</emphasis> and not in <emphasis
role="bold">ConfigFile</emphasis>.
So this is how it works. Those two will be picked up from default
configuration. The same rule takes place
- for options - additional will be picked up from default configuration. Whats
linking configuration in those two files
+ for options - additional will be picked up from default configuration. What
is linking configuration in those two files
is the <emphasis
role="bold"><![CDATA[<name>]]></emphasis>
tag.</note>
</sect3>
<sect3>
@@ -525,7 +525,7 @@
<value>java:/portal/IdentitySessionFactory</value>
</option>
<option>
- <name>jndiName</name>
+ <name>jNDIName</name>
<value>java:/portal/UserModule</value>
</option>
</config>
@@ -583,7 +583,7 @@
<sect3>
<title>Options</title>
<para>This section provides common options that are accessible by
identity modules. We put here options
- that may need to be shared. They are groupped, and can have many
values:</para>
+ that may need to be shared. They are grouped, and can have many
values:</para>
<programlisting><![CDATA[
<options>
<!--Common options section-->
@@ -730,9 +730,9 @@
</properties>
]]>
</programlisting>
- Configuration file contains properties definition that can be retreived using
<emphasis role="bold">PropertyInfo</emphasis> interface.
+ Configuration file contains properties definition that can be retrieved using
<emphasis role="bold">PropertyInfo</emphasis> interface.
Every property that will be used in portal need to be registered here.
- <note>Some informations provided for property have big influence on the
behaviour of UserProfileModule. For example
+ <note>Some information provided for property have big influence on the
behaviour of UserProfileModule. For example
<emphasis>access-mode</emphasis> can made property read-only, and
value provided in <emphasis>type</emphasis> will be checked
during <emphasis>setProperty()/getProperty()</emphasis> operations.
On the other hand tags like <emphasis>usage</emphasis>,
<emphasis>description</emphasis> or
<emphasis>display-name</emphasis> have mostly informational meaning at the
moment</note>
@@ -766,7 +766,7 @@
<note>In current implementation
<emphasis>column</emphasis> and <emphasis>dynamic</emphasis>
mappings have the same effect, as database mappings are defined
in hibernate configuration.</note>
<note>Property can have both <emphasis>ldap</emphasis>
and <emphasis>database</emphasis> mappings. In such situation when LDAP
support is enabled <emphasis>ldap</emphasis> mapping will take precedense.
- Also even when using ldap some properties will be mapped to ldap and some
to database. Its because LDAP schema doesn't support all attributes proper
+ Also even when using LDAP some properties will be mapped to LDAP and some
to database. Its because LDAP schema doesn't support all attributes proper
to for portal properties. To solve this we have <emphasis
role="bold">DelegatingUserProfileModuleImpl</emphasis> that will
delegate method invocation to
<emphasis>ldap</emphasis> or
<emphasis>database</emphasis> related
<emphasis>UserProfile</emphasis> module. When
<emphasis>LDAP</emphasis> support is enabled and
property need to be stored in database user will be synchronized into
database when needed. This behaviour can be configured.</note>
@@ -808,7 +808,7 @@
<emphasis>sessionFactoryJNDIName</emphasis> - JNDI name
under which hibernate SessionFactory object is registered
</listitem>
<listitem>
- <emphasis>jndiName</emphasis> - JNDI name under which this
module should be registered
+ <emphasis>jNDIName</emphasis> - JNDI name under which this
module should be registered
</listitem>
</itemizedlist>
</para>
@@ -836,7 +836,7 @@
<!--set of options that are set in instantiated object-->
<config>
<option>
- <name>jndiName</name>
+ <name>jNDIName</name>
<value>java:/portal/UserProfileModule</value>
</option>
<option>
Modified: docs/trunk/referenceGuide/en/modules/ldap.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/ldap.xml 2007-03-13 11:45:23 UTC (rev 6651)
+++ docs/trunk/referenceGuide/en/modules/ldap.xml 2007-03-13 13:19:38 UTC (rev 6652)
@@ -157,7 +157,7 @@
<para>For all modules you can set two config options:
<itemizedlist>
<listitem>
- <emphasis role="bold">jndiName</emphasis> - JNDI
name under which this module will be registered
+ <emphasis role="bold">jNDIName</emphasis> - JNDI
name under which this module will be registered
</listitem>
<listitem>
<emphasis
role="bold">connectionJNDIName</emphasis> - JNDI name under which LDAP
datasource is registered
Modified: docs/trunk/referenceGuide/en/modules/sso.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/sso.xml 2007-03-13 11:45:23 UTC (rev 6651)
+++ docs/trunk/referenceGuide/en/modules/sso.xml 2007-03-13 13:19:38 UTC (rev 6652)
@@ -10,11 +10,142 @@
<para>This chapter describes how to setup SSO in JBoss Portal</para>
<sect1>
<title>Overview of SSO in portal</title>
- <para>TODO:</para>
+ <para>Portal as an integration and aggregation platform provides some form
of SSO by itself. When you log into
+ portal you gain access to many systems accessed with portlets using single
identity. Still in many cases you
+ need to integrate portal infrastructure with other SSO enabled systems. There are
many different Identity Management
+ solutions on the market. In most cases each SSO framework provides its own way to
plug into JEE application. For custom configurations
+ you need to have good understanding of <link
linkend="identity">JBoss Portal Identity management</link> and <link
linkend="authentication">authentication</link>
+ mechanisms.</para>
</sect1>
<sect1>
<title>Using Tomcat Valve</title>
- <para>TODO:</para>
+ <para>JBoss Application Server embeds Apache Tomcat as default servlet
container. Tomcat provides builtin SSO support
+ using a valve. The Single Sign On Valve caches credentials on the server side, and
then invisibly authenticate users when they
+ reach different web applications. Credentials are stored in a host-wide session
which means that SSO will be effective throughout the session.
+ </para>
+ <note>Below we will describe configuration using <emphasis>JBoss
Application Server 4.0.5</emphasis>. For different versions it can be slightly
different.</note>
+ <sect2>
+ <title>Enabling Tomcat SSO Valve</title>
+ <para>
+ To enable SSO valve in Tomcat you should edit
<emphasis>$JBOSS_HOME/server/default/deploy/jbossweb-tomcat55.sar/server.xml</emphasis>
file and uncomment
+ following line:
+ <programlisting>
+ <![CDATA[
+ <Valve
className=’org.apache.catalina.authenticator.SingleSignOn’/>
+ ]]>
+ </programlisting>
+ </para>
+ </sect2>
+ <sect2>
+ <title>Example usage</title>
+ <para>
+ Lets look a little bit closer and configure SSO between portal and other web
application. As an example
+ we'll use <emphasis>jmx-console</emphasis> web-app that comes
with every JBoss Application Server installation.
+ You can find more information on how to secure
<emphasis>jmx-console</emphasis> in <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=SecureTheJmxConsole&qu... AS
wiki</ulink>.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>Take a clean install of <emphasis>JBoss Application
Server 4.0.5.GA</emphasis></para>
+ </listitem>
+ <listitem>
+ <para>Edit
<emphasis>$JBOSS_HOME/server/default/deploy/jmx-console.war/WEB-INF/web.xml</emphasis>
file and make sure it contains following content:</para>
+ <programlisting>
+ <![CDATA[
+ <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>HtmlAdaptor</web-resource-name>
+ <description>An example security config that only allows users with the
+ role JBossAdmin to access the HTML JMX console web application
+ </description>
+ <url-pattern>/*</url-pattern>
+ <http-method>GET</http-method>
+ <http-method>POST</http-method>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>Admin</role-name>
+ </auth-constraint>
+ </security-constraint>
+ <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>Public</web-resource-name>
+ <url-pattern>/public/*</url-pattern>
+ <http-method>GET</http-method>
+ <http-method>POST</http-method>
+ </web-resource-collection>
+ </security-constraint>
+
+ <login-config>
+ <auth-method>BASIC</auth-method>
+ <realm-name>jmx-console</realm-name>
+ </login-config>
+
+
+ <security-role>
+ <role-name>Admin</role-name>
+ </security-role>
+ ]]>
+ </programlisting>
+ <para>This will secure <emphasis>jmx-console</emphasis>
web application using BASIC browser authentication and restrict access for
+ users with <emphasis>Admin</emphasis> role only.</para>
+ </listitem>
+ <listitem>
+ <para>
+ Edit
<emphasis>$JBOSS_HOME/server/default/conf/props/jmx-console-roles.properties</emphasis>
file and make it contain:
+ </para>
+ <programlisting>
+ <![CDATA[
+ admin=JBossAdmin,HttpInvoker,Admin
+ ]]>
+ </programlisting>
+ <para>
+ This file is a simple identity store for this web application
authentication. It will make user <emphasis>admin</emphasis> belongs to
<emphasis>Admin</emphasis> role.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Deploy JBoss Portal</para>
+ </listitem>
+ <listitem>
+ <para>Run JBoss Application Server</para>
+ </listitem>
+ <listitem>
+ <para>Now you can check that when you go to
+ <itemizedlist>
+ <listitem>
+ <emphasis>http://localhost:8080/portal</emphasis>
+ </listitem>
+ <listitem>
+
<emphasis>http://localhost:8080/jmx-console</emphasis>
+ </listitem>
+ </itemizedlist>
+ you need to authenticate separately into each of those web
applications.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Shutdown Application Server</para>
+ </listitem>
+ <listitem>
+ <para>
+ Edit
<emphasis>$JBOSS_HOME/server/default/deploy/jbossweb-tomcat55.sar/server.xml</emphasis>
file and uncomment
+ following line:
+ <programlisting>
+ <![CDATA[
+ <Valve
className=’org.apache.catalina.authenticator.SingleSignOn’/>
+ ]]>
+ </programlisting>
+ </para>
+ <para>
+ Run JBoss Application Server.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ Now if you log into portal as user <emphasis>admin</emphasis>
with password <emphasis>admin</emphasis>, you won't
+ be asked for credentials when accessing
<emphasis>jmx-console</emphasis>. This should work in both directions.
+ </para>
+ <note>Please note that in this example
<emphasis>jmx-console</emphasis> uses <emphasis>BASIC</emphasis>
authentication method.
+ This means that user credentials are cached on the client side by browser and
passed on each request. Once authenticated to clear
+ authentication cache you may need to restart browser.</note>
+ </sect2>
</sect1>
<sect1>
<title>Using external authentication providers</title>