Author: bdaw
Date: 2007-03-05 12:24:31 -0500 (Mon, 05 Mar 2007)
New Revision: 6543
Modified:
docs/trunk/referenceGuide/en/modules/authentication.xml
docs/trunk/referenceGuide/en/modules/security.xml
Log:
addons for Authentication chapter
Modified: docs/trunk/referenceGuide/en/modules/authentication.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/authentication.xml 2007-03-05 17:04:16 UTC (rev
6542)
+++ docs/trunk/referenceGuide/en/modules/authentication.xml 2007-03-05 17:24:31 UTC (rev
6543)
@@ -11,6 +11,7 @@
<sect1 id="authentication_in_portal">
<title>Authentication in JBoss Portal</title>
<para>TODO</para>
+ <para>To understand authentication mechanisms in JBoss Portal better please
refer to <link
linkend="security.security_authentication">Security</link>
chapter</para>
<sect2 id="configuration">
<title>Configuration</title>
<para>You can configure JAAS authentication stack in
<emphasis>jboss-portal.sar/conf/login-config.xml</emphasis></para>
@@ -22,11 +23,83 @@
<para>JBoss Portal comes with few implementations of JAAS
<emphasis>LoginModule</emphasis> interface</para>
<sect2>
<title>org.jboss.portal.identity.auth.IdentityLoginModule</title>
- <para>TODO</para>
+ <para>This is standard portal LoginModule implementation, that use portal
identity modules to search for users and roles. By default it's the only
+ configured LoginModule in the portal authentication stack. Its behaviour can be
altered with following options:
+ <itemizedlist>
+ <listitem>
+ <emphasis
role="bold">userModuleJNDIName</emphasis> - JNDI name of portal
UserModule.
+ </listitem>
+ <listitem>
+ <emphasis
role="bold">roleModuleJNDIName</emphasis> - JNDI name of portal
RoleModule.
+ </listitem>
+ <listitem>
+ <emphasis
role="bold">membershipModuleJNDIName</emphasis> - JNDI name of portal
MembershipModule.
+ </listitem>
+ <listitem>
+ <emphasis role="bold">additionalRole</emphasis> -
additional user <emphasis>Principal</emphasis> that will be added to user
<emphasis>Subject</emphasis>.
+ This is important as in default portal configuration it is the role
that portal servlet is secured with.
+ </listitem>
+ <listitem>
+ <emphasis role="bold">havingRole</emphasis> -
only users belonging to role specified with this option will be authenticated.
+ </listitem>
+ <listitem>
+ <emphasis
role="bold">unauthenticatedIdentity</emphasis> - the principal to use
when a null username and password are seen.
+ </listitem>
+ </itemizedlist>
+ <note>IdentityLoginModule extends
org.jboss.security.auth.spi.UsernamePasswordLoginModule so if you are familiar with
JBossSX you can apply
+ few other options like "password-stacking". Please refer to JBossSX
documentation.</note>
+ </para>
</sect2>
<sect2>
<title>org.jboss.portal.identity.auth.DBIdentityLoginModule</title>
- <para>TODO</para>
+ <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
+ 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
+ <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=DatabaseServerLoginMod...
wiki page to learn more about
+ <emphasis>DatabaseServerLoginModule</emphasis>
configuration</para>
+ <para>
+ Options are:
+ <itemizedlist>
+ <listitem>
+ <emphasis role="bold">dsJndiName</emphasis> - The
name of the DataSource of the database containing the Principals and Roles tables
+ </listitem>
+ <listitem>
+ <emphasis role="bold">principalsQuery</emphasis>
- The prepared statement query, equivalent to: <emphasis>"select Password from
Principals where PrincipalID=?"</emphasis>
+ </listitem>
+ <listitem>
+ <emphasis role="bold">rolesQuery</emphasis> - The
prepared statement query, equivalent to: <emphasis>"select Role, RoleGroup from
Roles where PrincipalID=?"</emphasis>
+ </listitem>
+ <listitem>
+ <emphasis role="bold">hashAlgorithm</emphasis> -
The name of the <emphasis>java.security.MessageDigest</emphasis> algorithm to
use to hash the password.
+ There is no default so this option must be specified to enable hashing.
When hashAlgorithm is specified, the clear text password obtained from the
<emphasis>CallbackHandler</emphasis>
+ is hashed before it is passed to
UsernamePasswordLoginModule.validatePassword as the inputPassword argument. The
expectedPassword as stored in the users.properties
+ file must be comparably hashed.
+ </listitem>
+ <listitem>
+ <emphasis role="bold">hashEncoding</emphasis> -
The string format for the hashed pass and must be either "base64" or
"hex". Base64 is the default.
+ </listitem>
+ <listitem>
+ <emphasis role="bold">additionalRole</emphasis> -
additional user <emphasis>Principal</emphasis> that will be added to user
<emphasis>Subject</emphasis>.
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Configuration using portal database will look like this:
+ <programlisting>
+ <![CDATA[
+ <login-module code =
"org.jboss.portal.identity.auth.DBIdentityLoginModule"
flag="sufficient">
+ <module-option
name="dsJndiName">java:/PortalDS</module-option>
+ <module-option name="principalsQuery">SELECT
jbp_password FROM jbp_users WHERE jbp_uname=?</module-option>
+ <module-option name="rolesQuery">SELECT
jbp_roles.jbp_name, 'Roles' FROM jbp_role_membership INNER JOIN jbp_roles ON
jbp_role_membership.jbp_rid = jbp_roles.jbp_rid INNER JOIN jbp_users ON
jbp_role_membership.jbp_uid = jbp_users.jbp_uid WHERE
jbp_users.jbp_uname=?</module-option>
+ <module-option
name="hashAlgorithm">MD5</module-option>
+ <module-option
name="hashEncoding">HEX</module-option>
+ <module-option
name="additionalRole">Authenticated</module-option>
+ </login-module>
+ ]]>
+ </programlisting>
+ </para>
</sect2>
<sect2>
<title>org.jboss.portal.identity.auth.SynchronizingLdapLoginModule</title>
Modified: docs/trunk/referenceGuide/en/modules/security.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/security.xml 2007-03-05 17:04:16 UTC (rev 6542)
+++ docs/trunk/referenceGuide/en/modules/security.xml 2007-03-05 17:24:31 UTC (rev 6543)
@@ -112,7 +112,7 @@
</para>
</sect1>
- <sect1 id="security_authentication">
+ <sect1 id="security.security_authentication">
<title>Authentication with JBoss Portal</title>
<para>JBoss Portal relies on Java EE for the authentication of users. The
Java EE authentication has its advantages
and drawbacks. The main motivation for using Java EE security is the integration
with the application server and the