[jboss-cvs] JBossAS SVN: r85659 - in projects/docs/enterprise: 4.3.5/Server_Configuration_Guide/en-US and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Mar 9 23:27:21 EDT 2009
Author: irooskov at redhat.com
Date: 2009-03-09 23:27:21 -0400 (Mon, 09 Mar 2009)
New Revision: 85659
Modified:
projects/docs/enterprise/4.2.7/Server_Configuration_Guide/en-US/J2EE_Security_On_JBOSS.xml
projects/docs/enterprise/4.3.5/Server_Configuration_Guide/en-US/J2EE_Security_On_JBOSS.xml
Log:
updated Server Config Guides for 4.3.5 and 4.2.7 with JBPAPP-1584 LdapExtLoginModule information added
Modified: projects/docs/enterprise/4.2.7/Server_Configuration_Guide/en-US/J2EE_Security_On_JBOSS.xml
===================================================================
--- projects/docs/enterprise/4.2.7/Server_Configuration_Guide/en-US/J2EE_Security_On_JBOSS.xml 2009-03-10 02:56:24 UTC (rev 85658)
+++ projects/docs/enterprise/4.2.7/Server_Configuration_Guide/en-US/J2EE_Security_On_JBOSS.xml 2009-03-10 03:27:21 UTC (rev 85659)
@@ -1704,7 +1704,154 @@
This login module also supports unauthenticated identity and password stacking.
</para>
</section>
-
+ <section id="Using_JBoss_Login_Modules-LdapExtLoginModule">
+ <title>LdapExtLoginModule</title>
+ <para>
+ The <filename>org.jboss.security.auth.spi.LdapExtLoginModule</filename> is an alternate ldap login module implementation that uses searches for locating both the user to bind as for authentication as well as the associated roles. The roles query will recursively follow distinguished names (DNs) to navigate a hierarchical role structure.
+ </para>
+ <para>
+ The <classname>LoginModule</classname> options include whatever options your LDAP JNDI provider supports. Examples of standard property names are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Context.INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Context.SECURITY_PROTOCOL = "java.naming.security.protocol"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Context.PROVIDER_URL = "java.naming.provider.url"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Context.SECURITY_AUTHENTICATION = "java.naming.security.authentication"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Context.REFERRAL = "java.naming.referral"
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The authentication happens in 2 steps:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ An initial bind to the ldap server is done using the bindDN and bindCredential options. The <varname>bindDN</varname> is some user with the ability to search both the <varname>baseCtxDN</varname> and <varname>rolesCtxDN</varname> trees for the user and roles. The user DN to authenticate against is queried using the filter specified by the <varname>baseFilter</varname> attribute (see the <varname>baseFilter</varname> option description for its syntax).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 2.
+
+ The resulting user DN is then authenticated by binding to ldap server using the user DN as the <classname>InitialLdapContext</classname> environment <classname>Context.SECURITY_PRINCIPAL</classname>. The <varname>Context.SECURITY_CREDENTIALS</varname> property is either set to the String password obtained by the callback handler.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ If this is successful, the associated user roles are queried using the <methodname>rolesCtxDN</methodname>, <methodname>roleAttributeID</methodname>, <methodname>roleAttributeIsDN</methodname>, <methodname>roleNameAttributeID</methodname>, and <methodname>roleFilter</methodname> options.
+ </para>
+ <para>
+ The full module properties include:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <methodname>baseCtxDN</methodname>: The fixed DN of the context to start the user search from.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>bindDN</methodname>: The DN used to bind against the ldap server for the user and roles queries. This is some DN with read/search permissions on the <methodname>baseCtxDN</methodname> and <methodname>rolesCtxDN</methodname> values.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>bindCredential</methodname>: The password for the <methodname>bindDN</methodname>. This can be encrypted if the <varname>jaasSecurityDomain</varname> is specified.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>jaasSecurityDomain</varname>: The JMX ObjectName of the <classname>JaasSecurityDomain</classname> to use to decrypt the <methodname>java.naming.security.principal</methodname>. The encrypted form of the password is that returned by the <methodname>JaasSecurityDomainencrypt64(byte{FOOTNOTE DEF })</methodname> method. The <methodname>org.jboss.security.plugins.PBEUtils</methodname> can also be used to generate the encrypted form.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>baseFilter</methodname>: A search filter used to locate the context of the user to authenticate. The input username/userDN as obtained from the login module callback will be substituted into the filter anywhere a <code>{0}</code> expression is seen. This substitution behavior comes from the standard <methodname>DirContext.search(Name, String, Object{FOOTNOTE DEF }, SearchControls cons)</methodname> method. A common example for the search filter is <code>(uid=)</code>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>rolesCtxDN</methodname>: The fixed DN of the context to search for user roles. Consider that this is not the Distinguished Name of where the actual roles are; rather, this is the DN of where the objects containing the user roles are (for example, for active directory, this is the DN where the user account is)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>roleFilter</methodname>: A search filter used to locate the roles associated with the authenticated user. The input username/userDN as obtained from the login module callback will be substituted into the filter anywhere a <code>{0}</code> expression is seen. The authenticated <varname>userDN</varname> will be substituted into the filter anywhere a <code>{1}</code> is seen. An example search filter that matches on the input username is: <code>(member={0})</code>. An alternative that matches on the authenticated <varname>userDN</varname> is: <code>(member={1})</code>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>roleAttributeIsDN</varname>: A flag indicating whether the user's role attribute contains the fully distinguished name of a role object, or the users's role attribute contains the role name. If false, the role name is taken from the value of the user's role attribute. If true, the role attribute represents the distinguished name of a role object. The role name is taken from the value of the <varname>roleNameAttributeId</varname> attribute of the corresponding object. In certain directory schemas (for example, Microsoft Active Directory), role <emphasis>(group)attributes</emphasis> in the user object are stored as DNs to role objects instead of as simple names, in which case, this property should be set to true. The default value of this property is false.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>roleAttributeID</varname>: The name of the role attribute of the context which corresponds to the name of the role. If the <varname>roleAttributeIsDN</varname> property is set to true, this property is the DN of the context to query for the <varname>roleNameAttributeID</varname> attribute. If the <varname>roleAttributeIsDN</varname> property is set to false, this property is the attribute name of the role name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>roleNameAttributeID</varname>: The name of the role attribute of the context which corresponds to the name of the role. If the <varname>roleAttributeIsDN</varname> property is set to true, this property is used to find the role object's name attribute. If the <varname>roleAttributeIsDN</varname> property is set to false, this property is ignored.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>roleRecursion</varname> : How deep the role search will go below a given matching context. Disable with 0, which is the default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>searchTimeLimit</varname>: The timeout in milliseconds for the user/role searches. Defaults to 10000 (10 seconds).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>searchScope</varname>: Sets the search scope to one of the strings. The default is <varname>SUBTREE_SCOPE</varname>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <varname>OBJECT_SCOPE</varname>: only search the named roles context.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>ONELEVEL_SCOPE</varname>: search directly under the named roles context.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>SUBTREE_SCOPE</varname>: If the roles context is not a DirContext, search only the object. If the roles context is a <emphasis>DirContext</emphasis>, search the subtree rooted at the named object, including the named object itself
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>allowEmptyPasswords</varname>: A flag indicating if <code>empty(length==0)</code> passwords should be passed to the LDAP server. An empty password is treated as an anonymous login by some LDAP servers and this may not be a desirable feature. Set this to false to reject empty passwords, true to have the ldap server validate the empty password. The default is true.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
<section id="Using_JBoss_Login_Modules-DatabaseServerLoginModule">
<title>DatabaseServerLoginModule</title>
<para>
Modified: projects/docs/enterprise/4.3.5/Server_Configuration_Guide/en-US/J2EE_Security_On_JBOSS.xml
===================================================================
--- projects/docs/enterprise/4.3.5/Server_Configuration_Guide/en-US/J2EE_Security_On_JBOSS.xml 2009-03-10 02:56:24 UTC (rev 85658)
+++ projects/docs/enterprise/4.3.5/Server_Configuration_Guide/en-US/J2EE_Security_On_JBOSS.xml 2009-03-10 03:27:21 UTC (rev 85659)
@@ -1704,7 +1704,154 @@
This login module also supports unauthenticated identity and password stacking.
</para>
</section>
-
+ <section id="Using_JBoss_Login_Modules-LdapExtLoginModule">
+ <title>LdapExtLoginModule</title>
+ <para>
+ The <filename>org.jboss.security.auth.spi.LdapExtLoginModule</filename> is an alternate ldap login module implementation that uses searches for locating both the user to bind as for authentication as well as the associated roles. The roles query will recursively follow distinguished names (DNs) to navigate a hierarchical role structure.
+ </para>
+ <para>
+ The <classname>LoginModule</classname> options include whatever options your LDAP JNDI provider supports. Examples of standard property names are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Context.INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Context.SECURITY_PROTOCOL = "java.naming.security.protocol"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Context.PROVIDER_URL = "java.naming.provider.url"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Context.SECURITY_AUTHENTICATION = "java.naming.security.authentication"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Context.REFERRAL = "java.naming.referral"
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The authentication happens in 2 steps:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ An initial bind to the ldap server is done using the bindDN and bindCredential options. The <varname>bindDN</varname> is some user with the ability to search both the <varname>baseCtxDN</varname> and <varname>rolesCtxDN</varname> trees for the user and roles. The user DN to authenticate against is queried using the filter specified by the <varname>baseFilter</varname> attribute (see the <varname>baseFilter</varname> option description for its syntax).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 2.
+
+ The resulting user DN is then authenticated by binding to ldap server using the user DN as the <classname>InitialLdapContext</classname> environment <classname>Context.SECURITY_PRINCIPAL</classname>. The <varname>Context.SECURITY_CREDENTIALS</varname> property is either set to the String password obtained by the callback handler.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ If this is successful, the associated user roles are queried using the <methodname>rolesCtxDN</methodname>, <methodname>roleAttributeID</methodname>, <methodname>roleAttributeIsDN</methodname>, <methodname>roleNameAttributeID</methodname>, and <methodname>roleFilter</methodname> options.
+ </para>
+ <para>
+ The full module properties include:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <methodname>baseCtxDN</methodname>: The fixed DN of the context to start the user search from.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>bindDN</methodname>: The DN used to bind against the ldap server for the user and roles queries. This is some DN with read/search permissions on the <methodname>baseCtxDN</methodname> and <methodname>rolesCtxDN</methodname> values.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>bindCredential</methodname>: The password for the <methodname>bindDN</methodname>. This can be encrypted if the <varname>jaasSecurityDomain</varname> is specified.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>jaasSecurityDomain</varname>: The JMX ObjectName of the <classname>JaasSecurityDomain</classname> to use to decrypt the <methodname>java.naming.security.principal</methodname>. The encrypted form of the password is that returned by the <methodname>JaasSecurityDomainencrypt64(byte{FOOTNOTE DEF })</methodname> method. The <methodname>org.jboss.security.plugins.PBEUtils</methodname> can also be used to generate the encrypted form.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>baseFilter</methodname>: A search filter used to locate the context of the user to authenticate. The input username/userDN as obtained from the login module callback will be substituted into the filter anywhere a <code>{0}</code> expression is seen. This substitution behavior comes from the standard <methodname>DirContext.search(Name, String, Object{FOOTNOTE DEF }, SearchControls cons)</methodname> method. A common example for the search filter is <code>(uid=)</code>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>rolesCtxDN</methodname>: The fixed DN of the context to search for user roles. Consider that this is not the Distinguished Name of where the actual roles are; rather, this is the DN of where the objects containing the user roles are (for example, for active directory, this is the DN where the user account is)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>roleFilter</methodname>: A search filter used to locate the roles associated with the authenticated user. The input username/userDN as obtained from the login module callback will be substituted into the filter anywhere a <code>{0}</code> expression is seen. The authenticated <varname>userDN</varname> will be substituted into the filter anywhere a <code>{1}</code> is seen. An example search filter that matches on the input username is: <code>(member={0})</code>. An alternative that matches on the authenticated <varname>userDN</varname> is: <code>(member={1})</code>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>roleAttributeIsDN</varname>: A flag indicating whether the user's role attribute contains the fully distinguished name of a role object, or the users's role attribute contains the role name. If false, the role name is taken from the value of the user's role attribute. If true, the role attribute represents the distinguished name of a role object. The role name is taken from the value of the <varname>roleNameAttributeId</varname> attribute of the corresponding object. In certain directory schemas (for example, Microsoft Active Directory), role <emphasis>(group)attributes</emphasis> in the user object are stored as DNs to role objects instead of as simple names, in which case, this property should be set to true. The default value of this property is false.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>roleAttributeID</varname>: The name of the role attribute of the context which corresponds to the name of the role. If the <varname>roleAttributeIsDN</varname> property is set to true, this property is the DN of the context to query for the <varname>roleNameAttributeID</varname> attribute. If the <varname>roleAttributeIsDN</varname> property is set to false, this property is the attribute name of the role name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>roleNameAttributeID</varname>: The name of the role attribute of the context which corresponds to the name of the role. If the <varname>roleAttributeIsDN</varname> property is set to true, this property is used to find the role object's name attribute. If the <varname>roleAttributeIsDN</varname> property is set to false, this property is ignored.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>roleRecursion</varname> : How deep the role search will go below a given matching context. Disable with 0, which is the default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>searchTimeLimit</varname>: The timeout in milliseconds for the user/role searches. Defaults to 10000 (10 seconds).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>searchScope</varname>: Sets the search scope to one of the strings. The default is <varname>SUBTREE_SCOPE</varname>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <varname>OBJECT_SCOPE</varname>: only search the named roles context.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>ONELEVEL_SCOPE</varname>: search directly under the named roles context.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>SUBTREE_SCOPE</varname>: If the roles context is not a DirContext, search only the object. If the roles context is a <emphasis>DirContext</emphasis>, search the subtree rooted at the named object, including the named object itself
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>allowEmptyPasswords</varname>: A flag indicating if <code>empty(length==0)</code> passwords should be passed to the LDAP server. An empty password is treated as an anonymous login by some LDAP servers and this may not be a desirable feature. Set this to false to reject empty passwords, true to have the ldap server validate the empty password. The default is true.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
<section id="Using_JBoss_Login_Modules-DatabaseServerLoginModule">
<title>DatabaseServerLoginModule</title>
<para>
More information about the jboss-cvs-commits
mailing list