[jboss-cvs] JBossAS SVN: r102192 - projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Mar 10 00:08:58 EST 2010
Author: jaredmorgs
Date: 2010-03-10 00:08:57 -0500 (Wed, 10 Mar 2010)
New Revision: 102192
Modified:
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/JBoss_Security_Guide.xml
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Security_Configuration_And_Architecture.xml
Log:
[EAP 5.1] Updated Security Guide with blog post as reported in https://jira.jboss.org/jira/browse/JBPAPP-3319
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/JBoss_Security_Guide.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/JBoss_Security_Guide.xml 2010-03-10 05:07:05 UTC (rev 102191)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/JBoss_Security_Guide.xml 2010-03-10 05:08:57 UTC (rev 102192)
@@ -5,6 +5,14 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Preface.xml"/>
<!--<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="chap-JBoss_Security.xml"/>--> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="chap-Security_Configuration_And_Architecture.xml"/>
+ <appendix>
+ <title>Security Tips and Tricks</title>
+ <para/>
+ <section>
+ <title>Role Mapping at the Deployment Level</title>
+ <para/>
+ </section>
+ </appendix>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/>
<index/>
</book>
Modified: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Security_Configuration_And_Architecture.xml
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Security_Configuration_And_Architecture.xml 2010-03-10 05:07:05 UTC (rev 102191)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Security_Configuration_And_Architecture.xml 2010-03-10 05:08:57 UTC (rev 102192)
@@ -931,16 +931,22 @@
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. 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</liter!
al> element, and the security manager instance for the <literal>XYZ</literal> security domain will be created as needed for you. 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:
+ 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>
+ <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>
+ <title>Important: java:/jaas prefix is no longer mandatory</title>
+ <para>In Enterprise Application Platform versions prior to v5.0, the "<filename>java:/jaas</filename> prefix in each <sgmltag><securitydomain></sgmltag> deployment descrptor element was required to correctly bind the JNDI name to the security manager bindings. As of JBoss AS 5.0.0, it is possible to specify the name of the <sgmltag><securitydomain></sgmltag> only in <filename>jboss.xml</filename> and <filename>jboss-web.xml</filename>. The <filename>java:/jaas</filename> prefix is still supported however, and remains for backwards compatibility.</para>
+ </important>
<programlisting language="XML" role="XML"><jboss>
<!-- Configure all containers to be secured under the "hades" security domain -->
- <security-domain>java:/jaas/hades</security-domain>
+ <security-domain>hades</security-domain>
<!-- ... -->
</jboss>
</programlisting>
<para>
- Any lookup of the name <literal>java:/jaas/hades</literal> will return a security manager instance that has been associated with the security domain named <literal>hades</literal>. This security manager will implement the AuthenticationManager and RealmMapping security interfaces and will be of the type specified by the <literal>JaasSecurityManagerService</literal><literal>SecurityManagerClassName</literal> attribute.
+ Any lookup of the name <literal>hades</literal> will return a security manager instance that has been associated with the security domain named <literal>hades</literal>. This security manager will implement the AuthenticationManager and RealmMapping security interfaces and will be of the type specified by the <literal>JaasSecurityManagerService</literal><literal>SecurityManagerClassName</literal> attribute.
</para>
<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:
@@ -1097,7 +1103,7 @@
</section>
</section>
<section id="Security_on_JBoss-Defining_Security_Domains">
- <title>Configuring Security Domains</title>
+ <title>Security Domains</title>
<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>
@@ -1129,7 +1135,7 @@
</application-policy>
</programlisting>
<para>
- The <literal>name</literal> attribute of the <literal>application-policy</literal> is the login configuration name. Applications policy elements will be 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 <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)
</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:
@@ -1176,10 +1182,10 @@
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.
</para>
<section id="JBoss-Security-Configuring_Microcontainer_Security_Domains">
- <title>Configuring Microcontainer Security Domains</title>
-<!--Added this section from http://server.dzone.com/articles/security-features-jboss-510--> <para>Historically, the Enterprise Application Platform used the static <filename>login-config.xml</filename> file to configure the security domain. Extra functionality was provided with the introduction of the DynamicLoginConfig security service. This functionality allowed you to specify a Java Authentication and Authorisation Service (JAAS) as part of an application deployment, rather than having to include the configuration information in <filename>login-config.xml</filename>.</para>
- <para>The Enterprise Application Platform now provides these security requirements through the use of the JBoss Microcontainer and EJBs. </para>
- <para>In a security-conscious system, JavaEE components such as Web or Enterprise Java Bean (EJB) components require a Security Domain to manage the authentication, authorization, auditing, and mapping functionality. </para>
+ <title>Configuring Security Domains</title>
+<!--Added this section from http://server.dzone.com/articles/security-features-jboss-510--> <para>Historically, the Enterprise Application Platform used the static <filename>login-config.xml</filename> file to configure the security domain. Dynamic configuration was provided with the introduction of the DynamicLoginConfig security service. This functionality allowed you to specify a Java Authentication and Authorisation Service (JAAS) as part of an application deployment, rather than having to include the configuration information in <filename>login-config.xml</filename>.</para>
+ <para>The Enterprise Application Platform now provides an additional, simplified mechanism to configure security domains. </para>
+ <para>In the Enterprise Application Platform, the security domain configuration is important for the authentication, authorization, auditing, and mapping functionality associated with JavaEE components such a Web or EJBs. </para>
<para>The latest security implementation allows you to create a logically-named deployment descriptor file and specify the security domains within the file. The deployment descriptor can be deployed directly in the deploy folder, or packaged as part of the application JAR or WAR file.</para>
<procedure>
<title>Security Domain Deployment Descriptor</title>
@@ -1189,7 +1195,7 @@
<para>You must create a deployment descriptor file to contain the security domain configuration.</para>
<para>The filename takes the format <filename><replaceable>[domain_name]</replaceable>-jboss-beans.xml</filename>. The <replaceable>domain_name</replaceable> is arbitrary, however you should choose a name that is meaningful to the application. </para>
<para>The file must contain the standard XML declaration, and a correctly configured <sgmltag><deployment></sgmltag> element.</para>
- <programlisting role="XML" language="XML"><?xml version="1.0" encoding="UTF-8"?>
+ <programlisting language="XML" role="XML"><?xml version="1.0" encoding="UTF-8"?>
<deployment xmlns="urn:jboss:bean-deployer:2.0">
@@ -1208,21 +1214,21 @@
<step>
<title>Deploy or package the deployment descriptor</title>
<para>Move the deployment descriptor file to the <filename>deploy</filename> directory of the required server profile in your installation. </para>
- <para>Alternatively, package the deployment descriptor in the <filename>META-INF</filename> directory of the EJB Jar, or the Web application (WAR).</para>
+ <para>Alternatively, package the deployment descriptor in the <filename>META-INF</filename> directory of the EJB Jar, or WEB-INF/classes of your web application (WAR).</para>
</step>
</procedure>
<!--TODO: Thought I should mention this here, but technically the link provided in the Note links forward, instead of backwards. I wanted to mention the Login Modules here just in case readers didn't want to go old-school and use the login-config.xml method.--> </section>
<section>
<title>Configuring Authorization Stacks</title>
- <para>If a security domain does not define an authorization module, the default <parameter>jboss-web-policy</parameter> and <parameter>jboss-ejb-policy</parameter> authorization configured in <filename>security-policies-jboss-beans.xml</filename> is used. If you specify an JAAS authorization module, or create a custom deployment descriptor file with valid authorization configuration, these settings override the default settings in <filename>security-policies-jboss-beans.xml</filename>. </para>
- <para>Overriding the default authorization for EJB or Web components is implemented using Java Authorization Contract for Containers (JACC), Extensible Access Control Markup Language (XACML), or custom authorization methods. Configuring this functionality allows access control stacks to be pluggable for a particular component, overriding the default authorization contained in <filename>jboss.xml</filename> (for EJBs) and <filename>jboss-web.xml</filename> (for WAR).</para>
+ <para>If a security domain does not define an authorization module, the default <parameter>jboss-web-policy</parameter> and <parameter>jboss-ejb-policy</parameter> authorization configured in <filename>security-policies-jboss-beans.xml</filename> is used. If you specify an authorization module, or create a custom deployment descriptor file with valid authorization configuration, these settings override the default settings in <filename>security-policies-jboss-beans.xml</filename>. </para>
+ <para>Overriding the default authorization for EJB or Web components is provided for JACC and XACML, apart from the default modules that implement the specification behavior. Users can provide authorization modules that implement custom behavior. Configuring this functionality allows access control stacks to be pluggable for a particular component, overriding the default authorization contained in <filename>jboss.xml</filename> (for EJBs) and <filename>jboss-web.xml</filename> (for WAR).</para>
<formalpara>
<title>Setting authorization for all EJB and WEB components</title>
<para>You can override authorization for all EJBs and Web components, or for a particular component.</para>
</formalpara>
<procedure id="proc-Set_Auth_Policies_For_All_EJB_WAR_Components">
<title>Set authorization policies for all EJB and WAR components</title>
- <para>This procedure describes how to define JACC Authorization control for all EJB and WAR components. The example defines application policy modules for three components: <filename>jboss-web-policy</filename>, <filename>jboss-ejb-policy</filename>, and <filename>jacc-test</filename>.</para>
+ <para>This procedure describes how to define JACC Authorization control for all EJB and WAR components. The example defines application policy modules for Web and EJB applications: <filename>jboss-web-policy</filename>, and <filename>jboss-ejb-policy</filename>.</para>
<step>
<title>Open the security policy bean</title>
<para>Navigate to <filename><replaceable>[install_directory]</replaceable>/jboss-as/server/all/deploy/security</filename></para>
@@ -1294,16 +1300,16 @@
<para> </para>
<example id="exam-security-AuthorizationModuleDelegate_Class">
<title>AuthorizationModuleDelegate class</title>
- <programlisting role="JAVA" language="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/security-policies-authorization_delegate_example.java" parse="text"/></programlisting>
+ <programlisting language="Java" role="JAVA"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/security-policies-authorization_delegate_example.java" parse="text"/></programlisting>
</example>
<para>Some examples of authorization delegation are included for reference. <xref linkend="exam-security-EJBJACCPolicyModuleDelegate_Module"/> describes an authorization module responsible for authorization decisions for the EJB layer. <xref linkend="exam-security-WebJACCPolicyModuleDelegate_Module"/> describes a JACC-based authorization module helper that controls web layer authorization decisions.</para>
<example id="exam-security-EJBJACCPolicyModuleDelegate_Module">
<title>EJBJACCPolicyModuleDelegate.java</title>
- <programlisting role="JAVA" language="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/security-policies-EJBJACCPolicyModuleDelegate.java" parse="text"/></programlisting>
+ <programlisting language="Java" role="JAVA"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/security-policies-EJBJACCPolicyModuleDelegate.java" parse="text"/></programlisting>
</example>
<example id="exam-security-WebJACCPolicyModuleDelegate_Module">
<title>WebJACCPolicyModuleDelegate.java</title>
- <programlisting role="JAVA" language="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/security-policies-WebJACCPolicyModuleDelegate.java" parse="text"/></programlisting>
+ <programlisting language="Java" role="JAVA"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/security-policies-WebJACCPolicyModuleDelegate.java" parse="text"/></programlisting>
</example>
</section>
<section id="sect-Configure_Security_Auditing">
@@ -1331,7 +1337,7 @@
<para>By default, the Security Audit Provider category definition in the <filename>jboss-log4j.xml</filename> file is commented out. Uncomment the category definition shown in <xref linkend="exam-log4j_Security_Audit_Provider_Category"/>.</para>
<example id="exam-log4j_Security_Audit_Provider_Category">
<title>log4j Security Audit Provider category</title>
- <programlisting role="XML" language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/jboss-log4j-Security_Audit_Provider_Category.xml_sample" parse="text"/></programlisting>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/jboss-log4j-Security_Audit_Provider_Category.xml_sample" parse="text"/></programlisting>
</example>
</step>
<step>
@@ -1339,7 +1345,7 @@
<para>By default, the AUDIT appender definition in the <filename>jboss-log4j.xml</filename> file is commented out. Uncomment the appender definition shown in <xref linkend="exam-log4j_Security_Audit_Provider_Category"/>.</para>
<example id="exam-log4j_Security_Audit_AUDIT_Appender">
<title>log4j Security Audit Provider category</title>
- <programlisting role="XML" language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/jboss-log4j-Security_Audit_AUDIT_Appender.xml_sample" parse="text"/></programlisting>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/jboss-log4j-Security_Audit_AUDIT_Appender.xml_sample" parse="text"/></programlisting>
</example>
</step>
<step>
@@ -1409,7 +1415,7 @@
</procedure>
</section>
<section>
- <title>Configuring Customer Callback Handlers</title>
+ <title>Configuring Custom Callback Handlers</title>
<para>Implementing callback handlers into authentication procedures allows a Login Module to authenticate a user independent of the client application authentication method. </para>
<para>You can implement callback handlers using the following methods:</para>
<itemizedlist>
@@ -2116,7 +2122,7 @@
Next we, need to specify the JBoss security domain in <literal>jboss-web.xml</literal>:
</para>
<programlisting language="XML" role="XML"><jboss-web>
- <security-domain>java:/jaas/jmx-console</security-domain>
+ <security-domain>jmx-console</security-domain>
</jboss-web>
</programlisting>
<para>
@@ -2127,7 +2133,7 @@
<login-module code="org.jboss.security.auth.spi.BaseCertLoginModule"
flag="required">
<module-option name="password-stacking">useFirstPass</module-option>
- <module-option name="securityDomain">java:/jaas/jmx-console</module-option>
+ <module-option name="securityDomain">jmx-console</module-option>
</login-module>
<login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
flag="required">
@@ -2651,7 +2657,7 @@
</para>
<programlisting language="XML" role="XML"><?xml version="1.0"?>
<jboss>
- <security-domain>java:/jaas/security-ex2</security-domain>
+ <security-domain>security-ex2</security-domain>
</jboss>
</programlisting>
<para>
More information about the jboss-cvs-commits
mailing list