[jboss-cvs] JBossAS SVN: r101756 - in projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US: extras and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Mar 3 02:06:18 EST 2010
Author: jaredmorgs
Date: 2010-03-03 02:06:18 -0500 (Wed, 03 Mar 2010)
New Revision: 101756
Added:
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/extras/callback-handler-jboss_service_xml_CCH.xml_sample
projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/extras/callback-handler-jboss_service_xml_default.xml_sample
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:
Finalized last blog post incorporation. Updated all code examples with correct attributes. Commit for hudson publish tonight.
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-03 06:51:56 UTC (rev 101755)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/JBoss_Security_Guide.xml 2010-03-03 07:06:18 UTC (rev 101756)
@@ -1,11 +1,10 @@
<?xml version='1.0' encoding='UTF-8'?>
<!-- This document was created with Syntext Serna Free. --><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<book>
+<book status="draft">
<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"/>
+<!--<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"/>
<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-03 06:51:56 UTC (rev 101755)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/chap-Security_Configuration_And_Architecture.xml 2010-03-03 07:06:18 UTC (rev 101756)
@@ -33,7 +33,7 @@
</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>
- <programlisting><!-- A sample ejb-jar.xml fragment -->
+ <programlisting language="XML" role="XML"><!-- A sample ejb-jar.xml fragment -->
<ejb-jar>
<enterprise-beans>
<session>
@@ -54,7 +54,7 @@
</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>
- <programlisting><web-app>
+ <programlisting language="XML" role="XML"><web-app>
<servlet>
<servlet-name>AServlet</servlet-name>
...
@@ -87,7 +87,7 @@
<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.
</para>
- <programlisting><!-- A sample ejb-jar.xml fragment -->
+ <programlisting language="XML" role="XML"><!-- A sample ejb-jar.xml fragment -->
<ejb-jar>
<enterprise-beans>
<session>
@@ -114,7 +114,7 @@
<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.
</para>
- <programlisting><session>
+ <programlisting language="XML" role="XML"><session>
<ejb-name>RunAsBean</ejb-name>
<security-identity>
<run-as-principal>internal</run-as-principal>
@@ -124,7 +124,7 @@
<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:
</para>
- <programlisting><servlet>
+ <programlisting language="XML" role="XML"><servlet>
<servlet-name>AServlet</servlet-name>
<!-- ... -->
<run-as>
@@ -135,7 +135,7 @@
<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.
</para>
- <programlisting><servlet>
+ <programlisting language="XML" role="XML"><servlet>
<servlet-name>AServlet</servlet-name>
<run-as-principal>internal</run-as-principal>
</servlet>
@@ -162,7 +162,7 @@
</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>
- <programlisting><!-- A sample ejb-jar.xml fragment -->
+ <programlisting language="XML" role="XML"><!-- A sample ejb-jar.xml fragment -->
<ejb-jar>
<!-- ... -->
<assembly-descriptor>
@@ -179,7 +179,7 @@
</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>
- <programlisting><!-- A sample web.xml fragment -->
+ <programlisting language="XML" role="XML"><!-- A sample web.xml fragment -->
<web-app>
<!-- ... -->
<security-role>
@@ -220,7 +220,7 @@
<para>
The first is used for referring to all the home and component interface methods of the named enterprise bean:
</para>
- <programlisting><method>
+ <programlisting language="XML" role="XML"><method>
<ejb-name>EJBNAME</ejb-name>
<method-name>*</method-name>
</method>
@@ -228,7 +228,7 @@
<para>
The second style is used for referring to a specified method of the home or component interface of the named enterprise bean:
</para>
- <programlisting><method>
+ <programlisting language="XML" role="XML"><method>
<ejb-name>EJBNAME</ejb-name>
<method-name>METHOD</method-name>
</method>
@@ -239,7 +239,7 @@
<para>
The third style is used to refer to a specified method within a set of methods with an overloaded name:
</para>
- <programlisting><method>
+ <programlisting language="XML" role="XML"><method>
<ejb-name>EJBNAME</ejb-name>
<method-name>METHOD</method-name>
<method-params>
@@ -260,7 +260,7 @@
</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>
- <programlisting><ejb-jar>
+ <programlisting language="XML" role="XML"><ejb-jar>
<assembly-descriptor>
<method-permission>
<description>The employee and temp-employee roles may access any
@@ -362,7 +362,7 @@
</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>
- <programlisting><web-app>
+ <programlisting language="XML" role="XML"><web-app>
<!-- ... -->
<security-constraint>
<web-resource-collection>
@@ -468,7 +468,7 @@
<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:
</para>
- <programlisting>public Set getPrincipals() {...}
+ <programlisting language="Java" role="JAVA">public Set getPrincipals() {...}
public Set getPrincipals(Class c) {...}
</programlisting>
<para>
@@ -520,7 +520,7 @@
<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.
</para>
- <programlisting>CallbackHandler handler = new MyHandler();
+ <programlisting language="Java" role="JAVA">CallbackHandler handler = new MyHandler();
LoginContext lc = new LoginContext("some-config", handler);
try {
@@ -605,7 +605,7 @@
<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:
</para>
- <programlisting>void handle(Callback[] callbacks)
+ <programlisting language="Java" role="JAVA">void handle(Callback[] callbacks)
throws java.io.IOException,
UnsupportedCallbackException;
</programlisting>
@@ -692,7 +692,7 @@
</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>
- <programlisting>package org.jboss.book.security.ex1;
+ <programlisting language="Java" role="JAVA">package org.jboss.book.security.ex1;
import java.lang.reflect.Method;
import javax.ejb.EJBContext;
@@ -765,7 +765,7 @@
</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>
- <programlisting><jboss>
+ <programlisting language="XML" role="XML"><jboss>
<security-domain>java:/jaas/other</security-domain>
<enterprise-beans>
@@ -780,7 +780,7 @@
<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:
</para>
- <programlisting>public class ExClient
+ <programlisting language="Java" role="JAVA">public class ExClient
{
public static void main(String args[])
throws Exception
@@ -802,7 +802,7 @@
<para>
The first call should succeed, while the second should fail due to the fact that <literal>Four</literal> is a four-letter word. Run the client as follows using Ant from the examples directory:
</para>
- <programlisting>[examples]$ ant -Dchap=security -Dex=1 run-example
+ <screen>[examples]$ ant -Dchap=security -Dex=1 run-example
run-example1:
...
[echo] Waiting for 5 seconds for deploy...
@@ -813,8 +813,7 @@
[java] java.lang.SecurityException: No 4 letter words
...
[java] Caused by: java.lang.SecurityException: No 4 letter words
-...
-</programlisting>
+...</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.
</para>
@@ -934,7 +933,7 @@
<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:
</para>
- <programlisting><jboss>
+ <programlisting language="XML" role="XML"><jboss>
<!-- Configure all containers to be secured under the "hades" security domain -->
<security-domain>java:/jaas/hades</security-domain>
<!-- ... -->
@@ -992,7 +991,7 @@
<para>
This can be invoked programmatically using the following code snippet:
</para>
- <programlisting>MBeanServer server = ...;
+ <programlisting language="Java" role="JAVA">MBeanServer server = ...;
String jaasMgrName = "jboss.security:service=JaasSecurityManager";
ObjectName jaasMgr = new ObjectName(jaasMgrName);
Object[] params = {domainName};
@@ -1005,7 +1004,7 @@
<para>
This can be invoked programmatically using the following code snippet:
</para>
- <programlisting>MBeanServer server = ...;
+ <programlisting language="Java" role="JAVA">MBeanServer server = ...;
String jaasMgrName = "jboss.security:service=JaasSecurityManager";
ObjectName jaasMgr = new ObjectName(jaasMgrName);
Object[] params = {domainName};
@@ -1016,7 +1015,7 @@
<para>
The security manager has a few additional access methods.
</para>
- <programlisting>public boolean isValid(String securityDomain, Principal principal, Object credential);
+ <programlisting language="Java" role="JAVA">public boolean isValid(String securityDomain, Principal principal, Object credential);
public Principal getPrincipal(String securityDomain, Principal principal);
public boolean doesUserHaveRole(String securityDomain, Principal principal,
Object credential, Set roles);
@@ -1120,7 +1119,7 @@
<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.
</para>
- <programlisting><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>
@@ -1160,7 +1159,7 @@
<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.
</para>
- <programlisting><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">
@@ -1204,7 +1203,7 @@
<note>
<para>Other login modules are available for use with the Enterprise Application Platform. For more information about the available login modules, refer to <xref linkend="Defining_Security_Domains-Using_JBoss_Login_Modules"/></para>
</note>
- <programlisting language="XML" lang="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/jboss-beans.xml_sample" parse="text"/></programlisting>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/jboss-beans.xml_sample" parse="text"/></programlisting>
</step>
<step>
<title>Deploy or package the deployment descriptor</title>
@@ -1231,13 +1230,13 @@
<para>By default, the security-policies-jboss-beans.xml file contains the configuration in <xref linkend="exam-security_policies_default_configuration"/></para>
<example id="exam-security_policies_default_configuration">
<title>security-policies default configuration</title>
- <programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/security-policies-jboss-beans_default.xml_sample" parse="text"/></programlisting>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/security-policies-jboss-beans_default.xml_sample" parse="text"/></programlisting>
</example>
</step>
<step>
<title>Change the application-policy definitions</title>
<para>To set a single authorization policy for each component using JACC, amend each <sgmltag><policy-module></sgmltag> <parameter>code</parameter> attribute with the name of the JACC auuthorization module.</para>
- <programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/security-policies-jboss-beans_all_ejb_war.xml_sample" parse="text"/></programlisting>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/security-policies-jboss-beans_all_ejb_war.xml_sample" parse="text"/></programlisting>
</step>
<step>
<title>Restart server</title>
@@ -1273,12 +1272,12 @@
<step>
<title>Specify the test-domain security domain</title>
<para>In the target file chosen in step 1, specify the <parameter>test-domain</parameter> security domain. This domain contains the authentication information, including the <sgmltag><login-module></sgmltag> definition, and the JACC authorization policy module definition.</para>
- <programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/authorization-policy-specific-security-domain-1.xml_sample" parse="text"/></programlisting>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/authorization-policy-specific-security-domain-1.xml_sample" parse="text"/></programlisting>
</step>
<step>
<title>Append the test-domain-inherited security domain</title>
<para>Append the <parameter>test-domain-inherited</parameter> application policy definition after the <parameter>test-domain</parameter> application policy. Set the <parameter>extends</parameter> attribute to <literal>other</literal>, so the login module information is inherited. Specify the XACML authorization module in the <sgmltag><policy.module></sgmltag> element.</para>
- <programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/authorization-policy-specific-security-domain-2.xml_sample" parse="text"/></programlisting>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/authorization-policy-specific-security-domain-2.xml_sample" parse="text"/></programlisting>
</step>
<step>
<title>Restart server</title>
@@ -1418,55 +1417,79 @@
<para>Specify the CallbackHandlerClassName attribute in the <filename>conf/jboss-service.xml</filename> JaasSecurityManagerService mbean definition.</para>
</listitem>
<listitem>
- <para>Specify the fully qualified class name of the callback handler as a system property.</para>
- </listitem>
- <listitem>
<para>Inject a callback handler instance into the <filename>deploy/security/security-jboss-beans.xml</filename> JNDISecurityManagement bean. </para>
</listitem>
</itemizedlist>
<procedure>
<title>Set callback handler using attributes</title>
- <para/>
+ <para>This procedure describes how to specify a callback handler in the jboss-service.xml configuration file. </para>
<step>
- <title/>
- <para/>
+ <title>Open the configuration file</title>
+ <para>Navigate to <filename><replaceable>[install_directory]</replaceable>/jboss-as/server/<replaceable>$PROFILES</replaceable>/conf/</filename></para>
+ <para>Open the <filename>jboss-service.xml</filename> file. </para>
+ <para>By default, the <filename>jboss-service.xml</filename> file contains the configuration in <xref linkend="exam-JBoss_Service_JAAS_Default_Configuration"/></para>
+ <example id="exam-JBoss_Service_JAAS_Default_Configuration">
+ <title>jboss-service default configuration</title>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/callback-handler-jboss_service_xml_default.xml_sample" parse="text"/></programlisting>
+ </example>
</step>
<step>
- <title/>
- <para/>
+ <title>Append the attribute</title>
+ <para>To set the custom callback handler, append an <sgmltag><attribute></sgmltag> element as a child of the <sgmltag><mbean></sgmltag> element, and specify the fully qualified name of your callback handler. Refer to <xref linkend="exam-JBoss_Service_JAAS_Appended_CCH"/> for an example <sgmltag><attribute></sgmltag> element, with the callback handler specified. </para>
+ <example id="exam-JBoss_Service_JAAS_Appended_CCH">
+ <title>jboss-service appended callback handler</title>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/callback-handler-jboss_service_xml_CCH.xml_sample" parse="text"/></programlisting>
+ </example>
</step>
+ <step>
+ <title>Restart server</title>
+ <para>You have now configured the <filename>jboss-service.xml</filename> file to use a custom callback handler.</para>
+ <para>Restart the server to ensure the new security policy takes effect.</para>
+ </step>
</procedure>
<procedure>
- <title>Set callback handler using system properties</title>
- <para/>
+ <title>Set security callback handler using injection</title>
+ <para>This procedure describes how to inject a security callback handler instance into the JNDISecurityManagement bean. </para>
<step>
- <title/>
- <para/>
+ <title>Create custom callback instance</title>
+ <para>You must create an instance of the custom callback handler, and register it. </para>
</step>
<step>
- <title/>
- <para/>
+ <title>Open the configuration file</title>
+ <para>Navigate to <filename><replaceable>[install_directory]</replaceable>/jboss-as/server/<replaceable>$PROFILES</replaceable>/deploy/security/</filename></para>
+ <para>Open the <filename>security-jboss-beans.xml</filename> file. </para>
+ <para>By default, the <filename>security-jboss-beans.xml</filename> file contains the JNDIBasedSecurityManagement bean configuration in <xref linkend="exam-security_jboss_beans_default"/></para>
+ <example id="exam-security_jboss_beans_default">
+ <title>security-jboss-beans default configuration</title>
+ <programlisting language="XML" role="XML"><!-- JNDI Based Security Management -->
+<bean name="JNDIBasedSecurityManagement" class="org.jboss.security.integration.JNDIBasedSecurityManagement"/> </programlisting>
+ </example>
</step>
- </procedure>
- <procedure>
- <title>Set callback handler using injection</title>
- <para/>
<step>
- <title/>
- <para/>
+ <title>Append the injection property</title>
+ <para>To inject the callback handler, append a <sgmltag><property></sgmltag> element as a child of the JNDIBasedSecurityManagement <sgmltag><mbean></sgmltag> element. Specify the callback handler using the the <property> and <inject> elements described in <xref linkend="exam-JBoss_Service_JAAS_Appended_CCH"/>. </para>
+ <example id="exam-security_jboss_beans_CCH">
+ <title>security-jboss-beans callback handler</title>
+ <programlisting language="XML" role="XML"><bean name="JNDIBasedSecurityManagement"
+class="org.jboss.security.integration.JNDIBasedSecurityManagement">
+ <property name="callBackHandler">'
+ <inject bean="MyCustomCBH"/></property>
+</bean></programlisting>
+ </example>
</step>
<step>
- <title/>
- <para/>
+ <title>Restart server</title>
+ <para>You have now configured the <filename>security-jboss-beans.xml</filename> file to inject your custom callback handler.</para>
+ <para>Restart the server to ensure the new security policy takes effect.</para>
</step>
</procedure>
</section>
<section id="Defining_Security_Domains-Loading_Security_Domains">
<title>Loading 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 (refer to . 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 <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.
</para>
- <programlisting><mbean code="org.jboss.security.auth.login.XMLLoginConfig"
+ <programlisting language="XML" role="XML"><mbean code="org.jboss.security.auth.login.XMLLoginConfig"
name="jboss.security:service=XMLLoginConfig">
<attribute name="ConfigResource">login-config.xml</attribute>
</mbean>
@@ -1524,7 +1547,7 @@
<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>
- <programlisting> <mbean code="org.jboss.security.plugins.SecurityConfig"
+ <programlisting language="XML" role="XML"> <mbean code="org.jboss.security.plugins.SecurityConfig"
name="jboss.security:service=SecurityConfig">
<attribute name="LoginConfig">jboss.security:service=XMLLoginConfig</attribute>
</mbean>
@@ -1542,13 +1565,13 @@
<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>public void pushLoginConfig(String objectName) throws
+ <programlisting language="Java" role="JAVA">public void pushLoginConfig(String objectName) throws
JMException, MalformedObjectNameException;
</programlisting>
<para>
The <literal>objectName</literal> parameters specifies an MBean similar to the <literal>LoginConfig</literal> attribute. The current login configuration may be removed using:
</para>
- <programlisting>public void popLoginConfig() throws JMException;</programlisting>
+ <programlisting language="Java" role="JAVA">public void popLoginConfig() throws JMException;</programlisting>
</section>
<section id="Defining_Security_Domains-The_DynamicLoginConfig_service">
<title>The DynamicLoginConfig service</title>
@@ -1578,7 +1601,7 @@
<para>
Here is an example MBean definition using the <literal>DynamicLoginConfig</literal> service.
</para>
- <programlisting><server>
+ <programlisting language="XML" role="XML"><server>
<mbean code="org.jboss.security.auth.login.DynamicLoginConfig" name="...">
<attribute name="AuthConfig">login-config.xml</attribute>
@@ -1624,7 +1647,7 @@
<para>
The following listing shows how password stacking could be used:
</para>
- <programlisting><application-policy name="todo">
+ <programlisting language="XML" role="XML"><application-policy name="todo">
<authentication>
<login-module code="org.jboss.security.auth.spi.LdapLoginModule"
flag="required">
@@ -1678,7 +1701,7 @@
<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.
</para>
- <programlisting><policy>
+ <programlisting language="XML" role="XML"><policy>
<application-policy name="testUsersRoles">
<authentication>
<login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
@@ -1881,7 +1904,7 @@
<para>
The following is a sample <literal>login-config.xml</literal> entry.
</para>
- <programlisting>
+ <programlisting language="XML" role="XML">
<application-policy name="testLDAP">
<authentication>
<login-module code="org.jboss.security.auth.spi.LdapLoginModule"
@@ -2021,7 +2044,7 @@
<para>
A corresponding <literal>login-config.xml</literal> entry would be:
</para>
- <programlisting><policy>
+ <programlisting language="XML" role="XML"><policy>
<application-policy name="testDB">
<authentication>
<login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule"
@@ -2048,7 +2071,7 @@
<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:
</para>
- <programlisting><mbean code="org.jboss.security.plugins.JaasSecurityDomain"
+ <programlisting language="XML" role="XML"><mbean code="org.jboss.security.plugins.JaasSecurityDomain"
name="jboss.ch8:service=SecurityDomain">
<constructor>
<arg type="java.lang.String" value="jmx-console"/>
@@ -2060,7 +2083,7 @@
<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>
- <programlisting><?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">
@@ -2092,14 +2115,14 @@
<para>
Next we, need to specify the JBoss security domain in <literal>jboss-web.xml</literal>:
</para>
- <programlisting><jboss-web>
+ <programlisting language="XML" role="XML"><jboss-web>
<security-domain>java:/jaas/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><application-policy name="jmx-console">
+ <programlisting language="XML" role="XML"><application-policy name="jmx-console">
<authentication>
<login-module code="org.jboss.security.auth.spi.BaseCertLoginModule"
flag="required">
@@ -2118,7 +2141,7 @@
<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:
</para>
- <programlisting>[starksm at banshee9100 conf]$ keytool -printcert -file unit-tests-client.export
+ <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.
@@ -2126,15 +2149,13 @@
Valid from: Wed May 26 07:34:34 PDT 2004 until: Thu May 26 07:34:34 PDT 2005
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
-</programlisting>
+ SHA1: DE:DE:86:59:05:6C:00:E8:CC:C0:16:D3:C2:68:BF:95:B8:83:E9:58</screen>
<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:
</para>
- <programlisting># A sample roles.properties file for use with the UsersRolesLoginModule
+ <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
-admin=JBossAdmin
-</programlisting>
+admin=JBossAdmin</screen>
</section>
<section id="Using_JBoss_Login_Modules-IdentityLoginModule">
<title>IdentityLoginModule</title>
@@ -2159,7 +2180,7 @@
<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>
- <programlisting><policy>
+ <programlisting language="XML" role="XML"><policy>
<application-policy name="testIdentity">
<authentication>
<login-module code="org.jboss.security.auth.spi.IdentityLoginModule"
@@ -2241,7 +2262,7 @@
<para>
You can obtain security information associated with a <literal>Subject</literal> in six ways in JBoss using the following methods:
</para>
- <programlisting>java.util.Set getPrincipals()
+ <programlisting language="Java" role="JAVA">java.util.Set getPrincipals()
java.util.Set getPrincipals(java.lang.Class c)
java.util.Set getPrivateCredentials()
java.util.Set getPrivateCredentials(java.lang.Class c)
@@ -2268,7 +2289,7 @@
<para>
To simplify correct implementation of the <literal>Subject</literal> usage patterns described in the preceding section, JBossSX includes two abstract login modules that handle the population of the authenticated <literal>Subject</literal> with a template pattern that enforces correct <literal>Subject</literal> usage. The most generic of the two is the <literal>org.jboss.security.auth.spi.AbstractServerLoginModule</literal> class. 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>
- <programlisting>package org.jboss.security.auth.spi;
+ <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
@@ -2367,7 +2388,7 @@
<para>
The second abstract base login module suitable for custom login modules is the <literal>org.jboss.security.auth.spi.UsernamePasswordLoginModule</literal>. 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>package org.jboss.security.auth.spi;
+ <programlisting language="Java" role="JAVA">package org.jboss.security.auth.spi;
/**
* An abstract subclass of AbstractServerLoginModule that imposes a
@@ -2521,7 +2542,7 @@
</para>
<example id="A_Custom_LoginModule_Example-_A_JndiUserAndPass_custom_login_module">
<title> A JndiUserAndPass custom login module</title>
- <programlisting>package org.jboss.book.security.ex2;
+ <programlisting language="Java" role="JAVA">package org.jboss.book.security.ex2;
import java.security.acl.Group;
import java.util.Map;
@@ -2616,7 +2637,7 @@
<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.
</para>
- <programlisting>[examples]$ ant -Dchap=security -Dex=2 run-example
+ <screen>[examples]$ ant -Dchap=security -Dex=2 run-example
...
run-example2:
[echo] Waiting for 5 seconds for deploy...
@@ -2624,11 +2645,11 @@
[java] [INFO,ExClient] Looking up EchoBean2
[java] [INFO,ExClient] Created Echo
[java] [INFO,ExClient] Echo.echo('Hello') = Hello
-</programlisting>
+</screen>
<para>
The choice of using the <literal>JndiUserAndPass</literal> custom login module for the server side authentication of the user is determined by the login configuration for the example security domain. The EJB JAR <literal>META-INF/jboss.xml</literal> descriptor sets the security domain
</para>
- <programlisting><?xml version="1.0"?>
+ <programlisting language="XML" role="XML"><?xml version="1.0"?>
<jboss>
<security-domain>java:/jaas/security-ex2</security-domain>
</jboss>
@@ -2636,7 +2657,7 @@
<para>
The SAR <literal>META-INF/login-config.xml</literal> descriptor defines the login module configuration.
</para>
- <programlisting><application-policy name = "security-ex2">
+ <programlisting language="XML" role="XML"><application-policy name = "security-ex2">
<authentication>
<login-module code="org.jboss.book.security.ex2.JndiUserAndPass"
flag="required">
@@ -2831,20 +2852,21 @@
<para>
The <literal>SRPVerifierStoreService</literal> MBean also supports <literal>addUser</literal> and <literal>delUser</literal> operations for addition and deletion of users. The signatures are:
</para>
- <programlisting>public void addUser(String username, String password) throws IOException;
+ <programlisting language="Java" role="JAVA">public void addUser(String username, String password) throws IOException;
public void delUser(String username) throws IOException;
</programlisting>
<para>
- An example configuration of these services is presented in <xref linkend="Providing_Password_Information_for_SRP-The_SRPVerifierStore_interface"/>.
+ An example configuration of these services is presented in <xref linkend="Providing_Password_Information_for_SRP-The_SRPVerifierStore_Interface"/>.
</para>
<section id="The_Secure_Remote_Password_SRP_Protocol-Providing_Password_Information_for_SRP">
<title>Providing Password Information for SRP</title>
<para>
- The default implementation of the <literal>SRPVerifierStore</literal> interface is not likely to be suitable for your production security environment as it requires all password hash information to be available as a file of serialized objects. You need to provide an MBean service that provides an implementation of the <literal>SRPVerifierStore</literal> interface that integrates with your existing security information stores. The <literal>SRPVerifierStore</literal> interface is shown in.
+ The default implementation of the <literal>SRPVerifierStore</literal> interface is not likely to be suitable for your production security environment as it requires all password hash information to be available as a file of serialized objects. </para>
+ <para>You need to provide an MBean service that provides an implementation of the <literal>SRPVerifierStore</literal> interface that integrates with your existing security information stores. The <literal>SRPVerifierStore</literal> interface is shown in <xref linkend="Providing_Password_Information_for_SRP-The_SRPVerifierStore_Interface"/>.
</para>
- <example id="Providing_Password_Information_for_SRP-The_SRPVerifierStore_interface">
+ <example id="Providing_Password_Information_for_SRP-The_SRPVerifierStore_Interface">
<title>The SRPVerifierStore interface</title>
- <programlisting>package org.jboss.security.srp;
+ <programlisting language="Java" role="JAVA">package org.jboss.security.srp;
import java.io.IOException;
import java.io.Serializable;
@@ -3009,7 +3031,7 @@
<para>
We have covered quite a bit of material on SRP and now its time to demonstrate SRP in practice with an example. The example demonstrates client side authentication of the user via SRP as well as subsequent secured access to a simple EJB using the SRP session challenge as the user credential. The test code deploys an EJB JAR that includes a SAR for the configuration of the server side login module configuration and SRP services. As in the previous examples we will dynamically install the server side login module configuration using the <literal>SecurityConfig</literal> MBean. In this example we also use a custom implementation of the <literal>SRPVerifierStore</literal> interface that uses an in memory store that is seeded from a Java properties file rather than a serialized object store as used by the <literal>SRPVerifierStoreService</literal>. This custom service is <literal>org.jboss.book.security.ex3.service.PropertiesVerifierStore</literal>. The following shows the !
contents of the JAR that contains the example EJB and SRP services.
</para>
- <programlisting>[examples]$ jar tf output/security/security-ex3.jar
+ <screen>[examples]$ jar tf output/security/security-ex3.jar
META-INF/MANIFEST.MF
META-INF/ejb-jar.xml
META-INF/jboss.xml
@@ -3018,14 +3040,13 @@
org/jboss/book/security/ex3/EchoHome.class
roles.properties
users.properties
-security-ex3.sar
-</programlisting>
+security-ex3.sar</screen>
<para>
The key SRP related items in this example are the SRP MBean services configuration, and the SRP login module configurations. The <literal>jboss-service.xml</literal> descriptor of the <literal>security-ex3.sar</literal> is given in <xref linkend="An_SRP_example-The_security_ex3.sar_jboss_service.xml_descriptor_for_the_SRP_services"/>, while <xref linkend="An_SRP_example-The_client_side_standard_JAAS_configuration"/> and <xref linkend="An_SRP_example-The_server_side_XMLLoginConfig_configuration"/> give the example client side and server side login module configurations.
</para>
<example id="An_SRP_example-The_security_ex3.sar_jboss_service.xml_descriptor_for_the_SRP_services">
<title>The security-ex3.sar jboss-service.xml descriptor for the SRP services</title>
- <programlisting><server>
+ <programlisting language="XML" role="XML"><server>
<!-- The custom JAAS login configuration that installs
a Configuration capable of dynamically updating the
config settings -->
@@ -3071,7 +3092,7 @@
</example>
<example id="An_SRP_example-The_server_side_XMLLoginConfig_configuration">
<title>The server side XMLLoginConfig configuration</title>
- <programlisting><application-policy name="security-ex3">
+ <programlisting language="XML" role="XML"><application-policy name="security-ex3">
<authentication>
<login-module code="org.jboss.security.srp.jaas.SRPCacheLoginModule"
flag = "required">
@@ -3097,15 +3118,14 @@
<para>
Now, run the example 3 client by executing the following command from the book examples directory:
</para>
- <programlisting>[examples]$ ant -Dchap=security -Dex=3 run-example
+ <screen>[examples]$ ant -Dchap=security -Dex=3 run-example
...
run-example3:
[echo] Waiting for 5 seconds for deploy...
[java] Logging in using the 'srp' configuration
[java] Created Echo
[java] Echo.echo()#1 = This is call 1
- [java] Echo.echo()#2 = This is call 2
-</programlisting>
+ [java] Echo.echo()#2 = This is call 2</screen>
<para>
In the <literal>examples/logs</literal> directory you will find a file called <literal>ex3-trace.log</literal>. This is a detailed trace of the client side of the SRP algorithm. The traces show step-by-step the construction of the public keys, challenges, session key and verification.
</para>
@@ -3138,7 +3158,7 @@
<para>
Enabling Java 2 security is the easy part. The difficult part of Java 2 security is establishing the allowed permissions. If you look at the <literal>server.policy</literal> file that is contained in the default configuration file set, you'll see that it contains the following permission grant statement:
</para>
- <programlisting>grant {
+ <programlisting language="Java" role="JAVA">grant {
// Allow everything for now
permission java.security.AllPermission;
};
@@ -3185,7 +3205,7 @@
<para>
To conclude this discussion, here is a little-known tidbit on debugging security policy settings. There are various debugging flag that you can set to determine how the security manager is using your security policy file as well as what policy files are contributing permissions. Running the VM as follows shows the possible debugging flag settings:
</para>
- <programlisting>[bin]$ java -Djava.security.debug=help
+ <screen>[bin]$ java -Djava.security.debug=help
all turn on all debugging
access print all checkPermission results
@@ -3203,8 +3223,7 @@
failure before throwing exception, dump stack
and domain that didn't have permission
-Note: Separate multiple options with a comma
-</programlisting>
+Note: Separate multiple options with a comma</screen>
<para>
Running with <literal>-Djava.security.debug=all</literal> provides the most output, but the output volume is torrential. This might be a good place to start if you don't understand a given security failure at all. A less verbose setting that helps debug permission failures is to use <literal>-Djava.security.debug=access,failure</literal>. This is still relatively verbose, but not nearly as bad as the all mode as the security domain information is only displayed on access failures.
</para>
@@ -3220,9 +3239,12 @@
<title>Generating the keystore and truststore</title>
<para>
For SSL to work you need to create a public/private key pair, which will be stored in a keystore. Generate this using the <literal>genkey</literal> command that comes with the JDK.
-<programlisting>
- $cd $JBOSS_HOME/server/production/conf/
- $keytool -genkey -alias ejb3-ssl -keypass opensource -keystore localhost.keystore
+
+ where <literal>alias</literal> is the name ("ejb2-ssl") of the key pair within the keystore. <literal>keypass</literal> is the password ("opensource") for the keystore, and <literal>keystore</literal> specifies the location ("localhost.keystore") of the keystore to create/add to.
+ </para>
+ <screen>[home]$ cd <replaceable>[install_directory]</replaceable>/server/production/conf/
+
+[conf]$ keytool -genkey -alias ejb3-ssl -keypass opensource -keystore localhost.keystore
Enter keystore password: opensource
What is your first and last name?
[Unknown]:
@@ -3237,22 +3259,19 @@
What is the two-letter country code for this unit?
[Unknown]:
Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?
- [no]: yes
-</programlisting>
- where <literal>alias</literal> is the name ("ejb2-ssl") of the key pair within the keystore. <literal>keypass</literal> is the password ("opensource") for the keystore, and <literal>keystore</literal> specifies the location ("localhost.keystore") of the keystore to create/add to.
- </para>
+ [no]: yes</screen>
<para>
Since you have not signed our certificate through any certification authoritiy, you also need to create a truststore for the client, explicitly saying that you trust the certificate you just created. The first step is to export the certificate using the JDK keytool:
-<programlisting>
- $ keytool -export -alias ejb3-ssl -file mycert.cer -keystore localhost.keystore
+
+ </para>
+ <screen>[conf]$ keytool -export -alias ejb3-ssl -file mycert.cer -keystore localhost.keystore
Enter keystore password: opensource
- Certificate stored in file <mycert.cer>
-</programlisting>
- </para>
+ Certificate stored in file <mycert.cer></screen>
<para>
Then you need to create the truststore if it does not exist and import the certificate into the trueststore:
-<programlisting>
- $ keytool -import -alias ejb3-ssl -file mycert.cer -keystore localhost.truststore
+
+ </para>
+ <screen>[conf]$ keytool -import -alias ejb3-ssl -file mycert.cer -keystore localhost.truststore
Enter keystore password: opensource
Owner: CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
Issuer: CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
@@ -3262,9 +3281,7 @@
MD5: CF:DC:71:A8:F4:EA:8F:5A:E9:94:E3:E6:5B:A9:C8:F3
SHA1: 0E:AD:F3:D6:41:5E:F6:84:9A:D1:54:3D:DE:A9:B2:01:28:F6:7C:26
Trust this certificate? [no]: yes
- Certificate was added to keystore
-</programlisting>
- </para>
+ Certificate was added to keystore</screen>
</section>
<section>
<title id="Adding_SSL_to_EJB3_Setting_up_the_SSL_transport">Setting up the SSL transport</title>
@@ -3288,18 +3305,17 @@
</para>
<para>
Now you need to tell JBoss Remoting where to find the keystore to be used for SSl and its password. This is done using <literal>javax.net.ssl.keyStore</literal> and <literal>javax.net.ssl.keyStorePassword=opensource</literal> system properties when starting JBoss, as the following example shows:
-<programlisting>
- $cd $JBOSS_HOME/bin
- $ run -Djavax.net.ssl.keyStore=../server/production/conf/localhost.keystore
- -Djavax.net.ssl.keyStorePassword=opensource
-</programlisting>
+
</para>
+ <screen>[home]$ cd [install_directory]/bin
+[bin]$ run -Djavax.net.ssl.keyStore=../server/production/conf/localhost.keystore
+ -Djavax.net.ssl.keyStorePassword=opensource</screen>
</section>
<section id="Adding_SSL_to_EJB3_Configuring_your_beans">
<title>Configuring your beans to use the SSL transport</title>
<para>
By default all the beans will use the default connector on <literal>socket://0.0.0.0:3873</literal>. By using the <literal>@org.jboss.annotation.ejb.RemoteBinding</literal> annotation you can have the bean invokable via SSL.
-<programlisting>
+<programlisting language="Java" role="JAVA">
@RemoteBinding(clientBindUrl="sslsocket://0.0.0.0:3843", jndiBinding="StatefulSSL"),
@Remote(BusinessInterface.class)
public class StatefulBean implements BusinessInterface
@@ -3313,7 +3329,7 @@
</para>
<para>
You can also enable different types of communication for your beans
-<programlisting>
+<programlisting language="Java" role="JAVA">
@RemoteBindings({
@RemoteBinding(clientBindUrl="sslsocket://0.0.0.0:3843", jndiBinding="StatefulSSL"),
@RemoteBinding(jndiBinding="StatefulNormal")
@@ -3333,11 +3349,10 @@
<title>Setting up the client to use the truststore</title>
<para>
If not using a certificate signed by a certificate authorization authority, you need to point the client to the truststore using the <literal>javax.net.ssl.trustStore</literal> system property and specify the password using the <literal>javax.net.ssl.trustStorePassword</literal> system property:
-<programlisting>
-java -Djavax.net.ssl.trustStore=${resources}/test/ssl/localhost.truststore
- -Djavax.net.ssl.trustStorePassword=opensource com.acme.RunClient
-</programlisting>
+
</para>
+ <screen>[home]$ java -Djavax.net.ssl.trustStore=${resources}/test/ssl/localhost.truststore
+ -Djavax.net.ssl.trustStorePassword=opensource com.acme.RunClient</screen>
</section>
</section>
<section id="Adding_SSL_to_EJB2.1">
@@ -3352,15 +3367,14 @@
<title>Setting up the SSL transport</title>
<para>
Now you need to tell JBoss Remoting where to find the keystore to be used for SSl and its password. This is done using <literal>javax.net.ssl.keyStore</literal> and <literal>javax.net.ssl.keyStorePassword=opensource</literal> system properties when starting JBoss, as the following example shows:
-<programlisting>
- $cd $JBOSS_HOME/bin
- $ run -Djavax.net.ssl.keyStore=../server/production/conf/localhost.keystore
- -Djavax.net.ssl.keyStorePassword=opensource
-</programlisting>
+
</para>
+ <screen>[home]$ cd <replaceable>[install_directory]</replaceable>/bin
+[bin]$ run -Djavax.net.ssl.keyStore=../server/production/conf/localhost.keystore
+-Djavax.net.ssl.keyStorePassword=opensource</screen>
<para>
- If you wish to customize the SSLSocketBuilder you need to add the following to your <literal>$JBOSS_HOME/server/${serverConf}/conf/jboss-service.xml</literal> file.
-<programlisting>
+ If you wish to customize the SSLSocketBuilder you need to add the following to your <literal><replaceable>[install_directory]</replaceable>/server/<replaceable>$SERVERS</replaceable>/conf/jboss-service.xml</literal> file.
+<programlisting language="XML" role="XML">
<!-- This section is for custom (SSL) server socket factory -->
<mbean code="org.jboss.remoting.security.SSLSocketBuilder"
name="jboss.remoting:service=SocketBuilder,type=SSL"
@@ -3401,7 +3415,11 @@
<title>Configuring your beans to use the SSL transport</title>
<para>
In your <literal>$JBOSS_HOME/server/${serverConf}/conf/jboss-service.xml</literal> file, comment out the following lines:
-<programlisting>
+
+ and add the following in it's place:
+
+ </para>
+ <programlisting language="XML" role="XML">
<mbean code="org.jboss.remoting.transport.Connector"
name="jboss.remoting:service=Connector,transport=socket"
display-name="Socket transport Connector">
@@ -3484,8 +3502,7 @@
<depends>jboss.remoting:service=NetworkRegistry</depends>
</mbean>
</programlisting>
- and add the following in it's place:
-<programlisting>
+ <programlisting language="XML" role="XML">
<mbean code="org.jboss.remoting.transport.Connector"
xmbean-dd="org/jboss/remoting/transport/Connector.xml"
name="jboss.remoting:service=Connector,transport=sslsocket">
@@ -3511,7 +3528,6 @@
<depends>jboss.remoting:service=NetworkRegistry</depends>
</mbean>
</programlisting>
- </para>
</section>
<section id="Adding_SSL_to_EJB2.1_Setting_up_the_client_to_use_truststore">
<title>Setting up the client to use the truststore</title>
Added: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/extras/callback-handler-jboss_service_xml_CCH.xml_sample
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/extras/callback-handler-jboss_service_xml_CCH.xml_sample (rev 0)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/extras/callback-handler-jboss_service_xml_CCH.xml_sample 2010-03-03 07:06:18 UTC (rev 101756)
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+...
+
+<!-- ==================================================================== -->
+<!-- Security -->
+<!-- ==================================================================== -->
+
+<!-- JAAS security manager and realm mapping -->
+ <mbean code="org.jboss.security.plugins.JaasSecurityManagerService" name="jboss.security:service=JaasSecurityManager">
+ <!-- A flag which indicates whether the SecurityAssociation server mode
+ is set on service creation. This is true by default since the
+ SecurityAssociation should be thread local for multi-threaded server
+ operation.-->
+ <attribute name="ServerMode">true</attribute>
+
+ <attribute name="SecurityManagerClassName">org.jboss.security.plugins.JaasSecurityManager</attribute>
+
+ <attribute name="DefaultUnauthenticatedPrincipal">anonymous</attribute>
+
+ <!-- DefaultCacheTimeout: Specifies the default timed cache policy timeout
+ in seconds.
+ 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
+ AuthenticationCacheJndiName has been changed from the default value.-->
+
+ <attribute name="DefaultCacheTimeout">1800</attribute>
+
+ <!-- DefaultCacheResolution: 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 DefaultCacheTimeout
+ in order for the timeout to be meaningful. This has no affect if the
+ AuthenticationCacheJndiName has been changed from the default value.-->
+
+ <attribute name="DefaultCacheResolution">60</attribute>
+
+ <!-- DeepCopySubjectMode: This set the copy mode of subjects done by the
+ security managers to be deep copies that makes copies of the subject
+ principals and credentials if they are cloneable. It should be set to
+ true if subject include mutable content that can be corrupted when
+ multiple threads have the same identity and cache flushes/logout clearing
+ the subject in one thread results in subject references affecting other
+ threads.-->
+
+ <attribute name="DeepCopySubjectMode">false</attribute>
+
+ <attribute name="CallbackHandlerClassName">org.jboss.security.plugins.[Custom_Callback_Handler_Name]</attribute>
+
+ </mbean>
+
+...
Added: projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/extras/callback-handler-jboss_service_xml_default.xml_sample
===================================================================
--- projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/extras/callback-handler-jboss_service_xml_default.xml_sample (rev 0)
+++ projects/docs/enterprise/5.1/JBoss_Security_Guide/en-US/extras/callback-handler-jboss_service_xml_default.xml_sample 2010-03-03 07:06:18 UTC (rev 101756)
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+...
+
+<!-- ==================================================================== -->
+<!-- Security -->
+<!-- ==================================================================== -->
+
+<!-- JAAS security manager and realm mapping -->
+ <mbean code="org.jboss.security.plugins.JaasSecurityManagerService" name="jboss.security:service=JaasSecurityManager">
+ <!-- A flag which indicates whether the SecurityAssociation server mode
+ is set on service creation. This is true by default since the
+ SecurityAssociation should be thread local for multi-threaded server
+ operation.-->
+ <attribute name="ServerMode">true</attribute>
+
+ <attribute name="SecurityManagerClassName">org.jboss.security.plugins.JaasSecurityManager</attribute>
+
+ <attribute name="DefaultUnauthenticatedPrincipal">anonymous</attribute>
+
+ <!-- DefaultCacheTimeout: Specifies the default timed cache policy timeout
+ in seconds.
+ 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
+ AuthenticationCacheJndiName has been changed from the default value.-->
+
+ <attribute name="DefaultCacheTimeout">1800</attribute>
+
+ <!-- DefaultCacheResolution: 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 DefaultCacheTimeout
+ in order for the timeout to be meaningful. This has no affect if the
+ AuthenticationCacheJndiName has been changed from the default value.-->
+
+ <attribute name="DefaultCacheResolution">60</attribute>
+
+ <!-- DeepCopySubjectMode: This set the copy mode of subjects done by the
+ security managers to be deep copies that makes copies of the subject
+ principals and credentials if they are cloneable. It should be set to
+ true if subject include mutable content that can be corrupted when
+ multiple threads have the same identity and cache flushes/logout clearing
+ the subject in one thread results in subject references affecting other
+ threads.-->
+
+ <attribute name="DeepCopySubjectMode">false</attribute>
+
+ </mbean>
+
+...
More information about the jboss-cvs-commits
mailing list