[jboss-cvs] JBossAS SVN: r105135 - projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon May 24 02:41:03 EDT 2010
Author: jaredmorgs
Date: 2010-05-24 02:41:01 -0400 (Mon, 24 May 2010)
New Revision: 105135
Modified:
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Dynamically_Deploy_Security_Domains.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Introduction_To_JAAS.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-JBoss_Security_Extension_Architecture.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-JBoss_Security_Model.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Java_EE_Declarative_Security_Overview.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Loading_Static_Security_Domains.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Secure_Remote_Password_Protocol.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Security_Event_Auditing.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Static_Security_Domains.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-BaseCertLoginModule.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-ClientLoginModule.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Custom_LoginModule_Example.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Custom_Modules.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-DatabaseServerLoginModule.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-EJB_Method_Permissions.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Enabling_Declarative_Security.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-How_JaasSecurityManager_Uses_JAAS.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-IdentiyLoginModule.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-JaasSecurityDomain_MBean.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-JaasSecurityManagerService_MBean.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-LdapLoginModule.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Password_Hashing.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Password_Stacking.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-RunAsIdentity_Creation.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-RunAsLoginModule.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Security_Identity.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Security_References.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Security_Roles.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Subject_Authentication.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Subject_Usage_Pattern_Support.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Subject_and_Principal.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Unauthenticated_Identity.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-UsersRolesLoginModule.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Web_Content_Security_Constraints.xml
Log:
Begin reformat to bring guide into enterprise standards. Markup additions and more consistent structure applied according to the JDG.
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Dynamically_Deploy_Security_Domains.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Dynamically_Deploy_Security_Domains.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Dynamically_Deploy_Security_Domains.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -11,23 +11,28 @@
<para>
The service supports the following attributes:
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">AuthConfig</emphasis>: The resource path to the JAAS login configuration file to use. This defaults to <literal>login-config.xml</literal>
+ <variablelist>
+ <varlistentry>
+ <term>AuthConfig</term>
+ <listitem>
+ <para>Rresource path to the JAAS login configuration file to use. This defaults to <literal>login-config.xml</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LoginConfigService</term>
+ <listitem>
+ <para><literal>XMLLoginConfig</literal> service name to use for loading. This service must support a <literal>String loadConfig(URL)</literal> operation to load the configurations.
</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">LoginConfigService</emphasis>: the <literal>XMLLoginConfig</literal> service name to use for loading. This service must support a <literal>String loadConfig(URL)</literal> operation to load the configurations.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SecurityManagerService</term>
+ <listitem>
+ <para><literal>SecurityManagerService</literal> name used to flush the registered security domains. This service must support a <literal>flushAuthenticationCache(String)</literal> operation to flush the case for the argument security domain. Setting this triggers the flush of the authentication caches when the service is stopped.
</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">SecurityManagerService</emphasis>: The <literal>SecurityManagerService</literal> name used to flush the registered security domains. This service must support a <literal>flushAuthenticationCache(String)</literal> operation to flush the case for the argument security domain. Setting this triggers the flush of the authentication caches when the service is stopped.
- </para>
- </listitem>
- </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<para>
Here is an example MBean definition using the <literal>DynamicLoginConfig</literal> service.
</para>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Introduction_To_JAAS.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Introduction_To_JAAS.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Introduction_To_JAAS.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,13 +6,14 @@
<chapter id="Introduction_to_JAAS">
<title>Introduction to JAAS</title>
<para>
- The JBossSX framework is based on the JAAS API. It is important that you understand the basic elements of the JAAS API to understand the implementation details of JBossSX. The following sections provide an introduction to JAAS to prepare you for the JBossSX architecture discussion later in this chapter.
+ The JBossSX framework is based on the JAAS API. You must understand the basic elements of the JAAS API before you can understand the implementation details of JBossSX. The following sections provide an introduction to JAAS to prepare you for the JBossSX architecture discussion later in this guide.
</para>
<para>
- The JAAS 1.0 API consists of a set of Java packages designed for user authentication and authorization. It implements a Java version of the standard Pluggable Authentication Module (PAM) framework and compatibly extends the Java 2 Platform's access control architecture to support user-based authorization. JAAS was first released as an extension package for JDK 1.3 and is bundled with JDK 1.4+. Because the JBossSX framework uses only the authentication capabilities of JAAS to implement the declarative role-based J2EE security model, this introduction focuses on only that topic.
+ The JAAS 1.0 API consists of a set of Java packages designed for user authentication and authorization. The API implements a Java version of the standard Pluggable Authentication Module (PAM) framework and extends the Java 2 Platform access control architecture to support user-based authorization. </para>
+ <para>JAAS was first released as an extension package for JDK 1.3 and is bundled with JDK 1.5. Because the JBossSX framework only uses the authentication capabilities of JAAS to implement the declarative role-based J2EE security model, this introduction focuses on only that topic.
</para>
<para>
- JAAS authentication is performed in a pluggable fashion. This permits Java applications to remain independent from underlying authentication technologies and allows the JBossSX security manager to work in different security infrastructures. Integration with a security infrastructure can be achieved without changing the JBossSX security manager implementation. All that needs to change is the configuration of the authentication stack that JAAS uses.
+ JAAS authentication is performed in a pluggable fashion. This permits Java applications to remain independent from underlying authentication technologies, and allows the JBossSX security manager to work in different security infrastructures. Integration with a security infrastructure is achievable without changing the JBossSX security manager implementation. You need only change the configuration of the authentication stack JAAS uses.
</para>
<section id="What_is_JAAS-The_JAAS_Core_Classes">
<title>JAAS Core Classes</title>
@@ -25,12 +26,12 @@
<itemizedlist spacing="compact">
<listitem>
<para>
- <literal>Subject</literal> (<literal>javax.security.auth.Subject</literal>)
+ <literal>Subject</literal> (<classname>javax.security.auth.Subject</classname>)
</para>
</listitem>
<listitem>
<para>
- <literal>Principal</literal> (<literal>java.security.Principal</literal>)
+ <literal>Principal</literal> (<classname>java.security.Principal</classname>)
</para>
</listitem>
</itemizedlist>
@@ -40,27 +41,27 @@
<itemizedlist spacing="compact">
<listitem>
<para>
- <literal>Callback</literal> (<literal>javax.security.auth.callback.Callback</literal>)
+ <literal>Callback</literal> (<classname>javax.security.auth.callback.Callback</classname>)
</para>
</listitem>
<listitem>
<para>
- <literal>CallbackHandler</literal> (<literal>javax.security.auth.callback.CallbackHandler</literal>)
+ <literal>CallbackHandler</literal> (<classname>javax.security.auth.callback.CallbackHandler</classname>)
</para>
</listitem>
<listitem>
<para>
- <literal>Configuration</literal> (<literal>javax.security.auth.login.Configuration</literal>)
+ <literal>Configuration</literal> (<classname>javax.security.auth.login.Configuration</classname>)
</para>
</listitem>
<listitem>
<para>
- <literal>LoginContext</literal> (<literal>javax.security.auth.login.LoginContext</literal>)
+ <literal>LoginContext</literal> (<classname>javax.security.auth.login.LoginContext</classname>)
</para>
</listitem>
<listitem>
<para>
- <literal>LoginModule</literal> (<literal>javax.security.auth.spi.LoginModule</literal>)
+ <literal>LoginModule</literal> (<classname>javax.security.auth.spi.LoginModule</classname>)
</para>
</listitem>
</itemizedlist>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-JBoss_Security_Extension_Architecture.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-JBoss_Security_Extension_Architecture.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-JBoss_Security_Extension_Architecture.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,13 +6,13 @@
<chapter id="JBoss_Security_Extension_Architecture">
<title>The JBoss Security Extension Architecture</title>
<para>
- The preceding discussion of the general JBoss security layer has stated that the JBossSX security extension framework is an implementation of the security layer interfaces. This is the primary purpose of the JBossSX framework. The details of the implementation are interesting in that it offers a great deal of customization for integration into existing security infrastructures. A security infrastructure can be anything from a database or LDAP server to a sophisticated security software suite. The integration flexibility is achieved using the pluggable authentication model available in the JAAS framework.
+ The preceding discussion of the general JBoss security layer has stated that the JBossSX security extension framework is an implementation of the security layer interfaces. This is the primary purpose of the JBossSX framework. The details of the implementation are interesting in that it offers a great deal of customization for integration into existing security infrastructures. A security infrastructure can be anything from a database or LDAP server to a sophisticated security software suite. The integration flexibility is achieved using the <firstterm>Pluggable Authentication Model</firstterm> (PAM) available in the JAAS framework.
</para>
<para>
- The heart of the JBossSX framework is <literal>org.jboss.security.plugins.JaasSecurityManager</literal>. This is the default implementation of the <literal>AuthenticationManager</literal> and <literal>RealmMapping</literal> interfaces. <xref linkend="The_JBoss_Security_Extension_Architecture-The_relationship_between_the_security_domain_component_deployment_descriptor_value_the_component_container_and_the_JaasSecurityManager."/> shows how the <literal>JaasSecurityManager</literal> integrates into the EJB and web container layers based on the <literal>security-domain</literal> element of the corresponding component deployment descriptor.
+ The heart of the JBossSX framework is <classname>org.jboss.security.plugins.JaasSecurityManager</classname>. This is the default implementation of the <classname>AuthenticationManager</classname> and <classname>RealmMapping</classname> interfaces. <xref linkend="The_JBoss_Security_Extension_Architecture-The_relationship_between_the_security_domain_component_deployment_descriptor_value_the_component_container_and_the_JaasSecurityManager."/> shows how the <classname>JaasSecurityManager</classname> integrates into the EJB and web container layers based on the <markup>security-domain</markup> element of the corresponding component deployment descriptor.
</para>
<figure id="The_JBoss_Security_Extension_Architecture-The_relationship_between_the_security_domain_component_deployment_descriptor_value_the_component_container_and_the_JaasSecurityManager.">
- <title>The relationship between the security-domain component deployment descriptor value, the component container and the JaasSecurityManager.</title>
+ <title>Relationship between security-domain deployment descriptor value, component container, and JaasSecurityManager.</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/j2ee_chap8-9.jpg"/>
@@ -20,10 +20,10 @@
</mediaobject>
</figure>
<para>
- <xref linkend="The_JBoss_Security_Extension_Architecture-The_relationship_between_the_security_domain_component_deployment_descriptor_value_the_component_container_and_the_JaasSecurityManager."/> depicts an enterprise application that contains both EJBs and web content secured under the security domain <literal>jwdomain</literal>. The EJB and web containers have a request interceptor architecture that includes a security interceptor, which enforces the container security model. At deployment time, the <literal>security-domain</literal> element value in the <literal>jboss.xml</literal> and <literal>jboss-web.xml</literal> descriptors is used to obtain the security manager instance associated with the container. The security interceptor then uses the security manager to perform its role. When a secured component is requested, the security interceptor delegates security checks to the security manager instance associated with the container.
+ <xref linkend="The_JBoss_Security_Extension_Architecture-The_relationship_between_the_security_domain_component_deployment_descriptor_value_the_component_container_and_the_JaasSecurityManager."/> depicts an enterprise application that contains both EJBs and web content secured under the security domain <literal>jwdomain</literal>. The EJB and web containers have a request interceptor architecture that includes a security interceptor, which enforces the container security model. At deployment time, the <markup>security-domain</markup> element value in the <filename>jboss.xml</filename> and <filename>jboss-web.xml</filename> descriptors is used to obtain the security manager instance associated with the container. The security interceptor then uses the security manager to perform its role. When a secured component is requested, the security interceptor delegates security checks to the security manager instance associated with the container.
</para>
<para>
- The JBossSX <literal>JaasSecurityManager</literal> implementation performs security checks based on the information associated with the <literal>Subject</literal> instance that results from executing the JAAS login modules configured under the name matching the <literal>security-domain</literal> element value. We will drill into the <literal>JaasSecurityManager</literal> implementation and its use of JAAS in the following section.
+ The JBossSX <literal>JaasSecurityManager</literal> implementation performs security checks based on the information associated with the <literal>Subject</literal> instance that results from executing the JAAS login modules configured under the name matching the <markup>security-domain</markup> element value. We will drill into the <literal>JaasSecurityManager</literal> implementation and its use of JAAS in the following section.
</para>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="sect-How_JaasSecurityManager_Uses_JAAS.xml" encoding="UTF-8"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="sect-JaasSecurityManagerService_MBean.xml" encoding="UTF-8"/>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-JBoss_Security_Model.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-JBoss_Security_Model.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-JBoss_Security_Model.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,47 +6,47 @@
<chapter id="The_JBoss_Security_Model">
<title>JBoss Security Model</title>
<para>
- Similar to the rest of the JBoss architecture, security at the lowest level is defined as a set of interfaces for which alternate implementations may be provided. Three basic interfaces define the JBoss server security layer: <literal>org.jboss.security.AuthenticationManager</literal>, <literal>org.jboss.security.RealmMapping</literal>, and <literal>org.jboss.security.SecurityProxy</literal>. <xref linkend="The_JBoss_Security_Model-The_key_security_model_interfaces_and_their_relationship_to_the_JBoss_server_EJB_container_elements."/> shows a class diagram of the security interfaces and their relationship to the EJB container architecture.
+ Similar to the rest of the JBoss architecture, security at the lowest level is defined as a set of interfaces for which alternate implementations may be provided. Three basic interfaces define the JBoss server security layer: <classname>org.jboss.security.AuthenticationManager</classname>, <classname>org.jboss.security.RealmMapping</classname>, and <classname>org.jboss.security.SecurityProxy</classname>. <xref linkend="The_JBoss_Security_Model-The_key_security_model_interfaces_and_their_relationship_to_the_JBoss_server_EJB_container_elements."/> shows a class diagram of the security interfaces and their relationship to the EJB container architecture.
</para>
<figure id="The_JBoss_Security_Model-The_key_security_model_interfaces_and_their_relationship_to_the_JBoss_server_EJB_container_elements.">
- <title>The key security model interfaces and their relationship to the JBoss server EJB container elements.</title>
+ <title>Security Model Interface Relationships to JBoss Server EJB Container Elements.</title>
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/j2ee_chap8-6.jpg"/>
+ <imagedata align="center" fileref="images/j2ee_chap8-6.jpg" width="450px"/>
</imageobject>
</mediaobject>
</figure>
<para>
- The light blue classes represent the security interfaces while the yellow classes represent the EJB container layer. The two interfaces required for the implementation of the J2EE security model are <literal>org.jboss.security.AuthenticationManager</literal> and <literal>org.jboss.security.RealmMapping</literal>. The roles of the security interfaces presented in <xref linkend="The_JBoss_Security_Model-The_key_security_model_interfaces_and_their_relationship_to_the_JBoss_server_EJB_container_elements."/> are summarized in the following list.
+ The light blue classes represent the security interfaces. while the yellow classes represent the EJB container layer. The two interfaces required for the implementation of the J2EE security model are <classname>org.jboss.security.AuthenticationManager</classname> and <classname>org.jboss.security.RealmMapping</classname>. The roles of the security interfaces presented in <xref linkend="The_JBoss_Security_Model-The_key_security_model_interfaces_and_their_relationship_to_the_JBoss_server_EJB_container_elements."/> are summarized in the following list.
</para>
<itemizedlist>
<listitem>
- <para><classname>AuthenticationManager</classname>: This interface is responsible for validating credentials associated with principals. Principals are identities, such as usernames, employee numbers, and social security numbers. Credentials are proof of the identity, such as passwords, session keys, and digital signatures. The <literal>isValid</literal> method is invoked to determine whether a user identity and associated credentials as known in the operational environment are valid proof of the user's identity.
+ <para><interfacename>AuthenticationManager</interfacename>: This interface is responsible for validating credentials associated with <firstterm>Principals</firstterm>. Principals are identities, such as usernames, employee numbers, and social security numbers. <firstterm>Credentials</firstterm> are proof of the identity, such as passwords, session keys, and digital signatures. The <methodname>isValid</methodname> method is invoked to determine whether a user identity and associated credentials as known in the operational environment are valid proof of the user's identity.
</para>
</listitem>
<listitem>
- <para><classname>RealmMapping</classname>: This interface is responsible for principal mapping and role mapping. The <literal>getPrincipal</literal> method takes a user identity as known in the operational environment and returns the application domain identity. The <literal>doesUserHaveRole</literal> method validates that the user identity in the operation environment has been assigned the indicated role from the application domain.
+ <para><interfacename>RealmMapping</interfacename>: This interface is responsible for principal mapping and role mapping. The <literal>getPrincipal</literal> method takes a user identity as known in the operational environment and returns the application domain identity. The <methodname>doesUserHaveRole</methodname> method validates that the user identity in the operation environment has been assigned the indicated role from the application domain.
</para>
</listitem>
<listitem>
- <para><classname>SecurityProxy</classname>: This interface describes the requirements for a custom <literal>SecurityProxyInterceptor</literal> plugin. A <literal>SecurityProxy</literal> allows for the externalization of custom security checks on a per-method basis for both the EJB home and remote interface methods.
+ <para><interfacename>SecurityProxy</interfacename>: This interface describes the requirements for a custom <literal>SecurityProxyInterceptor</literal> plugin. A <literal>SecurityProxy</literal> allows for the externalization of custom security checks on a per-method basis for both the EJB home and remote interface methods.
</para>
</listitem>
<listitem>
- <para><classname>SubjectSecurityManager</classname>: This is a subinterface of <literal>AuthenticationManager</literal> that adds accessor methods for obtaining the security domain name of the security manager and the current thread's authenticated <literal>Subject</literal>.
+ <para><interfacename>SubjectSecurityManager</interfacename>: This is a subinterface of <interfacename>AuthenticationManager</interfacename> that adds accessor methods for obtaining the security domain name of the security manager and the current thread's authenticated <literal>Subject</literal>.
</para>
</listitem>
<listitem>
- <para><classname>SecurityDomain</classname>: This is an extension of the <literal>AuthenticationManager</literal>, <literal>RealmMapping</literal>, and <literal>SubjectSecurityManager</literal> interfaces. <classname>SecurityDomain</classname> is the recommended way to implement security in components, because of the advantages the JAAS Subject offers, and the increased support offered to to ASP-style application and resource deployments. A <literal>java.security.KeyStore</literal>, and the JSSE <literal>com.sun.net.ssl.KeyManagerFactory</literal> and <literal>com.sun.net.ssl.TrustManagerFactory</literal> interfaces are included in the class.
+ <para><interfacename>SecurityDomain</interfacename>: This is an extension of the <interfacename>AuthenticationManager</interfacename>, <interface>RealmMapping</interface>, and <literal>SubjectSecurityManager</literal> interfaces. <classname>SecurityDomain</classname> is the recommended way to implement security in components, because of the advantages the JAAS Subject offers, and the increased support offered to to ASP-style application and resource deployments. A <classname>java.security.KeyStore</classname>, and the JSSE <classname>com.sun.net.ssl.KeyManagerFactory</classname> and <classname>com.sun.net.ssl.TrustManagerFactory</classname> interfaces are included in the class.
</para>
</listitem>
</itemizedlist>
<para>
- Note that the <literal>AuthenticationManager</literal>, <literal>RealmMapping</literal> and <literal>SecurityProxy</literal> interfaces have no association to JAAS related classes. Although the JBossSX framework is heavily dependent on JAAS, the basic security interfaces required for implementation of the J2EE security model are not. The JBossSX framework is simply an implementation of the basic security plug-in interfaces that are based on JAAS. </para>
- <para>The component diagram presented in <xref linkend="The_JBoss_Security_Model-The_relationship_between_the_JBossSX_framework_implementation_classes_and_the_JBoss_server_EJB_container_layer."/> illustrates this fact. The implication of this plug-in architecture is that you are free to replace the JAAS-based JBossSX implementation classes with your own custom security manager implementation that does not make use of JAAS, if you so desire. You'll see how to do this when you look at the JBossSX MBeans available for the configuration of JBossSX in <xref linkend="The_JBoss_Security_Model-The_relationship_between_the_JBossSX_framework_implementation_classes_and_the_JBoss_server_EJB_container_layer."/>.
+ Note that the <interfacename>AuthenticationManager</interfacename>, <interfacename>RealmMapping</interfacename> and <interfacename>SecurityProxy</interfacename> interfaces have no association to JAAS related classes. Although the JBossSX framework is heavily dependent on JAAS, the basic security interfaces required for implementation of the Java EE security model are not. The JBossSX framework is simply an implementation of the basic security plug-in interfaces that are based on JAAS. </para>
+ <para>The component diagram in <xref linkend="The_JBoss_Security_Model-The_relationship_between_the_JBossSX_framework_implementation_classes_and_the_JBoss_server_EJB_container_layer."/> illustrates this fact. The implication of this plug-in architecture is that you are free to replace the JAAS-based JBossSX implementation classes with your own non-JAAS custom security manager implementation. You'll see how to do this when you look at the JBossSX MBeans available for JBossSX configuration in <xref linkend="The_JBoss_Security_Model-The_relationship_between_the_JBossSX_framework_implementation_classes_and_the_JBoss_server_EJB_container_layer."/>.
</para>
<figure id="The_JBoss_Security_Model-The_relationship_between_the_JBossSX_framework_implementation_classes_and_the_JBoss_server_EJB_container_layer.">
- <title>The relationship between the JBossSX framework implementation classes and the JBoss server EJB container layer.</title>
+ <title>JBossSX Framework Implementation Classes and the JBoss Server EJB Container Layer.</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/j2ee_chap8-7.jpg"/>
@@ -56,29 +56,29 @@
<section id="The_JBoss_Security_Model-Enabling_Declarative_Security_in_JBoss_Revisited">
<title>Enabling Declarative Security Revisited</title>
<!--TODO: Decide whether this REVISITED topic could be made into an appendix, or whether the information can be incorporated into sect-Enabling_Declarative_Security.xml--> <para>
- Earlier in this chapter, the discussion of the J2EE standard security model ended with a requirement for the use of JBoss server-specific deployment descriptor to enable security. The details of this configuration are presented here. <xref linkend="Enabling_Declarative_Security_in_JBoss_Revisited-The_security_element_subsets_of_the_JBoss_server_jboss.xml_and_jboss_web.xml_deployment_descriptors."/> shows the JBoss-specific EJB and web application deployment descriptor's security-related elements.
+ Earlier in this chapter, the discussion of the Java EE standard security model ended with a requirement for the use of JBoss server-specific deployment descriptor to enable security. The details of this configuration are presented here. <xref linkend="Enabling_Declarative_Security_in_JBoss_Revisited-The_security_element_subsets_of_the_JBoss_server_jboss.xml_and_jboss_web.xml_deployment_descriptors."/> shows the JBoss-specific EJB and web application deployment descriptor's security-related elements.
</para>
<figure id="Enabling_Declarative_Security_in_JBoss_Revisited-The_security_element_subsets_of_the_JBoss_server_jboss.xml_and_jboss_web.xml_deployment_descriptors.">
- <title>The security element subsets of the JBoss server jboss.xml and jboss-web.xml deployment descriptors.</title>
+ <title>jboss.xml and jboss-web.xml Security Element Subsets.</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/j2ee_chap8-8.jpg"/>
</imageobject>
</mediaobject>
</figure>
- <para>The value of a <literal>security-domain</literal> element specifies the JNDI name of the security manager interface implementation that JBoss uses for the EJB and web containers. This is an object that implements both of the <literal>AuthenticationManager</literal> and <literal>RealmMapping</literal> interfaces. When specified as a top-level element it defines what security domain in effect for all EJBs in the deployment unit. This is the typical usage because mixing security managers within a deployment unit complicates inter-component operation and administration.
+ <para>The value of a <markup>security-domain</markup> element specifies the JNDI name of the security manager interface implementation that JBoss uses for the EJB and web containers. This is an object that implements both of the <interfacename>AuthenticationManager</interfacename> and <interfacename>RealmMapping</interfacename> interfaces. When specified as a top-level element it defines what security domain in effect for all EJBs in the deployment unit. This is the typical usage because mixing security managers within a deployment unit complicates inter-component operation and administration.
</para>
- <para>To specify the security domain for an individual EJB, you specify the <literal>security-domain</literal> at the container configuration level. This will override any top-level security-domain element.
+ <para>To specify the security domain for an individual EJB, you specify the <markup>security-domain</markup> at the container configuration level. This will override any top-level security-domain element.
</para>
- <para>The <literal>unauthenticated-principal</literal> element specifies the name to use for the <literal>Principal</literal> object returned by the <literal>EJBContext.getUserPrincipal</literal> method when an unauthenticated user invokes an EJB. Note that this conveys no special permissions to an unauthenticated caller. Its primary purpose is to allow unsecured servlets and JSP pages to invoke unsecured EJBs and allow the target EJB to obtain a non-null <literal>Principal</literal> for the caller using the <literal>getUserPrincipal</literal> method. This is a J2EE specification requirement.
+ <para>The <markup>unauthenticated-principal</markup> element specifies the name to use for the <literal>Principal</literal> object returned by the <methodname>EJBContext.getUserPrincipal</methodname> method when an unauthenticated user invokes an EJB. Note that this conveys no special permissions to an unauthenticated caller. Its primary purpose is to allow unsecured servlets and JSP pages to invoke unsecured EJBs and allow the target EJB to obtain a non-null <literal>Principal</literal> for the caller using the <methodname>getUserPrincipal</methodname> method. This is a J2EE specification requirement.
</para>
- <para>The <literal>security-proxy</literal> element identifies a custom security proxy implementation that allows per-request security checks outside the scope of the EJB declarative security model without embedding security logic into the EJB implementation. This may be an implementation of the <literal>org.jboss.security.SecurityProxy</literal> interface, or just an object that implements methods in the home, remote, local home or local interfaces of the EJB to secure without implementing any common interface. If the given class does not implement the <literal>SecurityProxy</literal> interface, the instance must be wrapped in a <literal>SecurityProxy</literal> implementation that delegates the method invocations to the object. The <literal>org.jboss.security.SubjectSecurityProxy</literal> is an example <literal>SecurityProxy</literal> implementation used by the default JBossSX installation.
+ <para>The <markup>security-proxy</markup> element identifies a custom security proxy implementation that allows per-request security checks outside the scope of the EJB declarative security model without embedding security logic into the EJB implementation. This may be an implementation of the <interfacename>org.jboss.security.SecurityProxy</interfacename> interface, or just an object that implements methods in the home, remote, local home or local interfaces of the EJB to secure without implementing any common interface. If the given class does not implement the <interfacename>SecurityProxy</interfacename> interface, the instance must be wrapped in a <interfacename>SecurityProxy</interfacename> implementation that delegates the method invocations to the object. The <classname>org.jboss.security.SubjectSecurityProxy</classname> is an example <literal>SecurityProxy</literal> implementation used by the default JBossSX installation.
</para>
<para>
- Take a look at a simple example of a custom <literal>SecurityProxy</literal> in the context of a trivial stateless session bean. The custom <literal>SecurityProxy</literal> validates that no one invokes the bean's <literal>echo</literal> method with a four-letter word as its argument. This is a check that is not possible with role-based security; you cannot define a <literal>FourLetterEchoInvoker</literal> role because the security context is the method argument, not a property of the caller. The code for the custom <literal>SecurityProxy</literal> is given in <xref linkend="Enabling_Declarative_Security_in_JBoss_Revisited-The_example_1_custom_EchoSecurityProxy_implementation_that_enforces_the_echo_argument_based_security_constraint."/>, and the full source code is available in the <literal>src/main/org/jboss/book/security/ex1</literal> directory of the book examples.
+ Take a look at a simple example of a custom <literal>SecurityProxy</literal> in the context of a trivial stateless session bean. The custom <literal>SecurityProxy</literal> validates that no one invokes the bean's <methodname>echo</methodname> method with a four-letter word as its argument. This is a check that is not possible with role-based security; you cannot define a <literal>FourLetterEchoInvoker</literal> role because the security context is the method argument, not a property of the caller. The code for the custom <literal>SecurityProxy</literal> is given in <xref linkend="Enabling_Declarative_Security_in_JBoss_Revisited-The_example_1_custom_EchoSecurityProxy_implementation_that_enforces_the_echo_argument_based_security_constraint."/>, and the full source code is available in the <filename>src/main/org/jboss/book/security/ex1</filename> directory of the book examples.
</para>
<example id="Enabling_Declarative_Security_in_JBoss_Revisited-The_example_1_custom_EchoSecurityProxy_implementation_that_enforces_the_echo_argument_based_security_constraint.">
- <title>The example 1 custom EchoSecurityProxy implementation that enforces the echo argument-based security constraint.</title>
+ <title>Custom EchoSecurityProxy Implementation.</title>
<programlisting language="Java" role="JAVA">package org.jboss.book.security.ex1;
import java.lang.reflect.Method;
@@ -145,13 +145,14 @@
</programlisting>
</example>
<para>
- The <literal>EchoSecurityProxy</literal> checks that the method to be invoked on the bean instance corresponds to the <literal>echo(String)</literal> method loaded the init method. If there is a match, the method argument is obtained and its length compared against 4 or null. Either case results in a <literal>SecurityException</literal> being thrown. Certainly this is a contrived example, but only in its application. It is a common requirement that applications must perform security checks based on the value of method arguments. The point of the example is to demonstrate how custom security beyond the scope of the standard declarative security model can be introduced independent of the bean implementation. This allows the specification and coding of the security requirements to be delegated to security experts. Since the security proxy layer can be done independent of the bean implementation, security can be changed to match the deployment environment requirements.
+ The <literal>EchoSecurityProxy</literal> checks that the method to be invoked on the bean instance corresponds to the <methodname>echo(String)</methodname> method loaded the init method. If there is a match, the method argument is obtained and its length compared against 4 or null. Either case results in a <literal>SecurityException</literal> being thrown. </para>
+ <para>Certainly this is a contrived example, but only in its application. It is a common requirement that applications must perform security checks based on the value of method arguments. The point of the example is to demonstrate how custom security beyond the scope of the standard declarative security model can be introduced independent of the bean implementation. This allows the specification and coding of the security requirements to be delegated to security experts. Since the security proxy layer can be done independent of the bean implementation, security can be changed to match the deployment environment requirements.
</para>
<para>
The associated <literal>jboss.xml</literal> descriptor that installs the <literal>EchoSecurityProxy</literal> as the custom proxy for the <literal>EchoBean</literal> is given in <xref linkend="Enabling_Declarative_Security_in_JBoss_Revisited-The_jboss.xml_descriptor_which_configures_the_EchoSecurityProxy_as_the_custom_security_proxy_for_the_EchoBean."/>.
</para>
<example id="Enabling_Declarative_Security_in_JBoss_Revisited-The_jboss.xml_descriptor_which_configures_the_EchoSecurityProxy_as_the_custom_security_proxy_for_the_EchoBean.">
- <title>The jboss.xml descriptor, which configures the EchoSecurityProxy as the custom security proxy for the EchoBean.</title>
+ <title>jboss.xml descriptor</title>
<programlisting language="XML" role="XML"><jboss>
<security-domain>java:/jaas/other</security-domain>
@@ -165,7 +166,7 @@
</programlisting>
</example>
<para>
- Now test the custom proxy by running a client that attempts to invoke the <literal>EchoBean.echo</literal> method with the arguments <literal>Hello</literal> and <literal>Four</literal> as illustrated in this fragment:
+ Now test the custom proxy by running a client that attempts to invoke the <methodname>EchoBean.echo</methodname> method with the arguments <literal>Hello</literal> and <literal>Four</literal> as illustrated in this fragment:
</para>
<programlisting language="Java" role="JAVA">public class ExClient
{
@@ -202,7 +203,7 @@
[java] Caused by: java.lang.SecurityException: No 4 letter words
...</screen>
<para>
- The result is that the <literal>echo('Hello')</literal> method call succeeds as expected and the <literal>echo('Four')</literal> method call results in a rather messy looking exception, which is also expected. The above output has been truncated to fit in the book. The key part to the exception is that the <literal>SecurityException("No 4 letter words")</literal> generated by the <literal>EchoSecurityProxy</literal> was thrown to abort the attempted method invocation as desired.
+ The result is that the <methodname>echo('Hello')</methodname> method call succeeds as expected and the <methodname>echo('Four')</methodname> method call results in a rather messy looking exception, which is also expected. The above output has been truncated to fit in the book. The key part to the exception is that the <literal>SecurityException("No 4 letter words")</literal> generated by the <literal>EchoSecurityProxy</literal> was thrown to abort the attempted method invocation as desired.
</para>
</section>
</chapter>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Java_EE_Declarative_Security_Overview.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Java_EE_Declarative_Security_Overview.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Java_EE_Declarative_Security_Overview.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -1,10 +1,9 @@
<?xml version='1.0' encoding='UTF-8'?>
-<!-- This document was created with Syntext Serna Free. -->
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" []>
+<!-- This document was created with Syntext Serna Free. --><!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" []>
<chapter id="chap-Java_EE_Declarative_Security_Overview">
<title>Java EE Declarative Security Overview</title>
- <para>
- The Java EE security model declarative in that you describe the security roles and permissions in a standard XML descriptor rather than embedding security into your business component. This isolates security from business-level code because security tends to be more a function of where the component is deployed than an inherent aspect of the component's business logic. For example, consider an ATM component that is to be used to access a bank account. The security requirements, roles and permissions will vary independently of how you access the bank account, based on what bank is managing the account, where the ATM is located, and so on.
+ <para>Rather than embedding security into your business component, the Java EE security model is declarative: you describe the security roles and permissions in a standard XML descriptor. This isolates security from business-level code because security tends to be more a function of where the component is deployed than an inherent aspect of the component's business logic. </para>
+ <para>For example, consider an ATM component used to access a bank account. The security requirements, roles and permissions will vary independently of how you access the bank account, based on what bank is managing the account, where the ATM is located, and so on.
</para>
<para>
Securing a Java EE application is based on the specification of the application security requirements via the standard Java EE deployment descriptors. You secure access to EJBs and web components in an enterprise application by using the <literal>ejb-jar.xml</literal> and <literal>web.xml</literal> deployment descriptors. The following sections look at the purpose and usage of the various security elements.
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Loading_Static_Security_Domains.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Loading_Static_Security_Domains.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Loading_Static_Security_Domains.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,7 +6,7 @@
<chapter id="chap-Loading_Static_Security_Domains">
<title>Loading Static Security Domains</title>
<para>
- Authentication security domains are configured statically in the <literal>conf/login-config.xml</literal> file, or deployed using <filename>jboss-beans.xml</filename> deployment descriptors. For static domains, the <literal>XMLLoginConfig</literal> MBean is responsible for loading security configurations from this configurations from a local configuration file. The MBean is defined as shown below.
+ Authentication security domains are configured statically in the <filename>conf/login-config.xml</filename> file, or deployed using <filename>jboss-beans.xml</filename> deployment descriptors. For static domains, the <literal>XMLLoginConfig</literal> MBean is responsible for loading security configurations from this configurations from a local configuration file. The MBean is defined as shown below.
</para>
<programlisting language="XML" role="XML"><mbean code="org.jboss.security.auth.login.XMLLoginConfig"
name="jboss.security:service=XMLLoginConfig">
@@ -16,53 +16,72 @@
<para>
The MBean supports the following attributes:
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">ConfigURL</emphasis>: specifies the URL of the XML login configuration file that should be loaded by this MBean on startup. This must be a valid URL string representation.
+ <variablelist>
+ <varlistentry>
+ <term>ConfigURL</term>
+ <listitem>
+ <para>Specifies the URL of the XML login configuration file that should be loaded by this MBean on startup. This must be a valid URL string representation.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ConfigResource</term>
+ <listitem>
+ <para>Specifies the resource name of the XML login configuration file that should be loaded by this MBean on startup. The name is treated as a classpath resource for which a URL is located using the thread context class loader.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ValidateDTD</term>
+ <listitem>
+ <para>Specifies whether the XML configuration should be validated against its DTD. This defaults to true.
</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">ConfigResource</emphasis>: specifies the resource name of the XML login configuration file that should be loaded by this MBean on startup. The name is treated as a classpath resource for which a URL is located using the thread context class loader.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">ValidateDTD</emphasis>: a flag indicating if the XML configuration should be validated against its DTD. This defaults to true.
- </para>
- </listitem>
- </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<para>
- The MBean also supports the following operations that allow one to dynamically extend the login configurations at runtime. Note that any operation that attempts to alter login configuration requires a <literal>javax.security.auth.AuthPermission("refreshLoginConfiguration")</literal> when running with a security manager. The <literal>org.jboss.book.security.service.SecurityConfig</literal> service demonstrates how this can be used to add/remove a deployment specific security configuration dynamically.
+ The MBean also supports the following operations that allow you to dynamically extend the login configurations at runtime. Note that any operation that attempts to alter login configuration requires a <methodname>javax.security.auth.AuthPermission("refreshLoginConfiguration")</methodname> when running with a security manager. The <classname>org.jboss.book.security.service.SecurityConfig</classname> service demonstrates how this can be used to add/remove a deployment specific security configuration dynamically.
</para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>void addAppConfig(String appName, AppConfigurationEntry[] entries)</literal>: this adds the given login module configuration stack to the current configuration under the given <literal>appName</literal>. This replaces any existing entry under that name.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>void removeAppConfig(String appName)</literal>: this removes the login module configuration registered under the given <literal>appName</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>String[] loadConfig(URL configURL) throws Exception</literal>: this loads one or more login configurations from a URL representing either an XML or legacy Sun login configuration file. Note that all login configurations must be added or none will be added. It returns the names of the login configurations that were added.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>void removeConfigs(String[] appNames)</literal>: this removes the login configurations specified <literal>appNames</literal> array.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>String displayAppConfig(String appName)</literal>: this operation displays a simple string format of the named configuration if it exists.
- </para>
- </listitem>
- </itemizedlist>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <methodname>void addAppConfig(String appName, AppConfigurationEntry[] entries)</methodname>
+ </term>
+ <listitem>
+ <para>Adds the given login module configuration stack to the current configuration under the given <literal>appName</literal>. This replaces any existing entry under that name.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <methodname>void removeAppConfig(String appName)</methodname>
+ </term>
+ <listitem>
+ <para>Removes the login module configuration registered under the given <literal>appName</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <methodname>String[] loadConfig(URL configURL) throws Exception</methodname>
+ </term>
+ <listitem>
+ <para>Loads one or more login configurations from a URL representing either an XML or legacy Sun login configuration file. Note that all login configurations must be added or none will be added. It returns the names of the login configurations that were added.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <methodname>void removeConfigs(String[] appNames)</methodname>
+ </term>
+ <listitem>
+ <para>Removes the login configurations specified <literal>appNames</literal> array</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <methodname>String displayAppConfig(String appName)</methodname>
+ </term>
+ <listitem>
+ <para>Displays a simple string format of the named configuration if it exists.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<para>
The <literal>SecurityConfig</literal> MBean is responsible for selecting the <literal>javax.security.auth.login.Configuration</literal> to be used. The default configuration simply references the <literal>XMLLoginConfig</literal> MBean.
</para>
@@ -74,15 +93,15 @@
<para>
There is one configurable attribute:
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">LoginConfig</emphasis>: Specifies the JMX <literal>ObjectName</literal> string of the MBean that provides the default JAAS login configuration. When the <literal>SecurityConfig</literal> is started, this MBean is queried for its <literal>javax.security.auth.login.Configuration</literal> by calling its <literal>getConfiguration(Configuration currentConfig)</literal> operation. If the <literal>LoginConfig</literal> attribute is not specified then the default Sun <literal>Configuration</literal> implementation described in the <literal>Configuration</literal> class JavaDocs is used.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- In addition to allowing for a custom JAAS login configuration implementation, this service allows configurations to be chained together in a stack at runtime. This allows one to push a login configuration onto the stack and latter pop it. This is a feature used by the security unit tests to install custom login configurations into a default JBoss installation. Pushing a new configuration is done using:
+ <variablelist>
+ <varlistentry>
+ <term>LoginConfig</term>
+ <listitem>
+ <para>Specifies the JMX <literal>ObjectName</literal> string of the MBean that provides the default JAAS login configuration. When the <literal>SecurityConfig</literal> is started, this MBean is queried for its <literal>javax.security.auth.login.Configuration</literal> by calling its <literal>getConfiguration(Configuration currentConfig)</literal> operation. If the <literal>LoginConfig</literal> attribute is not specified then the default Sun <literal>Configuration</literal> implementation described in the <classname>Configuration</classname> class JavaDocs is used</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>In addition to allowing for a custom JAAS login configuration implementation, this service allows configurations to be chained together in a stack at runtime. This allows one to push a login configuration onto the stack and latter pop it. This is a feature used by the security unit tests to install custom login configurations into a default JBoss installation. Pushing a new configuration is done using:
</para>
<programlisting language="Java" role="JAVA">public void pushLoginConfig(String objectName) throws
JMException, MalformedObjectNameException;
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Secure_Remote_Password_Protocol.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Secure_Remote_Password_Protocol.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Secure_Remote_Password_Protocol.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -8,17 +8,15 @@
<para>
The Secure Remote Password (SRP) protocol is an implementation of a public key exchange handshake described in the Internet standards working group request for comments 2945(RFC2945). The RFC2945 abstract states:
</para>
- <para>
- This document describes a cryptographically strong network authentication mechanism known as the Secure Remote Password (SRP) protocol. This mechanism is suitable for negotiating secure connections using a user-supplied password, while eliminating the security problems traditionally associated with reusable passwords. This system also performs a secure key exchange in the process of authentication, allowing security layers (privacy and/or integrity protection) to be enabled during the session. Trusted key servers and certificate infrastructures are not required, and clients are not required to store or manage any long-term keys. SRP offers both security and deployment advantages over existing challenge-response techniques, making it an ideal drop-in replacement where secure password authentication is needed.
+ <blockquote>
+ <para>This document describes a cryptographically strong network authentication mechanism known as the Secure Remote Password (SRP) protocol. This mechanism is suitable for negotiating secure connections using a user-supplied password, while eliminating the security problems traditionally associated with reusable passwords. This system also performs a secure key exchange in the process of authentication, allowing security layers (privacy and/or integrity protection) to be enabled during the session. Trusted key servers and certificate infrastructures are not required, and clients are not required to store or manage any long-term keys. SRP offers both security and deployment advantages over existing challenge-response techniques, making it an ideal drop-in replacement where secure password authentication is needed.
</para>
- <para>
- Note: The complete RFC2945 specification can be obtained from <ulink url="http://www.rfc-editor.org/rfc.html"/>. Additional information on the SRP algorithm and its history can be found at <ulink url="http://www-cs-students.stanford.edu/~tjw/srp/"/>.
+ </blockquote>
+ <para>The complete RFC2945 specification can be obtained from <ulink url="http://www.rfc-editor.org/rfc.html"/>. Additional information on the SRP algorithm and its history can be found at <ulink url="http://www-cs-students.stanford.edu/~tjw/srp/"/>.
</para>
- <para>
- SRP is similar in concept and security to other public key exchange algorithms, such as Diffie-Hellman and RSA. SRP is based on simple string passwords in a way that does not require a clear text password to exist on the server. This is in contrast to other public key-based algorithms that require client certificates and the corresponding certificate management infrastructure.
+ <para>SRP is similar in concept and security to other public key exchange algorithms, such as Diffie-Hellman and RSA. SRP is based on simple string passwords in a way that does not require a clear text password to exist on the server. This is in contrast to other public key-based algorithms that require client certificates and the corresponding certificate management infrastructure.
</para>
- <para>
- Algorithms like Diffie-Hellman and RSA are known as public key exchange algorithms. The concept of public key algorithms is that you have two keys, one public that is available to everyone, and one that is private and known only to you. When someone wants to send encrypted information to you, then encrpyt the information using your public key. Only you are able to decrypt the information using your private key. Contrast this with the more traditional shared password based encryption schemes that require the sender and receiver to know the shared password. Public key algorithms eliminate the need to share passwords.
+ <para>Algorithms like Diffie-Hellman and RSA are known as public key exchange algorithms. The concept of public key algorithms is that you have two keys, one public that is available to everyone, and one that is private and known only to you. When someone wants to send encrypted information to you, then encrpyt the information using your public key. Only you are able to decrypt the information using your private key. Contrast this with the more traditional shared password based encryption schemes that require the sender and receiver to know the shared password. Public key algorithms eliminate the need to share passwords.
</para>
<para>
The JBossSX framework includes an implementation of SRP that consists of the following elements:
@@ -51,7 +49,7 @@
</listitem>
</itemizedlist>
<para>
- <xref linkend="The_Secure_Remote_Password_SRP_Protocol-The_JBossSX_components_of_the_SRP_client_server_framework."/> gives a diagram of the key components involved in the JBossSX implementation of the SRP client/server framework.
+ <xref linkend="The_Secure_Remote_Password_SRP_Protocol-The_JBossSX_components_of_the_SRP_client_server_framework."/> describes the key components involved in the JBossSX implementation of the SRP client/server framework.
</para>
<figure id="The_Secure_Remote_Password_SRP_Protocol-The_JBossSX_components_of_the_SRP_client_server_framework.">
<title>The JBossSX components of the SRP client-server framework.</title>
@@ -61,43 +59,48 @@
</imageobject>
</mediaobject>
</figure>
- <para>
- On the client side, SRP shows up as a custom JAAS <literal>LoginModule</literal> implementation that communicates to the authentication server through an <literal>org.jboss.security.srp.SRPServerInterface</literal> proxy. A client enables authentication using SRP by creating a login configuration entry that includes the <literal>org.jboss.security.srp.jaas.SRPLoginModule</literal>. This module supports the following configuration options:
+ <para>On the client side, SRP shows up as a custom JAAS <literal>LoginModule</literal> implementation that communicates to the authentication server through an <literal>org.jboss.security.srp.SRPServerInterface</literal> proxy. A client enables authentication using SRP by creating a login configuration entry that includes the <literal>org.jboss.security.srp.jaas.SRPLoginModule</literal>. This module supports the following configuration options:
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">principalClassName</emphasis>: This option is no longer supported. The principal class is now always <literal>org.jboss.security.srp.jaas.SRPPrincipal</literal>.
+ <variablelist>
+ <varlistentry>
+ <term>principalClassName</term>
+ <listitem>
+ <para>This option is no longer supported. The principal class is now always <literal>org.jboss.security.srp.jaas.SRPPrincipal</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>srpServerJndiName</term>
+ <listitem>
+ <para>The JNDI name of the <literal>SRPServerInterface</literal> object to use for communicating with the SRP authentication server. If both <literal>srpServerJndiName</literal> and <literal>srpServerRmiUrl</literal> options are specified, the <literal>srpServerJndiName</literal> is tried before <literal>srpServerRmiUrl</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>srpServerRmiUrl</term>
+ <listitem>
+ <para>The RMI protocol URL string for the location of the <literal>SRPServerInterface</literal> proxy to use for communicating with the SRP authentication server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>externalRandomA</term>
+ <listitem>
+ <para>A true/false flag indicating if the random component of the client public key A should come from the user callback. This can be used to input a strong cryptographic random number coming from a hardware token for example.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>hasAuxChallenge</term>
+ <listitem>
+ <para>A true/false flag indicating that a string will be sent to the server as an additional challenge for the server to validate. If the client session supports an encryption cipher then a temporary cipher will be created using the session private key and the challenge object sent as a <literal>javax.crypto.SealedObject</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>multipleSessions</term>
+ <listitem>
+ <para>a true/false flag indicating if a given client may have multiple SRP login sessions active simultaneously.
</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">srpServerJndiName</emphasis>: The JNDI name of the <literal>SRPServerInterface</literal> object to use for communicating with the SRP authentication server. If both <literal>srpServerJndiName</literal> and <literal>srpServerRmiUrl</literal> options are specified, the <literal>srpServerJndiName</literal> is tried before <literal>srpServerRmiUrl</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">srpServerRmiUrl</emphasis>: The RMI protocol URL string for the location of the <literal>SRPServerInterface</literal> proxy to use for communicating with the SRP authentication server.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">externalRandomA</emphasis>: A true/false flag indicating if the random component of the client public key A should come from the user callback. This can be used to input a strong cryptographic random number coming from a hardware token for example.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">hasAuxChallenge</emphasis>: A true/false flag indicating that a string will be sent to the server as an additional challenge for the server to validate. If the client session supports an encryption cipher then a temporary cipher will be created using the session private key and the challenge object sent as a <literal>javax.crypto.SealedObject</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">multipleSessions</emphasis>: a true/false flag indicating if a given client may have multiple SRP login sessions active simultaneously.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Any other options passed in that do not match one of the previous named options is treated as a JNDI property to use for the environment passed to the <literal>InitialContext</literal> constructor. This is useful if the SRP server interface is not available from the default <literal>InitialContext</literal>.
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>Any other options passed in that do not match one of the previous named options is treated as a JNDI property to use for the environment passed to the <literal>InitialContext</literal> constructor. This is useful if the SRP server interface is not available from the default <literal>InitialContext</literal>.
</para>
<para>
The <literal>SRPLoginModule</literal> needs to be configured along with the standard <literal>ClientLoginModule</literal> to allow the SRP authentication credentials to be used for validation of access to security Java EE components. An example login configuration entry that demonstrates such a setup is:
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Security_Event_Auditing.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Security_Event_Auditing.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Security_Event_Auditing.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -86,8 +86,7 @@
<step>
<title>Specify auditing levels system property</title>
<para>The auditing levels for Web applications must be specified using a system property in the <filename>run.bat</filename>, <filename>run.conf</filename> scripts. Alternatively, you can specify the system property in the <filename>/deploy/properties-service.xml</filename> file.</para>
- <para>EXAMPLES TO GO IN HERE</para>
- </step>
+<!--TODO: <para>EXAMPLES TO GO IN HERE</para>--> </step>
<step>
<title>Verify security auditing is functioning correctly</title>
<para>Once the system property is specified in the files, audit log entries will verify Web invocation success.</para>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Static_Security_Domains.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Static_Security_Domains.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Static_Security_Domains.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -8,7 +8,7 @@
<para>The standard way of configuring security domains for authentication and authorization in JBoss is to use the XML login configuration file. The login configuration policy defines a set of named security domains that each define a stack of login modules that will be called upon to authenticate and authorize users.
</para>
<para>
- The XML configuration file conforms to the DTD given by <xref linkend="Defining_Security_Domains-The_XMLLoginConfig_DTD"/>. This DTD can be found in <literal>docs/dtd/security_config.dtd</literal>.
+ The XML configuration file conforms to the DTD given by <xref linkend="Defining_Security_Domains-The_XMLLoginConfig_DTD"/>. This DTD can be found in <filename>docs/dtd/security_config.dtd</filename>.
</para>
<figure id="Defining_Security_Domains-The_XMLLoginConfig_DTD">
<title>The XMLLoginConfig DTD</title>
@@ -23,10 +23,11 @@
</imageobject>
</mediaobject>
</figure>
- <para>
- The following example shows a simple configuration named jmx-console that is backed by a single login module. The login module is configured by a simple set of name/value configuration pairs that have meaning to the login module in question. We'll see what these options mean later, for now we'll just be concerned with the structure of the configuration file.
+ <example id="exam-Login_Module_Intro_Example">
+ <title/>
+ <para>This exapmle describes a simple configuration named jmx-console that is backed by a single login module. The login module is configured by a simple set of name/value configuration pairs that have meaning to the login module in question. We'll see what these options mean later, for now we'll just be concerned with the structure of the configuration file.
</para>
- <programlisting language="XML" role="XML"><application-policy name="jmx-console">
+ <programlisting language="XML" role="XML"><application-policy name="jmx-console">
<authentication>
<login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
<module-option name="usersProperties">props/jmx-console-users.properties</module-option>
@@ -35,38 +36,46 @@
</authentication>
</application-policy>
</programlisting>
+ </example>
<para>
- The <literal>name</literal> attribute of the <literal>application-policy</literal> is the login configuration name. Applications policy elements are bound by that name in JNDI under the the <literal>java:/jaas</literal> context. Applications will link to security domains through this JNDI name in their deployment descriptors. (See the <literal>security-domain</literal> elements in <literal>jboss.xml</literal>, <literal>jboss-web.xml</literal> and <literal>jboss-service.xml</literal> files for examples)
+ The <literal>name</literal> attribute of the <markup>application-policy</markup> is the login configuration name. Applications policy elements are bound by that name in JNDI under the the <literal>java:/jaas</literal> context. Applications will link to security domains through this JNDI name in their deployment descriptors. (See the <markup>security-domain</markup> elements in <filename>jboss.xml</filename>, <filename>jboss-web.xml</filename> and <filename>jboss-service.xml</filename> files for examples)
</para>
<para>
- The <literal>code</literal> attribute of the <literal>login-module</literal> element specifies the class name of the login module implementation. The <literal>required</literal> flag attribute controls the overall behavior of the authentication stack. The allowed values and meanings are:
+ The <literal>code</literal> attribute of the <markup>login-module</markup> element specifies the class name of the login module implementation. The <literal>required</literal> flag attribute controls the overall behavior of the authentication stack. The allowed values and meanings are:
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">required</emphasis>: The login module is required to succeed for the authentication to be successful. If any required module fails, the authentication will fail. The remaining login modules in the stack will be called regardless of the outcome of the authentication.
+ <variablelist>
+ <varlistentry>
+ <term>required</term>
+ <listitem>
+ <para>The login module is required to succeed for the authentication to be successful. If any required module fails, the authentication will fail. The remaining login modules in the stack will be called regardless of the outcome of the authentication.
</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">requisite</emphasis>: The login module is required to succeed. If it succeeds, authentication continues down the login stack. If it fails, control immediately returns to the application.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>requisite</term>
+ <listitem>
+ <para>The login module is required to succeed. If it succeeds, authentication continues down the login stack. If it fails, control immediately returns to the application.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>sufficient</term>
+ <listitem>
+ <para>The login module is not required to succeed. If it does succeed, control immediately returns to the application. If it fails, authentication continues down the login stack.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>optional</term>
+ <listitem>
+ <para>The login module is not required to succeed. Authentication still continues to proceed down the login stack regardless of whether the login module succeeds or fails.
</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">sufficient</emphasis>: The login module is not required to succeed. If it does succeed, control immediately returns to the application. If it fails, authentication continues down the login stack.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">optional</emphasis>: The login module is not required to succeed. Authentication still continues to proceed down the login stack regardless of whether the login module succeeds or fails.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The following example shows the definition of a security domain that uses multiple login modules. Since both modules are marked as sufficient, only one of them need to succeed for login to proceed.
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <example>
+ <title>Security Domain using Multiple Login Modules</title>
+ <para>This example shows the definition of a security domain that uses multiple login modules. Since both modules are marked as sufficient, only one of them need to succeed for login to proceed.
</para>
- <programlisting language="XML" role="XML"><application-policy name="todo">
+ <programlisting language="XML" role="XML"><application-policy name="todo">
<authentication>
<login-module code="org.jboss.security.auth.spi.LdapLoginModule"
flag="sufficient">
@@ -79,7 +88,8 @@
</authentication>
</application-policy>
</programlisting>
+ </example>
<para>
- Each login module has its own set of configuration options. These are set as name/value pairs using the <literal>module-option</literal> elements. We'll cover module options in more depth when we look at the individual login modules available in JBoss AS.
+ Each login module has its own set of configuration options. These are set as name/value pairs using the <markup>module-option</markup> elements. Module options are covered in more depth when we look at the individual login modules available in JBoss AS.
</para>
</chapter>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-BaseCertLoginModule.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-BaseCertLoginModule.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-BaseCertLoginModule.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -5,11 +5,11 @@
]>
<section id="sect-BaseCertLoginModule">
<title>BaseCertLoginModule</title>
- <para>
- This is a login module which authenticates users based on X509 certificates. A typical use case for this login module is <literal>CLIENT-CERT</literal> authentication in the web tier. This login module only performs authentication. You need to combine it with another login module capable of acquiring the authorization roles to completely define access to a secured web or EJB component. Two subclasses of this login module, <literal>CertRolesLoginModule</literal> and <literal>DatabaseCertLoginModule</literal> extend the behavior to obtain the authorization roles from either a properties file or database.
+ <para><literal>BaseCertLoginModule</literal> authenticates users based on X509 certificates. A typical use case for this login module is <literal>CLIENT-CERT</literal> authentication in the web tier. </para>
+ <para>This login module only performs authentication: you must combine it with another login module capable of acquiring authorization roles to completely define access to a secured web or EJB component. Two subclasses of this login module, <literal>CertRolesLoginModule</literal> and <literal>DatabaseCertLoginModule</literal> extend the behavior to obtain the authorization roles from either a properties file or database.
</para>
<para>
- The <literal>BaseCertLoginModule</literal> needs a <literal>KeyStore</literal> to perform user validation. This is obtained through a <literal>org.jboss.security.SecurityDomain</literal> implementation. Typically, the <literal>SecurityDomain</literal> implementation is configured using the <literal>org.jboss.security.plugins.JaasSecurityDomain</literal> MBean as shown in this <literal>jboss-service.xml</literal> configuration fragment:
+ The <literal>BaseCertLoginModule</literal> needs a <literal>KeyStore</literal> to perform user validation. This is obtained through a <literal>org.jboss.security.SecurityDomain</literal> implementation. Typically, the <literal>SecurityDomain</literal> implementation is configured using the <literal>org.jboss.security.plugins.JaasSecurityDomain</literal> MBean as shown in this <filename>jboss-service.xml</filename> configuration fragment:
</para>
<programlisting language="XML" role="XML"><mbean code="org.jboss.security.plugins.JaasSecurityDomain"
name="jboss.ch8:service=SecurityDomain">
@@ -20,10 +20,15 @@
<attribute name="KeyStorePass">unit-tests-server</attribute>
</mbean>
</programlisting>
- <para>
- This creates a security domain with the name <literal>jmx-console</literal> whose <literal>SecurityDomain</literal> implementation is available via JNDI under the name <literal>java:/jaas/jmx-console</literal> following the JBossSX security domain naming pattern. To secure a web application such as the <literal>jmx-console.war</literal> using client certs and role based authorization, one would first modify the <literal>web.xml</literal> to declare the resources to be secured, along with the allowed roles and security domain to be used for authentication and authorization.
+ <para>The configuration creates a security domain with the name <literal>jmx-console</literal>, with a <literal>SecurityDomain</literal> implementation available through JNDI under the name <literal>java:/jaas/jmx-console</literal>. The security domain follows the JBossSX security domain naming pattern. </para>
+ <procedure id="proc-Secure_Web_Applications_With_Certs_Role_Based_Authorization">
+ <title>Secure Web Applications with Certificates and Role-based Authorization</title>
+ <para>This procedure describes how to secure a web application, such as the <filename>jmx-console.war,</filename> using client certs and role based authorization.</para>
+ <step>
+ <title>Declare Resources and Roles</title>
+ <para>Modify <filename>web.xml</filename> to declare the resources to be secured along with the allowed roles and security domain to be used for authentication and authorization.
</para>
- <programlisting language="XML" role="XML"><?xml version="1.0"?>
+ <programlisting language="XML" role="XML"><?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
@@ -52,17 +57,19 @@
</security-role>
</web-app>
</programlisting>
- <para>
- Next we, need to specify the JBoss security domain in <literal>jboss-web.xml</literal>:
- </para>
- <programlisting language="XML" role="XML"><jboss-web>
+ </step>
+ <step>
+ <title>Specify the JBoss Security Domain</title>
+ <para>In the <literal>jboss-web.xml</literal> file, specify the required security domain.</para>
+ <programlisting language="XML" role="XML"><jboss-web>
<security-domain>jmx-console</security-domain>
</jboss-web>
</programlisting>
- <para>
- Finally, you need to define the login module configuration for the jmx-console security domain you just specified. This is done in the <literal>conf/login-config.xml</literal> file.
- </para>
- <programlisting language="XML" role="XML"><application-policy name="jmx-console">
+ </step>
+ <step>
+ <title>Specify Login Module Configuration</title>
+ <para>Define the login module configuration for the jmx-console security domain you just specified. This is done in the <literal>conf/login-config.xml</literal> file.</para>
+ <programlisting language="XML" role="XML"><application-policy name="jmx-console">
<authentication>
<login-module code="org.jboss.security.auth.spi.BaseCertLoginModule"
flag="required">
@@ -78,10 +85,14 @@
</authentication>
</application-policy>
</programlisting>
- <para>
- Here the <literal>BaseCertLoginModule</literal> is used for authentication of the client cert, and the <literal>UsersRolesLoginModule</literal> is only used for authorization due to the <literal>password-stacking=useFirstPass</literal> option. Both the <literal>localhost.keystore</literal> and the <literal>jmx-console-roles.properties</literal> need an entry that maps to the principal associated with the client cert. By default, the principal is created using the client certificate distinguished name. Consider the following certificate:
+ </step>
+ </procedure>
+ <para><xref linkend="proc-Secure_Web_Applications_With_Certs_Role_Based_Authorization"/>shows the <literal>BaseCertLoginModule</literal> is used for authentication of the client cert, and the <literal>UsersRolesLoginModule</literal> is only used for authorization due to the <literal>password-stacking=useFirstPass</literal> option. Both the <literal>localhost.keystore</literal> and the <literal>jmx-console-roles.properties</literal> require an entry that maps to the principal associated with the client cert.</para>
+ <para>By default, the principal is created using the client certificate distinguished name, such as the DN specified in <xref linkend="exam-Certificate_Example"/>.
</para>
- <screen>[conf]$ keytool -printcert -file unit-tests-client.export
+ <example id="exam-Certificate_Example">
+ <title>Certificate Example</title>
+ <screen>[conf]$ keytool -printcert -file unit-tests-client.export
Owner: CN=unit-tests-client, OU=JBoss Inc., O=JBoss Inc., ST=Washington, C=US
Issuer: CN=jboss.com, C=US, ST=Washington, L=Snoqualmie Pass, EMAILADDRESS=admin
@jboss.com, OU=QA, O=JBoss Inc.
@@ -90,8 +101,9 @@
Certificate fingerprints:
MD5: 4A:9C:2B:CD:1B:50:AA:85:DD:89:F6:1D:F5:AF:9E:AB
SHA1: DE:DE:86:59:05:6C:00:E8:CC:C0:16:D3:C2:68:BF:95:B8:83:E9:58</screen>
+ </example>
<para>
- The <literal>localhost.keystore</literal> would need this cert stored with an alias of <literal>CN=unit-tests-client, OU=JBoss Inc., O=JBoss Inc., ST=Washington, C=US</literal> and the <literal>jmx-console-roles.properties</literal> would also need an entry for the same entry. Since the DN contains many characters that are normally treated as delimiters, you will need to escape the problem characters using a backslash ('<literal>\</literal>') as shown here:
+ The <literal>localhost.keystore</literal> would need the certificate in <xref linkend="exam-Certificate_Example"/> stored with an alias of <literal>CN=unit-tests-client, OU=JBoss Inc., O=JBoss Inc., ST=Washington, C=US</literal>. The <literal>jmx-console-roles.properties</literal> would also need an entry for the same entry. Since the DN contains characters that are normally treated as delimiters, you must escape the problem characters using a backslash ('<literal>\</literal>') as illustrated below.
</para>
<screen># A sample roles.properties file for use with the UsersRolesLoginModule
CN\=unit-tests-client,\ OU\=JBoss\ Inc.,\ O\=JBoss\ Inc.,\ ST\=Washington,\ C\=US=JBossAdmin
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-ClientLoginModule.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-ClientLoginModule.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-ClientLoginModule.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -5,34 +5,35 @@
]>
<section id="sect-ClientLoginModule">
<title>ClientLoginModule</title>
+ <para><literal>ClientLoginModule</literal> is an implementation of <literal>LoginModule</literal> for use by JBoss clients for the establishment of the caller identity and credentials. This simply sets the <literal>org.jboss.security.SecurityAssociation.principal</literal> to the value of the <literal>NameCallback</literal> filled in by the <literal>callbackhandler</literal>, and the <literal>org.jboss.security.SecurityAssociation.credential</literal> to the value of the <literal>PasswordCallback</literal> filled in by the <literal>callbackhandler</literal>. </para>
+ <para> <literal>ClientLoginModule</literal> is the only supported mechanism for a client to establish the current thread's caller. Both stand-alone client applications, and server environments (acting as JBoss EJB clients where the security environment has not been configured to use JBossSX transparently) must use <literal>ClientLoginModule</literal>. </para>
<para>
- The <literal>ClientLoginModule</literal> is an implementation of <literal>LoginModule</literal> for use by JBoss clients for the establishment of the caller identity and credentials. This simply sets the <literal>org.jboss.security.SecurityAssociation.principal</literal> to the value of the <literal>NameCallback</literal> filled in by the <literal>callbackhandler</literal>, and the <literal>org.jboss.security.SecurityAssociation.credential</literal> to the value of the <literal>PasswordCallback</literal> filled in by the <literal>callbackhandler</literal>. This is the only supported mechanism for a client to establish the current thread's caller. Both stand-alone client applications and server environments, acting as JBoss EJB clients where the security environment has not been configured to use JBossSX transparently, need to use the <literal>ClientLoginModule</literal>. Of course, you could always set the <literal>org.jboss.security.SecurityAssociation</literal> !
information directly, but this is considered an internal API that is subject to change without notice.
- </para>
- <para>
Note that this login module does not perform any authentication. It merely copies the login information provided to it into the JBoss server EJB invocation layer for subsequent authentication on the server. If you need to perform client-side authentication of users you would need to configure another login module in addition to the <literal>ClientLoginModule</literal>.
</para>
- <para>
- The supported login module configuration options include the following:
+ <para>The supported login module configuration options include the following:
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">multi-threaded</emphasis>: When the multi-threaded option is set to true, each login thread has its own principal and credential storage. This is useful in client environments where multiple user identities are active in separate threads. When true, each separate thread must perform its own login. When set to false the login identity and credentials are global variables that apply to all threads in the VM. The default for this option is false.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">password-stacking</emphasis>: When <literal>password-stacking</literal> option is set to <literal>useFirstPass</literal>, this module first looks for a shared username and password using <literal>javax.security.auth.login.name</literal> and <literal>javax.security.auth.login.password</literal> respectively in the login module shared state map. This allows a module configured prior to this one to establish a valid username and password that should be passed to JBoss. You would use this option if you want to perform client-side authentication of clients using some other login module such as the <literal>LdapLoginModule</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">restore-login-identity</emphasis>: When <literal>restore-login-identity</literal> is true, the <literal>SecurityAssociation</literal> principal and credential seen on entry to the <literal>login()</literal> method are saved and restored on either abort or logout. When false (the default), the abort and logout simply clear the <literal>SecurityAssociation</literal>. A <literal>restore-login-identity</literal> of true is needed if one need to change identities and then restore the original caller identity.
- </para>
- </listitem>
- </itemizedlist>
+ <variablelist>
+ <varlistentry>
+ <term>multi-threaded</term>
+ <listitem>
+ <para>Value that specifies the way login threads connect to principal and credential storage sources. When set to true, each login thread has its own principal and credential storage and each separate thread must perform its own login. This is useful in client environments where multiple user identities are active in separate threads. When set to false the login identity and credentials are global variables that apply to all threads in the VM. The default setting is <literal>false</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>password-stacking</term>
+ <listitem>
+ <para>Activates client-side authentication of clients using other login modules such as the <literal>LdapLoginModule</literal>. When <literal>password-stacking</literal> option is set to <literal>useFirstPass</literal>, the module first looks for a shared username and password using <literal>javax.security.auth.login.name</literal> and <literal>javax.security.auth.login.password</literal> respectively in the login module shared state map. This allows a module configured prior to this one to establish a valid JBoss username and password. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>restore-login-identity</term>
+ <listitem>
+ <para>Value that specifies whether the <literal>SecurityAssociation</literal> principal and credential seen on entry to the <methodname>login()</methodname> method are saved and restored on either abort or logout. This is necessary if you must change identities and then restore the original caller identity. If set to <literal>true</literal>, the principal and credential information is saved and restored on abort or logout. If set to <literal>false</literal>, abort and logout clear the <literal>SecurityAssociation</literal>. The default value is <literal>false</literal>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<para>
- A sample login configuration for <literal>ClientLoginModule</literal> is the default configuration entry found in the JBoss distribution <literal>client/auth.conf</literal> file. The configuration is:
+ A sample login configuration for <literal>ClientLoginModule</literal> is the default configuration entry found in the JBoss distribution <filename>client/auth.conf</filename> file. The configuration is:
</para>
<programlisting>other {
// Put your login modules that work without jBoss here
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Custom_LoginModule_Example.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Custom_LoginModule_Example.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Custom_LoginModule_Example.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -5,14 +5,14 @@
]>
<section id="sect-Custom_LoginModule_Example">
<title>Custom LoginModule Example</title>
- <para>
- In this section we will develop a custom login module example. It will extend the <literal>UsernamePasswordLoginModule</literal> and obtains a user's password and role names from a JNDI lookup. The idea is that there is a JNDI context that will return a user's password if you perform a lookup on the context using a name of the form <literal>password/<username></literal> where <literal><username></literal> is the current user being authenticated. Similarly, a lookup of the form <literal>roles/<username></literal> returns the requested user's roles.
+ <para>The following information will help you to create a custom Login Module example that extends the <literal>UsernamePasswordLoginModule</literal> and obtains a user's password and role names from a JNDI lookup. </para>
+ <para>At the end of this section you will have created a custom JNDI context login module that will return a user's password if you perform a lookup on the context using a name of the form <literal>password/<username></literal> (where <literal><username></literal> is the current user being authenticated). Similarly, a lookup of the form <literal>roles/<username></literal> returns the requested user's roles.
</para>
- <para>
- The source code for the example is located in the <literal>src/main/org/jboss/book/security/ex2</literal> directory of the book examples. <xref linkend="A_Custom_LoginModule_Example-_A_JndiUserAndPass_custom_login_module"/> shows the source code for the <literal>JndiUserAndPass</literal> custom login module. Note that because this extends the JBoss <literal>UsernamePasswordLoginModule</literal>, all the <literal>JndiUserAndPass</literal> does is obtain the user's password and roles from the JNDI store. The <literal>JndiUserAndPass</literal> does not concern itself with the JAAS <literal>LoginModule</literal> operations.
+ <para>The source code for the example is located in the <literal>src/main/org/jboss/book/security/ex2</literal> directory of the book examples. <xref linkend="A_Custom_LoginModule_Example-_A_JndiUserAndPass_custom_login_module"/> shows the source code for the <literal>JndiUserAndPass</literal> custom login module. </para>
+ <para>Note that because this extends the JBoss <literal>UsernamePasswordLoginModule</literal>, all the <literal>JndiUserAndPass</literal> does is obtain the user's password and roles from the JNDI store. The <literal>JndiUserAndPass</literal> does not interact with the JAAS <literal>LoginModule</literal> operations.
</para>
<example id="A_Custom_LoginModule_Example-_A_JndiUserAndPass_custom_login_module">
- <title> A JndiUserAndPass custom login module</title>
+ <title> JndiUserAndPass Custom Login Module</title>
<programlisting language="Java" role="JAVA">package org.jboss.book.security.ex2;
import java.security.acl.Group;
@@ -103,7 +103,8 @@
</programlisting>
</example>
<para>
- The details of the JNDI store are found in the <literal>org.jboss.book.security.ex2.service.JndiStore</literal> MBean. This service binds an <literal>ObjectFactory</literal> that returns a <literal>javax.naming.Context</literal> proxy into JNDI. The proxy handles lookup operations done against it by checking the prefix of the lookup name against <literal>password</literal> and <literal>roles</literal>. When the name begins with <literal>password</literal>, a user's password is being requested. When the name begins with <literal>roles</literal> the user's roles are being requested. The example implementation always returns a password of <literal>theduke</literal> and an array of roles names equal to <literal>{"TheDuke", "Echo"}</literal> regardless of what the username is. You can experiment with other implementations as you wish.
+ The details of the JNDI store are found in the <literal>org.jboss.book.security.ex2.service.JndiStore</literal> MBean. This service binds an <literal>ObjectFactory</literal> that returns a <literal>javax.naming.Context</literal> proxy into JNDI. The proxy handles lookup operations done against it by checking the prefix of the lookup name against <literal>password</literal> and <literal>roles</literal>. </para>
+ <para>When the name begins with <literal>password</literal>, a user's password is being requested. When the name begins with <literal>roles</literal> the user's roles are being requested. The example implementation always returns a password of <literal>theduke</literal> and an array of roles names equal to <literal>{"TheDuke", "Echo"}</literal> regardless of what the username is. You can experiment with other implementations as you wish.
</para>
<para>
The example code includes a simple session bean for testing the custom login module. To build, deploy and run the example, execute the following command in the examples directory.
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Custom_Modules.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Custom_Modules.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Custom_Modules.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,7 +6,8 @@
<section id="sect-Custom_Modules">
<title>Custom Modules</title>
<para>
- If the login modules bundled with the JBossSX framework do not work with your security environment, you can write your own custom login module implementation that does. Recall from the section on the <literal>JaasSecurityManager</literal> architecture that the <literal>JaasSecurityManager</literal> expected a particular usage pattern of the <literal>Subject</literal> principals set. You need to understand the JAAS Subject class's information storage features and the expected usage of these features to be able to write a login module that works with the <literal>JaasSecurityManager</literal>. This section examines this requirement and introduces two abstract base <literal>LoginModule</literal> implementations that can help you implement your own custom login modules.
+ If the login modules bundled with the JBossSX framework do not work with your security environment, you can write your own custom login module implementation. The <literal>JaasSecurityManager</literal> requires a particular usage pattern of the <literal>Subject</literal> principals set. You must understand the JAAS Subject class's information storage features and the expected usage of these features to write a login module that works with the <literal>JaasSecurityManager</literal>. </para>
+ <para>This section examines this requirement and introduces two abstract base <literal>LoginModule</literal> implementations that can help you implement custom login modules.
</para>
<para>
You can obtain security information associated with a <literal>Subject</literal> by using the following methods:
@@ -19,18 +20,32 @@
java.util.Set getPublicCredentials(java.lang.Class c)
</programlisting>
<para>
- For <literal>Subject</literal> identities and roles, JBossSX has selected the most natural choice: the principals sets obtained via <literal>getPrincipals()</literal> and <literal>getPrincipals(java.lang.Class)</literal>. The usage pattern is as follows:
+ For <literal>Subject</literal> identities and roles, JBossSX has selected the most logical choice: the principals sets obtained via <literal>getPrincipals()</literal> and <literal>getPrincipals(java.lang.Class)</literal>. The usage pattern is as follows:
</para>
<itemizedlist>
<listitem>
- <para>
- User identities (username, social security number, employee ID, and so on) are stored as <literal>java.security.Principal</literal> objects in the <literal>Subject</literal><literal>Principals</literal> set. The <literal>Principal</literal> implementation that represents the user identity must base comparisons and equality on the name of the principal. A suitable implementation is available as the <literal>org.jboss.security.SimplePrincipal</literal> class. Other <literal>Principal</literal> instances may be added to the <literal>Subject</literal><literal>Principals</literal> set as needed.
+ <para>User identities (for example; username, social security number, employee ID) are stored as <literal>java.security.Principal</literal> objects in the <literal>Subject</literal><literal>Principals</literal> set. The <literal>Principal</literal> implementation that represents the user identity must base comparisons and equality on the name of the principal. A suitable implementation is available as the <literal>org.jboss.security.SimplePrincipal</literal> class. Other <literal>Principal</literal> instances may be added to the <literal>Subject</literal><literal>Principals</literal> set as needed.
</para>
</listitem>
<listitem>
- <para>
- The assigned user roles are also stored in the <literal>Principals</literal> set, but they are grouped in named role sets using <literal>java.security.acl.Group</literal> instances. The <literal>Group</literal> interface defines a collection of <literal>Principal</literal>s and/or <literal>Group</literal>s, and is a subinterface of <literal>java.security.Principal</literal>. Any number of role sets can be assigned to a <literal>Subject</literal>. Currently, the JBossSX framework uses two well-known role sets with the names <literal>Roles</literal> and <literal>CallerPrincipal</literal>. The <literal>Roles</literal> Group is the collection of <literal>Principal</literal>s for the named roles as known in the application domain under which the <literal>Subject</literal> has been authenticated. This role set is used by methods like the <literal>EJBContext.isCallerInRole(String)</literal>, which EJBs can use to see if the current caller belongs to the named application dom!
ain role. The security interceptor logic that performs method permission checks also uses this role set. The <literal>CallerPrincipal</literal><literal>Group</literal> consists of the single <literal>Principal</literal> identity assigned to the user in the application domain. The <literal>EJBContext.getCallerPrincipal() </literal>method uses the <literal>CallerPrincipal</literal> to allow the application domain to map from the operation environment identity to a user identity suitable for the application. If a <literal>Subject</literal> does not have a <literal>CallerPrincipal</literal><literal>Group</literal>, the application identity is the same as operational environment identity.
+ <para>Assigned user roles are also stored in the <literal>Principals</literal> set, and are grouped in named role sets using <literal>java.security.acl.Group</literal> instances. The <literal>Group</literal> interface defines a collection of <literal>Principal</literal>s and/or <literal>Group</literal>s, and is a subinterface of <literal>java.security.Principal</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Any number of role sets can be assigned to a <literal>Subject</literal>. </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>The JBossSX framework uses two well-known role sets with the names <literal>Roles</literal> and <literal>CallerPrincipal</literal>. </para>
+ <itemizedlist>
+ <listitem>
+ <para>The <literal>Roles</literal> group is the collection of <literal>Principal</literal>s for the named roles as known in the application domain under which the <literal>Subject</literal> has been authenticated. This role set is used by methods like the <literal>EJBContext.isCallerInRole(String)</literal>, which EJBs can use to see if the current caller belongs to the named application domain role. The security interceptor logic that performs method permission checks also uses this role set. </para>
+ </listitem>
+ <listitem>
+ <para>The <literal>CallerPrincipal</literal><literal>Group</literal> consists of the single <literal>Principal</literal> identity assigned to the user in the application domain. The <literal>EJBContext.getCallerPrincipal() </literal>method uses the <literal>CallerPrincipal</literal> to allow the application domain to map from the operation environment identity to a user identity suitable for the application. If a <literal>Subject</literal> does not have a <literal>CallerPrincipal</literal><literal>Group</literal>, the application identity is the same as operational environment identity.
</para>
+ </listitem>
+ </itemizedlist>
</listitem>
</itemizedlist>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="sect-Subject_Usage_Pattern_Support.xml" encoding="UTF-8"/>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-DatabaseServerLoginModule.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-DatabaseServerLoginModule.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-DatabaseServerLoginModule.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -5,52 +5,72 @@
]>
<section id="sect-DatabaseServerLoginModule">
<title>DatabaseServerLoginModule</title>
- <para>
- The <literal>DatabaseServerLoginModule</literal> is a JDBC based login module that supports authentication and role mapping. You would use this login module if you have your username, password and role information relational database. The <literal>DatabaseServerLoginModule</literal> is based on two logical tables:
+ <para>The <literal>DatabaseServerLoginModule</literal> is a Java Database Connectivity-based (JDBC) login module that supports authentication and role mapping. Use this login module if you have your username, password and role information relational database. </para>
+ <note>
+ <para>
+ This module supports password stacking, password hashing and unathenticated identity.
</para>
+ </note>
+ <para>The <literal>DatabaseServerLoginModule</literal> is based on two logical tables:
+ </para>
<programlisting>Table Principals(PrincipalID text, Password text)
Table Roles(PrincipalID text, Role text, RoleGroup text)
</programlisting>
- <para>
- The <literal>Principals</literal> table associates the user <literal>PrincipalID</literal> with the valid password and the <literal>Roles</literal> table associates the user <literal>PrincipalID</literal> with its role sets. The roles used for user permissions must be contained in rows with a <literal>RoleGroup</literal> column value of <literal>Roles</literal>. The tables are logical in that you can specify the SQL query that the login module uses. All that is required is that the <literal>java.sql.ResultSet</literal> has the same logical structure as the <literal>Principals</literal> and <literal>Roles</literal> tables described previously. The actual names of the tables and columns are not relevant as the results are accessed based on the column index. To clarify this notion, consider a database with two tables, <literal>Principals</literal> and <literal>Roles</literal>, as already declared. The following statements build the tables to contain a <literal>PrincipalID!
</literal><literal>java</literal> with a <literal>Password</literal> of <literal>echoman</literal> in the <literal>Principals</literal> table, a <literal>PrincipalID</literal><literal>java</literal> with a role named <literal>Echo</literal> in the <literal>Roles</literal><literal>RoleGroup</literal> in the <literal>Roles</literal> table, and a <literal>PrincipalID</literal><literal>java</literal> with a role named <literal>caller_java</literal> in the <literal>CallerPrincipal</literal><literal>RoleGroup</literal> in the <literal>Roles</literal> table:
- </para>
- <programlisting>INSERT INTO Principals VALUES('java', 'echoman')
-INSERT INTO Roles VALUES('java', 'Echo', 'Roles')
-INSERT INTO Roles VALUES('java', 'caller_java', 'CallerPrincipal')
-</programlisting>
- <para>
- The supported login module configuration options include the following:
- </para>
+ <para>The <literal>Principals</literal> table associates the user <literal>PrincipalID</literal> with the valid password and the <literal>Roles</literal> table associates the user <literal>PrincipalID</literal> with its role sets. The roles used for user permissions must be contained in rows with a <literal>RoleGroup</literal> column value of <literal>Roles</literal>. </para>
+ <para>The tables are logical in that you can specify the SQL query that the login module uses. The only requirement is that the <literal>java.sql.ResultSet</literal> has the same logical structure as the <literal>Principals</literal> and <literal>Roles</literal> tables described previously. The actual names of the tables and columns are not relevant as the results are accessed based on the column index. </para>
+ <para>To clarify this notion, consider a database with two tables, <literal>Principals</literal> and <literal>Roles</literal>, as already declared. The following statements populate the tables with the following data:</para>
<itemizedlist>
<listitem>
- <para>
- <emphasis role="bold">dsJndiName</emphasis>: The JNDI name for the <literal>DataSource</literal> of the database containing the logical <literal>Principals</literal> and <literal>Roles</literal> tables. If not specified this defaults to <literal>java:/DefaultDS</literal>.
- </para>
+ <para><literal>PrincipalID</literal><literal>java</literal> with a <literal>Password</literal> of <literal>echoman</literal> in the <literal>Principals</literal> table</para>
</listitem>
<listitem>
- <para>
- <emphasis role="bold">principalsQuery</emphasis>: The prepared statement query equivalent to: <literal>select Password from Principals where PrincipalID=?</literal>. If not specified this is the exact prepared statement that will be used.
- </para>
+ <para><literal>PrincipalID</literal><literal>java</literal> with a role named <literal>Echo</literal> in the <literal>Roles</literal><literal>RoleGroup</literal> in the <literal>Roles</literal> table</para>
</listitem>
<listitem>
- <para>
- <emphasis role="bold">rolesQuery</emphasis>: The prepared statement query equivalent to: <literal>select Role, RoleGroup from Roles where PrincipalID=?</literal>. If not specified this is the exact prepared statement that will be used.
- </para>
+ <para><literal>PrincipalID</literal><literal>java</literal> with a role named <literal>caller_java</literal> in the <literal>CallerPrincipal</literal><literal>RoleGroup</literal> in the <literal>Roles</literal> table</para>
</listitem>
- <listitem>
- <para>
- <emphasis role="bold">ignorePasswordCase</emphasis>: A boolean flag indicating if the password comparison should ignore case. This can be useful for hashed password encoding where the case of the hashed password is not significant.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">principalClass</emphasis>: An option that specifies a <literal>Principal</literal> implementation class. This must support a constructor taking a string argument for the principal name.
- </para>
- </listitem>
</itemizedlist>
+ <programlisting>INSERT INTO Principals VALUES('java', 'echoman')
+INSERT INTO Roles VALUES('java', 'Echo', 'Roles')
+INSERT INTO Roles VALUES('java', 'caller_java', 'CallerPrincipal')
+</programlisting>
<para>
- As an example <literal>DatabaseServerLoginModule</literal> configuration, consider a custom table schema like the following:
+ The supported login module configuration options include the following:
</para>
+ <variablelist>
+ <varlistentry>
+ <term>dsJndiName</term>
+ <listitem>
+ <para>The JNDI name for the <literal>DataSource</literal> of the database containing the logical <literal>Principals</literal> and <literal>Roles</literal> tables. If not specified this defaults to <literal>java:/DefaultDS</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>principalsQuery</term>
+ <listitem>
+ <para>The prepared statement query equivalent to: <literal>select Password from Principals where PrincipalID=?</literal>. If not specified this is the exact prepared statement that will be used.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>rolesQuery</term>
+ <listitem>
+ <para>The prepared statement query equivalent to: <literal>select Role, RoleGroup from Roles where PrincipalID=?</literal>. If not specified this is the exact prepared statement that will be used.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ignorePasswordCase</term>
+ <listitem>
+ <para>A boolean flag indicating if the password comparison should ignore case. This can be useful for hashed password encoding where the case of the hashed password is not significant.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>principalClass</term>
+ <listitem>
+ <para>An option that specifies a <literal>Principal</literal> implementation class. This must support a constructor taking a string argument for the principal name.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>An example <literal>DatabaseServerLoginModule</literal> configuration could be constructed as follows:
+ </para>
<programlisting>CREATE TABLE Users(username VARCHAR(64) PRIMARY KEY, passwd VARCHAR(64))
CREATE TABLE UserRoles(username VARCHAR(64), userRoles VARCHAR(32))
</programlisting>
@@ -72,7 +92,4 @@
</application-policy>
</policy>
</programlisting>
- <para>
- This module supports password stacking, password hashing and unathenticated identity.
- </para>
</section>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-EJB_Method_Permissions.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-EJB_Method_Permissions.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-EJB_Method_Permissions.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -17,10 +17,10 @@
</mediaobject>
</figure>
<para>
- Each <literal>method-permission</literal> element contains one or more role-name child elements that define the logical roles that are allowed to access the EJB methods as identified by method child elements. You can also specify an <literal>unchecked</literal> element instead of the <literal>role-name</literal> element to declare that any authenticated user can access the methods identified by method child elements. In addition, you can declare that no one should have access to a method that has the <literal>exclude-list</literal> element. If an EJB has methods that have not been declared as accessible by a role using a <literal>method-permission</literal> element, the EJB methods default to being excluded from use. This is equivalent to defaulting the methods into the <literal>exclude-list</literal>.
+ Each <markup>method-permission</markup> element contains one or more role-name child elements that define the logical roles that are allowed to access the EJB methods as identified by method child elements. You can also specify an <markup>unchecked</markup> element instead of the <markup>role-name</markup> element to declare that any authenticated user can access the methods identified by method child elements. In addition, you can declare that no one should have access to a method that has the <markup>exclude-list</markup> element. If an EJB has methods that have not been declared as accessible by a role using a <markup>method-permission</markup> element, the EJB methods default to being excluded from use. This is equivalent to defaulting the methods into the <literal>exclude-list</literal>.
</para>
<figure id="EJB_method_permissions-The_method_element">
- <title>The method element</title>
+ <title><method> element</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/j2ee_method.jpg"/>
@@ -66,13 +66,13 @@
The method must be defined in the specified enterprise bean's home or remote interface. The method-param element values are the fully qualified name of the corresponding method parameter type. If there are multiple methods with the same overloaded signature, the permission applies to all of the matching overloaded methods.
</para>
<para>
- The optional <literal>method-intf</literal> element can be used to differentiate methods with the same name and signature that are defined in both the home and remote interfaces of an enterprise bean.
+ The optional <markup>method-intf</markup> element can be used to differentiate methods with the same name and signature that are defined in both the home and remote interfaces of an enterprise bean.
</para>
<para>
- <xref linkend="EJB_method_permissions-An_ejb_jar.xml_descriptor_fragment_that_illustrates_the_method_permission_element_usage."/> provides complete examples of the <literal>method-permission</literal> element usage.
+ <xref linkend="EJB_method_permissions-An_ejb_jar.xml_descriptor_fragment_that_illustrates_the_method_permission_element_usage."/> provides complete examples of the <markup>method-permission</markup> element usage.
</para>
<example id="EJB_method_permissions-An_ejb_jar.xml_descriptor_fragment_that_illustrates_the_method_permission_element_usage.">
- <title>An ejb-jar.xml descriptor fragment that illustrates the method-permission element usage.</title>
+ <title><method-permission> element usage</title>
<programlisting language="XML" role="XML"><ejb-jar>
<assembly-descriptor>
<method-permission>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Enabling_Declarative_Security.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Enabling_Declarative_Security.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Enabling_Declarative_Security.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,6 +6,7 @@
<section id="J2EE_Declarative_Security_Overview-Enabling_Declarative_Security_in_JBoss">
<title>Enabling Declarative Security</title>
<para>
- The Java EE security elements that have been covered so far describe the security requirements only from the application's perspective. Because Java EE security elements declare logical roles, the application deployer maps the roles from the application domain onto the deployment environment. The Java EE specifications omit these application server-specific details. In JBoss, mapping the application roles onto the deployment environment entails specifying a security manager that implements the Java EE security model using JBoss server specific deployment descriptors. The details behind the security configuration are discussed in <xref linkend="A_Custom_LoginModule_Example-_A_JndiUserAndPass_custom_login_module"/>.
+ The Java EE security elements that have been covered so far describe the security requirements only from the application's perspective. Because Java EE security elements declare logical roles, the application deployer maps the roles from the application domain onto the deployment environment. The Java EE specifications omit these application server-specific details. </para>
+ <para>To map application roles onto the deployment environment, you must specify a security manager that implements the Java EE security model using JBoss server specific deployment descriptors. The details behind the security configuration are discussed in <xref linkend="A_Custom_LoginModule_Example-_A_JndiUserAndPass_custom_login_module"/>.
</para>
</section>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-How_JaasSecurityManager_Uses_JAAS.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-How_JaasSecurityManager_Uses_JAAS.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-How_JaasSecurityManager_Uses_JAAS.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -9,10 +9,10 @@
The <literal>JaasSecurityManager</literal> uses the JAAS packages to implement the <literal>AuthenticationManager</literal> and <literal>RealmMapping</literal> interface behavior. In particular, its behavior derives from the execution of the login module instances that are configured under the name that matches the security domain to which the <literal>JaasSecurityManager</literal> has been assigned. The login modules implement the security domain's principal authentication and role-mapping behavior. Thus, you can use the <literal>JaasSecurityManager</literal> across different security domains simply by plugging in different login module configurations for the domains.
</para>
<para>
- To illustrate the details of the <literal>JaasSecurityManager</literal>'s usage of the JAAS authentication process, you will walk through a client invocation of an EJB home method invocation. The prerequisite setting is that the EJB has been deployed in the JBoss server and its home interface methods have been secured using <literal>method-permission</literal> elements in the <literal>ejb-jar.xml</literal> descriptor, and it has been assigned a security domain named <literal>jwdomain</literal> using the <literal>jboss.xml</literal> descriptor <literal>security-domain</literal> element.
+ To illustrate the details of the <literal>JaasSecurityManager</literal>'s usage of the JAAS authentication process, you will walk through a client invocation of an EJB home method invocation. The prerequisite setting is that the EJB has been deployed in the JBoss server and its home interface methods have been secured using <markup>method-permission</markup> elements in the <filename>ejb-jar.xml</filename> descriptor, and it has been assigned a security domain named <literal>jwdomain</literal> using the <filename>jboss.xml</filename> descriptor <markup>security-domain</markup> element.
</para>
<figure id="How_the_JaasSecurityManager_Uses_JAAS-An_illustration_of_the_steps_involved_in_the_authentication_and_authorization_of_a_secured_EJB_home_method_invocation.">
- <title>An illustration of the steps involved in the authentication and authorization of a secured EJB home method invocation.</title>
+ <title>Secured EJB Home Method Authentication and Authorization Invocation Steps.</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/authsteps.jpg"/>
@@ -20,17 +20,16 @@
</mediaobject>
</figure>
<para>
- <xref linkend="How_the_JaasSecurityManager_Uses_JAAS-An_illustration_of_the_steps_involved_in_the_authentication_and_authorization_of_a_secured_EJB_home_method_invocation."/> provides a view of the client to server communication we will discuss. The numbered steps shown are:
+ <xref linkend="How_the_JaasSecurityManager_Uses_JAAS-An_illustration_of_the_steps_involved_in_the_authentication_and_authorization_of_a_secured_EJB_home_method_invocation."/> provides a view of the client to server communication. The numbered steps shown are:
</para>
<orderedlist>
<listitem>
<para>
- The client first has to perform a JAAS login to establish the principal and credentials for authentication, and this is labeled <emphasis>Client Side Login</emphasis> in the figure. This is how clients establish their login identities in JBoss. Support for presenting the login information via JNDI <literal>InitialContext</literal> properties is provided via an alternate configuration. A JAAS login entails creating a <literal>LoginContext</literal> instance and passing the name of the configuration to use. The configuration name is <literal>other</literal>. This one-time login associates the login principal and credentials with all subsequent EJB method invocations. Note that the process might not authenticate the user. The nature of the client-side login depends on the login module configuration that the client uses. In this example, the <literal>other</literal> client-side login configuration entry is set up to use the <literal>ClientLoginModule</literal> module (an !
<literal>org.jboss.security.ClientLoginModule</literal>). This is the default client side module that simply binds the username and password to the JBoss EJB invocation layer for later authentication on the server. The identity of the client is not authenticated on the client.
+ The client must perform a JAAS login to establish the principal and credentials for authentication, and this is labeled <emphasis>Client Side Login</emphasis> in the figure. This is how clients establish their login identities in JBoss. Support for presenting the login information via JNDI <literal>InitialContext</literal> properties is provided via an alternate configuration. A JAAS login entails creating a <literal>LoginContext</literal> instance and passing the name of the configuration to use. The configuration name is <literal>other</literal>. This one-time login associates the login principal and credentials with all subsequent EJB method invocations. Note that the process might not authenticate the user. The nature of the client-side login depends on the login module configuration that the client uses. In this example, the <literal>other</literal> client-side login configuration entry is set up to use the <literal>ClientLoginModule</literal> module (an <classna!
me>org.jboss.security.ClientLoginModule</classname>). This is the default client side module that simply binds the username and password to the JBoss EJB invocation layer for later authentication on the server. The identity of the client is not authenticated on the client.
</para>
</listitem>
<listitem>
- <para>
- Later, the client obtains the EJB home interface and attempts to create a bean. This event is labeled as <emphasis>Home Method Invocation</emphasis>. This results in a home interface method invocation being sent to the JBoss server. The invocation includes the method arguments passed by the client along with the user identity and credentials from the client-side JAAS login performed in step 1.
+ <para>The client obtains the EJB home interface and attempts to create a bean. This event is labeled as <emphasis>Home Method Invocation</emphasis>. This results in a home interface method invocation being sent to the JBoss server. The invocation includes the method arguments passed by the client, along with the user identity and credentials from the client-side JAAS login performed in Step 1.
</para>
</listitem>
<listitem>
@@ -50,29 +49,29 @@
</listitem>
<listitem>
<para>
- A <literal>java.security.acl.Group</literal> named <literal>Roles</literal> that contains the role names from the application domain to which the user has been assigned. <literal>org.jboss.security.SimplePrincipal</literal> objects are used to represent the role names; <literal>SimplePrincipal</literal> is a simple string-based implementation of <literal>Principal</literal>. These roles are used to validate the roles assigned to methods in <literal>ejb-jar.xml</literal> and the <literal>EJBContext.isCallerInRole(String)</literal> method implementation.
+ A <literal>java.security.acl.Group</literal> named <literal>Roles</literal> that contains the role names from the application domain to which the user has been assigned. <literal>org.jboss.security.SimplePrincipal</literal> objects are used to represent the role names; <literal>SimplePrincipal</literal> is a simple string-based implementation of <literal>Principal</literal>. These roles are used to validate the roles assigned to methods in <filename>ejb-jar.xml</filename> and the <methodname>EJBContext.isCallerInRole(String)</methodname> method implementation.
</para>
</listitem>
<listitem>
<para>
- An optional <literal>java.security.acl.Group</literal> named <literal>CallerPrincipal</literal>, which contains a single <literal>org.jboss.security.SimplePrincipal</literal> that corresponds to the identity of the application domain's caller. The <literal>CallerPrincipal</literal> sole group member will be the value returned by the <literal>EJBContext.getCallerPrincipal()</literal> method. The purpose of this mapping is to allow a <literal>Principal</literal> as known in the operational security environment to map to a <literal>Principal</literal> with a name known to the application. In the absence of a <literal>CallerPrincipal</literal> mapping the deployment security environment principal is used as the <literal>getCallerPrincipal</literal> method value. That is, the operational principal is the same as the application domain principal.
+ An optional <literal>java.security.acl.Group</literal> named <literal>CallerPrincipal</literal>, which contains a single <literal>org.jboss.security.SimplePrincipal</literal> that corresponds to the identity of the application domain's caller. The <literal>CallerPrincipal</literal> sole group member will be the value returned by the <methodname>EJBContext.getCallerPrincipal()</methodname> method. The purpose of this mapping is to allow a <literal>Principal</literal> as known in the operational security environment to map to a <literal>Principal</literal> with a name known to the application. In the absence of a <literal>CallerPrincipal</literal> mapping the deployment security environment principal is used as the <literal>getCallerPrincipal</literal> method value. That is, the operational principal is the same as the application domain principal.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
- The final step of the security interceptor check is to verify that the authenticated user has permission to invoke the requested method This is labeled as <emphasis>Server Side Authorization</emphasis> in <xref linkend="How_the_JaasSecurityManager_Uses_JAAS-An_illustration_of_the_steps_involved_in_the_authentication_and_authorization_of_a_secured_EJB_home_method_invocation."/>. Performing the authorization this entails the following steps:
+ The final step of the security interceptor check is to verify that the authenticated user has permission to invoke the requested method. This is labeled as <emphasis>Server Side Authorization</emphasis> in <xref linkend="How_the_JaasSecurityManager_Uses_JAAS-An_illustration_of_the_steps_involved_in_the_authentication_and_authorization_of_a_secured_EJB_home_method_invocation."/>. Performing the authorization this entails the following steps:
</para>
<itemizedlist>
<listitem>
<para>
- Obtain the names of the roles allowed to access the EJB method from the EJB container. The role names are determined by <literal>ejb-jar.xml</literal> descriptor role-name elements of all <literal>method-permission</literal> elements containing the invoked method.
+ Obtain the names of the roles allowed to access the EJB method from the EJB container. The role names are determined by <filename>ejb-jar.xml</filename> descriptor role-name elements of all <markup>method-permission</markup> elements containing the invoked method.
</para>
</listitem>
<listitem>
<para>
- If no roles have been assigned, or the method is specified in an <literal>exclude-list</literal> element, then access to the method is denied. Otherwise, the <literal>doesUserHaveRole</literal> method is invoked on the security manager by the security interceptor to see if the caller has one of the assigned role names. This method iterates through the role names and checks if the authenticated user's Subject <literal>Roles</literal> group contains a <literal>SimplePrincipal</literal> with the assigned role name. Access is allowed if any role name is a member of the <literal>Roles</literal> group. Access is denied if none of the role names are members.
+ If no roles have been assigned, or the method is specified in an <markup>exclude-list</markup> element, then access to the method is denied. Otherwise, the <methodname>doesUserHaveRole</methodname> method is invoked on the security manager by the security interceptor to see if the caller has one of the assigned role names. This method iterates through the role names and checks if the authenticated user's Subject <literal>Roles</literal> group contains a <literal>SimplePrincipal</literal> with the assigned role name. Access is allowed if any role name is a member of the <literal>Roles</literal> group. Access is denied if none of the role names are members.
</para>
</listitem>
<listitem>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-IdentiyLoginModule.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-IdentiyLoginModule.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-IdentiyLoginModule.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -5,27 +5,33 @@
]>
<section id="sect-IdentityLoginModule">
<title>IdentityLoginModule</title>
- <para>
- The <literal>IdentityLoginModule</literal> is a simple login module that associates a hard-coded user name a to any subject authenticated against the module. It creates a <literal>SimplePrincipal</literal> instance using the name specified by the <literal>principal</literal> option. This login module is useful when you need to provide a fixed identity to a service and in development environments when you want to test the security associated with a given principal and associated roles.
+ <para><literal>IdentityLoginModule</literal> is a simple login module that associates a hard-coded user name to any subject authenticated against the module. It creates a <literal>SimplePrincipal</literal> instance using the name specified by the <literal>principal</literal> option. </para>
+ <note>
+ <para>
+ This module supports password stacking.
</para>
+ </note>
+ <para>This login module is useful when you need to provide a fixed identity to a service and in development environments when you want to test the security associated with a given principal and associated roles.
+ </para>
<para>
The supported login module configuration options include:
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">principal</emphasis>: This is the name to use for the <literal>SimplePrincipal</literal> all users are authenticated as. The principal name defaults to <literal>guest</literal> if no principal option is specified.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">roles</emphasis>: This is a comma-delimited list of roles that will be assigned to the user.
- </para>
- </listitem>
- </itemizedlist>
+ <variablelist>
+ <varlistentry>
+ <term>principal</term>
+ <listitem>
+ <para>This is the name to use for the <literal>SimplePrincipal</literal> all users are authenticated as. The principal name defaults to <literal>guest</literal> if no principal option is specified.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>roles</term>
+ <listitem>
+ <para>This is a comma-delimited list of roles that will be assigned to the user.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<para>
- A sample XMLLoginConfig configuration entry that would authenticate all users as the principal named <literal>jduke</literal> and assign role names of <literal>TheDuke</literal>, and <literal>AnimatedCharacter</literal> is:
- </para>
+ A sample XMLLoginConfig configuration entry is described below. The entry authenticates all users as the principal named <literal>jduke</literal> and assign role names of <literal>TheDuke</literal>, and <literal>AnimatedCharacter</literal>:.</para>
<programlisting language="XML" role="XML"><policy>
<application-policy name="testIdentity">
<authentication>
@@ -38,7 +44,4 @@
</application-policy>
</policy>
</programlisting>
- <para>
- This module supports password stacking.
- </para>
</section>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-JaasSecurityDomain_MBean.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-JaasSecurityDomain_MBean.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-JaasSecurityDomain_MBean.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,70 +6,76 @@
<section id="sect-JaasSecurityDomain_MBean">
<title>The JaasSecurityDomain MBean</title>
<para>
- The <literal>org.jboss.security.plugins.JaasSecurityDomain</literal> is an extension of <literal>JaasSecurityManager</literal> that adds the notion of a <literal>KeyStore</literal>, a JSSE <literal>KeyManagerFactory</literal> and a <literal>TrustManagerFactory</literal> for supporting SSL and other cryptographic use cases. The additional configurable attributes of the <literal>JaasSecurityDomain</literal> include:
+ The <classname>org.jboss.security.plugins.JaasSecurityDomain</classname> is an extension of <literal>JaasSecurityManager</literal> that adds the notion of a <literal>KeyStore</literal>, a JSSE <literal>KeyManagerFactory</literal> and a <literal>TrustManagerFactory</literal> for supporting SSL and other cryptographic use cases. The additional configurable attributes of the <literal>JaasSecurityDomain</literal> include:
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">KeyStoreType</emphasis>: The type of the <literal>KeyStore</literal> implementation. This is the type argument passed to the <literal>java.security.KeyStore.getInstance(String type)</literal> factory method. The default is <literal>JKS</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">KeyStoreURL</emphasis>: A URL to the location of the <literal>KeyStore</literal> database. This is used to obtain an <literal>InputStream</literal> to initialize the <literal>KeyStore</literal>. If the string is not a value URL, it is treated as a file.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">KeyStorePass</emphasis>: The password associated with the <literal>KeyStore</literal> database contents. The <literal>KeyStorePass</literal> is also used in combination with the <literal>Salt</literal> and <literal>IterationCount</literal> attributes to create a PBE secret key used with the encode/decode operations. The <literal>KeyStorePass</literal> attribute value format is one of the following:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The plaintext password for the <literal>KeyStore</literal> The <literal>toCharArray()</literal> value of the string is used without any manipulation.
+ <variablelist>
+ <varlistentry>
+ <term>KeyStoreType</term>
+ <listitem>
+ <para>The type of the <literal>KeyStore</literal> implementation. This is the type argument passed to the <methodname>java.security.KeyStore.getInstance(String type)</methodname> factory method. The default is <literal>JKS</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>KeyStoreURL</term>
+ <listitem>
+ <para>A URL to the location of the <literal>KeyStore</literal> database. This is used to obtain an <literal>InputStream</literal> to initialize the <literal>KeyStore</literal>. If the string is not a value URL, it is treated as a file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>KeyStorePass</term>
+ <listitem>
+ <para>The password associated with the <literal>KeyStore</literal> database contents. The <literal>KeyStorePass</literal> is also used in combination with the <literal>Salt</literal> and <literal>IterationCount</literal> attributes to create a PBE secret key used with the encode/decode operations. The <literal>KeyStorePass</literal> attribute value format is one of the following</para>
+ <itemizedlist>
+ <listitem>
+ <para>The plaintext password for the <literal>KeyStore</literal> The <literal>toCharArray(</literal> value of the string is used without any manipulation.
</para>
- </listitem>
- <listitem>
- <para>
- A command to execute to obtain the plaintext password. The format is <literal>{EXT}...</literal> where the <literal>...</literal> is the exact command line that will be passed to the <literal>Runtime.exec(String)</literal> method to execute a platform-specific command. The first line of the command output is used as the password.
+ </listitem>
+ <listitem>
+ <para>A command to execute to obtain the plaintext password. The format is <literal>{EXT}...</literal> where the <literal>...</literal> is the exact command line that will be passed to the <methodname>Runtime.exec(String)</methodname> method to execute a platform-specific command. The first line of the command output is used as the password.
</para>
- </listitem>
- <listitem>
- <para>
- A class to create to obtain the plaintext password. The format is <literal>{CLASS}classname[:ctorarg]</literal> where the <literal>[:ctorarg]</literal> is an optional string that will be passed to the constructor when instantiating the <literal>classname</literal>. The password is obtained from classname by invoking a <literal>toCharArray()</literal> method if found, otherwise, the <literal>toString()</literal> method is used.
+ </listitem>
+ <listitem>
+ <para>A class to create to obtain the plaintext password. The format is <literal>{CLASS}classname[:ctorarg]</literal> where the <literal>[:ctorarg]</literal> is an optional string that will be passed to the constructor when instantiating the <literal>classname</literal>. The password is obtained from classname by invoking a <methodname>toCharArray()</methodname> method if found, otherwise, the <methodname>toString()</methodname> method is used.
</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Salt</emphasis>: The <literal>PBEParameterSpec</literal> salt value.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">IterationCount</emphasis>: The <literal>PBEParameterSpec</literal> iteration count value.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">TrustStoreType</emphasis>: The type of the <literal>TrustStore</literal> implementation. This is the type argument passed to the <literal>java.security.KeyStore.getInstance(String type)</literal> factory method. The default is <literal>JKS</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">TrustStoreURL</emphasis>: A URL to the location of the <literal>TrustStore</literal> database. This is used to obtain an <literal>InputStream</literal> to initialize the <literal>KeyStore</literal>. If the string is not a value URL, it is treated as a file.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">TrustStorePass</emphasis>: The password associated with the trust store database contents. The <literal>TrustStorePass</literal> is a simple password and doesn't have the same configuration options as the <literal>KeyStorePass</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">ManagerServiceName</emphasis>: Sets the JMX object name string of the security manager service MBean. This is used to register the defaults to register the <literal>JaasSecurityDomain</literal> as a the security manager under <literal>java:/jaas/<domain></literal> where <literal><domain></literal> is the name passed to the MBean constructor. The name defaults to <literal>jboss.security:service=JaasSecurityManager</literal>.
- </para>
- </listitem>
- </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Salt</term>
+ <listitem>
+ <para>The <literal>PBEParameterSpec</literal> salt value.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>IterationCount</term>
+ <listitem>
+ <para>The <literal>PBEParameterSpec</literal> iteration count value.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TrustStoreType</term>
+ <listitem>
+ <para>The type of the <literal>TrustStore</literal> implementation. This is the type argument passed to the <methodname>java.security.KeyStore.getInstance(String type)</methodname> factory method. The default is <literal>JKS</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TrustStoreURL</term>
+ <listitem>
+ <para>A URL to the location of the <literal>TrustStore</literal> database. This is used to obtain an <literal>InputStream</literal> to initialize the <literal>KeyStore</literal>. If the string is not a value URL, it is treated as a file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TrustStorePass</term>
+ <listitem>
+ <para>The password associated with the trust store database contents. The <literal>TrustStorePass</literal> is a simple password and does not have the same configuration options as the <literal>KeyStorePass</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ManagerServiceName</term>
+ <listitem>
+ <para>Sets the JMX object name string of the security manager service MBean. This is used to register the defaults to register the <literal>JaasSecurityDomain</literal> as a the security manager under <literal>java:/jaas/<domain></literal> where <literal><domain></literal> is the name passed to the MBean constructor. The name defaults to <literal>jboss.security:service=JaasSecurityManager</literal>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-JaasSecurityManagerService_MBean.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-JaasSecurityManagerService_MBean.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-JaasSecurityManagerService_MBean.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -9,8 +9,8 @@
The <literal>JaasSecurityManagerService</literal> MBean service manages security managers. Although its name begins with <emphasis>Jaas</emphasis>, the security managers it handles need not use JAAS in their implementation. The name arose from the fact that the default security manager implementation is the <literal>JaasSecurityManager</literal>. The primary role of the <literal>JaasSecurityManagerService</literal> is to externalize the security manager implementation. You can change the security manager implementation by providing an alternate implementation of the <literal>AuthenticationManager</literal> and <literal>RealmMapping</literal> interfaces.
</para>
<para>
- The second fundamental role of the <literal>JaasSecurityManagerService</literal> is to provide a JNDI <literal>javax.naming.spi.ObjectFactory</literal> implementation to allow for simple code-free management of the JNDI name to security manager implementation mapping. It has been mentioned that security is enabled by specifying the JNDI name of the security manager implementation via the <literal>security-domain</literal> deployment descriptor element. </para>
- <para>When you specify a JNDI name, there has to be an object-binding there to use. To simplify the setup of the JNDI name to security manager bindings, the <literal>JaasSecurityManagerService</literal> manages the association of security manager instances to names by binding a next naming system reference with itself as the JNDI ObjectFactory under the name <literal>java:/jaas</literal>. This allows one to use a naming convention of the form <literal>java:/jaas/XYZ</literal> as the value for the <literal>security-domain</literal> element, and the security manager instance for the <literal>XYZ</literal> security domain will be created as needed for you. </para>
+ The second fundamental role of the <literal>JaasSecurityManagerService</literal> is to provide a JNDI <literal>javax.naming.spi.ObjectFactory</literal> implementation to allow for simple code-free management of the JNDI name to security manager implementation mapping. It has been mentioned that security is enabled by specifying the JNDI name of the security manager implementation via the <markup>security-domain</markup> deployment descriptor element. </para>
+ <para>When you specify a JNDI name, there has to be an object-binding there to use. To simplify the setup of the JNDI name to security manager bindings, the <literal>JaasSecurityManagerService</literal> manages the association of security manager instances to names by binding a next naming system reference with itself as the JNDI ObjectFactory under the name <literal>java:/jaas</literal>. This permits a naming convention of the form <literal>java:/jaas/XYZ</literal> as the value for the <markup>security-domain</markup> element, and the security manager instance for the <literal>XYZ</literal> security domain will be created as needed. </para>
<para>The security manager for the domain <literal>XYZ</literal> is created on the first lookup against the <literal>java:/jaas/XYZ</literal> binding by creating an instance of the class specified by the <literal>SecurityManagerClassName</literal> attribute using a constructor that takes the name of the security domain. For example, consider the following container security configuration snippet:
</para>
<important>
@@ -29,48 +29,56 @@
<para>
The <literal>JaasSecurityManagerService</literal> MBean is configured by default for use in the standard JBoss distribution, and you can often use the default configuration as is. The configurable attributes of the <literal>JaasSecurityManagerService</literal> include:
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">SecurityManagerClassName</emphasis>: The name of the class that provides the security manager implementation. The implementation must support both the <literal>org.jboss.security.AuthenticationManager</literal> and <literal>org.jboss.security.RealmMapping</literal> interfaces. If not specified this defaults to the JAAS-based <literal>org.jboss.security.plugins.JaasSecurityManager</literal>.
+ <variablelist>
+ <varlistentry>
+ <term>SecurityManagerClassName</term>
+ <listitem>
+ <para>The name of the class that provides the security manager implementation. The implementation must support both the <classname>org.jboss.security.AuthenticationManager</classname> and <literal>org.jboss.security.RealmMapping</literal> interfaces. If not specified this defaults to the JAAS-based <classname>org.jboss.security.plugins.JaasSecurityManager</classname>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>CallbackHandlerClassName</term>
+ <listitem>
+ <para>The name of the class that provides the <literal>javax.security.auth.callback.CallbackHandler</literal> implementation used by the <literal>JaasSecurityManager</literal>. You can override the handler used by the <literal>JaasSecurityManager</literal> if the default implementation (<classname>org.jboss.security.auth.callback.SecurityAssociationHandler</classname>) does not meet your needs. This is a rather deep configuration that generally should not be set unless you know what you are doing.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SecurityProxyFactoryClassName</term>
+ <listitem>
+ <para>The name of the class that provides the <classname>org.jboss.security.SecurityProxyFactory</classname> implementation. If not specified this defaults to <literal>org.jboss.security.SubjectSecurityProxyFactory</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>AuthenticationCacheJndiName</term>
+ <listitem>
+ <para>Specifies the location of the security credential cache policy. This is first treated as an <literal>ObjectFactory</literal> location capable of returning <literal>CachePolicy</literal> instances on a per-security-domain basis. This is done by appending the name of the security domain to this name when looking up the <literal>CachePolicy</literal> for a domain. If this fails, the location is treated as a single <literal>CachePolicy</literal> for all security domains. As a default, a timed cache policy is used.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DefaultCacheTimeout</term>
+ <listitem>
+ <para>Specifies the default timed cache policy timeout in seconds. The default value is 1800 seconds (30 minutes). The value you use for the timeout is a tradeoff between frequent authentication operations and how long credential information may be out of sync with respect to the security information store. If you want to disable caching of security credentials, set this to 0 to force authentication to occur every time. This has no affect if the <literal>AuthenticationCacheJndiName</literal> has been changed from the default value.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DefaultCacheResolution</term>
+ <listitem>
+ <para>Specifies the default timed cache policy resolution in seconds. This controls the interval at which the cache current timestamp is updated and should be less than the <literal>DefaultCacheTimeout</literal> in order for the timeout to be meaningful. The default resolution is 60 seconds (1 minute). This has no affect if the <literal>AuthenticationCacheJndiName</literal> has been changed from the default value.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DefaultUnauthenticatedPrincipal</term>
+ <listitem>
+ <para>Specifies the principal to use for unauthenticated users. This setting makes it possible to set default permissions for users who have not been authenticated.
</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">CallbackHandlerClassName</emphasis>: The name of the class that provides the <literal>javax.security.auth.callback.CallbackHandler</literal> implementation used by the <literal>JaasSecurityManager</literal>. You can override the handler used by the <literal>JaasSecurityManager</literal> if the default implementation (<literal>org.jboss.security.auth.callback.SecurityAssociationHandler</literal>) does not meet your needs. This is a rather deep configuration that generally should not be set unless you know what you are doing.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">SecurityProxyFactoryClassName</emphasis>: The name of the class that provides the <literal>org.jboss.security.SecurityProxyFactory</literal> implementation. If not specified this defaults to <literal>org.jboss.security.SubjectSecurityProxyFactory</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">AuthenticationCacheJndiName</emphasis>: Specifies the location of the security credential cache policy. This is first treated as an <literal>ObjectFactory</literal> location capable of returning <literal>CachePolicy</literal> instances on a per-security-domain basis. This is done by appending the name of the security domain to this name when looking up the <literal>CachePolicy</literal> for a domain. If this fails, the location is treated as a single <literal>CachePolicy</literal> for all security domains. As a default, a timed cache policy is used.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">DefaultCacheTimeout</emphasis>: Specifies the default timed cache policy timeout in seconds. The default value is 1800 seconds (30 minutes). The value you use for the timeout is a tradeoff between frequent authentication operations and how long credential information may be out of sync with respect to the security information store. If you want to disable caching of security credentials, set this to 0 to force authentication to occur every time. This has no affect if the <literal>AuthenticationCacheJndiName</literal> has been changed from the default value.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">DefaultCacheResolution</emphasis>: Specifies the default timed cache policy resolution in seconds. This controls the interval at which the cache current timestamp is updated and should be less than the <literal>DefaultCacheTimeout</literal> in order for the timeout to be meaningful. The default resolution is 60 seconds(1 minute). This has no affect if the <literal>AuthenticationCacheJndiName</literal> has been changed from the default value.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">DefaultUnauthenticatedPrincipal</emphasis>: Specifies the principal to use for unauthenticated users. This setting makes it possible to set default permissions for users who have not been authenticated.
- </para>
- </listitem>
- </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<para>
The <literal>JaasSecurityManagerService</literal> also supports a number of useful operations. These include flushing any security domain authentication cache at runtime, getting the list of active users in a security domain authentication cache, and any of the security manager interface methods.
</para>
<para>
- Flushing a security domain authentication cache can be used to drop all cached credentials when the underlying store has been updated and you want the store state to be used immediately. The MBean operation signature is: <literal>public void flushAuthenticationCache(String securityDomain)</literal>.
+ Flushing a security domain authentication cache can be used to drop all cached credentials when the underlying store has been updated and you want the store state to be used immediately. The MBean operation signature is: <methodname>public void flushAuthenticationCache(String securityDomain)</methodname>.
</para>
<para>
This can be invoked programmatically using the following code snippet:
@@ -83,7 +91,7 @@
server.invoke(jaasMgr, "flushAuthenticationCache", params, signature);
</programlisting>
<para>
- Getting the list of active users provides a snapshot of the <literal>Principals</literal> keys in a security domain authentication cache that are not expired. The MBean operation signature is: <literal>public List getAuthenticationCachePrincipals(String securityDomain)</literal>.
+ Getting the list of active users provides a snapshot of the <literal>Principals</literal> keys in a security domain authentication cache that are not expired. The MBean operation signature is: <classname>public List getAuthenticationCachePrincipals(String securityDomain)</classname>.
</para>
<para>
This can be invoked programmatically using the following code snippet:
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-LdapLoginModule.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-LdapLoginModule.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-LdapLoginModule.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -5,119 +5,186 @@
]>
<section id="sect-LdapLoginModule">
<title>LdapLoginModule</title>
- <para>
- The <literal>LdapLoginModule</literal> is a <literal>LoginModule</literal> implementation that authenticates against an LDAP server. You would use the <literal>LdapLoginModule</literal> if your username and credentials are stored in an LDAP server that is accessible using a JNDI LDAP provider.
+ <para><literal>LdapLoginModule</literal> is a <literal>LoginModule</literal> implementation that authenticates against an LDAP server. Use the <literal>LdapLoginModule</literal> if your username and credentials are stored in an LDAP server that is accessible using a JNDI LDAP provider.
</para>
- <para>
- The LDAP connectivity information is provided as configuration options that are passed through to the environment object used to create JNDI initial context. The standard LDAP JNDI properties used include the following:
+ <note>
+ <para>
+ This login module also supports unauthenticated identity and password stacking.
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">java.naming.factory.initial</emphasis>: The classname of the <literal>InitialContextFactory</literal> implementation. This defaults to the Sun LDAP provider implementation <literal>com.sun.jndi.ldap.LdapCtxFactory</literal>.
+ </note>
+ <para>The LDAP connectivity information is provided as configuration options that are passed through to the environment object used to create JNDI initial context. The standard LDAP JNDI properties used include the following:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <property>java.naming.factory.initial</property>
+ </term>
+ <listitem>
+ <para><classname>InitialContextFactory</classname> implementation classname. This defaults to the Sun LDAP provider implementation <literal>com.sun.jndi.ldap.LdapCtxFactory</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>java.naming.provider.url</property>
+ </term>
+ <listitem>
+ <para>LDAP URL for the LDAP server.
</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">java.naming.provider.url</emphasis>: The LDAP URL for the LDAP server
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">java.naming.security.authentication</emphasis>: The security level to use. This defaults to <literal>simple</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">java.naming.security.protocol</emphasis>: The transport protocol to use for secure access, such as, SSL.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">java.naming.security.principal</emphasis>: The principal for authenticating the caller to the service. This is built from other properties as described below.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">java.naming.security.credentials</emphasis>: The value of the property depends on the authentication scheme. For example, it could be a hashed password, clear-text password, key, certificate, and so on.
- </para>
- </listitem>
- </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>java.naming.security.authentication</property>
+ </term>
+ <listitem>
+ <para>Security level to use. This defaults to <literal>simple</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>java.naming.security.protocol</property>
+ </term>
+ <listitem>
+ <para>Transport protocol to use for secure access, such as, SSL.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>java.naming.security.principal</property>
+ </term>
+ <listitem>
+ <para>Principal for authenticating the caller to the service. This is built from other properties as described below.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>java.naming.security.credentials</property>
+ </term>
+ <listitem>
+ <para>Authentication scheme to use. For example, hashed password, clear-text password, key, certificate, and so on.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<para>
The supported login module configuration options include the following:
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">principalDNPrefix</emphasis>: A prefix to add to the username to form the user distinguished name. See <literal>principalDNSuffix</literal> for more info.
+ <variablelist>
+ <varlistentry>
+ <term>
+ <property>principalDNPrefix</property>
+ </term>
+ <listitem>
+ <para>Prefix added to the username to form the user distinguished name. See <literal>principalDNSuffix</literal> for more info.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>principalDNSuffix</property>
+ </term>
+ <listitem>
+ <para>Suffix added to the username when forming the user distinguished name. This is useful if you prompt a user for a username and you don't want the user to have to enter the fully distinguished name. Using this property and <literal>principalDNSuffix</literal> the <literal>userDN</literal> will be formed as <literal>principalDNPrefix + username + principalDNSuffix</literal>
</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">principalDNSuffix</emphasis>: A suffix to add to the username when forming the user distinguished name. This is useful if you prompt a user for a username and you don't want the user to have to enter the fully distinguished name. Using this property and <literal>principalDNSuffix</literal> the <literal>userDN</literal> will be formed as <literal>principalDNPrefix + username + principalDNSuffix</literal>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>useObjectCredential</property>
+ </term>
+ <listitem>
+ <para>Value that indicates the credential should be obtained as an opaque <literal>Object</literal> using the <literal>org.jboss.security.auth.callback.ObjectCallback</literal> type of <literal>Callback</literal> rather than as a <literal>char[]</literal> password using a JAAS <literal>PasswordCallback</literal>. This allows for passing non-<literal>char[]</literal> credential information to the LDAP server.
+ The available values are <literal>true</literal> and <literal>false</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>rolesCtxDN</property>
+ </term>
+ <listitem>
+ <para>Fixed, distinguished name to the context to search for user roles.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>userRolesCtxDNAttributeName</property>
+ </term>
+ <listitem>
+ <para>Name of an attribute in the user object that contains the distinguished name to the context to search for user roles. This differs from <literal>rolesCtxDN</literal> in that the context to search for a user's roles can be unique for each user.
</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">useObjectCredential</emphasis>: A true/false value that indicates that the credential should be obtained as an opaque <literal>Object</literal> using the <literal>org.jboss.security.auth.callback.ObjectCallback</literal> type of <literal>Callback</literal> rather than as a <literal>char[]</literal> password using a JAAS <literal>PasswordCallback</literal>. This allows for passing non-<literal>char[]</literal> credential information to the LDAP server.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">rolesCtxDN</emphasis>: The fixed distinguished name to the context to search for user roles.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">userRolesCtxDNAttributeName</emphasis>: The name of an attribute in the user object that contains the distinguished name to the context to search for user roles. This differs from <literal>rolesCtxDN</literal> in that the context to search for a user's roles can be unique for each user.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">roleAttributeID</emphasis>: The name of the attribute that contains the user roles. If not specified this defaults to <literal>roles</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">roleAttributeIsDN</emphasis>: A flag indicating whether the <literal>roleAttributeID</literal> contains the fully distinguished name of a role object, or the role name. If false, the role name is taken from the value of <literal>roleAttributeID</literal>. If true, the role attribute represents the distinguished name of a role object. The role name is taken from the value of the <literal>roleNameAttributeId</literal> attribute of the context name by the distinguished name. In certain directory schemas (e.g., MS ActiveDirectory), role attributes 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 is false.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">roleNameAttributeID</emphasis>: The name of the attribute of the context pointed to by the <literal>roleCtxDN</literal> distinguished name value which contains the role name. If the <literal>roleAttributeIsDN</literal> property is set to true, this property is used to find the role object's name attribute. The default is <literal>group</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">uidAttributeID</emphasis>: The name of the attribute in the object containing the user roles that corresponds to the userid. This is used to locate the user roles. If not specified this defaults to <literal>uid</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">matchOnUserDN</emphasis>: A true/false flag indicating if the search for user roles should match on the user's fully distinguished name. If false, just the username is used as the match value against the <literal>uidAttributeName</literal> attribute. If true, the full <literal>userDN</literal> is used as the match value.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">unauthenticatedIdentity</emphasis>: The principal name that should be assigned to requests that contain no authentication information. This behavior is inherited from the <literal>UsernamePasswordLoginModule</literal> superclass.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">allowEmptyPasswords</emphasis>: A flag indicating if empty (length 0) 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 or true to have the LDAP server validate the empty password. The default is true.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The authentication of a user is performed by connecting to the LDAP server based on the login module configuration options. Connecting to the LDAP server is done by creating an <literal>InitialLdapContext</literal> with an environment composed of the LDAP JNDI properties described previously in this section. The <literal>Context.SECURITY_PRINCIPAL</literal> is set to the distinguished name of the user as obtained by the callback handler in combination with the <literal>principalDNPrefix</literal> and <literal>principalDNSuffix</literal> option values, and the <literal>Context.SECURITY_CREDENTIALS</literal> property is either set to the <literal>String</literal> password or the <literal>Object</literal> credential depending on the <literal>useObjectCredential</literal> option.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>roleAttributeID</property>
+ </term>
+ <listitem>
+ <para>Name of the attribute containing the user roles. If not specified, this defaults to <literal>roles</literal>.
+</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>roleAttributeIsDN</property>
+ </term>
+ <listitem>
+ <para>Flag indicating whether the <literal>roleAttributeID</literal> contains the fully distinguished name of a role object, or the role name. The role name is taken from the value of the <literal>roleNameAttributeId</literal> attribute of the context name by the distinguished name. </para>
+ <para>If true, the role attribute represents the distinguished name of a role object. If false, the role name is taken from the value of <literal>roleAttributeID</literal>. The default is <literal>false</literal>.</para>
+ <note>
+ <para>In certain directory schemas (e.g., MS ActiveDirectory), role attributes in the user object are stored as DNs to role objects instead of simple names. For implementations that use this schema type, <property>roleAttributeIsDN</property> must be set to true. </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>roleNameAttributeID</property>
+ </term>
+ <listitem>
+ <para>Name of the attribute of the context pointed to by the <literal>roleCtxDN</literal> distinguished name value which contains the role name. If the <literal>roleAttributeIsDN</literal> property is set to true, this property is used to find the role object's name attribute. The default is <literal>group</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>uidAttributeID</property>
+ </term>
+ <listitem>
+ <para>Name of the attribute in the object containing the user roles that corresponds to the userid. This is used to locate the user roles. If not specified this defaults to <literal>uid</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>matchOnUserDN</property>
+ </term>
+ <listitem>
+ <para>Flag that specifies whether the search for user roles should match on the user's fully distinguished name. If true, the full <literal>userDN</literal> is used as the match value.
+If false, only the username is used as the match value against the <literal>uidAttributeName</literal> attribute. The default value is <literal>false</literal>. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>unauthenticatedIdentity</property>
+ </term>
+ <listitem>
+ <para>Principal name that should be assigned to requests containing no authentication information. This behavior is inherited from the <classname>UsernamePasswordLoginModule</classname> superclass.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <property>allowEmptyPasswords</property>
+ </term>
+ <listitem>
+ <para>A flag indicating if empty (length 0) 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. To reject empty passwords, set this to <literal>false</literal> . If set to <literal>true</literal>, the LDAP server will validate the empty password. The default is <literal>true</literal>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>User authentication is performed by connecting to the LDAP server, based on the login module configuration options. Connecting to the LDAP server is done by creating an <literal>InitialLdapContext</literal> with an environment composed of the LDAP JNDI properties described previously in this section. The <literal>Context.SECURITY_PRINCIPAL</literal> is set to the distinguished name of the user as obtained by the callback handler in combination with the <property>principalDNPrefix</property> and <property>principalDNSuffix</property> option values, and the <literal>Context.SECURITY_CREDENTIALS</literal> property is either set to the <literal>String</literal> password or the <literal>Object</literal> credential depending on the <property>useObjectCredential</property> option.
</para>
- <para>
- Once authentication has succeeded by virtue of being able to create an <literal>InitialLdapContext</literal> instance, the user's roles are queried by performing a search on the <literal>rolesCtxDN</literal> location with search attributes set to the <literal>roleAttributeName</literal> and <literal>uidAttributeName</literal> option values. The roles names are obtaining by invoking the <literal>toString</literal> method on the role attributes in the search result set.
+ <para>Once authentication has succeeded (<literal>InitialLdapContext</literal> instance is created), the user's roles are queried by performing a search on the <literal>rolesCtxDN</literal> location with search attributes set to the <property>roleAttributeName</property> and <property>uidAttributeName</property> option values. The roles names are obtaining by invoking the <methodname>toString</methodname> method on the role attributes in the search result set.
</para>
- <para>
+ <example>
+ <title>login-config.xml Sample</title>
+ <para>
The following is a sample <literal>login-config.xml</literal> entry.
</para>
- <programlisting language="XML" role="XML">
+ <programlisting language="XML" role="XML">
<application-policy name="testLDAP">
<authentication>
<login-module code="org.jboss.security.auth.spi.LdapLoginModule"
@@ -148,10 +215,13 @@
</authentication>
</application-policy>
</programlisting>
- <para>
+ </example>
+ <example id="exam-LDIF_File_Example">
+ <title>LDIF File Example</title>
+ <para>
An LDIF file representing the structure of the directory this data operates against is shown below.
</para>
- <programlisting>dn: dc=jboss,dc=org
+ <programlisting>dn: dc=jboss,dc=org
objectclass: top
objectclass: dcObject
objectclass: organization
@@ -184,22 +254,30 @@
member: uid=jduke,ou=People,dc=jboss,dc=org
description: the JBossAdmin group
</programlisting>
- <para>
- Looking back at the <literal>testLDAP</literal> login module configuration, the <literal>java.naming.factory.initial</literal>, <literal>java.naming.factory.url</literal> and <literal>java.naming.security</literal> options indicate the Sun LDAP JNDI provider implementation will be used, the LDAP server is located on host <literal>ldaphost.jboss.org</literal> on port 1389, and that the LDAP simple authentication method will be use to connect to the LDAP server.
+ </example>
+ <para>The <literal>java.naming.factory.initial</literal>, <literal>java.naming.factory.url</literal> and <literal>java.naming.security</literal> options in the <literal>testLDAP</literal> login module configuration indicate the following conditions:</para>
+ <itemizedlist>
+ <listitem>
+ <para>The Sun LDAP JNDI provider implementation will be used
</para>
- <para>
- The login module attempts to connect to the LDAP server using a DN representing the user it is trying to authenticate. This DN is constructed from the <literal>principalDNPrefix</literal>, passed in, the username of the user and the <literal>principalDNSuffix</literal> as described above. In this example, the username <literal>jduke</literal> would map to <literal>uid=jduke,ou=People,dc=jboss,dc=org</literal>. We've assumed the LDAP server authenticates users using the <literal>userPassword</literal> attribute of the user's entry (<literal>theduke</literal> in this example). This is the way most LDAP servers work, however, if your LDAP server handles authentication differently you will need to set the authentication credentials in a way that makes sense for your server.
+ </listitem>
+ <listitem>
+ <para>The LDAP server is located on host <literal>ldaphost.jboss.org</literal> on port 1389</para>
+ </listitem>
+ <listitem>
+ <para>The LDAP simple authentication method will be use to connect to the LDAP server.</para>
+ </listitem>
+ </itemizedlist>
+ <para>The login module attempts to connect to the LDAP server using a Distinguished Name (DN) representing the user it is trying to authenticate. This DN is constructed from the passed <literal>principalDNPrefix</literal>, the username of the user and the <literal>principalDNSuffix</literal> as described above. In <xref linkend="exam-LDIF_File_Example"/>, the username <literal>jduke</literal> would map to <literal>uid=jduke,ou=People,dc=jboss,dc=org</literal>. </para>
+ <note>
+ <para>The example assumes the LDAP server authenticates users using the <literal>userPassword</literal> attribute of the user's entry (<literal>theduke</literal> in this example). While most LDAP servers operate in this manner, however if your LDAP server handles authentication differently you must ensure LDAP is configured according to your production environment requirements.
</para>
- <para>
- Once authentication succeeds, the roles on which authorization will be based are retrieved by performing a subtree search of the <literal>rolesCtxDN</literal> for entries whose <literal>uidAttributeID</literal> match the user. If <literal>matchOnUserDN</literal> is true the search will be based on the full DN of the user. Otherwise the search will be based on the actual user name entered. In this example, the search is under <literal>ou=Roles,dc=jboss,dc=org</literal> for any entries that have a <literal>member</literal> attribute equal to <literal>uid=jduke,ou=People,dc=jboss,dc=org</literal>. The search would locate <literal>cn=JBossAdmin</literal> under the roles entry.
+ </note>
+ <para>Once authentication succeeds, the roles on which authorization will be based are retrieved by performing a subtree search of the <literal>rolesCtxDN</literal> for entries whose <literal>uidAttributeID</literal> match the user. If <literal>matchOnUserDN</literal> is true, the search will be based on the full DN of the user. Otherwise the search will be based on the actual user name entered. In this example, the search is under <literal>ou=Roles,dc=jboss,dc=org</literal> for any entries that have a <literal>member</literal> attribute equal to <literal>uid=jduke,ou=People,dc=jboss,dc=org</literal>. The search would locate <literal>cn=JBossAdmin</literal> under the roles entry.
</para>
<para>
The search returns the attribute specified in the <literal>roleAttributeID</literal> option. In this example, the attribute is <literal>cn</literal>. The value returned would be <literal>JBossAdmin</literal>, so the jduke user is assigned to the <literal>JBossAdmin</literal> role.
</para>
- <para>
- It's often the case that a local LDAP server provides identity and authentication services but is unable to use the authorization services. This is because application roles don't always map well onto LDAP groups, and LDAP administrators are often hesitant to allow external application-specific data in central LDAP servers. For this reason, the LDAP authentication module is often paired with another login module, such as the database login module, that can provide roles more suitable to the application being developed.
+ <para>A local LDAP server often provides identity and authentication services, but is unable to use authorization services. This is because application roles don't always map well onto LDAP groups, and LDAP administrators are often hesitant to allow external application-specific data in central LDAP servers. For this reason, the LDAP authentication module is often paired with another login module, such as the database login module, that can provide roles more suitable to the application being developed.
</para>
- <para>
- This login module also supports unauthenticated identity and password stacking.
- </para>
</section>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Password_Hashing.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Password_Hashing.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Password_Hashing.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,39 +6,13 @@
<section id="Using_JBoss_Login_Modules-Password_Hashing">
<title>Password Hashing</title>
<para>
- Most of the login modules need to compare a client-supplied password to a password stored in a user management system. These modules generally work with plain text passwords, but can also be configured to support hashed passwords to prevent plain text passwords from being stored on the server side.
+ Most login modules need to compare a client-supplied password to a password stored in a user management system. These modules generally work with plain text passwords, but can be configured to support hashed passwords to prevent plain text passwords from being stored on the server side.
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">hashAlgorithm</emphasis>: The name of the <literal>java.security.MessageDigest</literal> algorithm to use to hash the password. There is no default so this option must be specified to enable hashing. Typical values are <literal>MD5</literal> and <literal>SHA</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">hashEncoding</emphasis>: The string format for the hashed pass and must be either <literal>base64</literal>, <literal>hex</literal> or <literal>rfc2617</literal>. The default is <literal>base64</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">hashCharset</emphasis>: The encoding used to convert the clear text password to a byte array. The platform default encoding is the default.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">hashUserPassword</emphasis>: This indicates that the hashing algorithm should be applied to the password the user submits. The hashed user password will be compared against the value in the login module, which is expected to be a hash of the password. The default is true.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">hashStorePassword</emphasis>: This indicates that the hashing algorithm should be applied to the password stored on the server side. This is used for digest authentication where the user submits a hash of the user password along with a request-specific tokens from the server to be comare. JBoss uses the hash algorithm (for digest, this would be <literal>rfc2617</literal>) to compute a server-side hash that should match the hashed value sent from the client.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The following is an login module configuration that assigns unauthenticated users the principal name <literal>nobody</literal> and contains based64-encoded, MD5 hashes of the passwords in a <literal>usersb64.properties</literal> file.
+ <example>
+ <title/>
+ <para>The following is a login module configuration that assigns unauthenticated users the principal name <literal>nobody</literal> and contains based64-encoded, MD5 hashes of the passwords in a <filename>usersb64.properties</filename> file.
</para>
- <programlisting language="XML" role="XML"><policy>
+ <programlisting language="XML" role="XML"><policy>
<application-policy name="testUsersRoles">
<authentication>
<login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
@@ -50,8 +24,43 @@
</application-policy>
</policy>
</programlisting>
+ </example>
+ <variablelist>
+ <varlistentry>
+ <term>hashAlgorithm</term>
+ <listitem>
+ <para>Name of the <literal>java.security.MessageDigest</literal> algorithm to use to hash the password. There is no default so this option must be specified to enable hashing. Typical values are <literal>MD5</literal> and <literal>SHA</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>hashEncoding</term>
+ <listitem>
+ <para>String that specifies one of three encoding types: <literal>base64</literal>, <literal>hex</literal> or <literal>rfc2617</literal>. The default is <literal>base64</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>hashCharset</term>
+ <listitem>
+ <para>Encoding character set used to convert the clear text password to a byte array. The platform default encoding is the default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>hashUserPassword</term>
+ <listitem>
+ <para>Specifies the hashing algorithm must be applied to the password the user submits. The hashed user password is compared against the value in the login module, which is expected to be a hash of the password. The default is <literal>true</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>hashStorePassword</term>
+ <listitem>
+ <para>Specifies the hashing algorithm must be applied to the password stored on the server side. This is used for digest authentication, where the user submits a hash of the user password along with a request-specific tokens from the server to be compare. The hash algorithm (for digest, this would be <literal>rfc2617</literal>) is utilized to compute a server-side hash, which should match the hashed value sent from the client.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<para>
- If you need to generate passwords in code, <literal>the org.jboss.security.Util</literal> class provides a static helper method that will hash a password using a given encoding.
+ If you need to generate passwords in code, <classname>the org.jboss.security.Util</classname> class provides a static helper method that will hash a password using the specified encoding.
</para>
<programlisting>String hashedPassword = Util.createPasswordHash("MD5",
Util.BASE64_ENCODING,
@@ -64,6 +73,6 @@
</para>
<programlisting>echo -n password | openssl dgst -md5 -binary | openssl base64</programlisting>
<para>
- In both cases, the text password should hash to "X03MO1qnZdYdgyfeuILPmQ==". This is the value that would need to be stored in the user store.
+ In both cases, the text password should hash to <literal>X03MO1qnZdYdgyfeuILPmQ==</literal>. This value would need to be stored in the user store.
</para>
</section>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Password_Stacking.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Password_Stacking.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Password_Stacking.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,22 +6,24 @@
<section id="sect-Password_Stacking">
<title>Password Stacking</title>
<para>
- Multiple login modules can be chained together in a stack, with each login module providing both the authentication and authorization components. This works for many use cases, but sometimes authentication and authorization are split across multiple user management stores. A previous example showed how to combine LDAP and a relational database, allowing a user to be authenticated by either system. However, consider the case where users are managed in a central LDAP server but application-specific roles are stored in the application's relational database. The password-stacking module option captures this relationship.
+ Multiple login modules can be chained together in a stack, with each login module providing both the authentication and authorization components. This works for many use cases, but sometimes authentication and authorization are split across multiple user management stores. </para>
+ <para>A previous example showed how to combine LDAP and a relational database, allowing a user to be authenticated by either system. However, consider the case where users are managed in a central LDAP server but application-specific roles are stored in the application's relational database. The password-stacking module option captures this relationship.
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">password-stacking</emphasis>: When <literal>password-stacking</literal> option is set to <literal>useFirstPass</literal>, this module first looks for a shared username and password under the property names <literal>javax.security.auth.login.name</literal> and <literal>javax.security.auth.login.password</literal> respectively in the login module shared state map. If found these are used as the principal name and password. If not found the principal name and password are set by this login module and stored under the property names <literal>javax.security.auth.login.name</literal> and <literal>javax.security.auth.login.password</literal> respectively.
- </para>
- </listitem>
- </itemizedlist>
<para>
- To use password stacking, each login module should set <literal>password-stacking</literal> to <literal>useFirstPass</literal>. If a previous module configured for password stacking has authenticated the user, all the other stacking modules will consider the user authenticated and only attempt to provide a set of roles for the authorization step.
+ To use password stacking, each login module should set the <markup><module-option></markup> <literal>password-stacking</literal> attribute to <literal>useFirstPass</literal>. If a previous module configured for password stacking has authenticated the user, all the other stacking modules will consider the user authenticated and only attempt to provide a set of roles for the authorization step.
</para>
- <para>
- The following listing shows how password stacking could be used:
+ <para>When <literal>password-stacking</literal> option is set to <literal>useFirstPass</literal>, this module first looks for a shared username and password under the property names <property>javax.security.auth.login.name</property> and <property>javax.security.auth.login.password</property> respectively in the login module shared state map. </para>
+ <para>If found, these properties are used as the principal name and password. If not found, the principal name and password are set by this login module and stored under the property names <property>javax.security.auth.login.name</property> and <property>javax.security.auth.login.password</property> respectively.
+ </para>
+ <note>
+ <para>When using password stacking, set all modules to be required. This ensures that all modules are considered, and have chance to contribute roles to the authorization process.
</para>
- <programlisting language="XML" role="XML"><application-policy name="todo">
+ </note>
+ <example id="exam-Password_Stacking_Example">
+ <title>Password Stacking Sample</title>
+ <para>This example shows how password stacking could be used.
+ </para>
+ <programlisting language="XML" role="XML"><application-policy name="todo">
<authentication>
<login-module code="org.jboss.security.auth.spi.LdapLoginModule"
flag="required">
@@ -36,7 +38,5 @@
</authentication>
</application-policy>
</programlisting>
- <para>
- When using password stacking, it is usually appropriate to set all modules to be required to make sure that all modules are considered and have chance to contribute roles to the authorization process.
- </para>
+ </example>
</section>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-RunAsIdentity_Creation.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-RunAsIdentity_Creation.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-RunAsIdentity_Creation.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -9,7 +9,7 @@
<para>A user's identity in the server is represented either by a <classname>javax.security.auth.Subject</classname> instance or an <classname>org.jboss.security.RunAsIdentity</classname> instance. Both these classes store one or more principals that represent the identity and a list of roles that the identity possesses. In the case of the <classname>javax.security.auth.Subject</classname> a list of credentials is also stored.</para>
<para>In the <sgmltag><assembly-descriptor></sgmltag> section of the <filename>ejb-jar.xml</filename> deployment descriptor, you specify one or more roles that a user must have to access the various ejb methods.
-A comparision of these lists reveals whether the user has one of the roles necessary to access the EJB method.</para>
+A comparison of these lists reveals whether the user has one of the roles necessary to access the EJB method.</para>
<example id="exam-RunAsIdentity_Creation">
<title> org.jboss.security.RunAsIdentity Creation</title>
<para>In the <filename>ejb-jar.xml</filename> file, you specify a <sgmltag><security-identity></sgmltag> element with a <sgmltag><run-as></sgmltag> role defined as a child of the <session> element.</para>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-RunAsLoginModule.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-RunAsLoginModule.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-RunAsLoginModule.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -5,17 +5,18 @@
]>
<section id="sect-RunAsLoginModule">
<title>RunAsLoginModule</title>
- <para>
- JBoss has a helper login module called <literal>RunAsLoginModule</literal> that pushes a run as role for the duration of the login phase of authentication, and pops the run as role in either the commit or abort phase. The purpose of this login module is to provide a role for other login modules that need to access secured resources in order to perform their authentication. An example would be a login module that accesses an secured EJB. This login module must be configured ahead of the login module(s) that need a run as role established.
+ <para><literal>RunAsLoginModule</literal> is a helper module that pushes a run as role for the duration of the login phase of authentication, and pops the run as role in either the commit or abort phase. </para>
+ <para>The purpose of this login module is to provide a role for other login modules that need to access secured resources in order to perform their authentication (for example, a login module that accesses an secured EJB). <literal>RunAsLoginModule</literal> must be configured ahead of the login module(s) that require a run as role established.
</para>
<para>
The only login module configuration option is:
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">roleName</emphasis>: the name of the role to use as the run as role during login phase. If not specified a default of <literal>nobody</literal> is used.
- </para>
- </listitem>
- </itemizedlist>
+ <variablelist>
+ <varlistentry>
+ <term>roleName</term>
+ <listitem>
+ <para>Name of the role to use as the run as role during login phase. If not specified a default of <literal>nobody</literal> is used.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Security_Identity.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Security_Identity.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Security_Identity.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,7 +6,7 @@
<section id="J2EE_Declarative_Security_Overview-Security_Identity">
<title>Security Identity</title>
<para>
- An EJB has the capability to specify what identity an EJB should use when it invokes methods on other components using the <literal>security-identity</literal> element, shown in <xref linkend="Security_Identity-The_security_identity_element"/>
+ An EJB can specify what identity an EJB should use when it invokes methods on other components using the <literal>security-identity</literal> element, shown in <xref linkend="Security_Identity-The_security_identity_element"/>
</para>
<figure id="Security_Identity-The_security_identity_element">
<title>The security-identity element</title>
@@ -17,10 +17,10 @@
</mediaobject>
</figure>
<para>
- The invocation identity can be that of the current caller, or it can be a specific role. The application assembler uses the <literal>security-identity</literal> element with a <literal>use-caller-identity</literal> child element to indicate that the current caller's identity should be propagated as the security identity for method invocations made by the EJB. Propagation of the caller's identity is the default used in the absence of an explicit <literal>security-identity</literal> element declaration.
+ The invocation identity can be that of the current caller, or it can be a specific role. The application assembler uses the <literal>security-identity</literal> element with a <markup>use-caller-identity</markup> child element to indicate that the current caller's identity should be propagated as the security identity for method invocations made by the EJB. Propagation of the caller's identity is the default used in the absence of an explicit <markup>security-identity</markup> element declaration.
</para>
<para>
- Alternatively, the application assembler can use the <literal>run-as/role-name</literal> child element to specify that a specific security role given by the <literal>role-name</literal> value should be used as the security identity for method invocations made by the EJB. Note that this does not change the caller's identity as seen by the <literal>EJBContext.getCallerPrincipal()</literal> method. Rather, the caller's security roles are set to the single role specified by the <literal>run-as/role-name</literal> element value. One use case for the <literal>run-as</literal> element is to prevent external clients from accessing internal EJBs. You accomplish this by assigning the internal EJB <literal>method-permission</literal> elements that restrict access to a role never assigned to an external client. EJBs that need to use internal EJB are then configured with a <literal>run-as/role-name</literal> equal to the restricted role. The following descriptor fragment t!
hat illustrates <literal>security-identity</literal> element usage.
+ Alternatively, the application assembler can use the <markup>run-as/role-name</markup> child element to specify that a specific security role given by the <markup>role-name</markup> value should be used as the security identity for method invocations made by the EJB. Note that this does not change the caller's identity as seen by the <methodname>EJBContext.getCallerPrincipal()</methodname> method. Rather, the caller's security roles are set to the single role specified by the <markup>run-as/role-name</markup> element value. One use case for the <markup>run-as</markup> element is to prevent external clients from accessing internal EJBs. You accomplish this by assigning the internal EJB <markup>method-permission</markup> elements that restrict access to a role never assigned to an external client. EJBs that need to use internal EJB are then configured with a <markup>run-as/role-name</markup> equal to the restricted role. The following descriptor fragment that il!
lustrates <markup>security-identity</markup> element usage.
</para>
<programlisting language="XML" role="XML"><!-- A sample ejb-jar.xml fragment -->
<ejb-jar>
@@ -47,7 +47,7 @@
</ejb-jar>
</programlisting>
<para>
- When you use <literal>run-as</literal> to assign a specific role to outgoing calls, JBoss associates a principal named <literal>anonymous</literal>. If you want another principal to be associated with the call, you need to associate a <literal>run-as-principal</literal> with the bean in the <literal>jboss.xml</literal> file. The following fragment associates a principal named <literal>internal</literal> with <literal>RunAsBean</literal> from the prior example.
+ When you use <markup>run-as</markup> to assign a specific role to outgoing calls, JBoss associates a principal named <markup>anonymous</markup>. If you want another principal to be associated with the call, you need to associate a <markup>run-as-principal</markup> with the bean in the <filename>jboss.xml</filename> file. The following fragment associates a principal named <literal>internal</literal> with <literal>RunAsBean</literal> from the prior example.
</para>
<programlisting language="XML" role="XML"><session>
<ejb-name>RunAsBean</ejb-name>
@@ -57,7 +57,7 @@
</session>
</programlisting>
<para>
- The <literal>run-as</literal> element is also available in servlet definitions in a <literal>web.xml</literal> file. The following example shows how to assign the role <literal>InternalRole</literal> to a servlet:
+ The <markup>run-as</markup> element is also available in servlet definitions in a <filename>web.xml</filename> file. The following example shows how to assign the role <literal>InternalRole</literal> to a servlet:
</para>
<programlisting language="XML" role="XML"><servlet>
<servlet-name>AServlet</servlet-name>
@@ -68,7 +68,7 @@
</servlet>
</programlisting>
<para>
- Calls from this servlet will be associated with the anonymous <literal>principal</literal>. The <literal>run-as-principal</literal> element is available in the <literal>jboss-web.xml</literal> file to assign a specific principal to go along with the <literal>run-as</literal> role. The following fragment shows how to associate a principal named <literal>internal</literal> to the servlet in the prior example.
+ Calls from this servlet will be associated with the anonymous <literal>principal</literal>. The <markup>run-as-principal</markup> element is available in the <filename>jboss-web.xml</filename> file to assign a specific principal to go along with the <literal>run-as</literal> role. The following fragment shows how to associate a principal named <literal>internal</literal> to the servlet in the prior example.
</para>
<programlisting language="XML" role="XML"><servlet>
<servlet-name>AServlet</servlet-name>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Security_References.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Security_References.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Security_References.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,8 +6,7 @@
<section id="J2EE_Declarative_Security_Overview-Security_References">
<title>Security References</title>
<para>
- Both EJBs and servlets can declare one or more <literal>security-role-ref</literal> elements as shown in <xref linkend="Security_References-The_security_role_ref_element"/>. This element declares that a component is using the <literal>role-name</literal> value as an argument to the <literal>isCallerInRole(String)</literal> method. By using the <literal>isCallerInRole</literal> method, a component can verify whether the caller is in a role that has been declared with a <literal>security-role-ref/role-name</literal> element. The <literal>role-name</literal> element value must link to a <literal>security-role</literal> element through the <literal>role-link</literal> element. The typical use of <literal>isCallerInRole</literal> is to perform a security check that cannot be defined by using the role-based <literal>method-permissions</literal> elements.
- </para>
+ Both EJBs and servlets can declare one or more <literal>security-role-ref</literal> elements as shown in <xref linkend="Security_References-The_security_role_ref_element"/>. </para>
<figure id="Security_References-The_security_role_ref_element">
<title>The security-role-ref element</title>
<mediaobject>
@@ -16,11 +15,13 @@
</imageobject>
</mediaobject>
</figure>
+ <para>This element declares that a component is using the <literal>role-name</literal> value as an argument to the <literal>isCallerInRole(String)</literal> method. By using the <literal>isCallerInRole</literal> method, a component can verify whether the caller is in a role that has been declared with a <literal>security-role-ref/role-name</literal> element. The <literal>role-name</literal> element value must link to a <literal>security-role</literal> element through the <literal>role-link</literal> element. The typical use of <literal>isCallerInRole</literal> is to perform a security check that cannot be defined by using the role-based <literal>method-permissions</literal> elements.
+ </para>
<para>
- <xref linkend="Security_References-An_ejb_jar.xml_descriptor_fragment_that_illustrates_the_security_role_ref_element_usage."/> shows the use of <literal>security-role-ref</literal> in an <literal>ejb-jar.xml</literal>.
+ <xref linkend="Security_References-An_ejb_jar.xml_descriptor_fragment_that_illustrates_the_security_role_ref_element_usage."/> describes the the use of <literal>security-role-ref</literal> in an <literal>ejb-jar.xml</literal>.
</para>
<example id="Security_References-An_ejb_jar.xml_descriptor_fragment_that_illustrates_the_security_role_ref_element_usage.">
- <title>An ejb-jar.xml descriptor fragment that illustrates the security-role-ref element usage.</title>
+ <title>ejb-jar.xml descriptor fragment</title>
<programlisting language="XML" role="XML"><!-- A sample ejb-jar.xml fragment -->
<ejb-jar>
<enterprise-beans>
@@ -41,7 +42,7 @@
<xref linkend="Security_References-An_example_web.xml_descriptor_fragment_that_illustrates_the_security_role_ref_element_usage."/> shows the use of <literal>security-role-ref</literal> in a <literal>web.xml</literal>.
</para>
<example id="Security_References-An_example_web.xml_descriptor_fragment_that_illustrates_the_security_role_ref_element_usage.">
- <title>An example web.xml descriptor fragment that illustrates the security-role-ref element usage.</title>
+ <title>web.xml descriptor fragment</title>
<programlisting language="XML" role="XML"><web-app>
<servlet>
<servlet-name>AServlet</servlet-name>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Security_Roles.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Security_Roles.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Security_Roles.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,13 +6,13 @@
<section id="J2EE_Declarative_Security_Overview-Security_roles">
<title>Security roles</title>
<para>
- The security role name referenced by either the <literal>security-role-ref</literal> or <literal>security-identity</literal> element needs to map to one of the application's declared roles. An application assembler defines logical security roles by declaring <literal>security-role</literal> elements. The <literal>role-name</literal> value is a logical application role name like Administrator, Architect, SalesManager, etc.
+ The security role name referenced by either the <markup>security-role-ref</markup> or <markup>security-identity</markup> element needs to map to one of the application's declared roles. An application assembler defines logical security roles by declaring <markup>security-role</markup> elements. The <literal>role-name</literal> value is a logical application role name like Administrator, Architect, SalesManager, etc.
</para>
<para>
The Java EE specifications note that it is important to keep in mind that the security roles in the deployment descriptor are used to define the logical security view of an application. Roles defined in the Java EE deployment descriptors should not be confused with the user groups, users, principals, and other concepts that exist in the target enterprise's operational environment. The deployment descriptor roles are application constructs with application domain-specific names. For example, a banking application might use role names such as BankManager, Teller, or Customer.
</para>
<figure id="Security_roles-The_security_role_element">
- <title>The security-role element</title>
+ <title>security-role element</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/j2ee_security_role.jpg"/>
@@ -20,10 +20,11 @@
</mediaobject>
</figure>
<para>
- In JBoss, a <literal>security-role</literal> element is only used to map <literal>security-role-ref/role-name</literal> values to the logical role that the component role references. The user's assigned roles are a dynamic function of the application's security manager, as you will see when we discuss the JBossSX implementation details. JBoss does not require the definition of <literal>security-role</literal> elements in order to declare method permissions. However, the specification of <literal>security-role</literal> elements is still a recommended practice to ensure portability across application servers and for deployment descriptor maintenance. <xref linkend="Security_roles-An_ejb_jar.xml_descriptor_fragment_that_illustrates_the_security_role_element_usage."/> shows the usage of the <literal>security-role</literal> in an <literal>ejb-jar.xml</literal> file.
+ In JBoss, a <markup>security-role</markup> element is only used to map <literal>security-role-ref/role-name</literal> values to the logical role that the component role references. The user's assigned roles are a dynamic function of the application's security manager, as you will see when we discuss the JBossSX implementation details. </para>
+ <para>JBoss does not require the definition of <markup>security-role</markup> elements in order to declare method permissions. However, the specification of <markup>security-role</markup> elements is still a recommended practice to ensure portability across application servers and for deployment descriptor maintenance. <xref linkend="Security_roles-An_ejb_jar.xml_descriptor_fragment_that_illustrates_the_security_role_element_usage."/>describes the usage of the <markup>security-role</markup> in an <filename>ejb-jar.xml</filename> file.
</para>
<example id="Security_roles-An_ejb_jar.xml_descriptor_fragment_that_illustrates_the_security_role_element_usage.">
- <title>An ejb-jar.xml descriptor fragment that illustrates the security-role element usage.</title>
+ <title>ejb-jar.xml descriptor fragment</title>
<programlisting language="XML" role="XML"><!-- A sample ejb-jar.xml fragment -->
<ejb-jar>
<!-- ... -->
@@ -40,7 +41,7 @@
<xref linkend="Security_roles-An_example_web.xml_descriptor_fragment_that_illustrates_the_security_role_element_usage."/> shows the usage of the <literal>security-role</literal> in an <literal>web.xml</literal> file.
</para>
<example id="Security_roles-An_example_web.xml_descriptor_fragment_that_illustrates_the_security_role_element_usage.">
- <title>An example web.xml descriptor fragment that illustrates the security-role element usage.</title>
+ <title>example web.xml descriptor fragment</title>
<programlisting language="XML" role="XML"><!-- A sample web.xml fragment -->
<web-app>
<!-- ... -->
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Subject_Authentication.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Subject_Authentication.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Subject_Authentication.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -20,7 +20,7 @@
</listitem>
<listitem>
<para>
- The application invokes the <literal>LoginContext.login</literal> method.
+ The application invokes the <methodname>LoginContext.login</methodname> method.
</para>
</listitem>
<listitem>
@@ -35,17 +35,17 @@
</listitem>
<listitem>
<para>
- If authentication succeeds, the application retrieves the authenticated subject using the <literal>LoginContext.getSubject</literal> method.
+ If authentication succeeds, the application retrieves the authenticated subject using the <methodname>LoginContext.getSubject</methodname> method.
</para>
</listitem>
<listitem>
<para>
- After the scope of the subject authentication is complete, all principals and related information associated with the subject by the login method can be removed by invoking the <literal>LoginContext.logout</literal> method.
+ After the scope of the subject authentication is complete, all principals and related information associated with the subject by the login method can be removed by invoking the <methodname>LoginContext.logout</methodname> method.
</para>
</listitem>
</orderedlist>
<para>
- The <literal>LoginContext</literal> class provides the basic methods for authenticating subjects and offers a way to develop an application that is independent of the underlying authentication technology. The <literal>LoginContext</literal> consults a <literal>Configuration</literal> to determine the authentication services configured for a particular application. <literal>LoginModule</literal> classes represent the authentication services. Therefore, you can plug different login modules into an application without changing the application itself. The following code shows the steps required by an application to authenticate a subject.
+ The <classname>LoginContext</classname> class provides the basic methods for authenticating subjects and offers a way to develop an application that is independent of the underlying authentication technology. The <classname>LoginContext</classname> consults a <literal>Configuration</literal> to determine the authentication services configured for a particular application. <classname>LoginModule</classname> classes represent the authentication services. Therefore, you can plug different login modules into an application without changing the application itself. The following code shows the steps required by an application to authenticate a subject.
</para>
<programlisting language="Java" role="JAVA">CallbackHandler handler = new MyHandler();
LoginContext lc = new LoginContext("some-config", handler);
@@ -105,38 +105,37 @@
</listitem>
<listitem>
<para>
- Each <literal>LoginModule</literal> is initialized with a call to its initialize method. The <literal>Subject</literal> argument is guaranteed to be non-null. The signature of the initialize method is: <literal>public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options)</literal>.
- </para>
+ Each <literal>LoginModule</literal> is initialized with a call to its initialize method. The <literal>Subject</literal> argument is guaranteed to be non-null. The signature of the initialize method is: <methodname>public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options)</methodname></para>
</listitem>
<listitem>
<para>
- The <literal>login</literal> method is called to start the authentication process. For example, a method implementation might prompt the user for a username and password and then verify the information against data stored in a naming service such as NIS or LDAP. Alternative implementations might interface to smart cards and biometric devices, or simply extract user information from the underlying operating system. The validation of user identity by each <literal>LoginModule</literal> is considered phase 1 of JAAS authentication. The signature of the <literal>login</literal> method is <literal>boolean login() throws LoginException</literal>. A <literal>LoginException</literal> indicates failure. A return value of true indicates that the method succeeded, whereas a return valueof false indicates that the login module should be ignored.
+ The <methodname>login</methodname> method is called to start the authentication process. For example, a method implementation might prompt the user for a username and password and then verify the information against data stored in a naming service such as NIS or LDAP. Alternative implementations might interface to smart cards and biometric devices, or simply extract user information from the underlying operating system. The validation of user identity by each <literal>LoginModule</literal> is considered phase 1 of JAAS authentication. The signature of the <methodname>login</methodname> method is <methodname>boolean login() throws LoginException</methodname>. A <literal>LoginException</literal> indicates failure. A return value of true indicates that the method succeeded, whereas a return valueof false indicates that the login module should be ignored.
</para>
</listitem>
<listitem>
<para>
- If the <literal>LoginContext</literal>'s overall authentication succeeds, <literal>commit</literal> is invoked on each <literal>LoginModule</literal>. If phase 1 succeeds for a <literal>LoginModule</literal>, then the commit method continues with phase 2 and associates the relevant principals, public credentials, and/or private credentials with the subject. If phase 1 fails for a <literal>LoginModule</literal>, then <literal>commit</literal> removes any previously stored authentication state, such as usernames or passwords. The signature of the <literal>commit</literal> method is: <literal>boolean commit() throws LoginException</literal>. Failure to complete the commit phase is indicated by throwing a <literal>LoginException</literal>. A return of true indicates that the method succeeded, whereas a return of false indicates that the login module should be ignored.
+ If the <literal>LoginContext</literal>'s overall authentication succeeds, <literal>commit</literal> is invoked on each <literal>LoginModule</literal>. If phase 1 succeeds for a <literal>LoginModule</literal>, then the commit method continues with phase 2 and associates the relevant principals, public credentials, and/or private credentials with the subject. If phase 1 fails for a <literal>LoginModule</literal>, then <literal>commit</literal> removes any previously stored authentication state, such as usernames or passwords. The signature of the <methodname>commit</methodname> method is: <methodname>boolean commit() throws LoginException</methodname>. Failure to complete the commit phase is indicated by throwing a <literal>LoginException</literal>. A return of true indicates that the method succeeded, whereas a return of false indicates that the login module should be ignored.
</para>
</listitem>
<listitem>
<para>
- If the <literal>LoginContext</literal>'s overall authentication fails, then the <literal>abort</literal> method is invoked on each <literal>LoginModule</literal>. The <literal>abort</literal> method removes or destroys any authentication state created by the login or initialize methods. The signature of the <literal>abort</literal> method is <literal>boolean abort() throws LoginException</literal>. Failure to complete the <literal>abort</literal> phase is indicated by throwing a <literal>LoginException</literal>. A return of true indicates that the method succeeded, whereas a return of false indicates that the login module should be ignored.
+ If the <literal>LoginContext</literal>'s overall authentication fails, then the <methodname>abort</methodname> method is invoked on each <literal>LoginModule</literal>. The <literal>abort</literal> method removes or destroys any authentication state created by the login or initialize methods. The signature of the <literal>abort</literal> method is <methodname>boolean abort() throws LoginException</methodname>. Failure to complete the <literal>abort</literal> phase is indicated by throwing a <literal>LoginException</literal>. A return of true indicates that the method succeeded, whereas a return of false indicates that the login module should be ignored.
</para>
</listitem>
<listitem>
<para>
- To remove the authentication state after a successful login, the application invokes <literal>logout</literal> on the <literal>LoginContext</literal>. This in turn results in a <literal>logout</literal> method invocation on each <literal>LoginModule</literal>. The <literal>logout</literal> method removes the principals and credentials originally associated with the subject during the <literal>commit</literal> operation. Credentials should be destroyed upon removal. The signature of the <literal>logout</literal> method is: <literal>boolean logout() throws LoginException</literal>. Failure to complete the logout process is indicated by throwing a <literal>LoginException</literal>. A return of true indicates that the method succeeded, whereas a return of false indicates that the login module should be ignored.
+ To remove the authentication state after a successful login, the application invokes <literal>logout</literal> on the <literal>LoginContext</literal>. This in turn results in a <methodname>logout</methodname> method invocation on each <literal>LoginModule</literal>. The <methodname>logout</methodname> method removes the principals and credentials originally associated with the subject during the <literal>commit</literal> operation. Credentials should be destroyed upon removal. The signature of the <methodname>logout</methodname> method is: <methodname>boolean logout() throws LoginException</methodname>. Failure to complete the logout process is indicated by throwing a <literal>LoginException</literal>. A return of true indicates that the method succeeded, whereas a return of false indicates that the login module should be ignored.
</para>
</listitem>
</itemizedlist>
<para>
- When a <literal>LoginModule</literal> must communicate with the user to obtain authentication information, it uses a <literal>CallbackHandler</literal> object. Applications implement the <literal>CallbackHandler</literal> interface and pass it to the LoginContext, which forwards it directly to the underlying login modules. Login modules use the <literal>CallbackHandler</literal> both to gather input from users, such as a password or smart card PIN, and to supply information to users, such as status information. By allowing the application to specify the <literal>CallbackHandler</literal>, underlying <literal>LoginModule</literal>s remain independent from the different ways applications interact with users. For example, a <literal>CallbackHandler</literal>'s implementation for a GUI application might display a window to solicit user input. On the other hand, a <literal>callbackhandler</literal>'s implementation for a non-GUI environment, such as an applicatio!
n server, might simply obtain credential information by using an application server API. The <literal>callbackhandler</literal> interface has one method to implement:
+ When a <literal>LoginModule</literal> must communicate with the user to obtain authentication information, it uses a <literal>CallbackHandler</literal> object. Applications implement the <interface>CallbackHandler</interface> interface and pass it to the <literal>LoginContext</literal>, which forwards it directly to the underlying login modules. Login modules use the <literal>CallbackHandler</literal> both to gather input from users, such as a password or smart card PIN, and to supply information to users, such as status information. By allowing the application to specify the <literal>CallbackHandler</literal>, underlying <literal>LoginModule</literal>s remain independent from the different ways applications interact with users. For example, a <literal>CallbackHandler</literal>'s implementation for a GUI application might display a window to solicit user input. On the other hand, a <interface>callbackhandler</interface>'s implementation for a non-GUI environ!
ment, such as an application server, might simply obtain credential information by using an application server API. The <interface>callbackhandler</interface> interface has one method to implement:
</para>
<programlisting language="Java" role="JAVA">void handle(Callback[] callbacks)
throws java.io.IOException,
UnsupportedCallbackException;
</programlisting>
<para>
- The <literal>Callback</literal> interface is the last authentication class we will look at. This is a tagging interface for which several default implementations are provided, including the <literal>NameCallback</literal> and <literal>PasswordCallback</literal> used in an earlier example. A <literal>LoginModule</literal> uses a <literal>Callback</literal> to request information required by the authentication mechanism. <literal>LoginModule</literal>s pass an array of <literal>Callback</literal>s directly to the <literal>CallbackHandler.handle</literal> method during the authentication's login phase. If a <literal>callbackhandler</literal> does not understand how to use a <literal>Callback</literal> object passed into the handle method, it throws an <literal>UnsupportedCallbackException</literal> to abort the login call.
+ The <literal>Callback</literal> interface is the last authentication class we will look at. This is a tagging interface for which several default implementations are provided, including the <literal>NameCallback</literal> and <literal>PasswordCallback</literal> used in an earlier example. A <literal>LoginModule</literal> uses a <literal>Callback</literal> to request information required by the authentication mechanism. <literal>LoginModule</literal>s pass an array of <literal>Callback</literal>s directly to the <methodname>CallbackHandler.handle</methodname> method during the authentication's login phase. If a <literal>callbackhandler</literal> does not understand how to use a <literal>Callback</literal> object passed into the handle method, it throws an <literal>UnsupportedCallbackException</literal> to abort the login call.
</para>
</section>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Subject_Usage_Pattern_Support.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Subject_Usage_Pattern_Support.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Subject_Usage_Pattern_Support.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,14 +6,22 @@
<section id="sect-Subject_Usage_Pattern_Support">
<title>Subject Usage Pattern Support</title>
<para>
- To simplify correct implementation of the <literal>Subject</literal> usage patterns described in the preceding section, JBossSX includes login modules that populate the authenticated <literal>Subject</literal> with a a template pattern which enforces correct <literal>Subject</literal> usage. </para>
+ To simplify correct implementation of the <literal>Subject</literal> usage patterns described in <xref linkend="sect-Custom_Modules"/>, JBossSX includes login modules that populate the authenticated <literal>Subject</literal> with a a template pattern that enforces correct <literal>Subject</literal> usage. </para>
<formalpara>
<title>AbstractServerLoginModule</title>
<para>The most generic of the two is the <literal>org.jboss.security.auth.spi.AbstractServerLoginModule</literal> class. </para>
</formalpara>
- <para>It provides a concrete implementation of the <literal>javax.security.auth.spi.LoginModule</literal> interface and offers abstract methods for the key tasks specific to an operation environment security infrastructure. The key details of the class are highlighted in the following class fragment. The JavaDoc comments detail the responsibilities of subclasses.
+ <para>It provides an implementation of the <literal>javax.security.auth.spi.LoginModule</literal> interface and offers abstract methods for the key tasks specific to an operation environment security infrastructure. The key details of the class are highlighted in <xref linkend="exam-AbstractServerLoginModule_Class_Fragment"/>. The JavaDoc comments detail the responsibilities of subclasses.
</para>
- <programlisting language="Java" role="JAVA">package org.jboss.security.auth.spi;
+ <important>
+ <para>The <literal>loginOk</literal> instance variable is pivotal. This must be set to <literal>true</literal> if the login succeeds, or <literal>false</literal> by any subclasses that override the login method. If this variable is incorrectly set, the commit method will not correctly update the subject.
+ </para>
+ </important>
+ <para>Tracking the outcome of the login phase allows login modules to be chained together with control flags that do not require that the login module succeed in order for the overall login to succeed.
+ </para>
+ <example id="exam-AbstractServerLoginModule_Class_Fragment">
+ <title>AbstractServerLoginModule Class Fragment</title>
+ <programlisting language="Java" role="JAVA">package org.jboss.security.auth.spi;
/**
* This class implements the common functionality required for a JAAS
* server-side LoginModule and implements the JBossSX standard
@@ -106,9 +114,7 @@
abstract protected Group[] getRoleSets() throws LoginException;
}
</programlisting>
- <para>
- You'll need to pay attention to the <literal>loginOk</literal> instance variable. This must be set to true if the login succeeds, false otherwise by any subclasses that override the login method. Failure to set this variable correctly will result in the commit method either not updating the subject when it should, or updating the subject when it should not. Tracking the outcome of the login phase was added to allow login modules to be chained together with control flags that do not require that the login module succeed in order for the overall login to succeed.
- </para>
+ </example>
<formalpara>
<title>UsernamePasswordLoginModule</title>
<para>
@@ -116,7 +122,9 @@
</formalpara>
<para>This login module further simplifies custom login module implementation by enforcing a string-based username as the user identity and a <literal>char[]</literal> password as the authentication credentials. It also supports the mapping of anonymous users (indicated by a null username and password) to a principal with no roles. The key details of the class are highlighted in the following class fragment. The JavaDoc comments detail the responsibilities of subclasses.
</para>
- <programlisting language="Java" role="JAVA">package org.jboss.security.auth.spi;
+ <example id="exam-UsernamePasswordLoginModule_Class_Fragment">
+ <title>UsernamePasswordLoginModule Class Fragment</title>
+ <programlisting language="Java" role="JAVA">package org.jboss.security.auth.spi;
/**
* An abstract subclass of AbstractServerLoginModule that imposes a
@@ -208,12 +216,17 @@
throws LoginException;
}
</programlisting>
- <para>
- The choice of subclassing the <literal>AbstractServerLoginModule</literal> versus <literal>UsernamePasswordLoginModule</literal> is simply based on whether a string-based username and credentials are usable for the authentication technology you are writing the login module for. If the string-based semantic is valid, then subclass <literal>UsernamePasswordLoginModule</literal>, otherwise subclass <literal>AbstractServerLoginModule</literal>.
+ </example>
+ <formalpara>
+ <title>Subclassing Login Modules</title>
+ <para>The choice of subclassing the <literal>AbstractServerLoginModule</literal> versus <literal>UsernamePasswordLoginModule</literal> is simply based on whether a string-based username and credentials are usable for the authentication technology you are writing the login module for. If the string-based semantic is valid, then subclass <literal>UsernamePasswordLoginModule</literal>, otherwise subclass <literal>AbstractServerLoginModule</literal>.
</para>
- <para>
- The steps you are required to perform when writing a custom login module are summarized in the following depending on which base login module class you choose. When writing a custom login module that integrates with your security infrastructure, you should start by subclassing <literal>AbstractServerLoginModule</literal> or <literal>UsernamePasswordLoginModule</literal> to ensure that your login module provides the authenticated <literal>Principal</literal> information in the form expected by the JBossSX security manager.
+ </formalpara>
+ <formalpara>
+ <title>Subclassing Steps</title>
+ <para>The steps your custom login module must execute are summarized in the following depending on which base login module class you choose. When writing a custom login module that integrates with your security infrastructure, you should start by subclassing <literal>AbstractServerLoginModule</literal> or <literal>UsernamePasswordLoginModule</literal> to ensure that your login module provides the authenticated <literal>Principal</literal> information in the form expected by the JBossSX security manager.
</para>
+ </formalpara>
<para>
When subclassing the <literal>AbstractServerLoginModule</literal>, you need to override the following:
</para>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Subject_and_Principal.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Subject_and_Principal.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Subject_and_Principal.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,7 +6,7 @@
<section id="sect-The_Subject_and_Principal_Classes">
<title>Subject and Principal Classes</title>
<para>
- To authorize access to resources, applications first need to authenticate the request's source. The JAAS framework defines the term subject to represent a request's source. The <literal>Subject</literal> class is the central class in JAAS. A <literal>Subject</literal> represents information for a single entity, such as a person or service. It encompasses the entity's principals, public credentials, and private credentials. The JAAS APIs use the existing Java 2 <literal>java.security.Principal</literal> interface to represent a principal, which is essentially just a typed name.
+ To authorize access to resources, applications must first authenticate the request's source. The JAAS framework defines the term subject to represent a request's source. The <classname>Subject</classname> class is the central class in JAAS. A <classname>Subject</classname> represents information for a single entity, such as a person or service. It encompasses the entity's principals, public credentials, and private credentials. The JAAS APIs use the existing Java 2 <classname>java.security.Principal</classname> interface to represent a principal, which is essentially just a typed name.
</para>
<para>
During the authentication process, a subject is populated with associated identities, or principals. A subject may have many principals. For example, a person may have a name principal (John Doe), a social security number principal (123-45-6789), and a username principal (johnd), all of which help distinguish the subject from other subjects. To retrieve the principals associated with a subject, two methods are available:
@@ -14,7 +14,6 @@
<programlisting language="Java" role="JAVA">public Set getPrincipals() {...}
public Set getPrincipals(Class c) {...}
</programlisting>
- <para>
- The first method returns all principals contained in the subject. The second method returns only those principals that are instances of class <literal>c</literal> or one of its subclasses. An empty set is returned if the subject has no matching principals. Note that the <literal>java.security.acl.Group</literal> interface is a subinterface of <literal>java.security.Principal</literal>, so an instance in the principals set may represent a logical grouping of other principals or groups of principals.
+ <para><methodname>getPrincipals()</methodname> returns all principals contained in the subject. <methodname>getPrincipals(Class c)</methodname> returns only those principals that are instances of class <literal>c</literal> or one of its subclasses. An empty set is returned if the subject has no matching principals. Note that the <classname>java.security.acl.Group</classname> interface is a subinterface of <classname>java.security.Principal</classname>, so an instance in the principals set may represent a logical grouping of other principals or groups of principals.
</para>
</section>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Unauthenticated_Identity.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Unauthenticated_Identity.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Unauthenticated_Identity.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -5,8 +5,7 @@
]>
<section id="Using_JBoss_Login_Modules-Unauthenticated_Identity">
<title>Unauthenticated Identity</title>
- <para>
- Not all requests come in authenticated. The unauthenticated identity is a login module configuration option that assigns a specific identity (guest, for example) to requests that are made with no associated authentication information. This can be used to allow unprotected servlets to invoke methods on EJBs that do not require a specific role. Such a principal has no associated roles and so can only access either unsecured EJBs or EJB methods that are associated with the unchecked permission constraint.
+ <para>Not all requests are received in an authenticated format. <literal>unauthenticated identity</literal> is a login module configuration option that assigns a specific identity (guest, for example) to requests that are made with no associated authentication information. This can be used to allow unprotected servlets to invoke methods on EJBs that do not require a specific role. Such a principal has no associated roles and so can only access either unsecured EJBs or EJB methods that are associated with the unchecked permission constraint.
</para>
<itemizedlist>
<listitem>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-UsersRolesLoginModule.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-UsersRolesLoginModule.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-UsersRolesLoginModule.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -5,25 +5,25 @@
]>
<section id="sect-UsersRolesLoginModule">
<title>UsersRolesLoginModule</title>
- <para>
- The <literal>UsersRolesLoginModule</literal> is a simple login module that supports multiple users and user roles loaded from Java properties files. The username-to-password mapping file is called <literal>users.properties</literal> and the username-to-roles mapping file is called <literal>roles.properties</literal>. The properties files are loaded during initialization using the initialize method thread context class loader. This means that these files can be placed into the Java EE deployment JAR, the JBoss configuration directory, or any directory on the JBoss server or system classpath. The primary purpose of this login module is to easily test the security settings of multiple users and roles using properties files deployed with the application.
+ <para><literal>UsersRolesLoginModule</literal> is a simple login module that supports multiple users and user roles loaded from Java properties files. The username-to-password mapping file is called <filename>users.properties</filename> and the username-to-roles mapping file is called <filename>roles.properties</filename>. </para>
+ <para>The properties files are loaded during initialization using the initialize method thread context class loader. This means that these files can be placed into the Java EE deployment JAR, the JBoss configuration directory, or any directory on the JBoss server or system classpath. The primary purpose of this login module is to easily test the security settings of multiple users and roles using properties files deployed with the application.
</para>
<para>
- The <literal>users.properties</literal> file uses a <literal>username=password</literal> format with each user entry on a separate line as show here:
+ The <filename>users.properties</filename> file uses a <filename>username=password</filename> format with each user entry on a separate line as show here:
</para>
<programlisting>username1=password1
username2=password2
...
</programlisting>
<para>
- The <literal>roles.properties</literal> file uses as <literal>username=role1,role2,...</literal> format with an optional group name value. For example:
+ The <filename>roles.properties</filename> file uses as <literal>username=role1,role2,...</literal> format with an optional group name value. For example:
</para>
<programlisting>username1=role1,role2,...
username1.RoleGroup1=role3,role4,...
username2=role1,role3,...
</programlisting>
<para>
- The <literal>username.XXX</literal> form of property name is used to assign the username roles to a particular named group of roles where the <literal>XXX</literal> portion of the property name is the group name. The <literal>username=...</literal> form is an abbreviation for <literal>username.Roles=...</literal>, where the <literal>Roles</literal> group name is the standard name the <literal>JaasSecurityManager</literal> expects to contain the roles which define the users permissions.
+ The <property>username.XXX</property> form of property name is used to assign the username roles to a particular named group of roles where the <literal>XXX</literal> portion of the property name is the group name. The <property>username=...</property> form is an abbreviation for <property>username.Roles=...</property>, where the <literal>Roles</literal> group name is the standard name the <literal>JaasSecurityManager</literal> expects to contain the roles which define the users permissions.
</para>
<para>
The following would be equivalent definitions for the <literal>jduke</literal> username:
@@ -34,19 +34,22 @@
<para>
The supported login module configuration options include the following:
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">usersProperties</emphasis>: The name of the properties resource containing the username to password mappings. This defaults to <literal>users.properties</literal>.
+ <variablelist>
+ <varlistentry>
+ <term>usersProperties</term>
+ <listitem>
+ <para>Name of the properties resource (file) containing the username to password mappings. This defaults to <filename>users.properties</filename>.
</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">rolesProperties</emphasis>: The name of the properties resource containing the username to roles mappings. This defaults to <literal>roles.properties</literal>.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>rolesProperties</term>
+ <listitem>
+ <para>Name of the properties resource (file) containing the username to roles mappings. This defaults to <filename>roles.properties</filename>.
</para>
- </listitem>
- </itemizedlist>
- <para>
- This login module supports password stacking, password hashing and unauthenticated identity.
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>This login module supports password stacking, password hashing, and unauthenticated identity.
</para>
</section>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Web_Content_Security_Constraints.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Web_Content_Security_Constraints.xml 2010-05-24 06:39:53 UTC (rev 105134)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/sect-Web_Content_Security_Constraints.xml 2010-05-24 06:41:01 UTC (rev 105135)
@@ -6,10 +6,10 @@
<section id="J2EE_Declarative_Security_Overview-Web_Content_Security_Constraints">
<title>Web Content Security Constraints</title>
<para>
- In a web application, security is defined by the roles that are allowed access to content by a URL pattern that identifies the protected content. This set of information is declared by using the <literal>web.xml</literal><literal>security-constraint</literal> element.
+ In a web application, security is defined by the roles that are allowed access to content by a URL pattern that identifies the protected content. This set of information is declared by using the <filename>web.xml</filename><markup> security-constraint</markup> element.
</para>
<figure id="Web_Content_Security_Constraints-The_security_constraint_element">
- <title>The security-constraint element</title>
+ <title><security-constraint> element</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/webapp_security_constraint.jpg"/>
@@ -17,16 +17,16 @@
</mediaobject>
</figure>
<para>
- The content to be secured is declared using one or more <literal>web-resource-collection</literal> elements. Each <literal>web-resource-collection</literal> element contains an optional series of <literal>url-pattern</literal> elements followed by an optional series of <literal>http-method</literal> elements. The <literal>url-pattern</literal> element value specifies a URL pattern against which a request URL must match for the request to correspond to an attempt to access secured content. The <literal>http-method</literal> element value specifies a type of HTTP request to allow.
+ The content to be secured is declared using one or more <markup>web-resource-collection</markup> elements. Each <markup>web-resource-collection</markup> element contains an optional series of <markup>url-pattern</markup> elements followed by an optional series of <markup>http-method</markup> elements. The <markup>url-pattern</markup> element value specifies a URL pattern against which a request URL must match for the request to correspond to an attempt to access secured content. The <markup>http-method</markup> element value specifies a type of HTTP request to allow.
</para>
<para>
- The optional <literal>user-data-constraint</literal> element specifies the requirements for the transport layer of the client to server connection. The requirement may be for content integrity (preventing data tampering in the communication process) or for confidentiality (preventing reading while in transit). The transport-guarantee element value specifies the degree to which communication between the client and server should be protected. Its values are <literal>NONE</literal>, <literal>INTEGRAL</literal>, and <literal>CONFIDENTIAL</literal>. A value of <literal>NONE</literal> means that the application does not require any transport guarantees. A value of <literal>INTEGRAL</literal> means that the application requires the data sent between the client and server to be sent in such a way that it can't be changed in transit. A value of <literal>CONFIDENTIAL</literal> means that the application requires the data to be transmitted in a fashion that prevents other ent!
ities from observing the contents of the transmission. In most cases, the presence of the <literal>INTEGRAL</literal> or <literal>CONFIDENTIAL</literal> flag indicates that the use of SSL is required.
+ The optional <markup>user-data-constraint</markup> element specifies the requirements for the transport layer of the client to server connection. The requirement may be for content integrity (preventing data tampering in the communication process) or for confidentiality (preventing reading while in transit). The transport-guarantee element value specifies the degree to which communication between the client and server should be protected. Its values are <literal>NONE</literal>, <literal>INTEGRAL</literal>, and <literal>CONFIDENTIAL</literal>. A value of <literal>NONE</literal> means that the application does not require any transport guarantees. A value of <literal>INTEGRAL</literal> means that the application requires the data sent between the client and server to be sent in such a way that it can't be changed in transit. A value of <literal>CONFIDENTIAL</literal> means that the application requires the data to be transmitted in a fashion that prevents other entit!
ies from observing the contents of the transmission. In most cases, the presence of the <literal>INTEGRAL</literal> or <literal>CONFIDENTIAL</literal> flag indicates that the use of SSL is required.
</para>
<para>
- The optional <literal>login-config</literal> element is used to configure the authentication method that should be used, the realm name that should be used for rhw application, and the attributes that are needed by the form login mechanism.
+ The optional <markup>login-config</markup> element is used to configure the authentication method that should be used, the realm name that should be used for rhw application, and the attributes that are needed by the form login mechanism.
</para>
<figure id="Web_Content_Security_Constraints-The_login_config_element">
- <title>The login-config element</title>
+ <title><login-config> element</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/webapp_login_config.jpg"/>
@@ -36,11 +36,10 @@
<para>
The <literal>auth-method</literal> child element specifies the authentication mechanism for the web application. As a prerequisite to gaining access to any web resources that are protected by an authorization constraint, a user must have authenticated using the configured mechanism. Legal <literal>auth-method</literal> values are <literal>BASIC</literal>, <literal>DIGEST</literal>, <literal>FORM</literal>, and <literal>CLIENT-CERT</literal>. The <literal>realm-name</literal> child element specifies the realm name to use in HTTP basic and digest authorization. The <literal>form-login-config</literal> child element specifies the log in as well as error pages that should be used in form-based login. If the <literal>auth-method</literal> value is not <literal>FORM</literal>, then <literal>form-login-config</literal> and its child elements are ignored.
</para>
- <para>
- As an example, the <literal>web.xml</literal> descriptor fragment given in <xref linkend="Web_Content_Security_Constraints-_A_web.xml_descriptor_fragment_which_illustrates_the_use_of_the_security_constraint_and_related_elements."/> indicates that any URL lying under the web application's <literal>/restricted</literal> path requires an <literal>AuthorizedUser</literal> role. There is no required transport guarantee and the authentication method used for obtaining the user identity is BASIC HTTP authentication.
+ <para><xref linkend="Web_Content_Security_Constraints-_A_web.xml_descriptor_fragment_which_illustrates_the_use_of_the_security_constraint_and_related_elements."/> indicates that any URL lying under the web application's <filename>/restricted</filename> path requires an <literal>AuthorizedUser</literal> role. There is no required transport guarantee and the authentication method used for obtaining the user identity is BASIC HTTP authentication.
</para>
<example id="Web_Content_Security_Constraints-_A_web.xml_descriptor_fragment_which_illustrates_the_use_of_the_security_constraint_and_related_elements.">
- <title> A web.xml descriptor fragment which illustrates the use of the security-constraint and related elements.</title>
+ <title> web.xml descriptor fragment</title>
<programlisting language="XML" role="XML"><web-app>
<!-- ... -->
<security-constraint>
More information about the jboss-cvs-commits
mailing list