[jboss-cvs] JBossAS SVN: r108142 - in projects/docs/community/6: Security_Guide and 3 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Sep 14 16:27:05 EDT 2010
Author: mmoyses
Date: 2010-09-14 16:27:04 -0400 (Tue, 14 Sep 2010)
New Revision: 108142
Added:
projects/docs/community/6/Security_Guide/
projects/docs/community/6/Security_Guide/en-US/
projects/docs/community/6/Security_Guide/en-US/Author_Group.xml
projects/docs/community/6/Security_Guide/en-US/Book_Info.xml
projects/docs/community/6/Security_Guide/en-US/Legal_Notice.xml
projects/docs/community/6/Security_Guide/en-US/Security_Guide-Authorization_Stacks.xml
projects/docs/community/6/Security_Guide/en-US/Security_Guide-Deployment-level_Role_Mapping.xml
projects/docs/community/6/Security_Guide/en-US/Security_Guide-Dynamic_Security_Domains.xml
projects/docs/community/6/Security_Guide/en-US/Security_Guide-Introduction_to_JAAS.xml
projects/docs/community/6/Security_Guide/en-US/Security_Guide-JBossSX_Architecture.xml
projects/docs/community/6/Security_Guide/en-US/Security_Guide-JBoss_Login_Modules.xml
projects/docs/community/6/Security_Guide/en-US/Security_Guide-JBoss_Security_Model.xml
projects/docs/community/6/Security_Guide/en-US/Security_Guide-Loading_Static_Security_Domains.xml
projects/docs/community/6/Security_Guide/en-US/Security_Guide-Overview.xml
projects/docs/community/6/Security_Guide/en-US/Security_Guide-Static_Security_Domains.xml
projects/docs/community/6/Security_Guide/en-US/Security_Guide.xml
projects/docs/community/6/Security_Guide/en-US/chap-Consoles_And_Invokers.xml
projects/docs/community/6/Security_Guide/en-US/chap-Encrypting_DataSource_Passwords.xml
projects/docs/community/6/Security_Guide/en-US/chap-Encrypting_Keystore_Password_in_Tomcat_Connector.xml
projects/docs/community/6/Security_Guide/en-US/chap-Firewalls.xml
projects/docs/community/6/Security_Guide/en-US/chap-Java_EE_Security_Manager.xml
projects/docs/community/6/Security_Guide/en-US/chap-Masking_Passwords.xml
projects/docs/community/6/Security_Guide/en-US/chap-Overridding_SSL_Configuration.xml
projects/docs/community/6/Security_Guide/en-US/chap-Secure_Remote_Password_Protocol.xml
projects/docs/community/6/Security_Guide/en-US/chap-Secure_Socket_Layer.xml
projects/docs/community/6/Security_Guide/en-US/chap-Using_LdapExtLoginModule.xml
projects/docs/community/6/Security_Guide/en-US/extras/
projects/docs/community/6/Security_Guide/en-US/extras/authorization-policy-specific-security-domain-1.xml_sample
projects/docs/community/6/Security_Guide/en-US/extras/authorization-policy-specific-security-domain-2.xml_sample
projects/docs/community/6/Security_Guide/en-US/extras/jboss-beans.xml_sample
projects/docs/community/6/Security_Guide/en-US/extras/security-policies-EJBJACCPolicyModuleDelegate.java
projects/docs/community/6/Security_Guide/en-US/extras/security-policies-WebJACCPolicyModuleDelegate.java
projects/docs/community/6/Security_Guide/en-US/extras/security-policies-authorization_delegate_example.java
projects/docs/community/6/Security_Guide/en-US/extras/security-policies-jboss-beans_all_ejb_war.xml_sample
projects/docs/community/6/Security_Guide/en-US/extras/security-policies-jboss-beans_default.xml_sample
projects/docs/community/6/Security_Guide/en-US/images/
projects/docs/community/6/Security_Guide/en-US/images/AS6_SecurityModel_Interface.png
projects/docs/community/6/Security_Guide/en-US/images/authsteps.png
projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap2-47.jpg
projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-13.jpg
projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-14.jpg
projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-7.jpg
projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-8.jpg
projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-9.jpg
projects/docs/community/6/Security_Guide/en-US/images/j2ee_method.jpg
projects/docs/community/6/Security_Guide/en-US/images/j2ee_method_permission.jpg
projects/docs/community/6/Security_Guide/en-US/images/j2ee_security_identity.jpg
projects/docs/community/6/Security_Guide/en-US/images/j2ee_security_role.jpg
projects/docs/community/6/Security_Guide/en-US/images/j2ee_security_role_ref.jpg
projects/docs/community/6/Security_Guide/en-US/images/security_config_login_module.jpg
projects/docs/community/6/Security_Guide/en-US/images/security_config_policy.jpg
projects/docs/community/6/Security_Guide/en-US/images/webapp_login_config.jpg
projects/docs/community/6/Security_Guide/en-US/images/webapp_security_constraint.jpg
projects/docs/community/6/Security_Guide/en-US/sect-Configure_Secure_Remote_Password_Information.xml
projects/docs/community/6/Security_Guide/en-US/sect-Secure_Remote_Password_Example.xml
projects/docs/community/6/Security_Guide/en-US/sect-Understanding_The_Algorithm.xml
projects/docs/community/6/Security_Guide/en-US/template.xml
projects/docs/community/6/Security_Guide/pom.xml
Log:
adding security guide
Added: projects/docs/community/6/Security_Guide/en-US/Author_Group.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/Author_Group.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/Author_Group.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,17 @@
+<?xml version='1.0'?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+ ]>
+<authorgroup>
+ <author>
+ <firstname>Anil</firstname>
+ <surname>Saldhana</surname>
+ </author>
+ <author>
+ <firstname>Marcus</firstname>
+ <surname>Moyses</surname>
+ </author>
+ <author>
+ <firstname>Stefan</firstname>
+ <surname>Guilhen</surname>
+ </author>
+</authorgroup>
Added: projects/docs/community/6/Security_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/Book_Info.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/Book_Info.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,17 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+
+<bookinfo>
+<title>JBoss AS 6.0 Security Guide</title>
+ <subtitle>Security with JBoss Application Server 6</subtitle>
+ <productname>JBoss Application Server</productname>
+ <productnumber>6.0</productnumber>
+ <pubdate>Sep 2010</pubdate>
+ <abstract>
+ <para>
+ This book is the JBoss Application Server 6 Security Guide.
+ </para>
+ </abstract>
+ <!-- <subtitle>Authors</subtitle>-->
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</bookinfo>
Added: projects/docs/community/6/Security_Guide/en-US/Legal_Notice.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/Legal_Notice.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/Legal_Notice.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,17 @@
+<?xml version='1.0'?>
+<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<legalnotice id="Book-Legal_Notice">
+ <title>Legal Notice</title>
+ <para>
+ <address>
+ <street>1801 Varsity Drive</street>
+ <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country><phone>Phone: +1 919 754 3700</phone>
+ <phone>Phone: 888 733 4281</phone>
+ <fax>Fax: +1 919 754 3701</fax>
+ <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country>
+ </address>
+ </para>
+</legalnotice>
+
Added: projects/docs/community/6/Security_Guide/en-US/Security_Guide-Authorization_Stacks.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/Security_Guide-Authorization_Stacks.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/Security_Guide-Authorization_Stacks.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,192 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+ <chapter id="Authorization_Stacks">
+ <title>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 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 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>$JBOSS_HOME/server/$PROFILE/deploy/security</filename>
+ </para>
+
+ <para>
+ Open the <filename>security-policies-jboss-beans.xml</filename> file.
+ </para>
+
+ <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 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 authorization module.
+ </para>
+
+ <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>
+ <para>
+ You have now configured the <filename>security-policy-jboss-beans.xml</filename> file with JACC authorization enabled for each application policy.
+ </para>
+
+ <para>
+ Restart the server to ensure the new security policy takes effect.
+ </para>
+ </step>
+ </procedure>
+
+ <formalpara>
+ <title>Setting authorization for specific EJB and WEB components</title>
+ <para>
+ If applications require more granular security policies, you can declare multiple authorization security policies for each application policy. New security domains can inherit base settings from another application policy, and override specific settings such as the authorization policy module.
+ </para>
+ </formalpara>
+
+ <procedure id="proc-Set_Auth_Policies_For_Specific_Domains">
+ <title>Set authorization policies for specific security domains </title>
+ <para>
+ This procedure describes how to inherit settings from other application policy definitions, and specify different authorization policies per security domain.
+ </para>
+
+ <para>
+ In this procedure, two security domains are defined. The <parameter>test-domain</parameter> security domain uses the UsersRolesLoginModule login module and uses JACC authorization. The
+ <parameter>test-domain-inherited</parameter> security domain inherits the login module information from <parameter>test-domain</parameter>, and specifies XACML authorization must be used.
+ </para>
+
+ <step>
+ <title>Open the security policy </title>
+ <para>
+ You can specify the security domain settings in the <filename>login-config.xml</filename> file, or create a deployment descriptor file containing the settings. Choose the deployment
+ descriptor if you want to package the security domain settings with your application.
+ </para>
+
+ <stepalternatives performance="required">
+ <step performance="optional">
+ <title>Locate and open login-config.xml</title>
+ <para>
+ Navigate to the <filename>login-config.xml</filename> file for the server profile you are using and open the file for editing. For example:
+ </para>
+
+ <para>
+ <filename><replaceable>$JBOSS_HOME</replaceable>/jboss-as/server/$PROFILE/conf/login.config.xml</filename>
+ </para>
+ </step>
+
+ <step performance="optional">
+ <title>Create a jboss-beans.xml descriptor</title>
+ <para>
+ Create a <filename><replaceable>[prefix]</replaceable>-jboss-beans.xml</filename> descriptor, replacing <replaceable>[prefix]</replaceable> with a meaningful name (for example, <filename>test-war-jboss-beans.xml</filename>)
+ </para>
+
+ <para>
+ Save this file in the deploy directory of the server profile you are configuring. For example:
+ </para>
+
+ <para>
+ <filename><replaceable>$JBOSS_HOME</replaceable>/jboss-as/server/$PROFILE/deploy/test-war-jboss-beans.xml</filename>
+ </para>
+ </step>
+ </stepalternatives>
+ </step>
+
+ <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 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 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>
+ <para>
+ You have now configured the target file with two security domains that use different authorization methods.
+ </para>
+
+ <para>
+ Restart the server to ensure the new security policy takes effect.
+ </para>
+ </step>
+ </procedure>
+
+ <formalpara>
+ <title>Setting authorization module delegates</title>
+ <para>
+ <xref linkend="proc-Set_Auth_Policies_For_All_EJB_WAR_Components"/> and <xref linkend="proc-Set_Auth_Policies_For_Specific_Domains"/> describe simplistic examples that show how authentication and authorization can be configured in security domains.
+ </para>
+ </formalpara>
+
+ <para>
+ Because authorization relates to the type of component (not the layer) you want to protect, you can use delegation within a deployment descriptor to specify different authorization policies to the standard authentication in your implementation.
+ </para>
+
+ <para>
+ The delegates must be a subclass of <classname>AuthorizationModuleDelegate</classname>. <xref linkend="exam-security-AuthorizationModuleDelegate_Class"/> describes the base <classname>AuthorizationModuleDelegate</classname> interface.
+ </para>
+
+ <example id="exam-security-AuthorizationModuleDelegate_Class">
+ <title>AuthorizationModuleDelegate class</title>
+ <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 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 language="Java" role="JAVA"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/security-policies-WebJACCPolicyModuleDelegate.java" parse="text"/>
+ </programlisting>
+ </example>
+ </chapter>
Added: projects/docs/community/6/Security_Guide/en-US/Security_Guide-Deployment-level_Role_Mapping.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/Security_Guide-Deployment-level_Role_Mapping.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/Security_Guide-Deployment-level_Role_Mapping.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,57 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+ <chapter id="Deployment-level_Role_Mapping">
+ <title>Deployment-level Role Mapping </title>
+ <para>
+ In JBoss AS 6, it is possible to map additional roles at the deployment level from those derived at the security domain level (such as at the EAR level). This is achieved by declaring the <classname>org.jboss.security.mapping.providers.DeploymentRolesMappingProvider</classname> class as the value for the <parameter>class</parameter> attribute in the <sgmltag><mapping-module></sgmltag> element. Additionally, the <parameter>type</parameter> attribute must be set to <literal>role</literal>.
+ </para>
+
+ <para>
+ By configuring the mapping configuration element within the role-based parameter, you can force additional role interpretation to the declared principals specified for the particular deployment (war, ear, ejb-jar etc).
+ </para>
+
+ <important>
+ <title>Important: <rolemapping> deprecated for <mapping></title>
+ <para>
+ In previous versions, the <sgmltag><rolemapping></sgmltag> element contained the <sgmltag><mapping-module></sgmltag> element and class declaration. <sgmltag><rolemapping></sgmltag> has now been deprecated, and replaced with the <sgmltag><mapping></sgmltag> element.
+ </para>
+ </important>
+
+ <example>
+ <title><mapping-module> declaration</title>
+ <programlisting language="XML" role="XML"><application-policy name="some-sec-domain">
+<authentication>
+...
+</authentication>
+<mapping>
+ <mapping-module code="org.jboss.security.mapping.providers.DeploymentRolesMappingProvider"
+ type="role"/>
+</mapping>
+...
+</application-policy>
+ </programlisting>
+ </example>
+
+ <para>
+ Once the security domain is configured correctly, you can append the <sgmltag><security-role></sgmltag> element group as a child element of the <sgmltag><assembly-descriptor></sgmltag> to the <filename>jboss.xml</filename>, or <filename>jboss-web.xml</filename> files.
+ </para>
+
+ <example id="exam-Deploy_Level_Security_Role_Declaration">
+ <title><security-role> declaration</title>
+ <programlisting><assembly-descriptor>
+ ...
+ <security-role>
+ <role-name>Support</role-name>
+ <principal-name>Mark</principal-name>
+ <principal-name>Tom</principal-name>
+ </security-role>
+ ...
+</assembly-descriptor>
+ </programlisting>
+ </example>
+
+ <para>
+ In <xref linkend="exam-Deploy_Level_Security_Role_Declaration"/>, a security role relating to Support principals is implemented in addition to the base security role information contained in <filename>jboss.xml</filename> or <filename>jboss-web.xml</filename>.
+ </para>
+ </chapter>
Added: projects/docs/community/6/Security_Guide/en-US/Security_Guide-Dynamic_Security_Domains.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/Security_Guide-Dynamic_Security_Domains.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/Security_Guide-Dynamic_Security_Domains.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,82 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+ <chapter id="Dynamic_Security_Domains">
+ <title>Dynamic Security Domains</title>
+ <para>
+ Historically, the Enterprise Application Platform used the static <filename>$JBOSS_HOME/server/<replaceable>$PROFILE</replaceable>/conf/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 Authorization Service (JAAS) as part of an application deployment, rather than having to include the configuration information in <filename>login-config.xml</filename>.
+ </para>
+
+ <para>
+ JBoss AS 6 now provides an additional, simplified mechanism to configure security domains.
+ </para>
+
+ <para>
+ In JBoss AS, the security domain configuration is important for the authentication, authorization, auditing, and mapping functionality associated with Java EE 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>
+ <para>
+ Follow this procedure to configure a security domain deployment descriptor with two domains named web-test and ejb-test.
+ </para>
+
+ <step>
+ <title>Create deployment descriptor</title>
+ <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 language="XML" role="XML"><?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+
+</deployment>
+ </programlisting>
+ </step>
+
+ <step>
+ <title>Define application policies</title>
+ <para>
+ Within the <sgmltag><deployment></sgmltag> element, the individual application policies are defined. Each policy specifies the login module to use, and any required options.
+ </para>
+
+ <para>
+ In the example below, two application policies are specified. Each policy uses the same login module, and module parameters.
+ </para>
+
+ <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="JBoss_Login_Modules"/>
+ </para>
+ </note>
+
+ <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>
+ <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 <filename>WEB-INF</filename> directory of your web application (WAR).
+ </para>
+ </step>
+ </procedure>
+ </chapter>
Added: projects/docs/community/6/Security_Guide/en-US/Security_Guide-Introduction_to_JAAS.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/Security_Guide-Introduction_to_JAAS.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/Security_Guide-Introduction_to_JAAS.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,237 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+ <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.
+ </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 <emphasis>Pluggable Authentication Module</emphasis> (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.
+ </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.
+ </para>
+
+ <section id="Introduction_to_JAAS-The_JAAS_Core_Classes">
+ <title>The JAAS Core Classes</title>
+ <para>
+ The JAAS core classes can be broken down into three categories: common, authentication, and authorization. The following list presents only the common and authentication classes because these are the specific classes used to implement the functionality of JBossSX covered in this chapter.
+ </para>
+
+ <para>
+ The are the common classes:
+ </para>
+
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ <literal>Subject</literal> (<literal>javax.security.auth.Subject</literal>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>Principal</literal> (<literal>java.security.Principal</literal>)
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ These are the authentication classes:
+ </para>
+
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ <literal>Callback</literal> (<literal>javax.security.auth.callback.Callback</literal>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>CallbackHandler</literal> (<literal>javax.security.auth.callback.CallbackHandler</literal>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>Configuration</literal> (<literal>javax.security.auth.login.Configuration</literal>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>LoginContext</literal> (<literal>javax.security.auth.login.LoginContext</literal>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>LoginModule</literal> (<literal>javax.security.auth.spi.LoginModule</literal>)
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <section id="The_JAAS_Core_Classes-The_Subject_and_Principal_Classes">
+ <title>The 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.
+ </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:
+ </para>
+
+ <programlisting>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>
+ </section>
+
+ <section id="The_JAAS_Core_Classes-Authentication_of_a_Subject">
+ <title>Authentication of a Subject</title>
+ <para>
+ Authentication of a subject requires a JAAS login. The login procedure consists of the following steps:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ An application instantiates a <literal>LoginContext</literal> and passes in the name of the login configuration and a <literal>CallbackHandler</literal> to populate the <literal>Callback</literal> objects, as required by the configuration <literal>LoginModule</literal>s.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>LoginContext</literal> consults a <literal>Configuration</literal> to load all the <literal>LoginModules</literal> included in the named login configuration. If no such named configuration exists the <literal>other</literal> configuration is used as a default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The application invokes the <literal>LoginContext.login</literal> method.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The login method invokes all the loaded <literal>LoginModule</literal>s. As each <literal>LoginModule</literal> attempts to authenticate the subject, it invokes the handle method on the associated <literal>CallbackHandler</literal> to obtain the information required for the authentication process. The required information is passed to the handle method in the form of an array of <literal>Callback</literal> objects. Upon success, the <literal>LoginModule</literal>s associate relevant principals and credentials with the subject.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>LoginContext</literal> returns the authentication status to the application. Success is represented by a return from the login method. Failure is represented through a LoginException being thrown by the login method.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If authentication succeeds, the application retrieves the authenticated subject using the <literal>LoginContext.getSubject</literal> 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.
+ </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.
+ </para>
+
+ <programlisting>CallbackHandler handler = new MyHandler();
+LoginContext lc = new LoginContext("some-config", handler);
+
+try {
+ lc.login();
+ Subject subject = lc.getSubject();
+} catch(LoginException e) {
+ System.out.println("authentication failed");
+ e.printStackTrace();
+}
+
+// Perform work as authenticated Subject
+// ...
+
+// Scope of work complete, logout to remove authentication info
+try {
+ lc.logout();
+} catch(LoginException e) {
+ System.out.println("logout failed");
+ e.printStackTrace();
+}
+
+// A sample MyHandler class
+class MyHandler implements CallbackHandler
+{
+ public void handle(Callback[] callbacks) throws
+ IOException, UnsupportedCallbackException
+ {
+ for (int i = 0; i < callbacks.length; i++) {
+ if (callbacks[i] instanceof NameCallback) {
+ NameCallback nc = (NameCallback)callbacks[i];
+ nc.setName(username);
+ } else if (callbacks[i] instanceof PasswordCallback) {
+ PasswordCallback pc = (PasswordCallback)callbacks[i];
+ pc.setPassword(password);
+ } else {
+ throw new UnsupportedCallbackException(callbacks[i],
+ "Unrecognized Callback");
+ }
+ }
+ }
+}
+ </programlisting>
+
+ <para>
+ Developers integrate with an authentication technology by creating an implementation of the <literal>LoginModule</literal> interface. This allows an administrator to plug different authentication technologies into an application. You can chain together multiple <literal>LoginModule</literal>s to allow for more than one authentication technology to participate in the authentication process. For example, one <literal>LoginModule</literal> may perform username/password-based authentication, while another may interface to hardware devices such as smart card readers or biometric authenticators.
+ </para>
+
+ <para>
+ The life cycle of a <literal>LoginModule</literal> is driven by the <literal>LoginContext</literal> object against which the client creates and issues the login method. The process consists of two phases. The steps of the process are as follows:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <literal>LoginContext</literal> creates each configured <literal>LoginModule</literal> using its public no-arg constructor.
+ </para>
+ </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>
+ </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.
+ </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.
+ </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.
+ </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.
+ </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 th!
e other hand, a <literal>callbackhandler</literal>'s implementation for a non-GUI environment, such as an application 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) 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.
+ </para>
+ </section>
+ </section>
+ </chapter>
Added: projects/docs/community/6/Security_Guide/en-US/Security_Guide-JBossSX_Architecture.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/Security_Guide-JBossSX_Architecture.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/Security_Guide-JBossSX_Architecture.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,417 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+ <chapter id="The_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.
+ </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.
+ </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>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/j2ee_chap8-9.jpg" />
+ </imageobject>
+ </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.
+ </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.
+ </para>
+
+ <section id="The_JBoss_Security_Extension_Architecture-How_the_JaasSecurityManager_Uses_JAAS">
+ <title>How the JaasSecurityManager Uses JAAS</title>
+ <para>
+ 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.
+ </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>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/authsteps.png" />
+ </imageobject>
+ </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:
+ </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 lo!
gin 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.
+ </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>
+ </listitem>
+ <listitem>
+ <para>
+ On the server side, the security interceptor first requires authentication of the user invoking the call, which, as on the client side, involves a JAAS login.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The security domain under which the EJB is secured determines the choice of login modules. The security domain name is used as the login configuration entry name passed to the <literal>LoginContext</literal> constructor. The EJB security domain is <literal>jwdomain</literal>. If the JAAS login authenticates the user, a JAAS <literal>Subject</literal> is created that contains the following in its <literal>PrincipalsSet</literal>:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ A <literal>java.security.Principal</literal> that corresponds to the client identity as known in the deployment security environment.
+ </para>
+ </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.
+ </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 appli!
cation 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:
+ </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.
+ </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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the EJB was configured with a custom security proxy, the method invocation is delegated to it. If the security proxy wants to deny access to the caller, it will throw a <literal>java.lang.SecurityException</literal>. If no <literal>SecurityException</literal> is thrown, access to the EJB method is allowed and the method invocation passes to the next container interceptor. Note that the <literal>SecurityProxyInterceptor</literal> handles this check and this interceptor is not shown.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ Every secured EJB method invocation, or secured web content access, requires the authentication and authorization of the caller because security information is handled as a stateless attribute of the request that must be presented and validated on each request. This can be an expensive operation if the JAAS login involves client-to-server communication. Because of this, the <literal>JaasSecurityManager</literal> supports the notion of an authentication cache that is used to store principal and credential information from previous successful logins. You can specify the authentication cache instance to use as part of the <literal>JaasSecurityManager</literal> configuration as you will see when the associated MBean service is discussed in following section. In the absence of any user-defined cache, a default cache that maintains credential information for a configurable period of time is used.
+ </para>
+ </section>
+
+ <section id="The_JBoss_Security_Extension_Architecture-The_JaasSecurityManagerService_MBean">
+ <title>The JaasSecurityManagerService MBean</title>
+ <para>
+ 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/X!
YZ</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. 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>java:/jaas prefix is no longer mandatory</title>
+ <para>
+ In previous versions of JBoss, the <literal>java:/jaas</literal> prefix in each <literal>securitydomain</literal> deployment descrptor element was required to correctly bind the JNDI name to the security manager bindings. As of JBoss AS 6, it is possible to specify the name of the <literal>securitydomain</literal> only in <literal>jboss.xml</literal> and <literal>jboss-web.xml</literal>. The <literal>java:/jaas</literal> prefix is still supported however, and remains for backwards compatibility.
+ </para>
+ </important>
+
+ <programlisting><jboss>
+ <!-- Configure all containers to be secured under the "hades" security domain -->
+ <security-domain>hades</security-domain>
+ <!-- ... -->
+</jboss>
+ </programlisting>
+
+ <para>
+ 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:
+ </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>.
+ </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>
+ <listitem>
+ <para>
+ <emphasis role="bold">DefaultCacheFlushPeriod</emphasis>: Specifies the default period of time in seconds that the authentication cache will flush expired entries. Default value is 3600 or one hour.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <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>.
+ </para>
+
+ <para>
+ This can be invoked programmatically using the following code snippet:
+ </para>
+
+ <programlisting>MBeanServer server = ...;
+String jaasMgrName = "jboss.security:service=JaasSecurityManager";
+ObjectName jaasMgr = new ObjectName(jaasMgrName);
+Object[] params = {domainName};
+String[] signature = {"java.lang.String"};
+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>.
+ </para>
+
+ <para>
+ This can be invoked programmatically using the following code snippet:
+ </para>
+
+ <programlisting>MBeanServer server = ...;
+String jaasMgrName = "jboss.security:service=JaasSecurityManager";
+ObjectName jaasMgr = new ObjectName(jaasMgrName);
+Object[] params = {domainName};
+String[] signature = {"java.lang.String"};
+List users = (List) server.invoke(jaasMgr, "getAuthenticationCachePrincipals",
+ params, signature);
+ </programlisting>
+
+ <para>
+ The security manager has a few additional access methods.
+ </para>
+
+ <programlisting>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);
+public Set getUserRoles(String securityDomain, Principal principal, Object credential);
+ </programlisting>
+
+ <para>
+ They provide access to the corresponding <literal>AuthenticationManager</literal> and <literal>RealmMapping</literal> interface method of the associated security domain named by the <literal>securityDomain</literal> argument.
+ </para>
+
+ <section id="The_JaasSecurityManagerService_MBean-The_JNDIBasedSecurityManagement_Bean">
+ <title>The JNDIBasedSecurityManagement Bean</title>
+ <para>
+ In AS 6 most MBeans were replaced by <emphasis>Micro Container</emphasis> (MC) Beans. <literal>JaasSecurityManagerService</literal> was not removed to maintain compatibility with previous versions but most of its functionalities are done by the <literal>JNDIBasedSecurityManagement</literal> MC Bean now. This Bean is located in <literal>conf/bootstrap/security.xml</literal>.
+ </para>
+
+ <para>
+ In <xref linkend="The_JNDIBasedSecurityManagement_Bean-Setting_custom_values." /> an example of how to set up the <literal>AuthenticationManager</literal> class, <literal>CallbackHandler</literal> class and default values for the authentication cache is shown:
+ </para>
+
+ <example id="The_JNDIBasedSecurityManagement_Bean-Setting_custom_values.">
+ <title>Setting custom values for the JNDIBasedSecurityManagement Bean</title>
+ <programlisting><bean name="JNDIBasedSecurityManagement"
+ class="org.jboss.security.integration.JNDIBasedSecurityManagement">
+ <property name="authenticationMgrClass">org.example.MyAuthenticationManager</property>
+ <property name="defaultCacheTimeout">1800</property>
+ <property name="defaultCacheResolution">60</property>
+ <property name="defaultCacheFlushPeriod">3600</property>
+ <property name="callBackHandler"><inject bean="CallbackHandler"/></property>
+</bean>
+
+<bean name="CallbackHandler" class="org.example.MyCallbackHandler"/>
+ </programlisting>
+ </example>
+ </section>
+ </section>
+
+ <section id="The_JBoss_Security_Extension_Architecture-The_JaasSecurityDomain_Bean">
+ <title>The JaasSecurityDomain Bean</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:
+ </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.
+ </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.
+ </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.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">keyStoreAlias</emphasis>: Alias of the <literal>KeyStore</literal> containing the certificate to be used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">keyStoreProvider</emphasis>: Security <literal>Provider</literal> of the <literal>KeyStore</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">keyStoreProviderArgument</emphasis>: Argument to be passed to the constructor of the <literal>KeyStore</literal> security <literal>Provider</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">keyManagerFactoryProvider</emphasis>: Security <literal>Provider</literal> of the <literal>KeyManagerFactory</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">keyManagerFactoryAlgorithm</emphasis>: Algorithm of the <literal>KeyManagerFactory</literal>.
+ </para>
+ </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> has the same configuration options as the <literal>keyStorePass</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">trustStoreProvider</emphasis>: Security <literal>Provider</literal> of the <literal>TrustStore</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">trustStoreProviderArgument</emphasis>: Argument to be passed to the constructor of the <literal>TrustStore</literal> security <literal>Provider</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">trustManagerFactoryProvider</emphasis>: Security <literal>Provider</literal> of the <literal>TrustManagerFactory</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">trustManagerFactoryAlgorithm</emphasis>: Algorithm of the <literal>TrustManagerFactory</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ In <xref linkend="The_JaasSecurityDomain_Bean-JaasSecurityDomain_example." /> an example <literal>JaasSecurityDomain</literal> Bean is shown:
+ </para>
+
+ <example id="The_JaasSecurityDomain_Bean-JaasSecurityDomain_example.">
+ <title>JaasSecurityDomain example</title>
+ <programlisting><bean name="example" class="org.jboss.security.plugins.JaasSecurityDomain">
+ <constructor>
+ <parameter>example</parameter>
+ </constructor>
+ <property name="keyStorePass">changeit</property>
+ <property name="keyStoreURL">resource:localhost.keystore</property>
+ <!-- introduce a JMX annotation to export this bean as an MBean -->
+ <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX
+ (name="jboss.security:service=JaasSecurityDomain,domain=example",
+ exposedInterface=org.jboss.security.plugins.JaasSecurityDomainMBean.class)
+ </annotation>
+ </bean>
+ </programlisting>
+ </example>
+
+ <important>
+ <title>JaasSecurityDomain can still be deployed as a MBean</title>
+ <para>
+ To maintain compatibility with previous versions, <literal>JaasSecurityDomain</literal> can still be deployed as a MBean.
+ </para>
+ </important>
+ </section>
+ </chapter>
Added: projects/docs/community/6/Security_Guide/en-US/Security_Guide-JBoss_Login_Modules.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/Security_Guide-JBoss_Login_Modules.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/Security_Guide-JBoss_Login_Modules.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,1388 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+ <chapter id="Login_Modules">
+ <title>JBoss Login Modules</title>
+
+ <section id="JBoss_Login_Modules">
+ <title>Using Modules</title>
+ <para>
+ JBoss AS includes several bundled login modules suitable for most user management needs. JBoss AS can read user information from a relational database, a LDAP server or flat files. In addition to these core login modules, JBoss provides several other login modules that provide user information for very customized needs in JBoss. Before we explore the individual login modules, let's take a look at a few login module configuration options that are common to multiple modules.
+ </para>
+
+ <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.
+ </para>
+
+ <para>
+ <xref linkend="sect-LdapLoginModule"/>describes 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>
+
+ <para>
+ 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>
+ 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 the chance to contribute roles to the authorization process.
+ </para>
+ </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">
+ <!-- LDAP configuration -->
+ <module-option name="password-stacking">useFirstPass</module-option>
+ </login-module>
+ <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule"
+ flag="required">
+ <!-- database configuration -->
+ <module-option name="password-stacking">useFirstPass</module-option>
+ </login-module>
+ </authentication>
+</application-policy>
+ </programlisting>
+ </example>
+ </section>
+
+ <section id="Using_JBoss_Login_Modules-Password_Hashing">
+ <title>Password Hashing</title>
+ <para>
+ Most login modules must 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>
+
+ <example>
+ <title>Password Hashing</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. The <filename>usersb64.properties</filename> file can be part of the deployment classpath, or be saved in the <filename>/conf</filename> directory.
+ </para>
+
+ <programlisting language="XML" role="XML"><policy>
+ <application-policy name="testUsersRoles">
+ <authentication>
+ <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
+ flag="required">
+ <module-option name="usersProperties">usersb64.properties</module-option>
+ <module-option name="rolesProperties">test-users-roles.properties</module-option>
+ <module-option name="unauthenticatedIdentity">nobody</module-option>
+ <module-option name="hashAlgorithm">MD5</module-option>
+ <module-option name="hashEncoding">base64</module-option>
+ </login-module>
+ </authentication>
+ </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 must 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,
+ null,
+ null,
+ "password");
+ </programlisting>
+
+ <para>
+ OpenSSL provides an alternative way to quickly generate hashed passwords.
+ </para>
+
+ <programlisting>echo -n password | openssl dgst -md5 -binary | openssl base64
+ </programlisting>
+
+ <para>
+ In both cases, the text password should hash to <literal>X03MO1qnZdYdgyfeuILPmQ==</literal>. This value must be stored in the user store.
+ </para>
+ </section>
+
+ <section id="Using_JBoss_Login_Modules-Unauthenticated_Identity">
+ <title>Unauthenticated Identity</title>
+ <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>
+ <para>
+ <emphasis role="bold">unauthenticatedIdentity</emphasis>: This defines the principal name that should be assigned to requests that contain no authentication information.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="Using_JBoss_Login_Modules-PrincipalClass">
+ <title>Principal Class</title>
+ <para>
+ Sometimes the implementation of the <literal>Principal</literal> interface provided by JBoss is not enough for the applications needs. In this case customers can use a custom implementation.
+ </para>
+
+ <itemizedlist>
+ <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>
+ </section>
+
+ <section id="sect-UsersRolesLoginModule">
+ <title>UsersRolesLoginModule</title>
+ <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 supported login module configuration options include the following:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>usersProperties</term>
+ <listitem>
+ <para>
+ Name of the properties resource (file) containing the username to password mappings. This defaults to <filename><filename_prefix>-users.properties</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>rolesProperties</term>
+ <listitem>
+ <para>
+ Name of the properties resource (file) containing the username to roles mappings. This defaults to <filename><filename_prefix>-roles.properties</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ This login module supports password stacking, password hashing, and unauthenticated identity.
+ </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>
+
+ <example id="exam-UsersRoleLoginModule">
+ <title>UserRolesLoginModule</title>
+ <programlisting language="XML"><deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <!-- ejb3 test application-policy definition -->
+ <application-policy xmlns="urn:jboss:security-beans:1.0" name="ejb3-sampleapp">
+ <authentication>
+ <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
+ <module-option name="usersProperties">ejb3-sampleapp-users.properties</module-option>
+ <module-option name="rolesProperties">ejb3-sampleapp-roles.properties</module-option>
+ </login-module>
+ </authentication>
+ </application-policy>
+
+</deployment>
+ </programlisting>
+ </example>
+
+ <para>
+ In <xref linkend="exam-UsersRoleLoginModule"/>, the <filename>ejb3-sampleapp-users.properties</filename> file uses a <filename>username=password</filename> format with each user entry on a separate line:
+ </para>
+
+ <programlisting>username1=password1
+username2=password2
+...
+ </programlisting>
+
+ <para>
+ The <filename>ejb3-sampleapp-roles.properties</filename> file referenced in <xref linkend="exam-UsersRoleLoginModule"/> uses the pattern <literal>username=role1,role2,</literal> with an optional group name value. For example:
+ </para>
+
+ <programlisting>username1=role1,role2,...
+username1.RoleGroup1=role3,role4,...
+username2=role1,role3,...
+ </programlisting>
+
+ <para>
+ The <property>username.XXX</property> property name pattern present in <filename>ejb3-sampleapp-roles.properties</filename> 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:
+ </para>
+
+ <programlisting>jduke=TheDuke,AnimatedCharacter
+jduke.Roles=TheDuke,AnimatedCharacter
+ </programlisting>
+ </section>
+
+ <section id="sect-DatabaseServerLoginModule">
+ <title>DatabaseServerLoginModule</title>
+ <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 stored in a relational database.
+ </para>
+
+ <note>
+ <para>
+ This module supports password stacking, password hashing and unauthenticated 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>.
+ </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>
+ <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>
+ <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>
+ <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>
+ </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>
+ 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>
+ </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>
+
+ <para>
+ A corresponding <literal>login-config.xml</literal> entry would be:
+ </para>
+
+ <programlisting language="XML" role="XML"><policy>
+ <application-policy name="testDB">
+ <authentication>
+ <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule"
+ flag="required">
+ <module-option name="dsJndiName">java:/MyDatabaseDS</module-option>
+ <module-option name="principalsQuery">
+ select passwd from Users username where username=?</module-option>
+ <module-option name="rolesQuery">
+ select userRoles, 'Roles' from UserRoles where username=?</module-option>
+ </login-module>
+ </authentication>
+ </application-policy>
+</policy>
+ </programlisting>
+ </section>
+
+ <section id="sect-LdapLoginModule">
+ <title>LdapLoginModule</title>
+ <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>
+
+ <note>
+ <para>
+ This login module also supports unauthenticated identity and password stacking.
+ </para>
+ </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 class name. 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>
+ </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>
+
+ <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>
+ </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>
+ </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>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 <property>Context.SECURITY_PRINCIPAL</property> 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 <property>Context.SECURITY_CREDENTIALS</property> 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 (<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>
+
+ <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">
+ <application-policy name="testLDAP">
+ <authentication>
+ <login-module code="org.jboss.security.auth.spi.LdapLoginModule"
+ flag="required">
+ <module-option name="java.naming.factory.initial">
+ com.sun.jndi.ldap.LdapCtxFactory
+ </module-option>
+ <module-option name="java.naming.provider.url">
+ ldap://ldaphost.jboss.org:1389/
+ </module-option>
+ <module-option name="java.naming.security.authentication">
+ simple
+ </module-option>
+ <module-option name="principalDNPrefix">uid=</module-option>
+ <module-option name="principalDNSuffix">
+ ,ou=People,dc=jboss,dc=org
+ </module-option>
+
+ <module-option name="rolesCtxDN">
+ ou=Roles,dc=jboss,dc=org
+ </module-option>
+ <module-option name="uidAttributeID">member</module-option>
+ <module-option name="matchOnUserDN">true</module-option>
+
+ <module-option name="roleAttributeID">cn</module-option>
+ <module-option name="roleAttributeIsDN">false </module-option>
+ </login-module>
+ </authentication>
+ </application-policy>
+ </programlisting>
+ </example>
+
+ <para>
+ An LDIF file representing the structure of the directory this data operates against is shown below.
+ </para>
+
+ <example id="exam-LDIF_File_Example">
+ <title>LDIF File Example</title>
+ <programlisting>dn: dc=jboss,dc=org
+objectclass: top
+objectclass: dcObject
+objectclass: organization
+dc: jboss
+o: JBoss
+
+dn: ou=People,dc=jboss,dc=org
+objectclass: top
+objectclass: organizationalUnit
+ou: People
+
+dn: uid=jduke,ou=People,dc=jboss,dc=org
+objectclass: top
+objectclass: uidObject
+objectclass: person
+uid: jduke
+cn: Java Duke
+sn: Duke
+userPassword: theduke
+
+dn: ou=Roles,dc=jboss,dc=org
+objectclass: top
+objectclass: organizationalUnit
+ou: Roles
+
+dn: cn=JBossAdmin,ou=Roles,dc=jboss,dc=org
+objectclass: top
+objectclass: groupOfNames
+cn: JBossAdmin
+member: uid=jduke,ou=People,dc=jboss,dc=org
+description: the JBossAdmin group
+ </programlisting>
+ </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>
+ </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). 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>
+ </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>
+ 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>
+ </section>
+
+ <section id="sec-LdapExtLoginModule">
+ <title>LdapExtLoginModule</title>
+ <para>
+ The <classname>org.jboss.security.auth.spi.LdapExtLoginModule</classname> is an alternate ldap login module implementation that uses searches for locating both the user to bind as for authentication as well as the associated roles. The roles query will recursively follow distinguished names (DNs) to navigate a hierarchical role structure.
+ </para>
+
+ <para>
+ The <classname>LoginModule</classname> options include whatever options your LDAP JNDI provider supports. Examples of standard property names are:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <methodname>Context.INITIAL_CONTEXT_FACTORY</methodname> = "java.naming.factory.initial"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>Context.SECURITY_PROTOCOL</methodname> = "java.naming.security.protocol"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>Context.PROVIDER_URL</methodname> = "java.naming.provider.url"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>Context.SECURITY_AUTHENTICATION</methodname> = "java.naming.security.authentication"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>Context.REFERRAL</methodname> = "java.naming.referral"
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The authentication happens in 2 steps:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ An initial bind to the ldap server is done using the bindDN and bindCredential options. The <methodname>bindDN</methodname> is some user with the ability to search both the <methodname>baseCtxDN</methodname> and <methodname>rolesCtxDN</methodname> trees for the user and roles. The user DN to authenticate against is queried using the filter specified by the <methodname>baseFilter</methodname> attribute (see the <methodname>baseFilter</methodname> option description for its syntax).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The resulting user DN is then authenticated by binding to ldap server using the user DN as the <classname>InitialLdapContext</classname> environment <methodname>Context.SECURITY_PRINCIPAL</methodname>. The <methodname>Context.SECURITY_CREDENTIALS</methodname> property is either set to the String password obtained by the callback handler.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ If this is successful, the associated user roles are queried using the <methodname>rolesCtxDN</methodname>, <methodname>roleAttributeID</methodname>, <methodname>roleAttributeIsDN</methodname>, <methodname>roleNameAttributeID</methodname>, and <methodname>roleFilter</methodname> options.
+ </para>
+
+ <para>
+ The full module properties include:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <methodname>baseCtxDN</methodname>: The fixed DN of the context to start the user search from.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>bindDN</methodname>: The DN used to bind against the ldap server for the user and roles queries. This is some DN with read/search permissions on the <methodname>baseCtxDN</methodname> and <methodname>rolesCtxDN</methodname> values.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>bindCredential</methodname>: The password for the <methodname>bindDN</methodname>. This can be encrypted if the <methodname>jaasSecurityDomain</methodname> is specified.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>jaasSecurityDomain</methodname>: The JMX ObjectName of the <classname>JaasSecurityDomain</classname> to use to decrypt the <methodname>java.naming.security.principal</methodname>. The encrypted form of the password is that returned by the <methodname>JaasSecurityDomain.encrypt64(byte[])</methodname> method. The <methodname>org.jboss.security.plugins.PBEUtils</methodname> class can also be used to generate the encrypted form.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>baseFilter</methodname>: A search filter used to locate the context of the user to authenticate. The input username/userDN as obtained from the login module callback will be substituted into the filter anywhere a <code>{0}</code> expression is seen. This substitution behavior comes from the standard <methodname>DirContext.search(Name, String, Object[], SearchControls cons)</methodname> method. A common example for the search filter is <code>(uid={0})</code>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>rolesCtxDN</methodname>: The fixed DN of the context to search for user roles. Consider that this is not the Distinguished Name of where the actual roles are; rather, this is the DN of where the objects containing the user roles are (for example, for Active Directory, this is the DN where the user account is).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>roleFilter</methodname>: A search filter used to locate the roles associated with the authenticated user. The input username/userDN as obtained from the login module callback will be substituted into the filter anywhere a <code>{0}</code> expression is seen. The authenticated <methodname>userDN</methodname> will be substituted into the filter anywhere a <code>{1}</code> is seen. An example search filter that matches on the input username is: <code>(member={0})</code>. An alternative that matches on the authenticated <methodname>userDN</methodname> is: <code>(member={1})</code>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>roleAttributeIsDN</methodname>: A flag indicating whether the user's role attribute contains the fully distinguished name of a role object, or the users's role attribute contains the role name. If false, the role name is taken from the value of the user's role attribute. If true, the role attribute represents the distinguished name of a role object. The role name is taken from the value of the <methodname>roleNameAttributeId</methodname> attribute of the corresponding object. In certain directory schemas (for example, Microsoft Active Directory), role <emphasis>(group)attributes</emphasis> in the user object are stored as DNs to role objects instead of as simple names, in which case, this property should be set to true. The default value of this property is false.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>roleAttributeID</methodname>: The name of the role attribute of the context which corresponds to the name of the role. If the <methodname>roleAttributeIsDN</methodname> property is set to true, this property is the DN of the context to query for the <methodname>roleNameAttributeID</methodname> attribute. If the <methodname>roleAttributeIsDN</methodname> property is set to false, this property is the attribute name of the role name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>roleNameAttributeID</methodname>: The name of the role attribute of the context which corresponds to the name of the role. If the <methodname>roleAttributeIsDN</methodname> property is set to true, this property is used to find the role object's name attribute. If the <methodname>roleAttributeIsDN</methodname> property is set to false, this property is ignored.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>distinguishedNameAttribute</methodname>: The name of an attribute in the user entry that contains the DN of the user. This may be necessary if the DN of the user itself contains special characters (backslash for example) that may prevent correct user mapping. Defaults to distinguishedName. If there is no such attribute, the entry's DN will be used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>roleRecursion</methodname> : How deep the role search will go below a given matching context. Disable with 0, which is the default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>searchTimeLimit</methodname>: The timeout in milliseconds for the user/role searches. Defaults to 10000 (10 seconds).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>searchScope</methodname>: Sets the search scope to one of the strings. The default is <methodname>SUBTREE_SCOPE</methodname>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <methodname>OBJECT_SCOPE</methodname>: only search the named roles context.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>ONELEVEL_SCOPE</methodname>: search directly under the named roles context.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>SUBTREE_SCOPE</methodname>: If the roles context is not a DirContext, search only the object. If the roles context is a <emphasis>DirContext</emphasis>, search the subtree rooted at the named object, including the named object itself
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>allowEmptyPasswords</methodname>: A flag indicating if <code>empty(length==0)</code> passwords should be passed to the LDAP server. An empty password is treated as an anonymous login by some LDAP servers and this may not be a desirable feature. Set this to false to reject empty passwords, true to have the ldap server validate the empty password. The default is true.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="sect-BaseCertLoginModule">
+ <title>BaseCertLoginModule</title>
+ <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 <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">
+ <constructor>
+ <arg type="java.lang.String" value="jmx-console"/>
+ </constructor>
+ <attribute name="KeyStoreURL">resource:localhost.keystore</attribute>
+ <attribute name="KeyStorePass">unit-tests-server</attribute>
+</mbean>
+ </programlisting>
+
+ <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 certificates 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"?>
+<web-app version="2.5"
+ xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
+
+ ...
+ <!-- A security constraint that restricts access to the HTML JMX console
+ to users with the role JBossAdmin. Edit the roles to what you want and
+ uncomment the WEB-INF/jboss-web.xml/security-domain element to enable
+ secured access to the HTML JMX console.
+ -->
+ <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>HtmlAdaptor</web-resource-name>
+ <description>An example security config that only allows users with the
+ role JBossAdmin to access the HTML JMX console web application
+ </description>
+ <url-pattern>/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>JBossAdmin</role-name>
+ </auth-constraint>
+ </security-constraint>
+
+ <login-config>
+ <auth-method>BASIC</auth-method>
+ <realm-name>JBoss JMX Console</realm-name>
+ </login-config>
+
+ <security-role>
+ <role-name>JBossAdmin</role-name>
+ </security-role>
+</web-app>
+ </programlisting>
+ </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>
+ </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">
+ <module-option name="password-stacking">useFirstPass</module-option>
+ <module-option name="securityDomain">jmx-console</module-option>
+ </login-module>
+ <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
+ flag="required">
+ <module-option name="password-stacking">useFirstPass</module-option>
+ <module-option name="usersProperties">jmx-console-users.properties</module-option>
+ <module-option name="rolesProperties">jmx-console-roles.properties</module-option>
+ </login-module>
+ </authentication>
+</application-policy>
+ </programlisting>
+ </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>
+
+ <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
+ at jboss.com, OU=QA, O=JBoss Inc.
+Serial number: 100103
+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
+ </screen>
+ </example>
+
+ <para>
+ 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
+admin=JBossAdmin
+ </screen>
+ </section>
+
+ <section id="sect-IdentityLoginModule">
+ <title>IdentityLoginModule</title>
+ <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>
+
+ <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 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>
+ <login-module code="org.jboss.security.auth.spi.IdentityLoginModule"
+ flag="required">
+ <module-option name="principal">jduke</module-option>
+ <module-option name="roles">TheDuke,AnimatedCharacter</module-option>
+ </login-module>
+ </authentication>
+ </application-policy>
+</policy>
+ </programlisting>
+ </section>
+
+ <section id="sect-RunAsLoginModule">
+ <title>RunAsLoginModule</title>
+ <para>
+ <literal>RunAsLoginModule</literal> (<classname>org.jboss.security.auth.spi.RunAsLoginModule</classname>) is a helper module that pushes a run as role onto the stack 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 must access secured resources in order to perform their authentication (for example, a login module that accesses a secured EJB). <literal>RunAsLoginModule</literal> must be configured ahead of the login modules that require a run as role established.
+ </para>
+
+ <para>
+ The only login module configuration option is:
+ </para>
+
+ <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>
+
+ <section id="sect-ClientLoginModule">
+ <title>ClientLoginModule</title>
+ <para>
+ <literal>ClientLoginModule</literal> (<classname>org.jboss.security.ClientLoginModule</classname>) is an implementation of <literal>LoginModule</literal> for use by JBoss clients for establishing caller identity and credentials. This simply sets the principal to the value of the <literal>NameCallback</literal> filled in by the <literal>callbackhandler</literal>, and the credential to the value of the <literal>PasswordCallback</literal> filled in by the <literal>callbackhandler</literal> in the security context.
+ </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>
+ 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>
+
+ <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>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>
+ </section>
+ </section>
+
+ <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. 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:
+ </para>
+
+ <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)
+java.util.Set getPublicCredentials()
+java.util.Set getPublicCredentials(java.lang.Class c)
+ </programlisting>
+
+ <para>
+ 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 (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>
+ 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 used for login.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+ <section id="sect-Custom_LoginModule_Example">
+ <title>Custom LoginModule Example</title>
+ <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>
+ <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 <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> JndiUserAndPass Custom Login Module</title>
+ <programlisting language="Java" role="JAVA">package org.jboss.book.security.ex2;
+
+import java.security.acl.Group;
+import java.util.Map;
+import javax.naming.InitialContext;
+import javax.naming.NamingException;
+import javax.security.auth.Subject;
+import javax.security.auth.callback.CallbackHandler;
+import javax.security.auth.login.LoginException;
+
+import org.jboss.security.SimpleGroup;
+import org.jboss.security.SimplePrincipal;
+import org.jboss.security.auth.spi.UsernamePasswordLoginModule;
+
+/**
+ * An example custom login module that obtains passwords and roles
+ * for a user from a JNDI lookup.
+ *
+ * @author Scott.Stark at jboss.org
+ * @version $Revision: 1.4 $
+*/
+public class JndiUserAndPass
+ extends UsernamePasswordLoginModule
+{
+ /** The JNDI name to the context that handles the password/username lookup */
+ private String userPathPrefix;
+ /** The JNDI name to the context that handles the roles/ username lookup */
+ private String rolesPathPrefix;
+
+ /**
+ * Override to obtain the userPathPrefix and rolesPathPrefix options.
+ */
+ public void initialize(Subject subject, CallbackHandler callbackHandler,
+ Map sharedState, Map options)
+ {
+ super.initialize(subject, callbackHandler, sharedState, options);
+ userPathPrefix = (String) options.get("userPathPrefix");
+ rolesPathPrefix = (String) options.get("rolesPathPrefix");
+ }
+
+ /**
+ * Get the roles the current user belongs to by querying the
+ * rolesPathPrefix + '/' + super.getUsername() JNDI location.
+ */
+ protected Group[] getRoleSets() throws LoginException
+ {
+ try {
+ InitialContext ctx = new InitialContext();
+ String rolesPath = rolesPathPrefix + '/' + super.getUsername();
+
+ String[] roles = (String[]) ctx.lookup(rolesPath);
+ Group[] groups = {new SimpleGroup("Roles")};
+ log.info("Getting roles for user="+super.getUsername());
+ for(int r = 0; r < roles.length; r ++) {
+ SimplePrincipal role = new SimplePrincipal(roles[r]);
+ log.info("Found role="+roles[r]);
+ groups[0].addMember(role);
+ }
+ return groups;
+ } catch(NamingException e) {
+ log.error("Failed to obtain groups for
+ user="+super.getUsername(), e);
+ throw new LoginException(e.toString(true));
+ }
+ }
+
+ /**
+ * Get the password of the current user by querying the
+ * userPathPrefix + '/' + super.getUsername() JNDI location.
+ */
+ protected String getUsersPassword()
+ throws LoginException
+ {
+ try {
+ InitialContext ctx = new InitialContext();
+ String userPath = userPathPrefix + '/' + super.getUsername();
+ log.info("Getting password for user="+super.getUsername());
+ String passwd = (String) ctx.lookup(userPath);
+ log.info("Found password="+passwd);
+ return passwd;
+ } catch(NamingException e) {
+ log.error("Failed to obtain password for
+ user="+super.getUsername(), e);
+ throw new LoginException(e.toString(true));
+ }
+ }
+}
+ </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>.
+ </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.
+ </para>
+
+ <screen>[examples]$ ant -Dchap=security -Dex=2 run-example
+...
+run-example2:
+ [echo] Waiting for 5 seconds for deploy...
+ [java] [INFO,ExClient] Login with username=jduke, password=theduke
+ [java] [INFO,ExClient] Looking up EchoBean2
+ [java] [INFO,ExClient] Created Echo
+ [java] [INFO,ExClient] Echo.echo('Hello') = Hello
+ </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 language="XML" role="XML"><?xml version="1.0"?>
+<jboss>
+ <security-domain>security-ex2</security-domain>
+</jboss>
+ </programlisting>
+
+ <para>
+ The SAR <literal>META-INF/login-config.xml</literal> descriptor defines the login module configuration.
+ </para>
+
+ <programlisting language="XML" role="XML"><application-policy name = "security-ex2">
+ <authentication>
+ <login-module code="org.jboss.book.security.ex2.JndiUserAndPass"
+ flag="required">
+ <module-option name = "userPathPrefix">/security/store/password</module-option>
+ <module-option name = "rolesPathPrefix">/security/store/roles</module-option>
+ </login-module>
+ </authentication>
+</application-policy>
+ </programlisting>
+ </section>
+ </section>
+ </chapter>
Added: projects/docs/community/6/Security_Guide/en-US/Security_Guide-JBoss_Security_Model.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/Security_Guide-JBoss_Security_Model.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/Security_Guide-JBoss_Security_Model.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,302 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+ <chapter id="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. The following interfaces define the JBoss server security layer:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">org.jboss.security.AuthenticationManager</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">org.jboss.security.RealmMapping</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">org.jboss.security.SecurityProxy</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">org.jboss.security.AuthorizationManager</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">org.jboss.security.AuditManager</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">org.jboss.security.MappingManager</emphasis>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ <xref linkend="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="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>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/AS6_SecurityModel_Interface.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ The EJB Container layer is represented by the classes <literal>org.jboss.ejb.Container</literal>, <literal>org.jboss.SecurityInterceptor</literal> and <literal>org.jboss.SecurityProxyInterceptor</literal>. The other classes are interfaces and classes provided by the JBoss security subsystem.
+ </para>
+
+ <para>
+ The two interfaces required for the J2EE security model implementation are:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">org.jboss.security.AuthenticationManager</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">org.jboss.security.AuthorizationManager</emphasis>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The roles of the security interfaces presented in <xref linkend="JBoss_Security_Model-The_key_security_model_interfaces_and_their_relationship_to_the_JBoss_server_EJB_container_elements." /> are summarized below.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">AuthenticationManager</emphasis>: This interface is responsible for validating credentials associated with <emphasis>Principals</emphasis>. Principals are identities, such as usernames, employee numbers, and social security numbers. <emphasis>Credentials</emphasis> 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>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">AuthorizationManager</emphasis>: This interface is responsible for the access control mandated by the J2EE specifications. The implementation of this interface provides the ability to stack a set of Policy Providers useful for pluggable authorization.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">SecurityProxy</emphasis>: 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>
+ <emphasis role="bold">AuditManager</emphasis>: This interface is responsible for providing an audit trail of security events.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">MappingManager</emphasis>: This interface is responsible for providing mapping of Principal, Role, and Attributes. The implementation of AuthorizationManager may internally call the mapping manager to map roles before performing access control.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">RealMapping</emphasis>: This interface is responsible for principal mapping and role mapping. The <literal>getPrincipal</literal> method takes an 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>
+ </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 plugin interfaces that are based on JAAS.
+ </para>
+
+ <para>
+ The component diagram in <xref linkend="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="JBoss_Security_Model-The_relationship_between_the_JBossSX_framework_implementation_classes_and_the_JBoss_server_EJB_container_layer." />.
+ </para>
+
+ <figure id="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>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/j2ee_chap8-7.jpg" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <section id="JBoss_Security_Model-Enabling_Declarative_Security_in_JBoss_Revisited">
+ <title>Enabling Declarative Security in JBoss Revisited</title>
+ <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.
+ </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>
+ <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>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <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." />.
+ </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;
+
+import java.lang.reflect.Method;
+import javax.ejb.EJBContext;
+
+import org.apache.log4j.Category;
+
+import org.jboss.security.SecurityProxy;
+
+/** A simple example of a custom SecurityProxy implementation
+ * that demonstrates method argument based security checks.
+ * @author Scott.Stark at jboss.org
+ * @version $Revision: 1.4 $
+ */
+public class EchoSecurityProxy implements SecurityProxy
+{
+ Category log = Category.getInstance(EchoSecurityProxy.class);
+ Method echo;
+
+ public void init(Class beanHome, Class beanRemote,
+ Object securityMgr)
+ throws InstantiationException
+ {
+ log.debug("init, beanHome="+beanHome
+ + ", beanRemote="+beanRemote
+ + ", securityMgr="+securityMgr);
+ // Get the echo method for equality testing in invoke
+ try {
+ Class[] params = {String.class};
+ echo = beanRemote.getDeclaredMethod("echo", params);
+ } catch(Exception e) {
+ String msg = "Failed to finde an echo(String) method";
+ log.error(msg, e);
+ throw new InstantiationException(msg);
+ }
+ }
+
+ public void setEJBContext(EJBContext ctx)
+ {
+ log.debug("setEJBContext, ctx="+ctx);
+ }
+
+ public void invokeHome(Method m, Object[] args)
+ throws SecurityException
+ {
+ // We don't validate access to home methods
+ }
+
+ public void invoke(Method m, Object[] args, Object bean)
+ throws SecurityException
+ {
+ log.debug"invoke, m="+m);
+ // Check for the echo method
+ if (m.equals(echo)) {
+ // Validate that the msg arg is not 4 letter word
+ String arg = (String) args[0];
+ if (arg == null || arg.length() == 4)
+ throw new SecurityException("No 4 letter words");
+ }
+ // We are not responsible for doing the invoke
+ }
+}
+ </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.
+ </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>
+ <programlisting><jboss>
+ <security-domain>other</security-domain>
+
+ <enterprise-beans>
+ <session>
+ <ejb-name>EchoBean</ejb-name>
+ <security-proxy>org.jboss.book.security.ex1.EchoSecurityProxy</security-proxy>
+ </session>
+ </enterprise-beans>
+</jboss>
+ </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:
+ </para>
+
+ <programlisting>public class ExClient
+{
+ public static void main(String args[])
+ throws Exception
+ {
+ Logger log = Logger.getLogger("ExClient");
+ log.info("Looking up EchoBean");
+
+ InitialContext iniCtx = new InitialContext();
+ Object ref = iniCtx.lookup("EchoBean");
+ EchoHome home = (EchoHome) ref;
+ Echo echo = home.create();
+
+ log.info("Created Echo");
+ log.info("Echo.echo('Hello') = "+echo.echo("Hello="));
+ log.info("Echo.echo('Four') = "+echo.echo("Four"));
+ }
+}
+ </programlisting>
+
+ <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
+run-example1:
+...
+ [echo] Waiting for 5 seconds for deploy...
+ [java] [INFO,ExClient] Looking up EchoBean
+ [java] [INFO,ExClient] Created Echo
+ [java] [INFO,ExClient] Echo.echo('Hello') = Hello
+ [java] Exception in thread "main" java.rmi.AccessException: SecurityException; nested exception is:
+ [java] java.lang.SecurityException: No 4 letter words
+...
+ [java] Caused by: java.lang.SecurityException: No 4 letter words
+...
+ </programlisting>
+
+ <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>
+ </section>
+ </chapter>
Added: projects/docs/community/6/Security_Guide/en-US/Security_Guide-Loading_Static_Security_Domains.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/Security_Guide-Loading_Static_Security_Domains.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/Security_Guide-Loading_Static_Security_Domains.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,70 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+ <chapter id="Loading_Static_Security_Domains">
+ <title>Loading Static Security Domains</title>
+ <para>
+ Authentication security domains are configured statically in the <filename>/server/<replaceable>$PROFILE</replaceable>/conf/login-config.xml</filename> file, or deployed using <filename>jboss-beans.xml</filename> deployment descriptors. For static domains, the <literal>XMLLoginConfig</literal> bean is responsible for loading security configurations specified in <filename>login-config.xml</filename>. The bean definition is located in the <filename>/server/<replaceable>$PROFILE</replaceable>/deploy/security/security-jboss-beans.xml</filename> file. The bean is defined as shown below.
+ </para>
+
+ <programlisting language="XML" role="XML"><bean name="XMLLoginConfig" class="org.jboss.security.auth.login.XMLLoginConfig">
+ <property name="configResource">login-config.xml</property>
+</bean>
+ </programlisting>
+
+ <para>
+ The bean supports the following attributes:
+ </para>
+
+ <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>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <literal>SecurityConfig</literal> bean is responsible for selecting the <literal>javax.security.auth.login.Configuration</literal> to be used. The default configuration simply references the <literal>XMLLoginConfig</literal> bean.
+ </para>
+
+ <programlisting language="XML" role="XML"><bean name="SecurityConfig" class="org.jboss.security.plugins.SecurityConfig">
+ <property name="mbeanServer"><inject bean="JMXKernel" property="mbeanServer"/></property>
+ <property name="defaultLoginConfig"><inject bean="XMLLoginConfig"/></property>
+</bean>
+ </programlisting>
+
+ <para>
+ There is one configurable attribute:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>defaultLoginConfig</term>
+ <listitem>
+ <para>
+ Specifies the bean name of the MC bean that provides the default JAAS login configuration. When the <literal>SecurityConfig</literal> is started, this bean is queried for its <literal>javax.security.auth.login.Configuration</literal> by calling its <literal>getConfiguration(Configuration currentConfig)</literal> operation. If the <literal>defaultLoginConfig</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>
+ </chapter>
Added: projects/docs/community/6/Security_Guide/en-US/Security_Guide-Overview.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/Security_Guide-Overview.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/Security_Guide-Overview.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,448 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+ <chapter id="J2EE_Declarative_Security_Overview">
+ <title>J2EE Declarative Security Overview</title>
+ <para>
+ Rather than embedding security into your business component, the J2EE 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 Automatic Teller Machine (ATM) component used to access a bank account. The security requirements, roles, and permissions of the component will vary independently of how you access the bank account. How you access your account information may also vary based on which bank is managing the account, or where the ATM is located.
+ </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.
+ </para>
+
+ <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>
+
+ <figure id="Security_References-The_security_role_ref_element">
+ <title>The security-role-ref element</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/j2ee_security_role_ref.jpg" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <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>.
+ </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 -->
+<ejb-jar>
+ <enterprise-beans>
+ <session>
+ <ejb-name>ASessionBean</ejb-name>
+ ...
+ <security-role-ref>
+ <role-name>TheRoleICheck</role-name>
+ <role-link>TheApplicationRole</role-link>
+ </security-role-ref>
+ </session>
+ </enterprise-beans>
+ ...
+</ejb-jar>
+ </programlisting>
+ </example>
+
+ <para>
+ <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>
+ <programlisting><web-app>
+ <servlet>
+ <servlet-name>AServlet</servlet-name>
+ ...
+ <security-role-ref>
+ <role-name>TheServletRole</role-name>
+ <role-link>TheApplicationRole</role-link>
+ </security-role-ref>
+ </servlet>
+ ...
+</web-app>
+ </programlisting>
+ </example>
+ </section>
+
+ <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" />
+ </para>
+
+ <figure id="Security_Identity-The_security_identity_element">
+ <title>The security-identity element</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/j2ee_security_identity.jpg" />
+ </imageobject>
+ </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.
+ </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 EJ!
B are then configured with a <literal>run-as/role-name</literal> equal to the restricted role. The following descriptor fragment that illustrates <literal>security-identity</literal> element usage.
+ </para>
+
+ <programlisting><!-- A sample ejb-jar.xml fragment -->
+<ejb-jar>
+ <enterprise-beans>
+ <session>
+ <ejb-name>ASessionBean</ejb-name>
+ <!-- ... -->
+ <security-identity>
+ <use-caller-identity/>
+ </security-identity>
+ </session>
+ <session>
+ <ejb-name>RunAsBean</ejb-name>
+ <!-- ... -->
+ <security-identity>
+ <run-as>
+ <description>A private internal role</description>
+ <role-name>InternalRole</role-name>
+ </run-as>
+ </security-identity>
+ </session>
+ </enterprise-beans>
+ <!-- ... -->
+</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.
+ </para>
+
+ <programlisting><session>
+ <ejb-name>RunAsBean</ejb-name>
+ <security-identity>
+ <run-as-principal>internal</run-as-principal>
+ </security-identity>
+</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:
+ </para>
+
+ <programlisting><servlet>
+ <servlet-name>AServlet</servlet-name>
+ <!-- ... -->
+ <run-as>
+ <role-name>InternalRole</role-name>
+ </run-as>
+</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.
+ </para>
+
+ <programlisting><servlet>
+ <servlet-name>AServlet</servlet-name>
+ <run-as-principal>internal</run-as-principal>
+</servlet>
+ </programlisting>
+ </section>
+
+ <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.
+ </para>
+
+ <para>
+ The J2EE 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 J2EE 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>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/j2ee_security_role.jpg" />
+ </imageobject>
+ </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 <liter!
al>security-role</literal> in an <literal>ejb-jar.xml</literal> 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>
+ <programlisting><!-- A sample ejb-jar.xml fragment -->
+<ejb-jar>
+ <!-- ... -->
+ <assembly-descriptor>
+ <security-role>
+ <description>The single application role</description>
+ <role-name>TheApplicationRole</role-name>
+ </security-role>
+ </assembly-descriptor>
+</ejb-jar>
+ </programlisting>
+ </example>
+
+ <para>
+ <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>
+ <programlisting><!-- A sample web.xml fragment -->
+<web-app>
+ <!-- ... -->
+ <security-role>
+ <description>The single application role</description>
+ <role-name>TheApplicationRole</role-name>
+ </security-role>
+</web-app>
+ </programlisting>
+ </example>
+ </section>
+
+ <section id="J2EE_Declarative_Security_Overview-EJB_method_permissions">
+ <title>EJB method permissions</title>
+ <para>
+ An application assembler can set the roles that are allowed to invoke an EJB's home and remote interface methods through method-permission element declarations.
+ </para>
+
+ <figure id="EJB_method_permissions-The_method_permissions_element">
+ <title>The method-permissions element</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/j2ee_method_permission.jpg" />
+ </imageobject>
+ </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>.
+ </para>
+
+ <figure id="EJB_method_permissions-The_method_element">
+ <title>The method element</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/j2ee_method.jpg" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ There are three supported styles of method element declarations.
+ </para>
+
+ <para>
+ The first is used for referring to all the home and component interface methods of the named enterprise bean:
+ </para>
+
+ <programlisting><method>
+ <ejb-name>EJBNAME</ejb-name>
+ <method-name>*</method-name>
+</method>
+ </programlisting>
+
+ <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>
+ <ejb-name>EJBNAME</ejb-name>
+ <method-name>METHOD</method-name>
+ </method>
+ </programlisting>
+
+ <para>
+ If there are multiple methods with the same overloaded name, this style refers to all of the overloaded methods.
+ </para>
+
+ <para>
+ The third style is used to refer to a specified method within a set of methods with an overloaded name:
+ </para>
+
+ <programlisting><method>
+ <ejb-name>EJBNAME</ejb-name>
+ <method-name>METHOD</method-name>
+ <method-params>
+ <method-param>PARAMETER_1</method-param>
+ <!-- ... -->
+ <method-param>PARAMETER_N</method-param>
+ </method-params>
+</method>
+ </programlisting>
+
+ <para>
+ 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.
+ </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.
+ </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>
+ <assembly-descriptor>
+ <method-permission>
+ <description>The employee and temp-employee roles may access any
+ method of the EmployeeService bean </description>
+ <role-name>employee</role-name>
+ <role-name>temp-employee</role-name>
+ <method>
+ <ejb-name>EmployeeService</ejb-name>
+ <method-name>*</method-name>
+ </method>
+ </method-permission>
+ <method-permission>
+ <description>The employee role may access the findByPrimaryKey,
+ getEmployeeInfo, and the updateEmployeeInfo(String) method of
+ the AardvarkPayroll bean </description>
+ <role-name>employee</role-name>
+ <method>
+ <ejb-name>AardvarkPayroll</ejb-name>
+ <method-name>findByPrimaryKey</method-name>
+ </method>
+ <method>
+ <ejb-name>AardvarkPayroll</ejb-name>
+ <method-name>getEmployeeInfo</method-name>
+ </method>
+ <method>
+ <ejb-name>AardvarkPayroll</ejb-name>
+ <method-name>updateEmployeeInfo</method-name>
+ <method-params>
+ <method-param>java.lang.String</method-param>
+ </method-params>
+ </method>
+ </method-permission>
+ <method-permission>
+ <description>The admin role may access any method of the
+ EmployeeServiceAdmin bean </description>
+ <role-name>admin</role-name>
+ <method>
+ <ejb-name>EmployeeServiceAdmin</ejb-name>
+ <method-name>*</method-name>
+ </method>
+ </method-permission>
+ <method-permission>
+ <description>Any authenticated user may access any method of the
+ EmployeeServiceHelp bean</description>
+ <unchecked/>
+ <method>
+ <ejb-name>EmployeeServiceHelp</ejb-name>
+ <method-name>*</method-name>
+ </method>
+ </method-permission>
+ <exclude-list>
+ <description>No fireTheCTO methods of the EmployeeFiring bean may be
+ used in this deployment</description>
+ <method>
+ <ejb-name>EmployeeFiring</ejb-name>
+ <method-name>fireTheCTO</method-name>
+ </method>
+ </exclude-list>
+ </assembly-descriptor>
+</ejb-jar>
+ </programlisting>
+ </example>
+ </section>
+
+ <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.
+ </para>
+
+ <figure id="Web_Content_Security_Constraints-The_security_constraint_element">
+ <title>The security-constraint element</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/webapp_security_constraint.jpg" />
+ </imageobject>
+ </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.
+ </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 applic!
ation requires the data to be transmitted in a fashion that prevents other entities 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.
+ </para>
+
+ <figure id="Web_Content_Security_Constraints-The_login_config_element">
+ <title>The login-config element</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/webapp_login_config.jpg" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <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>
+
+ <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>
+ <!-- ... -->
+ <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>Secure Content</web-resource-name>
+ <url-pattern>/restricted/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>AuthorizedUser</role-name>
+ </auth-constraint>
+ <user-data-constraint>
+ <transport-guarantee>NONE</transport-guarantee>
+ </user-data-constraint>
+ </security-constraint>
+ <!-- ... -->
+ <login-config>
+ <auth-method>BASIC</auth-method>
+ <realm-name>The Restricted Zone</realm-name>
+ </login-config>
+ <!-- ... -->
+ <security-role>
+ <description>The role required to access restricted content </description>
+ <role-name>AuthorizedUser</role-name>
+ </security-role>
+</web-app>
+ </programlisting>
+ </example>
+ </section>
+
+ <section id="J2EE_Declarative_Security_Overview-Enabling_Declarative_Security_in_JBoss">
+ <title>Enabling Declarative Security in JBoss</title>
+ <para>
+ The J2EE security elements that have been covered so far describe the security requirements only from the application's perspective. Because J2EE security elements declare logical roles, the application deployer maps the roles from the application domain onto the deployment environment. The J2EE 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 J2EE security model using JBoss server specific deployment descriptors. The details behind the security configuration are discussed in <xref linkend="JBoss_Security_Model" />.
+ </para>
+ </section>
+ </chapter>
Added: projects/docs/community/6/Security_Guide/en-US/Security_Guide-Static_Security_Domains.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/Security_Guide-Static_Security_Domains.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/Security_Guide-Static_Security_Domains.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,113 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+ <chapter id="Static_Security_Domains">
+ <title>Static 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>
+ 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>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/security_config_policy.jpg"/>
+ </imageobject>
+ </mediaobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/security_config_login_module.jpg"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <example id="exam-Login_Module_Intro_Example">
+ <title/>
+ <para>
+ This example 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="example">
+ <authentication>
+ <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
+ flag="required">
+ <module-option name="usersProperties">users.properties</module-option>
+ <module-option name="rolesProperties">roles.properties</module-option>
+ </login-module>
+ </authentication>
+</application-policy>
+ </programlisting>
+ </example>
+
+ <para>
+ 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 <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>
+
+ <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>
+ </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>
+ </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 must succeed for login to proceed.
+ </para>
+
+ <programlisting language="XML" role="XML"><application-policy name="todo">
+ <authentication>
+ <login-module code="org.jboss.security.auth.spi.LdapLoginModule"
+ flag="sufficient">
+ <!-- LDAP configuration -->
+ </login-module>
+ <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule"
+ flag="sufficient">
+ <!-- database configuration -->
+ </login-module>
+ </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 <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>
Added: projects/docs/community/6/Security_Guide/en-US/Security_Guide.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/Security_Guide.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/Security_Guide.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<book>
+
+<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<part id="Security_Overview">
+ <title>Security Overview</title>
+ <partintro>
+ <para>
+ Security is a fundamental part of any enterprise application. You need to be able to restrict who is allowed to access your applications and control what operations application users may perform.
+ </para>
+ <para>
+ The <emphasis>Java Enterprise Edition</emphasis> (J2EE) specification defines a simple role-based security model for <emphasis>Enterprise Java Beans</emphasis> (EJBs) and web components. The <emphasis>JBoss Security Extension</emphasis> (JBossSX) framework handles platform security, and provides support for both the role-based declarative J2EE security model and integration of custom security through a security proxy layer.
+ </para>
+ <para>
+ The default implementation of the declarative security model is based on <emphasis>Java Authentication and Authorization Service</emphasis> (JAAS) login modules and subjects. The security proxy layer allows custom security that cannot be described using the declarative model to be added to an EJB in a way that is independent of the EJB business object.
+ </para>
+ </partintro>
+ <xi:include href="Security_Guide-Overview.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Security_Guide-Introduction_to_JAAS.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Security_Guide-JBoss_Security_Model.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Security_Guide-JBossSX_Architecture.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</part>
+
+<part id="Security_Domains_and_Components">
+ <title>Security Domains and Components</title>
+ <xi:include href="Security_Guide-Static_Security_Domains.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="Security_Guide-Loading_Static_Security_Domains.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="Security_Guide-Dynamic_Security_Domains.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="Security_Guide-Authorization_Stacks.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="Security_Guide-Deployment-level_Role_Mapping.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="Security_Guide-JBoss_Login_Modules.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+</part>
+
+<part id="Encryption_and_Security">
+ <title>Encryption and Security</title>
+ <xi:include href="chap-Java_EE_Security_Manager.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="chap-Secure_Socket_Layer.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="chap-Masking_Passwords.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="chap-Overridding_SSL_Configuration.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="chap-Encrypting_DataSource_Passwords.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="chap-Encrypting_Keystore_Password_in_Tomcat_Connector.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="chap-Using_LdapExtLoginModule.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="chap-Firewalls.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="chap-Secure_Remote_Password_Protocol.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="chap-Consoles_And_Invokers.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+</part>
+
+</book>
Added: projects/docs/community/6/Security_Guide/en-US/chap-Consoles_And_Invokers.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/chap-Consoles_And_Invokers.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/chap-Consoles_And_Invokers.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,523 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="chap-Consoles_and_Invokers">
+ <title>Consoles and Invokers</title>
+ <para>
+ JBoss AS ships with several administrative access points that must be secured or removed to prevent unauthorized access to administrative functions in a deployment. This chapter discusses the various administration services and how to secure them.
+ </para>
+ <section id="sect-The_JMX_Console">
+ <title>JMX Console</title>
+ <para>
+ The <filename>jmx-console.war</filename> found in the <filename>deploy</filename> directory provides an HTML view into the JMX Microkernel. As such, it provides access to administrative actions like shutting down the server, stopping services, deploying new services, etc. It should either be secured like any other web application, or removed.
+ </para>
+ </section>
+ <section id="How_to_Secure_the_JBoss_Server-The_Web_Console">
+ <title>Admin Console</title>
+ <para>
+ The Admin Console replaces the Web Console, and uses JBoss Operations Network security elements to secure the console. For more information, refer to the <citetitle>JBoss Admin Console Quick Start User Guide</citetitle>. </para>
+ </section>
+ <section id="How_to_Secure_the_JBoss_Server-The_HTTP_Invokers">
+ <title>HTTP Invokers</title>
+ <para>
+ The <filename>http-invoker.sar</filename> found in the <filename>deploy</filename> directory is a service that provides RMI/HTTP access for EJBs and the JNDI <literal>Naming</literal> service. This includes a servlet that processes posts of marshaled <literal>org.jboss.invocation.Invocation</literal> objects that represent invocations that should be dispatched onto the <literal>MBeanServer</literal>. Effectively this allows access to MBeans that support the detached invoker operation via HTTP POST requests. Securing this access point involves securing the <literal>JMXInvokerServlet</literal> servlet found in the <filename>http-invoker.sar/invoker.war/WEB-INF/web.xml</filename> descriptor. There is a secure mapping defined for the <filename>/restricted/JMXInvokerServlet</filename> path by default. Remove the other paths and configure the <literal>http-invoker</literal> security domain setup in the <filename>http-invoker.sar/invoker.war/WEB-INF/jboss-web.xml</filename> de!
ployment descriptor.
+ </para>
+ <para>
+ <note>
+ <para>
+See the <citetitle>Admin Console Quick Start Guide</citetitle> for in-depth information on securing the HTTP invoker.
+ </para>
+ </note>
+ </para>
+ </section>
+ <section id="How_to_Secure_the_JBoss_Server-The_JMX_Invoker">
+ <title>JMX Invoker</title>
+ <para>
+ The <filename>jmx-invoker-service.xml</filename> is a configuration file that exposes the JMX MBeanServer interface via an RMI compatible interface using the RMI/JRMP detached invoker service. </para>
+ </section>
+ <section id="Remote_Access_to_Services_Detached_Invokers">
+ <title>Remote Access to Services, Detached Invokers</title>
+ <para>
+ In addition to the MBean services notion that allows for the ability to integrate arbitrary functionality, JBoss also has a detached invoker concept that allows MBean services to expose functional interfaces via arbitrary protocols for remote access by clients. The notion of a detached invoker is that remoting and the protocol by which a service is accessed is a functional aspect or service independent of the component. Therefore, you can make a naming service available for use via RMI/JRMP, RMI/HTTP, RMI/SOAP, or any arbitrary custom transport.
+ </para>
+ <para>
+ The discussion of the detached invoker architecture will begin with an overview of the components involved. The main components in the detached invoker architecture are shown in <xref linkend="Remote_Access_to_Services_Detached_Invokers-The_main_components_in_the_detached_invoker_architecture"/>.
+ </para>
+ <figure id="Remote_Access_to_Services_Detached_Invokers-The_main_components_in_the_detached_invoker_architecture">
+ <title>The main components in the detached invoker architecture</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/j2ee_chap2-47.jpg"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ On the client side, there exists a client proxy which exposes the interface(s) of the MBean service. This is the same smart, compile-less dynamic proxy that is used for EJB home and remote interfaces. The only difference between the proxy for an arbitrary service and the EJB is the set of interfaces exposed as well as the client side interceptors found inside the proxy. The client interceptors are represented by the rectangles found inside of the client proxy. An interceptor is an assembly line type of pattern that allows for transformation of a method invocation and/or return values. A client obtains a proxy through some lookup mechanism, typically JNDI. Although RMI is indicated in <xref linkend="Remote_Access_to_Services_Detached_Invokers-The_main_components_in_the_detached_invoker_architecture"/>, the only real requirement on the exposed interface and its types is that they are serializable between the client server over JNDI as well as the transport layer.
+ </para>
+ <para>
+ The choice of the transport layer is determined by the last interceptor in the client proxy, which is referred to as the <emphasis>Invoker Interceptor</emphasis> in <xref linkend="Remote_Access_to_Services_Detached_Invokers-The_main_components_in_the_detached_invoker_architecture"/>. The invoker interceptor contains a reference to the transport specific stub of the server side <emphasis>Detached Invoker</emphasis> MBean service. The invoker interceptor also handles the optimization of calls that occur within the same VM as the target MBean. When the invoker interceptor detects that this is the case the call is passed to a call-by-reference invoker that simply passes the invocation along to the target MBean.
+ </para>
+ <para>
+ The detached invoker service is responsible for making a generic invoke operation available via the transport the detached invoker handles. The <literal>Invoker</literal> interface illustrates the generic invoke operation.
+ </para>
+ <programlisting language="Java">
+package org.jboss.invocation;
+
+import java.rmi.Remote;
+import org.jboss.proxy.Interceptor;
+import org.jboss.util.id.GUID;
+
+
+public interface Invoker
+ extends Remote
+{
+ GUID ID = new GUID();
+
+ String getServerHostName() throws Exception;
+
+ Object invoke(Invocation invocation) throws Exception;
+}
+</programlisting>
+ <para>
+ The Invoker interface extends <literal>Remote</literal> to be compatible with RMI, but this does not mean that an invoker must expose an RMI service stub. The detached invoker service simply acts as a transport gateway that accepts invocations represented as the <literal>org.jboss.invocation.Invocation</literal> object over its specific transport, unmarshalls the invocation, forwards the invocation onto the destination MBean service, represented by the <emphasis>Target MBean</emphasis> in <xref linkend="Remote_Access_to_Services_Detached_Invokers-The_main_components_in_the_detached_invoker_architecture"/>, and marshalls the return value or exception resulting from the forwarded call back to the client.
+ </para>
+ <para>
+ The <literal>Invocation</literal> object is just a representation of a method invocation context. This includes the target MBean name, the method, the method arguments, a context of information associated with the proxy by the proxy factory, and an arbitrary map of data associated with the invocation by the client proxy interceptors.
+ </para>
+ <para>
+ The configuration of the client proxy is done by the server side proxy factory MBean service, indicated by the <emphasis>Proxy Factory</emphasis> component in <xref linkend="Remote_Access_to_Services_Detached_Invokers-The_main_components_in_the_detached_invoker_architecture"/>. The proxy factory performs the following tasks:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Create a dynamic proxy that implements the interface the target MBean wishes to expose.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Associate the client proxy interceptors with the dynamic proxy handler.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Associate the invocation context with the dynamic proxy. This includes the target MBean, detached invoker stub and the proxy JNDI name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Make the proxy available to clients by binding the proxy into JNDI.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The last component in <xref linkend="Remote_Access_to_Services_Detached_Invokers-The_main_components_in_the_detached_invoker_architecture"/> is the <emphasis>Target MBean</emphasis> service that wishes to expose an interface for invocations to remote clients. The steps required for an MBean service to be accessible through a given interface are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Define a JMX operation matching the signature: <literal>public Object invoke(org.jboss.invocation.Invocation) throws Exception</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create a <literal>HashMap<Long, Method></literal> mapping from the exposed interface <literal>java.lang.reflect.Method</literal>s to the long hash representation using the <literal>org.jboss.invocation.MarshalledInvocation.calculateHash</literal> method.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Implement the <literal>invoke(Invocation)</literal> JMX operation and use the interface method hash mapping to transform from the long hash representation of the invoked method to the <literal>java.lang.reflect.Method</literal> of the exposed interface. Reflection is used to perform the actual invocation on the object associated with the MBean service that actually implements the exposed interface.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section id="Remote_Access_to_Services_Detached_Invokers-A_Detached_Invoker_Example_the_MBeanServer_Invoker_Adaptor_Service">
+ <title>A Detached Invoker Example, the MBeanServer Invoker Adaptor Service</title>
+ <para>
+This section presents the <literal>org.jboss.jmx.connector.invoker.InvokerAdaptorService</literal> and its configuration for access via RMI/JRMP as an example of the steps required to provide remote access to an MBean service.
+ </para>
+ <example id="A_Detached_Invoker_Example_the_MBeanServer_Invoker_Adaptor_Service-The_InvokerAdaptorService_MBean">
+ <title>The InvokerAdaptorService MBean</title>
+ <para>
+ The <literal>InvokerAdaptorService</literal> is a simple MBean service that exists to fulfill the target MBean role in the detached invoker pattern.
+ </para>
+ <programlisting language="Java">package org.jboss.jmx.connector.invoker;
+public interface InvokerAdaptorServiceMBean
+ extends org.jboss.system.ServiceMBean
+{
+ Class getExportedInterface();
+ void setExportedInterface(Class exportedInterface);
+
+ Object invoke(org.jboss.invocation.Invocation invocation)
+ throws Exception;
+}
+
+package org.jboss.jmx.connector.invoker;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.UndeclaredThrowableException;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+
+import javax.management.MBeanServer;
+import javax.management.ObjectName;
+
+import org.jboss.invocation.Invocation;
+import org.jboss.invocation.MarshalledInvocation;
+import org.jboss.mx.server.ServerConstants;
+import org.jboss.system.ServiceMBeanSupport;
+import org.jboss.system.Registry;
+
+public class InvokerAdaptorService
+ extends ServiceMBeanSupport
+ implements InvokerAdaptorServiceMBean, ServerConstants
+{
+ private static ObjectName mbeanRegistry;
+
+ static {
+ try {
+ mbeanRegistry = new ObjectName(MBEAN_REGISTRY);
+ } catch (Exception e) {
+ throw new RuntimeException(e.toString());
+ }
+ }
+
+ private Map marshalledInvocationMapping = new HashMap();
+ private Class exportedInterface;
+
+ public Class getExportedInterface()
+ {
+ return exportedInterface;
+ }
+
+ public void setExportedInterface(Class exportedInterface)
+ {
+ this.exportedInterface = exportedInterface;
+ }
+
+ protected void startService()
+ throws Exception
+ {
+ // Build the interface method map
+ Method[] methods = exportedInterface.getMethods();
+ HashMap tmpMap = new HashMap(methods.length);
+ for (int m = 0; m < methods.length; m ++) {
+ Method method = methods[m];
+ Long hash = new Long(MarshalledInvocation.calculateHash(method));
+ tmpMap.put(hash, method);
+ }
+
+ marshalledInvocationMapping = Collections.unmodifiableMap(tmpMap);
+ // Place our ObjectName hash into the Registry so invokers can
+ // resolve it
+ Registry.bind(new Integer(serviceName.hashCode()), serviceName);
+ }
+
+ protected void stopService()
+ throws Exception
+ {
+ Registry.unbind(new Integer(serviceName.hashCode()));
+ }
+
+
+ public Object invoke(Invocation invocation)
+ throws Exception
+ {
+ // Make sure we have the correct classloader before unmarshalling
+ Thread thread = Thread.currentThread();
+ ClassLoader oldCL = thread.getContextClassLoader();
+
+ // Get the MBean this operation applies to
+ ClassLoader newCL = null;
+ ObjectName objectName = (ObjectName)
+ invocation.getValue("JMX_OBJECT_NAME");
+ if (objectName != null) {
+ // Obtain the ClassLoader associated with the MBean deployment
+ newCL = (ClassLoader)
+ server.invoke(mbeanRegistry, "getValue",
+ new Object[] { objectName, CLASSLOADER },
+ new String[] { ObjectName.class.getName(),
+ "java.lang.String" });
+ }
+
+ if (newCL != null && newCL != oldCL) {
+ thread.setContextClassLoader(newCL);
+ }
+
+ try {
+ // Set the method hash to Method mapping
+ if (invocation instanceof MarshalledInvocation) {
+ MarshalledInvocation mi = (MarshalledInvocation) invocation;
+ mi.setMethodMap(marshalledInvocationMapping);
+ }
+
+ // Invoke the MBeanServer method via reflection
+ Method method = invocation.getMethod();
+ Object[] args = invocation.getArguments();
+ Object value = null;
+ try {
+ String name = method.getName();
+ Class[] sig = method.getParameterTypes();
+ Method mbeanServerMethod =
+ MBeanServer.class.getMethod(name, sig);
+ value = mbeanServerMethod.invoke(server, args);
+ } catch(InvocationTargetException e) {
+ Throwable t = e.getTargetException();
+ if (t instanceof Exception) {
+ throw (Exception) t;
+ } else {
+ throw new UndeclaredThrowableException(t, method.toString());
+ }
+ }
+
+ return value;
+ } finally {
+ if (newCL != null && newCL != oldCL) {
+ thread.setContextClassLoader(oldCL);
+ }
+ }
+ }
+}
+</programlisting>
+ </example>
+ <para>To help understand the components that make up the <literal>InvokerAdaptorServiceMBean</literal>, the code has been split into logical blocks, with commentary about how each block interoperates.</para>
+ <example>
+ <title>Block One</title>
+ <programlisting language="Java">package org.jboss.jmx.connector.invoker;
+public interface InvokerAdaptorServiceMBean
+ extends org.jboss.system.ServiceMBean
+{
+ Class getExportedInterface();
+ void setExportedInterface(Class exportedInterface);
+
+ Object invoke(org.jboss.invocation.Invocation invocation)
+ throws Exception;
+}
+
+package org.jboss.jmx.connector.invoker;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.UndeclaredThrowableException;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+
+import javax.management.MBeanServer;
+import javax.management.ObjectName;
+
+import org.jboss.invocation.Invocation;
+import org.jboss.invocation.MarshalledInvocation;
+import org.jboss.mx.server.ServerConstants;
+import org.jboss.system.ServiceMBeanSupport;
+import org.jboss.system.Registry;
+
+public class InvokerAdaptorService
+ extends ServiceMBeanSupport
+ implements InvokerAdaptorServiceMBean, ServerConstants
+{
+ private static ObjectName mbeanRegistry;
+
+ static {
+ try {
+ mbeanRegistry = new ObjectName(MBEAN_REGISTRY);
+ } catch (Exception e) {
+ throw new RuntimeException(e.toString());
+ }
+ }
+
+ private Map marshalledInvocationMapping = new HashMap();
+ private Class exportedInterface;
+
+ public Class getExportedInterface()
+ {
+ return exportedInterface;
+ }
+
+ public void setExportedInterface(Class exportedInterface)
+ {
+ this.exportedInterface = exportedInterface;
+ }
+...</programlisting>
+ <para> The <literal>InvokerAdaptorServiceMBean</literal> Standard MBean interface of the <literal>InvokerAdaptorService</literal> has a single <literal>ExportedInterface</literal> attribute and a single <literal>invoke(Invocation)</literal> operation. </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <literal>ExportedInterface</literal>
+ </term>
+ <listitem>
+ <para>The attribute allows customization of the type of interface the service exposes to clients. This must be compatible with the <literal>MBeanServer</literal> class in terms of method name and signature. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>invoke(Invocation)</literal>
+ </term>
+ <listitem>
+ <para>The operation is the required entry point that target MBean services must expose to participate in the detached invoker pattern. This operation is invoked by the detached invoker services that have been configured to provide access to the <literal>InvokerAdaptorService</literal>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </example>
+ <example id="exam-Block_2">
+ <title>Block Two</title>
+ <programlisting language="Java"> protected void startService()
+ throws Exception
+ {
+ // Build the interface method map
+ Method[] methods = exportedInterface.getMethods();
+ HashMap tmpMap = new HashMap(methods.length);
+ for (int m = 0; m &lt; methods.length; m ++) {
+ Method method = methods[m];
+ Long hash = new Long(MarshalledInvocation.calculateHash(method));
+ tmpMap.put(hash, method);
+ }
+
+ marshalledInvocationMapping = Collections.unmodifiableMap(tmpMap);
+ // Place our ObjectName hash into the Registry so invokers can
+ // resolve it
+ Registry.bind(new Integer(serviceName.hashCode()), serviceName);
+ }
+ protected void stopService()
+ throws Exception
+ {
+ Registry.unbind(new Integer(serviceName.hashCode()));
+ }</programlisting>
+ <para>This code block builds the HashMap<Long, Method> of the <classname>exportedInterface</classname> Class using the <methodname>org.jboss.invocation.MarshalledInvocation.calculateHash(Method)</methodname> utility method. </para>
+ <para>Because <literal>java.lang.reflect.Method</literal> instances are not serializable, a <literal>MarshalledInvocation</literal> version of the non-serializable <literal>Invocation</literal> class is used to marshall the invocation between the client and server. The <literal>MarshalledInvocation</literal> replaces the Method instances with their corresponding hash representation. On the server side, the <literal>MarshalledInvocation</literal> must be told what the hash to Method mapping is.
+ </para>
+ <para>This code block creates a mapping between the <literal>InvokerAdaptorService</literal> service name and its hash code representation. This is used by detached invokers to determine what the target MBean <literal>ObjectName</literal> of an <literal>Invocation</literal> is. </para>
+ <para>When the target MBean name is stored in the <literal>Invocation</literal>, its store as its hashCode because <literal>ObjectName</literal>s are relatively expensive objects to create. The <literal>org.jboss.system.Registry</literal> is a global map like construct that invokers use to store the hash code to <literal>ObjectName</literal> mappings in.
+ </para>
+ </example>
+ <example>
+ <title>Block Three</title>
+ <programlisting language="Java"> public Object invoke(Invocation invocation)
+ throws Exception
+ {
+ // Make sure we have the correct classloader before unmarshalling
+ Thread thread = Thread.currentThread();
+ ClassLoader oldCL = thread.getContextClassLoader();
+
+ // Get the MBean this operation applies to
+ ClassLoader newCL = null;
+ ObjectName objectName = (ObjectName)
+ invocation.getValue(&quot;JMX_OBJECT_NAME&quot;);
+ if (objectName != null) {
+ // Obtain the ClassLoader associated with the MBean deployment
+ newCL = (ClassLoader)
+ server.invoke(mbeanRegistry, &quot;getValue&quot;,
+ new Object[] { objectName, CLASSLOADER },
+ new String[] { ObjectName.class.getName(),
+ &quot;java.lang.String&quot; });
+ }
+
+ if (newCL != null &amp;&amp; newCL != oldCL) {
+ thread.setContextClassLoader(newCL);
+ }
+</programlisting>
+ <para>This code block obtains the name of the MBean on which the MBeanServer operation is being performed, and then looks up the class loader associated with the MBean's SAR deployment. This information is available via the <classname>org.jboss.mx.server.registry.BasicMBeanRegistry</classname>, a JBoss JMX implementation-specific class. </para>
+ <para>It is generally necessary for an MBean to establish the correct class loading context because the detached invoker protocol layer may not have access to the class loaders needed to unmarshall the types associated with an invocation.
+ </para>
+ </example>
+ <example>
+ <title>Block Four</title>
+ <programlisting language="Java">...
+ try {
+ // Set the method hash to Method mapping
+ if (invocation instanceof MarshalledInvocation) {
+ MarshalledInvocation mi = (MarshalledInvocation) invocation;
+ mi.setMethodMap(marshalledInvocationMapping);
+ }
+...</programlisting>
+ <para>This code block installs the <literal>ExposedInterface</literal> class method hash to method mapping if the invocation argument is of type <literal>MarshalledInvocation</literal>. The method mapping calculated in <xref linkend="exam-Block_2"/>is used here.
+ </para>
+ <para>A second mapping is performed from the <methodname>ExposedInterface</methodname> method to the matching method of the MBeanServer class. The <literal>InvokerServiceAdaptor</literal> decouples the <literal>ExposedInterface</literal> from the <classname>MBeanServer</classname> class in that it allows an arbitrary interface. This is required because the standard <classname>java.lang.reflect.Proxy</classname> class can only proxy interfaces. It also allows you to only expose a subset of the MBeanServer methods and add transport specific exceptions such as <literal>java.rmi.RemoteException</literal> to the <literal>ExposedInterface</literal> method signatures.
+ </para>
+ </example>
+ <example>
+ <title>Block Five</title>
+ <programlisting language="Java">...
+ // Invoke the MBeanServer method via reflection
+ Method method = invocation.getMethod();
+ Object[] args = invocation.getArguments();
+ Object value = null;
+ try {
+ String name = method.getName();
+ Class[] sig = method.getParameterTypes();
+ Method mbeanServerMethod =
+ MBeanServer.class.getMethod(name, sig);
+ value = mbeanServerMethod.invoke(server, args);
+ } catch(InvocationTargetException e) {
+ Throwable t = e.getTargetException();
+ if (t instanceof Exception) {
+ throw (Exception) t;
+ } else {
+ throw new UndeclaredThrowableException(t, method.toString());
+ }
+ }
+
+ return value;
+ } finally {
+ if (newCL != null &amp;&amp; newCL != oldCL) {
+ thread.setContextClassLoader(oldCL);
+ }
+ }
+ }
+}</programlisting>
+ <para>The code block dispatches the MBeanServer method invocation to the <literal>InvokerAdaptorService</literal> MBeanServer instance to which the was deployed. The server instance variable is inherited from the <literal>ServiceMBeanSupport</literal> superclass.
+ </para>
+ <para>Any exceptions that result from the reflective invocation are handled, including unwrapping any declared exceptions thrown by the invocation.
+ The MBean code completes with the return of the successful MBeanServer method invocation result.
+ </para>
+ </example>
+ <note>
+ <para>The <literal>InvokerAdaptorService</literal> MBean does not deal directly with any transport specific details. There is the calculation of the method hash to Method mapping, but this is a transport independent detail.
+ </para>
+ </note>
+ <para>
+ Now take a look at how the <literal>InvokerAdaptorService</literal> may be used to expose the same <literal>org.jboss.jmx.adaptor.rmi.RMIAdaptor</literal> interface via RMI/JRMP as seen in Connecting to JMX Using RMI. </para>
+ <para>We start by presenting the proxy factory and <literal>InvokerAdaptorService</literal> configurations found in the default setup in the <literal>jmx-invoker-adaptor-service.sar</literal> deployment. <xref linkend="A_Detached_Invoker_Example_the_MBeanServer_Invoker_Adaptor_Service-The_default_jmx_invoker_adaptor_server.sar_jboss_service.xml_deployment_descriptor"/> shows the <literal>jboss-service.xml</literal> descriptor for this deployment.
+ </para>
+ <example id="A_Detached_Invoker_Example_the_MBeanServer_Invoker_Adaptor_Service-The_default_jmx_invoker_adaptor_server.sar_jboss_service.xml_deployment_descriptor">
+ <title>Default jmx-invoker-adaptor-server.sar deployment descriptor</title>
+ <programlisting language="XML"><server>
+ <!-- The JRMP invoker proxy configuration for the InvokerAdaptorService -->
+ <mbean code="org.jboss.invocation.jrmp.server.JRMPProxyFactory"
+ name="jboss.jmx:type=adaptor,name=Invoker,protocol=jrmp,service=proxyFactory">
+ <!-- Use the standard JRMPInvoker from conf/jboss-service.xml -->
+ <attribute name="InvokerName">jboss:service=invoker,type=jrmp</attribute>
+ <!-- The target MBean is the InvokerAdaptorService configured below -->
+ <attribute name="TargetName">jboss.jmx:type=adaptor,name=Invoker</attribute>
+ <!-- Where to bind the RMIAdaptor proxy -->
+ <attribute name="JndiName">jmx/invoker/RMIAdaptor</attribute>
+ <!-- The RMI compatible MBeanServer interface -->
+ <attribute name="ExportedInterface">org.jboss.jmx.adaptor.rmi.RMIAdaptor</attribute>
+ <attribute name="ClientInterceptors">
+ <iterceptors>
+ <interceptor>org.jboss.proxy.ClientMethodInterceptor</interceptor>
+ <interceptor>
+ org.jboss.jmx.connector.invoker.client.InvokerAdaptorClientInterceptor
+ </interceptor>
+ <interceptor>org.jboss.invocation.InvokerInterceptor</interceptor>
+ </iterceptors>
+ </attribute>
+ <depends>jboss:service=invoker,type=jrmp</depends>
+ </mbean>
+ <!-- This is the service that handles the RMIAdaptor invocations by routing
+ them to the MBeanServer the service is deployed under. -->
+ <mbean code="org.jboss.jmx.connector.invoker.InvokerAdaptorService"
+ name="jboss.jmx:type=adaptor,name=Invoker">
+ <attribute name="ExportedInterface">org.jboss.jmx.adaptor.rmi.RMIAdaptor</attribute>
+ </mbean>
+</server>
+</programlisting>
+ </example>
+ <para>
+ The first MBean, <literal>org.jboss.invocation.jrmp.server.JRMPProxyFactory</literal>, is the proxy factory MBean service that creates proxies for the RMI/JRMP protocol. The configuration of this service as shown in <xref linkend="A_Detached_Invoker_Example_the_MBeanServer_Invoker_Adaptor_Service-The_default_jmx_invoker_adaptor_server.sar_jboss_service.xml_deployment_descriptor"/> states that the JRMPInvoker will be used as the detached invoker, the <literal>InvokerAdaptorService</literal> is the target mbean to which requests will be forwarded, that the proxy will expose the <literal>RMIAdaptor</literal> interface, the proxy will be bound into JNDI under the name <literal>jmx/invoker/RMIAdaptor</literal>, and the proxy will contain 3 interceptors: <literal>ClientMethodInterceptor</literal>, <literal>InvokerAdaptorClientInterceptor</literal>, <literal>InvokerInterceptor</literal>. The configuration of the <literal>InvokerAdaptorService</literal> simply sets the RMIAdapt!
or interface that the service is exposing.
+ </para>
+ <para>
+ The last piece of the configuration for exposing the <literal>InvokerAdaptorService</literal> via RMI/JRMP is the detached invoker. The detached invoker we will use is the standard RMI/JRMP invoker used by the EJB containers for home and remote invocations, and this is the <literal>org.jboss.invocation.jrmp.server.JRMPInvoker</literal> MBean service configured in the <literal>conf/jboss-service.xml</literal> descriptor. That we can use the same service instance emphasizes the detached nature of the invokers. The JRMPInvoker simply acts as the RMI/JRMP endpoint for all RMI/JRMP proxies regardless of the interface(s) the proxies expose or the service the proxies utilize.
+ </para>
+ </section>
+ </section>
+</chapter>
Added: projects/docs/community/6/Security_Guide/en-US/chap-Encrypting_DataSource_Passwords.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/chap-Encrypting_DataSource_Passwords.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/chap-Encrypting_DataSource_Passwords.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,446 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="Encrypting_Data_Source_Passwords">
+ <title>Encrypting Data Source Passwords</title>
+
+<!--
+ Relevant info:
+ http://community.jboss.org/wiki/ConfigJCALoginModule
+ http://community.jboss.org/wiki/EncryptingDataSourcePasswords
+
+-->
+
+ <para>
+ Database connections for the JBoss AS are defined in <filename>*-ds.xml</filename> data source files. These database connection details include clear text passwords. You can increase the security of your server by replacing clear text passwords in datasource files with encrypted passwords.
+ </para>
+
+ <para>
+ This chapter presents two different methods for encrypting data source passwords. The first is <firstterm>Secured Identity</firstterm>. The second is <firstterm>Configured Identity with Password Based Encryption (PBE)</firstterm>.
+ </para>
+
+<!-- Here we need a discussion of the pros, cons, and relative merits of each of the two methods -->
+
+ <section>
+ <title>Secured Identity</title>
+
+ <para>
+ The class <classname>org.jboss.resource.security.SecureIdentityLoginModule</classname> can be used to both encrypt database passwords and to provide a decrypted version of the password when the data source configuration is required by the server. The <classname>SecureIdentityLoginModule</classname> uses a hard-coded password to encrypt/decrypt the data source password.
+ </para>
+
+ <procedure>
+ <title>Overview: Using SecureIdentityLoginModule to encrypt a datasource password</title>
+ <step>
+ <para>Encrypt the data source password.</para>
+ </step>
+ <step>
+ <para>Create an application authentication policy with the encrypted password.</para>
+ </step>
+ <step>
+ <para>Configure the data source to use the application authentication policy.</para>
+ </step>
+ </procedure>
+
+ <section id="sect-encrypt-data-source-password">
+ <title>Encrypt the data source password</title>
+ <para>
+ The data source password is encrypted using the <methodname>SecureIdentityLoginModule</methodname> main method by passing in the clear text password. The SecureIdentityLoginModule is provided by <filename>jbosssx.jar</filename>.
+ </para>
+
+ <procedure>
+ <title>Encrypt a datasource password</title>
+ <para>This procedure is for JBoss Enterprise Application Platform versions 5.1 and later</para>
+ <step>
+ <para>Change directory to the <filename>jboss-as</filename> directory</para>
+ </step>
+ <step>
+ <formalpara>
+ <title>Linux command</title>
+ <para><screen><command>java -cp client/jboss-logging-spi.jar:lib/jbosssx.jar org.jboss.resource.security.SecureIdentityLoginModule <replaceable>PASSWORD</replaceable></command></screen></para>
+ </formalpara>
+ <formalpara>
+ <title>Windows command:</title>
+ <para><screen><command>java -cp client\jboss-logging-spi.jar;lib\jbosssx.jar org.jboss.resource.security.SecureIdentityLoginModule <replaceable>PASSWORD</replaceable></command></screen></para>
+ </formalpara>
+ <formalpara>
+ <title>Result:</title>
+ <para>The command will return an encrypted password.</para>
+ </formalpara>
+ </step>
+ </procedure>
+ </section>
+
+ <section id="sect-create-auth-policy-datasource">
+ <title>Create an application authentication policy with the encrypted password</title>
+
+ <para>
+ Each JBoss Application Server server profile has a <filename>conf/login-config.xml</filename> file, where application authentication policies are defined for that profile. To create a an application authentication policy for your encrypted password, add a new <application-policy> element to the <policy> element.
+ </para>
+
+ <para><xref linkend="example-app-policy-encrypted-datasource"/> is a fragment of a <filename>login-config.xml</filename> file showing an application authentication policy of name "EncryptDBPassword".</para>
+
+ <example id="example-app-policy-encrypted-datasource">
+ <title>Example application authentication policy with encrypted data source password</title>
+ <programlisting language="XML">
+ <![CDATA[
+ <policy>
+ ...
+ <!-- Example usage of the SecureIdentityLoginModule -->
+ <application-policy name="EncryptDBPassword">
+ <authentication>
+ <login-module code="org.jboss.resource.security.SecureIdentityLoginModule" flag="required">
+ <module-option name="username">admin</module-option>
+ <module-option name="password">5dfc52b51bd35553df8592078de921bc</module-option>
+ <module-option name="managedConnectionFactoryName">jboss.jca:name=PostgresDS,service=LocalTxCM</module-option>
+ </login-module>
+ </authentication>
+ </application-policy>
+ </policy>]]>
+ </programlisting>
+ </example>
+
+ <variablelist>
+ <title>SecureIdentityLoginModule module options</title>
+ <varlistentry>
+ <term>username</term>
+ <listitem>
+ <para>Specify the user name to use when establishing a connection to the database.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>password</term>
+ <listitem>
+ <para>Provide the encrypted password generated in <xref linkend="sect-encrypt-data-source-password"/>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>managedConnectionFactoryName</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>jboss.jca:name</term>
+ <listitem>
+ <para>Nominate a Java Naming and Directory Interface (JNDI) name for this datasource.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>jboss.jca:service</term>
+ <listitem>
+ <para>Specify the transaction type</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <variablelist>
+ <title>Transaction types</title>
+ <!-- This info from: http://community.jboss.org/wiki/ConfigJCALoginModule -->
+ <!-- Also: http://community.jboss.org/wiki/DependOnDataSource -->
+ <varlistentry>
+ <term>NoTxCM</term>
+ <listitem>
+ <para>No transaction support</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LocalTxCM</term>
+ <listitem>
+ <para>Single resource transaction support</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TxCM</term>
+ <listitem>
+ <para>Single resource or distributed transaction support</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>XATxCM</term>
+ <listitem>
+ <para>Distributed transaction support</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Configure the data source to use the application authentication policy</title>
+
+ <para>
+ The data source is configured in a <filename>*-ds.xml</filename> file. Remove the <user-name> and <password> elements from this file, and replace them with a <security-domain> element. This element will contain the application authentication policy name specified following <xref linkend="sect-create-auth-policy-datasource"/>.
+ </para>
+
+ <para>
+ Using the example name from <xref linkend="sect-create-auth-policy-datasource"/>, "EncryptDBPassword", will result in a data source file that looks something like <xref linkend="example-datasource-with-auth-policy"/>.
+ </para>
+
+ <example id="example-datasource-with-auth-policy">
+ <title>Example data source file using secured identity</title>
+ <programlisting language="XML">
+<![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<datasources>
+ <local-tx-datasource>
+ <jndi-name>PostgresDS</jndi-name>
+ <connection-url>jdbc:postgresql://127.0.0.1:5432/test?protocolVersion=2</connection-url>
+ <driver-class>org.postgresql.Driver</driver-class>
+ <min-pool-size>1</min-pool-size>
+ <max-pool-size>20</max-pool-size>
+
+ <!-- REPLACED WITH security-domain BELOW
+ <user-name>admin</user-name>
+ <password>password</password>
+ -->
+
+ <security-domain>EncryptDBPassword</security-domain>
+
+ <metadata>
+ <type-mapping>PostgreSQL 8.0</type-mapping>
+ </metadata>
+ </local-tx-datasource>
+</datasources>]]>
+ </programlisting>
+ </example>
+ </section>
+ </section>
+
+ <section>
+ <title>Configured Identity with Password Based Encryption</title>
+
+<!--A KeyStore Based Login Module for Encrypting a Data Source Password -->
+ <para>
+ The <classname>org.jboss.resource.security.JaasSecurityDomainIdentityLoginModule</classname> is a login module for statically defining a data source using an encrypted password. that has been encrypted by a JaasSecurityDomain. The base64 format of the data source password may be generated using the PBEUtils command:
+ </para>
+ <screen><command>java -cp jbosssx.jar org.jboss.security.plugins.PBEUtils <replaceable>SALT</replaceable> <replaceable>ITERATION-COUNT</replaceable> <replaceable>DOMAIN-PASSWORD</replaceable> <replaceable>DATASOURCE-PASSWORD</replaceable></command></screen>
+ <para>
+ The commands for PBEUtils arguments are:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>SALT</term>
+ <listitem>
+ <para>
+ The Salt attribute from the JaasSecurityDomain (Must only be eight characters long).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ITERATION COUNT</term>
+ <listitem>
+ <para>The IterationCount attribute from the JaasSecurity domain.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DOMAIN-PASSWORD</term>
+ <listitem>
+ <para>The plaintext password that maps to the KeyStorePass attribute from the JaasSecurityDomain.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DATASOURCE-PASSWORD</term>
+ <listitem>
+ <para>The plaintext password for the data source that should be encrypted with the JaasSecurityDomain password.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para><xref linkend="exam-PBEUtils_Example_Command"/>
+provides an example of the command.
+ </para>
+ <example id="exam-PBEUtils_Example_Command">
+ <title>PBEUtils command example</title>
+ <screen>
+ java -cp jbosssx.jar org.jboss.security.plugins.PBEUtils abcdefgh 13 master ''
+ Encoded password: E5gtGMKcXPP
+ </screen>
+ </example>
+ <para>
+Add the following application policy to the <filename>$JBOSS_HOME/server/$PROFILE/conf/login-config.xml</filename>
+ file.</para>
+ <programlisting language="XML">
+ <![CDATA[
+<application-policy name = "EncryptedHsqlDbRealm">
+ <authentication>
+ <login-module code = "org.jboss.resource.security.JaasSecurityDomainIdentityLoginModule"
+ flag = "required">
+ <module-option name = "username">sa</module-option>
+ <module-option name = "password">E5gtGMKcXPP</module-option>
+ <module-option name = "managedConnectionFactoryName">jboss.jca:service=LocalTxCM,name=DefaultDS</module-option>
+ <module-option name = "jaasSecurityDomain">jboss.security:service=JaasSecurityDomain,domain=ServerMasterPassword</module-option>
+ </login-module>
+ </authentication>
+ </application-policy>]]>
+ </programlisting>
+ <para>
+The <filename>$JBOSS_HOME/server/$PROFILE/docs/examples/jca/hsqldb-encrypted-ds.xml</filename> illustrates that data source configuration along with the JaasSecurityDomain configuration for the keystore:
+ </para>
+ <programlisting language="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- The Hypersonic embedded database JCA connection factory config
+that illustrates the use of the JaasSecurityDomainIdentityLoginModule
+to use encrypted password in the data source configuration.
+
+$Id: hsqldb-encrypted-ds.xml,v 1.1.2.1 2004/06/04 02:20:52 starksm Exp $ -->
+
+
+<datasources>
+ <local-tx-datasource>
+
+ <!-- The jndi name of the DataSource, it is prefixed with java:/ -->
+ <!-- Datasources are not available outside the virtual machine -->
+ <jndi-name>DefaultDS</jndi-name>
+
+ <!-- for tcp connection, allowing other processes to use the hsqldb
+ database. This requires the org.jboss.jdbc.HypersonicDatabase mbean.
+ <connection-url>jdbc:hsqldb:hsql://localhost:1701</connection-url>
+ -->
+ <!-- for totally in-memory db, not saved when jboss stops.
+ The org.jboss.jdbc.HypersonicDatabase mbean necessary
+ <connection-url>jdbc:hsqldb:.</connection-url>
+ -->
+ <!-- for in-process persistent db, saved when jboss stops. The
+ org.jboss.jdbc.HypersonicDatabase mbean is necessary for properly db shutdown
+ -->
+ <connection-url>jdbc:hsqldb:${jboss.server.data.dir}${/}hypersonic${/}localDB</connection-url>
+
+ <!-- The driver class -->
+ <driver-class>org.hsqldb.jdbcDriver</driver-class>
+
+ <!--example of how to specify class that determines if exception means connection should be destroyed-->
+ <!--exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.DummyExceptionSorter</exception-sorter-class-name-->
+
+ <!-- this will be run before a managed connection is removed from the pool for use by a client-->
+ <!--<check-valid-connection-sql>select * from something</check-valid-connection-sql> -->
+
+ <!-- The minimum connections in a pool/sub-pool. Pools are lazily constructed on first use -->
+ <min-pool-size>5</min-pool-size>
+
+ <!-- The maximum connections in a pool/sub-pool -->
+ <max-pool-size>20</max-pool-size>
+
+ <!-- The time before an unused connection is destroyed -->
+ <!-- NOTE: This is the check period. It will be destroyed somewhere between 1x and 2x this timeout after last use -->
+ <!-- TEMPORARY FIX! - Disable idle connection removal, HSQLDB has a problem with not reaping threads on closed connections -->
+ <idle-timeout-minutes>0</idle-timeout-minutes>
+
+ <!-- sql to call when connection is created
+ <new-connection-sql>some arbitrary sql</new-connection-sql>
+ -->
+
+ <!-- sql to call on an existing pooled connection when it is obtained from pool
+ <check-valid-connection-sql>some arbitrary sql</check-valid-connection-sql>
+ -->
+
+ <!-- example of how to specify a class that determines a connection is valid before it is handed out from the pool
+ <valid-connection-checker-class-name>org.jboss.resource.adapter.jdbc.vendor.DummyValidConnectionChecker</valid-connection-checker-class-name>
+ -->
+
+ <!-- Whether to check all statements are closed when the connection is returned to the pool,
+ this is a debugging feature that should be turned off in production -->
+ <track-statements></track-statements>
+
+ <!-- Use the getConnection(user, pw) for logins
+ <application-managed-security></application-managed-security>
+ -->
+
+ <!-- Use the security domain defined in conf/login-config.xml -->
+ <security-domain>EncryptedHsqlDbRealm</security-domain>
+
+ <!-- This mbean can be used when using in process persistent hypersonic -->
+ <depends>jboss:service=Hypersonic,database=localDB</depends>
+
+ <!-- The datasource must depend on the mbean -->
+ <depends>jboss.security:service=JaasSecurityDomain,domain=ServerMasterPassword</depends>
+ </local-tx-datasource>
+
+ <!-- The JaasSecurityDomain used for encryption. Use the name
+ "jboss.security:service=JaasSecurityDomain,domain=ServerMasterPassword"
+ as the value of the JaasSecurityDomainIdentityLoginModule
+ jaasSecurityDomain login module option in the EncryptedHsqlDbRealm
+ login-config.xml section. Typically this service config should be in
+ the conf/jboss-service.xml descriptor.
+ The opaque master.password file could be created using:
+ java -cp jbosssx.jar org.jboss.security.plugins.FilePassword 12345678 17 master server.password
+
+ The corresponding login-config.xml would look like:
+ <application-policy name = "EncryptedHsqlDbRealm">
+ <authentication>
+ <login-module code = "org.jboss.resource.security.JaasSecurityDomainIdentityLoginModule"
+ flag = "required">
+ <module-option name = "username">sa</module-option>
+ <module-option name = "password">E5gtGMKcXPP</module-option>
+ <module-option name = "managedConnectionFactoryName">jboss.jca:service=LocalTxCM,name=DefaultDS</module-option>
+ <module-option name = "jaasSecurityDomain">jboss.security:service=JaasSecurityDomain,domain=ServerMasterPassword</module-option>
+ </login-module>
+ </authentication>
+ </application-policy>
+ where the encrypted password was generated using:
+ java -cp jbosssx.jar org.jboss.security.plugins.PBEUtils abcdefgh 13 master ''
+ Encoded password: E5gtGMKcXPP
+ -->
+ <mbean code="org.jboss.security.plugins.JaasSecurityDomain"
+ name="jboss.security:service=JaasSecurityDomain,domain=ServerMasterPassword">
+ <constructor>
+ <arg type="java.lang.String" value="ServerMasterPassword"></arg>
+ </constructor>
+ <!-- The opaque master password file used to decrypt the encrypted
+ database password key -->
+ <attribute name="KeyStorePass">{CLASS}org.jboss.security.plugins.FilePassword:${jboss.server.home.dir}/conf/server.password</attribute>
+ <attribute name="Salt">abcdefgh</attribute>
+ <attribute name="IterationCount">13</attribute>
+ </mbean>
+
+ <!-- This mbean can be used when using in process persistent db -->
+ <mbean code="org.jboss.jdbc.HypersonicDatabase"
+ name="jboss:service=Hypersonic,database=localDB">
+ <attribute name="Database">localDB</attribute>
+ <attribute name="InProcessMode">true</attribute>
+ </mbean>
+</datasources>]]>
+ </programlisting>
+
+ <warning>
+ <para>
+Remember to use the same Salt and IterationCount in the MBean that was used during the password generation step.
+ </para>
+ </warning>
+
+ <note>
+ <para>
+You may see the following error while starting a service that depends on the encrypted data source:
+ </para>
+ <programlisting>
+Caused by: java.security.InvalidAlgorithmParameterException: Parameters missing
+ at com.sun.crypto.provider.SunJCE_af.a(DashoA12275)
+ at com.sun.crypto.provider.PBEWithMD5AndDESCipher.engineInit(DashoA12275)
+ at javax.crypto.Cipher.a(DashoA12275)
+ at javax.crypto.Cipher.a(DashoA12275)
+ at javax.crypto.Cipher.init(DashoA12275)
+ at javax.crypto.Cipher.init(DashoA12275)
+ at org.jboss.security.plugins.JaasSecurityDomain.decode(JaasSecurityDomain.java:325)
+ at org.jboss.security.plugins.JaasSecurityDomain.decode64(JaasSecurityDomain.java:351)
+ at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+ at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
+ at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
+ at java.lang.reflect.Method.invoke(Method.java:585)
+ at org.jboss.mx.interceptor.ReflectedDispatcher.invoke(ReflectedDispatcher.java:155)
+ ... 139 more
+ </programlisting>
+ <para>
+The error most likely means that the following MBean is not yet started as a service:
+ </para>
+ <programlisting>
+(jboss.security:service=JaasSecurityDomain,domain=ServerMasterPassword)
+ </programlisting>
+ <para>
+ The following element should be included so that the MBean starts before the data source, as per the example <filename>hsqldb-encrypted-ds.xml</filename> code shown previously.
+ </para>
+ <programlisting>
+<depends>jboss.security:service=JaasSecurityDomain,domain=ServerMasterPassword</depends>
+ </programlisting>
+ </note>
+
+ </section>
+</chapter>
Added: projects/docs/community/6/Security_Guide/en-US/chap-Encrypting_Keystore_Password_in_Tomcat_Connector.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/chap-Encrypting_Keystore_Password_in_Tomcat_Connector.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/chap-Encrypting_Keystore_Password_in_Tomcat_Connector.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,150 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="Encrypting_The_Keystore_Password_In_Tomcat">
+ <title>Encrypting the Keystore Password in a Tomcat Connector</title>
+ <para>
+ SSL with Tomcat requires a secure connector. This means that the keystore/truststore password cannot be passed as an attribute in the connector element of Tomcat's <filename>server.xml</filename>.
+ </para>
+ <para>
+A working understanding of the JaasSecurityDomain that supports keystores, truststores, and password based encryption is advised. Please see <xref linkend="chap-Secure_Remote_Password_Protocol"/> for more information.
+ </para>
+<!--BZ 629141 jbossweb.sar replaces outdated service archive name--> <para>
+The first step is to add a connector element in <filename>server.xml</filename> in <filename>$JBOSS_HOME/server/$PROFILE/deploy/jbossweb.sar</filename>.
+ </para>
+ <programlisting language="XML">
+ <![CDATA[
+<!-- SSL/TLS Connector with encrypted keystore password configuration -->
+ <Connector protocol="HTTP/1.1" SSLEnabled="true"
+ port="8443" address="${jboss.bind.address}"
+ scheme="https" secure="true" clientAuth="false"
+ sslProtocol="TLS"
+ securityDomain="encrypt-keystore-password"
+ SSLImplementation="org.jboss.net.ssl.JBossImplementation"/> ]]>
+ </programlisting>
+ <para>
+You now need to provide the definition for the JaasSecurityDomain in a <filename>*-service.xml</filename> or in <filename>*-jboss-beans.xml</filename> in the deploy directory. Here is a MBean example:
+ </para>
+ <programlisting language="XML">
+ <![CDATA[
+<mbean code="org.jboss.security.plugins.JaasSecurityDomain"
+ name="jboss.security:service=PBESecurityDomain">
+ <constructor>
+ <arg type="java.lang.String" value="encrypt-keystore-password"></arg>
+ </constructor>
+ <attribute name="KeyStoreURL">resource:localhost.keystore</attribute>
+ <attribute name="KeyStorePass">{CLASS}org.jboss.security.plugins.FilePassword:${jboss.server.home.dir}/conf/keystore.password</attribute>
+ <attribute name="Salt">abcdefgh</attribute>
+ <attribute name="IterationCount">13</attribute>
+ </mbean>]]>
+ </programlisting>
+ <para>
+The Salt and IterationCount are the variables that define the strength of your encrypted password, so you can vary it from what is shown. Just remember to use the changed value when generating the encrypted password.
+ </para>
+ <para>
+ <note>
+ <para>
+The Salt must be eight characters long.
+ </para>
+ </note>
+ </para>
+ <para>
+Your keystore is the localhost.keystore which will be in your conf directory. The keystore.password is your encrypted password that will reside in the conf directory and will be generated in the next step.
+ </para>
+ <para>
+You now need to go to the conf directory of your JBoss AS instance (<filename>default/conf</filename>, for example).
+ </para>
+ <programlisting>
+java -cp ../lib/jbosssx.jar org.jboss.security.plugins.FilePassword abcdefgh 13 unit-tests-server keystore.password
+ </programlisting>
+ <para>
+Run this on a single line. In the above example, "abcdefgh" is the Salt and 13 is the iteration count; 'unit-tests-server' is the password of the keystore that you are protecting; and keystore.password is the file in which the encrypted password will be stored.
+ </para>
+ <para>
+You can then update the Tomcat service MBean to depend on your JaasSecurityDomain MBean because Tomcat has to start after <methodname>jboss.security:service=PBESecurityDomain</methodname>.
+ </para>
+ <para>
+Navigate to <filename>$JBOSS_HOME/server/$PROFILE/deploy/jbossweb.sar/META-INF</filename>. Open <filename>jboss-service.xml</filename> and add the following <depends> tag towards the end.
+ </para>
+ <programlisting>
+ <![CDATA[
+ <depends>jboss.security:service=PBESecurityDomain</depends>
+ </mbean>
+</server>]]>
+ </programlisting>
+ <note>
+ <para>
+ In case of a native connector the <methodname>SSLPassword</methodname> attribute can also be encrypted using a JaasSecurityDomain bean. One additional step required is to create the masked password with:
+ </para>
+ <screen><command>java -cp jbosssx.jar org.jboss.security.plugins.PBEUtils <replaceable>SALT</replaceable> <replaceable>ITERATION-COUNT</replaceable> <replaceable>DOMAIN-PASSWORD</replaceable> <replaceable>KEYSTORE-PASSWORD</replaceable></command></screen>
+ <para>
+ Using the encrypted password output given by the above command the native connector can now be set up. Here is an example:
+ </para>
+ <programlisting language="XML">
+ <![CDATA[
+<!-- SSL/TLS Connector with encrypted keystore password configuration -->
+ <Connector protocol="HTTP/1.1" SSLEnabled="true"
+ port="8443" address="${jboss.bind.address}"
+ scheme="https" secure="true" clientAuth="false"
+ SSLPassword="KAaxoMQCJH30GZWb96Mov"
+ securityDomain="encrypt-keystore-password"
+ SSLCertificateFile="server.crt"
+ SSLCertificateKeyFile="server.pem" SSLProtocol="TLSv1" /> ]]>
+ </programlisting>
+ </note>
+ <para>
+Please see <xref linkend="Encrypting_Data_Source_Passwords"/> for related information.
+ </para>
+ <section>
+ <title>Medium Security Usecase</title>
+ <para>
+A user does not want to encrypt the keystore password but wants to externalize it (outside of <filename>server.xml</filename>) or wants to make use of a predefined JaasSecurityDomain.
+ </para>
+ <procedure id="predefined_JaasSecurityDomain">
+ <title>Predefined JaasSecurityDomain</title>
+ <step>
+ <title>Update <filename>jboss-service.xml</filename> to add a connector</title>
+ <programlisting language="XML"><![CDATA[<mbean code="org.jboss.security.plugins.JaasSecurityDomain"
+ name="jboss.security:service=SecurityDomain">
+ <constructor>
+ <arg type="java.lang.String" value="jbosstest-ssl"></arg>
+ </constructor>
+ <attribute name="KeyStoreURL">resource:localhost.keystore</attribute>
+ <attribute name="KeyStorePass">unit-tests-server</attribute>
+ </mbean>]]>
+ </programlisting>
+ </step>
+ <step>
+ <title>Add a <depends> tag to the Tomcat service</title>
+ <para>Navigate to <filename>$JBOSS_HOME/server/$PROFILE/deploy/jbossweb.sar</filename>. Open <filename>server.xml</filename> and add the following <markup><depends></markup> element towards the end:
+ </para>
+ <programlisting language="XML"><![CDATA[<depends>jboss.security:service=SecurityDomain</depends>
+ </mbean>
+</server> ]]>
+ </programlisting>
+ </step>
+ <step>
+ <title>Define the JaasSecurityDomain MBean in a <filename>-service.xml</filename> file</title>
+ <para>
+<filename>security-service.xml</filename> in the deploy directory, for example.
+ </para>
+ <programlisting language="XML"><![CDATA[
+ <mbean code="org.jboss.security.plugins.JaasSecurityDomain"
+ name="jboss.security:service=SecurityDomain">
+ <constructor>
+ <arg type="java.lang.String" value="jbosstest-ssl"></arg>
+ </constructor>
+ <attribute name="KeyStoreURL">resource:localhost.keystore</attribute>
+ <attribute name="KeyStorePass">unit-tests-server</attribute>
+ </mbean>]]>
+ </programlisting>
+ </step>
+ </procedure>
+ <para>
+ <note>
+ <title>File Permission issue reading the keystore (or FileNotFoundException)</title>
+ <para>If you see this error, remember the keystore file should be writable by the user id that is running JBoss Enterprise Application Platform.
+ </para>
+ </note>
+ </para>
+ </section>
+</chapter>
Added: projects/docs/community/6/Security_Guide/en-US/chap-Firewalls.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/chap-Firewalls.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/chap-Firewalls.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,188 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="chap-Firewalls">
+ <title>Firewalls</title>
+ <para>
+ JBoss AS ships with many socket-based services that require open firewall ports. <xref linkend="table-Default_Configuration_Ports"/> lists services that listen on ports that must be activated when accessing JBoss behind a firewall. <xref linkend="Configuring_JBoss_for_use_Behind_a_Firewall-Additional_ports_in_the_all_configuration"/> lists additional ports that exist in the all profile.
+ </para>
+ <table id="table-Default_Configuration_Ports">
+ <title>The ports found in the default configuration</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colname="c1" colwidth="50px"/>
+ <colspec colnum="2" colname="c2" colwidth="50px"/>
+ <colspec colnum="3" colname="c3" colwidth="350px"/>
+ <thead>
+ <row>
+ <entry> Port </entry>
+ <entry> Type </entry>
+ <entry> Service </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>1098 </entry>
+ <entry>TCP </entry>
+ <entry>
+ <classname>org.jboss.naming.NamingService</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>1099 </entry>
+ <entry>TCP </entry>
+ <entry>
+ <classname>org.jboss.naming.NamingService</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>4444 </entry>
+ <entry>TCP </entry>
+ <entry>
+ <classname>org.jboss.invocation.jrmp.server.JRMPInvoker</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>4445 </entry>
+ <entry>TCP </entry>
+ <entry>
+ <classname>org.jboss.invocation.pooled.server.PooledInvoker</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>8009 </entry>
+ <entry>TCP </entry>
+ <entry>
+ <classname>org.jboss.web.tomcat.tc4.EmbeddedTomcatService</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>8080 </entry>
+ <entry>TCP </entry>
+ <entry>
+ <classname>org.jboss.web.tomcat.tc4.EmbeddedTomcatService</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>8083 </entry>
+ <entry>TCP </entry>
+ <entry>
+ <classname>org.jboss.web.WebService</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>8093 </entry>
+ <entry>TCP </entry>
+ <entry>
+ <classname>org.jboss.mq.il.uil2.UILServerILService</classname>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table id="Configuring_JBoss_for_use_Behind_a_Firewall-Additional_ports_in_the_all_configuration">
+ <title>Additional ports in the all configuration</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colname="c1" colwidth="50px"/>
+ <colspec colnum="2" colname="c2" colwidth="50px"/>
+ <colspec colnum="3" colname="c3" colwidth="350px"/>
+ <thead>
+ <row>
+ <entry> Port </entry>
+ <entry> Type </entry>
+ <entry> Service </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>1100 </entry>
+ <entry>TCP </entry>
+ <entry>
+ <classname>org.jboss.ha.jndi.HANamingService</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>1101 </entry>
+ <entry>TCP </entry>
+ <entry>
+ <classname>org.jboss.ha.jndi.HANamingService</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>1102 </entry>
+ <entry>UDP </entry>
+ <entry>
+ <classname>org.jboss.ha.jndi.HANamingService</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>1161 </entry>
+ <entry>UDP </entry>
+ <entry>
+ <classname>org.jboss.jmx.adaptor.snmp.agent.SnmpAgentService</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>1162 </entry>
+ <entry>UDP </entry>
+ <entry>
+ <classname>org.jboss.jmx.adaptor.snmp.trapd.TrapdService</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>1389</entry>
+ <entry>TCP</entry>
+ <entry>
+ <classname>ldaphost.jboss.org.LdapLoginModule</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>3843<footnote>
+ <para>Necessary only if SSL transport is configured for EJB3</para>
+ </footnote></entry>
+ <entry>TCP</entry>
+ <entry>
+ <classname>org.jboss.ejb3.SSLRemotingConnector</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>3528 </entry>
+ <entry>TCP </entry>
+ <entry>
+ <classname>org.jboss.invocation.iiop.IIOPInvoker</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>3873</entry>
+ <entry>TCP</entry>
+ <entry>
+ <classname>org.jboss.ejb3.RemotingConnectors</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>4447 </entry>
+ <entry>TCP </entry>
+ <entry>
+ <classname>org.jboss.invocation.jrmp.server.JRMPInvokerHA</classname>
+ </entry>
+ </row>
+ <row>
+ <entry>10099</entry>
+ <entry>RMI</entry>
+ <entry>
+ <classname>org.jboss.security.srp.SRPRemoteServerInterface</classname>
+ </entry>
+ </row>
+ <row>
+ <entry> 45566<footnote>
+ <para>
+ Plus two additional anonymous UDP ports, one can be set using the <literal>rcv_port</literal>, and the other cannot be set.
+ </para>
+ </footnote></entry>
+ <entry>UDP </entry>
+ <entry>
+ <classname>org.jboss.ha.framework.server.ClusterPartition</classname>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+</chapter>
Added: projects/docs/community/6/Security_Guide/en-US/chap-Java_EE_Security_Manager.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/chap-Java_EE_Security_Manager.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/chap-Java_EE_Security_Manager.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,262 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!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_Security_Manager">
+ <title>Java Security Manager</title>
+ <para>To restrict code privileges using Java permissions, you must configure the JBoss server to run under a security manager. This is done by configuring the Java VM options in the <filename>run.conf</filename> in the JBoss server distribution bin directory. The two required VM options are as follows:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>java.security.manager</term>
+ <listitem>
+ <para>Used without any value to specify that the default security manager should be used. This is the preferred security manager. You can also pass a value to the <literal>java.security.manager</literal> option to specify a custom security manager implementation. The value must be the fully qualified class name of a subclass of <literal>java.lang.SecurityManager</literal>. This form specifies that the policy file should augment the default security policy as configured by the VM installation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>java.security.policy</term>
+ <listitem>
+ <para>Used to specify the policy file that will augment the default security policy information for the VM. This option takes two forms: <literal>java.security.policy=policyFileURL</literal> and <literal>java.security.policy==policyFileURL</literal>. The first form specifies that the policy file should augment the default security policy as configured by the VM installation. The second form specifies that only the indicated policy file should be used. The <literal>policyFileURL</literal> value can be any URL for which a protocol handler exists, or a file path specification.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>Both the <literal>run.bat</literal> and <literal>run.sh</literal> start scripts reference a <varname>JAVA_OPTS</varname> variable specified in <filename>run.conf</filename> (Linux) or <filename>run.conf.bat</filename> (Windows) that sets the required security manager properties.
+ </para>
+ <para>The next element of Java security is establishing the allowed permissions. If you look at the <filename>$JBOSS_HOME/bin/server.policy.cert</filename> file that is contained in the default configuration file set you will notice it contains the following grant statement:
+ </para>
+ <programlisting language="Java" role="JAVA">grant signedBy "jboss" {
+ permission java.security.AllPermission;
+};
+</programlisting>
+ <para>This statement declares that all code signed by JBoss is trusted.
+ To import the public key to your keystore, follow <xref linkend="proc-Activate_Java_Security_Manager"/></para>
+ <important>
+ <para>Carefully consider what permissions you grant. Be particularly cautious about granting <option>java.security.AllPermission</option>: you can potentially allow changes to the system binary, including the JVM runtime environment.</para>
+ </important>
+ <para>The current set of JBoss specific <literal>java.lang.RuntimePermissions</literal> are described below.</para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <classname> org.jboss.security.SecurityAssociation.getPrincipalInfo</classname>
+ </term>
+ <listitem>
+ <para>Provides access to the <methodname>org.jboss.security.SecurityAssociation getPrincipal() </methodname>and <methodname>getCredential()</methodname> methods. The risk involved with using this runtime permission is the ability to see the current thread caller and credentials. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <classname>org.jboss.security.SecurityAssociation.getSubject</classname>
+ </term>
+ <listitem>
+ <para>Provides access to the <methodname>org.jboss.security.SecurityAssociation getSubject()</methodname> method. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <classname>org.jboss.security.SecurityAssociation.setPrincipalInfo</classname>
+ </term>
+ <listitem>
+ <para>Provides access to the <methodname>org.jboss.security.SecurityAssociation setPrincipal()</methodname>, <methodname>setCredential()</methodname>, <methodname>setSubject()</methodname>, <methodname>pushSubjectContext()</methodname>, and <methodname>popSubjectContext()</methodname> methods. The risk involved with using this runtime permission is the ability to set the current thread caller and credentials. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <classname> org.jboss.security.SecurityAssociation.setServer</classname>
+ </term>
+ <listitem>
+ <para>Provides access to the <methodname>org.jboss.security.SecurityAssociation setServer </methodname>method. The risk involved with using this runtime permission is the ability to enable or disable multithread storage of the caller principal and credential.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <classname> org.jboss.security.SecurityAssociation.setRunAsRole</classname>
+ </term>
+ <listitem>
+ <para>Provides access to the <methodname>org.jboss.security.SecurityAssociation pushRunAsRole</methodname> and <methodname>popRunAsRole</methodname>, <methodname>pushRunAsIdentity</methodname> and <methodname>popRunAsIdentity</methodname> methods. The risk involved with using this runtime permission is the ability to change the current caller run-as role principal. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <classname>org.jboss.security.SecurityAssociation.accessContextInfo</classname>
+ </term>
+ <listitem>
+ <para>Provides access to the <methodname>org.jboss.security.SecurityAssociation accessContextInfo, "Get"</methodname> and <methodname>accessContextInfo, "Set"</methodname> methods, allowing you to both set and get the current security context info.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <classname>org.jboss.naming.JndiPermission</classname>
+ </term>
+ <listitem>
+ <para>Provides special permissions to files and directories in a specified JNDI tree path, or recursively to all files and subdirectories. A JndiPermission consists of a pathname and a set of valid permissions related to the file or directory. </para>
+ <para>The available permissions include: <option>bind</option>, <option>rebind</option>, <option>unbind</option>, <option>lookup</option>, <option>list</option>, <option>listBindings</option>, <option>createSubcontext</option>, and <option>all</option>. </para>
+ <para>Pathnames ending in <literal>/*</literal> indicate the specified permissions apply to all files and directories of the pathname. Pathnames ending in <literal>/-</literal> indicate recursive permissions to all files and subdirectories of the pathname. Pathnames consisting of the special token <literal><<ALL BINDINGS>></literal> matches any file in any directory.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <classname>org.jboss.security.srp.SRPPermission</classname>
+ </term>
+ <listitem>
+ <para>A custom permission class for protecting access to sensitive SRP information like the private session key and private key.
+This permission doesn't have any actions defined. The <property>getSessionKey</property> target provides access to the private session key resulting from the SRP negotiation. Access to this key will allow you to encrypt and decrypt messages
+that have been encrypted with the session key.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <classname>org.hibernate.secure.HibernatePermission</classname>
+ </term>
+ <listitem>
+ <para>This permission class provides basic permissions to secure Hibernate sessions.
+The target for this property is the entity name.
+The available actions include:
+<property>insert</property>, <property>delete</property>, <property>update</property>, <property>read</property>, <property>*</property> (all).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <classname>org.jboss.metadata.spi.stack.MetaDataStackPermission</classname>
+ </term>
+ <listitem>
+ <para>Provides a custom permission class for controlling how callers interact with the metadata stack. The available permissions are: <option>modify</option> (push/pop onto the stack), <option>peek</option> (peek onto the stack), and <option>*</option> (all).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <classname>org.jboss.config.spi.ConfigurationPermission</classname>
+ </term>
+ <listitem>
+ <para>Secures setting of configuration properties.
+Defines only permission target names, and no actions.
+The targets for this property include:
+<markup><property name></markup> - property which code has permission to set;
+<property>*</property> - all properties.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <classname>org.jboss.kernel.KernelPermission</classname>
+ </term>
+ <listitem>
+ <para>Secures access to the kernel configuration.
+Defines only permission target names and no actions.
+The targets for this property include: <property>access</property> - access the kernel configuration;
+<property>configure</property> - configure the kernel (access is implied);
+<property>*</property> - all of the above.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <classname>org.jboss.kernel.plugins.util.KernelLocatorPermission</classname>
+ </term>
+ <listitem>
+ <para>Secures access to the kernel.
+Defines only permission target names and no actions.
+The targets for this property include:
+<property>kernel</property> - access the kernel;
+<property>*</property> - access all areas.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <procedure id="proc-Activate_Java_Security_Manager">
+ <title>Activate Java Security Manager</title>
+ <para>Follow this procedure to correctly configure the JSM for secure, production-ready operation. This procedure is only required while configuring your server for the first time. In this procedure, <filename>$JAVA_HOME</filename> refers to the installation directory of the JRE.</para>
+ <step>
+ <title>Import public key to keystore</title>
+ <para>Execute the following command:</para>
+ <formalpara>
+ <title>Linux</title>
+ <para><screen>[home]$ sudo $JAVA_HOME/bin/keytool -import -alias jboss -file JBossPublicKey.RSA -keystore $JAVA_HOME/jre/lib/security/cacerts</screen></para>
+ </formalpara>
+ <formalpara>
+ <title>Windows</title>
+ <para><screen>C:\> %JAVA_HOME%\bin\keytool -import -alias jboss -file JBossPublicKey.RSA -keystore %JAVA_HOME%\jre\lib\security\cacerts </screen></para>
+ </formalpara>
+ </step>
+ <step>
+ <title>Verify key signature</title>
+ <para>Execute the following command in the terminal.</para>
+ <note>
+ <para>The default JVM Keystore password is <literal>changeit</literal>. </para>
+ </note>
+ <screen>$ keytool -list -keystore $JAVA_HOME/jre/lib/security/cacerts
+Enter keystore password:
+
+Keystore type: JKS
+Keystore provider: SUN
+
+Your keystore contains 2 entries
+
+jboss, Aug 12, 2009, trustedCertEntry,
+Certificate fingerprint (MD5): 93:F2:F1:8B:EF:8A:E0:E3:D0:E7:69:BC:69:96:29:C1
+jbosscodesign2009, Aug 12, 2009, trustedCertEntry,
+Certificate fingerprint (MD5): 93:F2:F1:8B:EF:8A:E0:E3:D0:E7:69:BC:69:96:29:C1</screen>
+ </step>
+ <step>
+ <title>Specify additional JAVA_OPTS</title>
+ <formalpara>
+ <title>Linux</title>
+ <para>Ensure the following block is present in the <filename>$JBOSS_HOME/server/$PROFILE/run.conf</filename> file.</para>
+ </formalpara>
+ <programlisting>## Specify the Security Manager options
+JAVA_OPTS="$JAVA_OPTS -Djava.security.manager -Djava.security.policy==$DIRNAME/server.policy.cert
+-Djava.protocol.handler.pkgs=org.jboss.handlers.stub
+-Djava.security.debug=access:failure
+-Djboss.home.dir=$DIRNAME/../
+-Djboss.server.home.dir=$DIRNAME/../server/default/"</programlisting>
+ <note>
+ <para>Placing <filename>run.conf</filename> into the target profile directory will mean the file overrides any other <filename>run.conf</filename> files outside server profiles.</para>
+ </note>
+ <formalpara>
+ <title>Windows</title>
+ <para>Ensure the following block is present in the <filename>$JBOSS_HOME\bin\run.conf.bat</filename> file.</para>
+ </formalpara>
+ <programlisting>rem # Specify the Security Manager options
+set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.manager
+-Djava.security.policy==%DIRNAME%\server.policy.cert
+-Djava.protocol.handler.pkgs=org.jboss.handlers.stub
+-Djava.security.debug=access:failure
+-Djboss.home.dir=%DIRNAME%/../
+-Djboss.server.home.dir=%DIRNAME%/../server/default/"</programlisting>
+ </step>
+ <step>
+ <title>Start the server</title>
+ <para>Start JBoss using the <filename>run.sh</filename> or <filename>run.bat</filename> (Windows) script.</para>
+ </step>
+ </procedure>
+ <para>A number of Java debugging flags are available to assist you in determining how the security manager is using your security policy file, and what policy files are contributing permissions. Running the VM as follows shows the possible debugging flag settings:
+ </para>
+ <screen>[bin]$ java -Djava.security.debug=help
+
+all turn on all debugging
+access print all checkPermission results
+combiner SubjectDomainCombiner debugging
+configfile JAAS ConfigFile loading
+configparser JAAS ConfigFile parsing
+gssloginconfig GSS LoginConfigImpl debugging
+jar jar verification
+logincontext login context results
+policy loading and granting
+provider security provider debugging
+scl permissions SecureClassLoader assigns
+
+The following can be used with access:
+
+stack include stack trace
+domain dump all domains in context
+failure before throwing exception, dump stack
+ and domain that didn't have permission
+
+The following can be used with stack and domain:
+
+permission=<classname>
+ only dump output if specified permission
+ is being checked
+codebase=<URL>
+ only dump output if specified codebase
+ is being checked
+</screen>
+ <para>Running with <literal>-Djava.security.debug=all</literal> provides the most output, but the output volume is acutely verbose. This might be a good place to start if you don't understand a given security failure at all. For less verbose output that will still assist with debugging permission failures, use <literal>-Djava.security.debug=access,failure</literal>.
+ </para>
+</chapter>
Added: projects/docs/community/6/Security_Guide/en-US/chap-Masking_Passwords.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/chap-Masking_Passwords.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/chap-Masking_Passwords.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,331 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<!-- Author: Joshua Wulf -->
+<!-- Author email: jwulf at redhat.com -->
+
+<!-- SME: Marcus Moyses <mmoyses at redhat.com> -->
+
+<!-- Verified by: Marcus Moyses <mmoyses at redhat.com> -->
+<!-- Verified on: 9 Sep 2010 -->
+
+<!-- License: CC-SA-BY -->
+<!-- Contains content from: Anil Saldhana http://community.jboss.org/wiki/maskingpasswordsinjbossasxmlconfiguration -->
+
+<chapter id="Masking_Passwords">
+ <title>Masking Passwords in XML Configuration</title>
+
+ <para>
+ Follow the instructions in this chapter to increase the security of your JBoss AS Installation by masking passwords that would otherwise be stored on the file system as clear text.
+ </para>
+
+ <section>
+ <title>Password Masking Overview</title>
+ <para>
+ Passwords are secret authentication tokens that are used to limit access to resources to authorised parties only. In order for JBoss services to access password protected resources, the password must be made available to the JBoss service. This can be done by means of command line arguments passed to the JBoss Application Server on start up, however this is not practical in a production environment. In production environments, typically, passwords are made available to JBoss services by their inclusion in configuration files.
+ </para>
+ <para>
+ All JBoss configuration files should be stored on secure file systems, and should be readable by the JBoss Application Server process owner only. Additionally, you can mask the password in the configuration file for an added level of security. Follow the instructions in this chapter to replace a clear text password in a Microcontainer bean configuration with a password mask. Refer to <xref linkend="Encrypting_Data_Source_Passwords"/> for instructions on encrypting Data Source passwords; to <xref linkend="Encrypting_The_Keystore_Password_In_Tomcat"/> for instructions on encrypting the key store password in Tomcat; and to <xref linkend="Using_LdapExtLoginModule_with_JaasSecurityDomain"/> for instructions on encrypting the password for LdapExtLoginModule.
+ </para>
+
+ <note>
+ <para>There is no such thing as impenetrable security. All good security measures merely increase the cost involved in unauthorised access of a system. Masking passwords is no exception - it is not impenetrable, but does defeat casual inspection of configuration files, and increases the amount of effort that will be required to extract the password in clear text.
+ </para>
+ </note>
+
+ <procedure>
+ <title>Masking a clear text password overview</title>
+ <step>
+ <para>
+ Generate a key pair to use to encrypt passwords.
+ </para>
+ </step>
+ <step>
+ <para>
+ Encrypt the key store password.
+ </para>
+ </step>
+ <step>
+ <para>
+ Create password masks.
+ </para>
+ </step>
+ <step>
+ <para>
+ Replace clear text passwords with their password masks.
+ </para>
+ </step>
+ </procedure>
+ </section>
+
+ <section>
+ <title>
+ Generate a key store and a masked password
+ </title>
+
+ <formalpara>
+ <title>Generate a key store</title>
+
+ <para>
+ Password masking uses a public/private key pair to encrypt passwords. You need to generate a key pair for use in password masking. By default JBoss Enterprise Application Platform 5 expects a key pair with the alias <filename>jboss</filename> in a key store at <filename>jboss-as/bin/password/password.keystore</filename>. The following procedures follow this default configuration. If you wish to change the key store location or key alias you will need to change the default configuration, and should refer to <xref linkend="sect-changing-password-masking-keystore"/> for instructions.
+ </para>
+ </formalpara>
+
+ <procedure id="proc-generate-keystore">
+ <title>Generate a key pair and key store for password masking</title>
+ <step>
+ <para>
+ At the command line, change directory to the <filename>jboss-as/bin/password</filename> directory.
+ </para>
+ </step>
+ <step>
+ <para>Use <command>keytool</command> to generate the key pair with the following command:</para>
+ <screen><command>keytool -genkey -alias jboss -keyalg RSA -keysize 1024 -keystore password.keystore</command></screen>
+ <formalpara>
+ <title>Important:</title>
+ <para>You must specify the same password for the key store and key pair</para>
+ </formalpara>
+ </step>
+ <step>
+ <formalpara>
+ <title>Optional:</title>
+ <para>Make the resulting password.keystore readable by the JBoss Application Server process owner only.</para>
+ </formalpara>
+ <para>On Unix-based systems this is accomplished by using the <command>chown</command> command to change ownership to the JBoss Application Server process owner, and <command>chmod 600 password.keystore</command> to make the file readable only by the owner.</para>
+ <para>This step is recommended to increase the security of your server.</para>
+ <para>
+ Note: the JBoss Application Server process owner should not have interactive console login access. In that case you will be performing these operations as another user. Creating masked passwords requires read access to the key store, so you may wish to complete configuration of masked passwords before restricting the key store file permissions.
+ </para>
+ </step>
+ </procedure>
+
+ <para>For more on key stores and the <command>keytool</command> command, refer to <xref linkend="sect-keystore-background"/>.</para>
+
+ </section>
+
+ <section id="sect-encrypt-key-store-password">
+ <title>Encrypt the key store password</title>
+
+ <para>
+ With password masking, passwords needed by Jboss services are not stored in clear text in xml configuration files. Instead they are stored in a file that is encrypted using a key pair that you provide.
+ </para>
+
+ <para>
+ In order to decrypt this file and access the masked passwords at run time, JBoss Application Server needs to be able to use the key pair you created. You provide the key store password to JBoss Application Server by means of the JBoss Password Tool, <command>password_tool</command>. This tool will encrypt and store your key store password. Your key store password will then be available to the JBoss Password Tool for masking passwords, and to the JBoss Application Server for decrypting them at run time.
+ </para>
+
+ <procedure id="proc-encrypt-key-store-password">
+ <title>Encrypt the key store password</title>
+ <step>
+ <para>At the command line, change to the <filename>jboss-as/bin</filename> directory.</para>
+ </step>
+ <step>
+ <para>Run the password tool, using the command <command>./password_tool.sh</command> for Unix-based systems, or <command>password_tool.bat</command> for Windows-based systems.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The JBoss Password Tool will start, and will report '<command>Keystore is null. Please specify keystore below:</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Select '<command>0: Encrypt Keystore Password</command>' by pressing 0, then Enter.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool responds with '<command>Enter keystore password</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Enter the key store password you specified in <xref linkend="proc-generate-keystore"/>.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool responds with '<command>Enter Salt (String should be at least 8 characters)</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Enter a random string of characters to aid with encryption strength.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool responds with '<command>Enter Iterator Count (integer value)</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Enter a whole number to aid with encryption strength.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool responds with: '<command>Keystore Password encrypted into password/jboss_keystore_pass.dat</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Select '<command>5:Exit</command>' to exit.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool will exit with the message: '<command>Keystore is null. Cannot store.</command>'. This is normal.</para>
+ </formalpara>
+ </step>
+ <step>
+ <formalpara>
+ <title>Optional:</title>
+ <para>Make the resulting file <filename>password/jboss_keystore_pass.dat</filename> readable by the JBoss Application Server process owner only.</para>
+ </formalpara>
+ <para>On Unix-based systems this is accomplished by using the <command>chown</command> command to change ownership to the JBoss Application Server process owner, and <command>chmod 600 jboss-keystore_pass.dat</command> to make the file readable only by the owner.</para>
+ <para>This step is recommended to increase the security of your server. Be aware that if this encrypted key is compromised, the security offered by password masking is significantly reduced. This file should be stored on a secure file system.</para>
+ <para>
+ Note: the JBoss Application Server process owner should not have interactive console login access. In this case you will be performing these operations as another user. Creating masked passwords requires read access to the key store, so you may wish to complete configuration of masked passwords before restricting the key store file permissions.
+ </para>
+ </step>
+ </procedure>
+
+ <formalpara>
+ <title>Note:</title>
+ <para>
+ You should only perform this key store password encryption procedure once. If you make a mistake entering the keystore password, or you change the key store at a later date, you should delete the <filename>jboss-keystore_pass.dat</filename> file and repeat the procedure. Be aware that if you change the key store any masked passwords that were previously generated will no longer function.
+ </para>
+ </formalpara>
+ </section>
+
+ <section>
+ <title>Create password masks</title>
+
+<!-- I opened https://jira.jboss.org/browse/JBPAPP-5046 about this - we need conceptual consistency here.
+You create a password mask using the password_tool.
+The password mask is then placed into the configuration file instead of the clear text password.
+
+At the moment the terminology in the tool is a mix of "passwords" and "domains". And "mask" and the idea of "masking" is not really used as a metaphor except in the chapter title. It's a mixed bag of metaphors that needs to be thinned out.
+
+To introduce the concepts we should stick to the masking metaphor, and introduce domains when we get to bean annotation, where we can just say: "put the password mask in as the value of the Securitydomain". Done. :-)
+-->
+
+ <para>
+ The JBoss Password Tool maintains an encrypted password file <filename>jboss-as/bin/password/jboss_password_enc.dat</filename>. This file is encrypted using a key pair you provide to the password tool, and it contains the passwords that will be masked in configuration files. Passwords are stored and retrieved from this file by 'domain', an arbitrary unique identifier that you specify to the Password Tool when storing the password, and that you specify as part of the annotation that replaces that clear text password in configuration files. This allows the JBoss Application Server to retrieve the correct password from the file at run time.
+ </para>
+
+ <formalpara>
+ <title>Note:</title>
+ <para>If you previously made the key store and encrypted key store password file readable only by the JBoss Application Server process owner, then you need to perform the following procedure as the JBoss Application Server process owner, or else make the keystore (<filename>jboss-as/bin/password/password.keystore</filename>) and encrypted key store password file (<filename>jboss-as/bin/password/jboss_keystore_pass.dat</filename>) readable by your user, and the encrypted passwords file <filename>jboss-as/bin/password/jboss_password_enc.dat</filename> (if it already exists) read and writeable, while you perform this operation.</para>
+ </formalpara>
+
+ <procedure id="proc-create-password-masks">
+ <title>Create password masks</title>
+ <itemizedlist>
+ <title>Prerequisites:</title>
+ <listitem>
+ <para>
+ <xref linkend="proc-generate-keystore"/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref linkend="proc-encrypt-key-store-password"/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <step>
+ <para>At the command line, change to the <filename>jboss-as/bin</filename> directory.</para>
+ </step>
+ <step>
+ <para>Run the password tool, using the command <command>./password_tool.sh</command> for Unix-based systems, or <command>password_tool.bat</command> for Windows-based systems.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The JBoss Password Tool will start, and will report '<command>Keystore is null. Please specify keystore below:</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Select '<command>1:Specify KeyStore</command>' by pressing 1 then Enter.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool responds with '<command>Enter Keystore location including the file name</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Enter the path to the key store you created in <xref linkend="proc-generate-keystore"/>. You can specify an absolute path, or the path relative to <filename>jboss-as/bin</filename>. This should be <filename>password/password.keystore</filename>, unless you have performed an advanced installation and changed the defaults as per <xref linkend="sect-changing-password-masking-keystore"/>.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool responds with '<command>Enter Keystore alias</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Enter the key alias. This should be <classname>jboss</classname>, unless you have performed an advanced installation and changed the defaults as per <xref linkend="sect-changing-password-masking-keystore"/>. </para>
+ <formalpara>
+ <title>Result:</title>
+ <para>If the key store and key alias are accessible, the password tool will respond with some log4j WARNING messages, then the line '<command>Loading domains [</command>', followed by any existing password masks, and the main menu.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>
+ Select '<command>2:Create Password</command>' by pressing 2, then Enter
+ </para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The password tool responds with: '<command>Enter security domain:</command>'.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>
+ Enter a name for the password mask. This is an arbitrary unique name that you will use to identify the password mask in configuration files.
+ </para>
+ <formalpara>
+ <title>Result:</title>
+ <para>
+ The password tool responds with: '<command>Enter passwd:</command>'.
+ </para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Enter the password that you wish to mask.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>
+ The password tool responds with: '<command>Password created for domain:<replaceable>mask name</replaceable></command>'
+ </para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Repeat the password mask creation process to create masks for all passwords you wish to mask.</para>
+ </step>
+ <step>
+ <para>Exit the program by choosing '<command>5:Exit</command>'</para>
+ </step>
+ </procedure>
+ </section>
+
+ <section>
+ <title>Replace clear text passwords with their password masks</title>
+
+ <para>
+ Clear text passwords in xml configuration files can be replaced with password masks by changing the property assignment for an annotation. Generate password masks for any clear text password that you wish to mask in Microcontainer bean configuration files by following <xref linkend="proc-create-password-masks"/>. Then replace the configuration occurrence of each clear text password with an annotation referencing its mask.
+ </para>
+
+ <para>The general form of the annotation is:</para>
+
+ <example>
+ <title>General form of password mask annotation</title>
+ <screen><annotation>@org.jboss.security.integration.password.Password(securityDomain=<replaceable>MASK_NAME</replaceable>,methodName=set<replaceable>PROPERTY_NAME</replaceable>)</annotation></screen>
+ </example>
+
+ </section>
+
+ <section id="sect-changing-password-masking-keystore">
+ <title>Changing the password masking defaults</title>
+
+ <para>
+ JBoss Enterprise Application Platform 5 ships with server profiles preconfigured for password masking. By default the server profiles are configured to use the keystore <filename>jboss-as/bin/password/password.keystore</filename>, and the key alias <filename>jboss</filename>. If you store the key pair used for password masking elsewhere, or under a different alias, you will need to update the server profiles with the new location or key alias.
+ </para>
+
+ <para>
+ The password masking key store location and key alias is specified in the file <filename>deploy/security/security-jboss-beans.xml</filename> under each of the included JBoss Application Server server profiles.
+ </para>
+
+ <example>
+ <title>Preconfigured Password Masking defaults in security-jboss-beans.xml</title>
+ <screen><![CDATA[<!-- Password Mask Management Bean-->
+ <bean name="JBossSecurityPasswordMaskManagement"
+ class="org.jboss.security.integration.password.PasswordMaskManagement" >
+ <property name="keyStoreLocation">password/password.keystore</property>
+ <property name="keyStoreAlias">jboss</property>
+ <property name="passwordEncryptedFileName">password/jboss_password_enc.dat</property>
+ <property name="keyStorePasswordEncryptedFileName">password/jboss_keystore_pass.dat</property>
+ </bean>]]>
+ </screen>
+ </example>
+ </section>
+
+</chapter>
Added: projects/docs/community/6/Security_Guide/en-US/chap-Overridding_SSL_Configuration.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/chap-Overridding_SSL_Configuration.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/chap-Overridding_SSL_Configuration.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,105 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="chap-Overridding_SSL_Configuration">
+ <title>Overriding SSL Configuration</title>
+ <para>
+ Many services in JBoss allow usage of SSL for secure communication. To configure SSL, these services require a <emphasis>KeyStore</emphasis> for the certificate and private key and possibly a <emphasis>TrustStore</emphasis> with the trusted client certificates. Those attributes can be configured using the JDK system properties (<methodname>javax.net.ssl.keyStore</methodname>, <methodname>javax.net.ssl.keyStorePassword</methodname>, <methodname>javax.net.ssl.trustStore</methodname>, <methodname>javax.net.ssl.trustStorePassword</methodname>) or by a service specific set of attributes.
+ </para>
+
+ <para>
+ There can be situations when the AS as a whole should be using just one keystore and truststore for all the services, essentially ignoring all the system properties and service's specific configurations.
+ </para>
+
+ <para>
+ Starting in JBoss AS 6 there is a new service that can be installed at bootstrap that can override all the configuration for the <emphasis>KeyStore</emphasis> and <emphasis>TrustStore</emphasis>, provided that the service uses the default algorithm for the <classname>KeyManagerFactory</classname> (<methodname>SunX509</methodname> for Sun, JRockit and OpenJDK and <methodname>IbmX509</methodname> for IBM) and <classname>TrustManagerFactory</classname> (<methodname>PKIX</methodname> for Sun, JRockit, OpenJDK and IBM).
+ </para>
+
+ <para>
+ Here is an example configuration for the service in <filename>conf/bootstrap/security.xml</filename>:
+ </para>
+
+ <programlisting><?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Security bootstrap configuration
+-->
+<deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ ...
+
+ <bean name="JBossSSLConfiguration" class="org.jboss.security.ssl.JBossSSLConfiguration">
+ <property name="keyStoreURL">my.keystore</property>
+ <property name="keyStorePassword">changeit</property>
+ </bean>
+</deployment>
+ </programlisting>
+
+ <para>
+ With this service in place, the <methodname>keystoreFile</methodname> and <methodname>keystorePass</methodname> attributes of a HTTPS connector in <filename>deploy/jbossweb.sar/server.xml</filename> would be overridden for example.
+ </para>
+
+ <para>
+ These are the properties the JBossSSLConfiguration bean accepts:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <methodname>keyStoreURL</methodname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>keyStorePassword</methodname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>keyStoreAlias</methodname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>keyStoreProvider</methodname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>keyStoreProviderArgument</methodname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>trustStoreURL</methodname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>trustStorePassword</methodname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>trustStoreProvider</methodname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <methodname>trustStoreProviderArgument</methodname>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ These properties are the same as the ones in the <classname>JaasSecurityDomain</classname> bean. See <xref linkend="The_JBoss_Security_Extension_Architecture-The_JaasSecurityDomain_Bean"/> for a detailed description.
+ </para>
+
+ <para>
+ The <methodname>keyStorePassword</methodname> can be masked using the same methods described for the <methodname>keyStorePass</methodname>.
+ </para>
+
+ <note>
+ <para>
+ There is still no support for using the Password annotation (shown in <xref linkend="Masking_Passwords"/>) to mask those passwords as the <classname>PasswordMaskManagement</classname> bean is started much later in the boot process.
+ </para>
+ </note>
+</chapter>
Added: projects/docs/community/6/Security_Guide/en-US/chap-Secure_Remote_Password_Protocol.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/chap-Secure_Remote_Password_Protocol.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/chap-Secure_Remote_Password_Protocol.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,230 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="chap-Secure_Remote_Password_Protocol">
+ <title>Secure Remote Password Protocol</title>
+ <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>
+ <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>
+ </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>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 encrypt 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:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ An implementation of the SRP handshake protocol that is independent of any particular client/server protocol
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ An RMI implementation of the handshake protocol as the default client/server SRP implementation
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A client side JAAS <literal>LoginModule</literal> implementation that uses the RMI implementation for use in authenticating clients in a secure fashion
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A JMX MBean for managing the RMI server implementation. The MBean allows the RMI server implementation to be plugged into a JMX framework and externalizes the configuration of the verification information store. It also establishes an authentication cache that is bound into the JBoss server JNDI namespace.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A server side JAAS <literal>LoginModule</literal> implementation that uses the authentication cache managed by the SRP JMX MBean.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <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>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/j2ee_chap8-13.jpg"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>On the client side, SRP shows up as a custom JAAS <literal>LoginModule</literal> implementation that communicates with 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>
+ <variablelist>
+ <varlistentry>
+ <term>principalClassName</term>
+ <listitem>
+ <para>Constant value, set to <literal>org.jboss.security.srp.jaas.SRPPrincipal</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>srpServerJndiName</term>
+ <listitem>
+ <para> JNDI name of the <literal>SRPServerInterface</literal> object used to communicate with the SRP authentication server. If both <literal>srpServerJndiName</literal> and <literal>srpServerRmiUrl</literal> options are specified, <literal>srpServerJndiName</literal> takes priority over <literal>srpServerRmiUrl</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>srpServerRmiUrl</term>
+ <listitem>
+ <para> RMI protocol URL string for the location of the <literal>SRPServerInterface</literal> proxy used to communicate with the SRP authentication server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>externalRandomA</term>
+ <listitem>
+ <para>Flag that specifies whether 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. If set to <literal>true</literal>, the feature is activated. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>hasAuxChallenge</term>
+ <listitem>
+ <para>Flag that specifies whether 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>. If set to <literal>true</literal>, the feature is activated. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>multipleSessions</term>
+ <listitem>
+ <para>Flag that specifies whether a given client may have multiple SRP login sessions active.
+ If set to <literal>true</literal>, the feature is activated.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>Any other passed options that do not match one of the previously named options are 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> and the standard <literal>ClientLoginModule</literal> must be configured to allow SRP authentication credentials to be used for access validation to security Java EE components. An example login configuration is described in <xref linkend="exam-Login_Configuration_Entry"/>.</para>
+ <example id="exam-Login_Configuration_Entry">
+ <title>Login Configuration Entry</title>
+ <programlisting>srp {
+ org.jboss.security.srp.jaas.SRPLoginModule required
+ srpServerJndiName="SRPServerInterface"
+ ;
+
+ org.jboss.security.ClientLoginModule required
+ password-stacking="useFirstPass"
+ ;
+};
+</programlisting>
+ </example>
+ <para>
+ On the JBoss server side, there are two MBeans that manage the objects that collectively make up the SRP server. The primary service is the <literal>org.jboss.security.srp.SRPService</literal> MBean. The other MBean is<classname>org.jboss.security.srp.SRPVerifierStoreService</classname>.</para>
+ <para><literal>org.jboss.security.srp.SRPService</literal> is responsible for exposing an RMI accessible version of the SRPServerInterface as well as updating the SRP authentication session cache. </para>
+ <para>The configurable SRPService MBean attributes include the following:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>JndiName</term>
+ <listitem>
+ <para>Specifies the name from which the SRPServerInterface proxy should be available. This is the location where the <literal>SRPService</literal> binds the serializable dynamic proxy to the <literal>SRPServerInterface</literal>. The default value is <literal>srp/SRPServerInterface</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>VerifierSourceJndiName</term>
+ <listitem>
+ <para>Specifies the name of the <literal>SRPVerifierSource</literal> implementation the <literal>SRPService</literal> must use. The source JNDI name defaults to <literal>srp/DefaultVerifierSource</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>AuthenticationCacheJndiName</term>
+ <listitem>
+ <para>Specifies the name under which the <literal>org.jboss.util.CachePolicy</literal> authentication implementation used for caching authentication information is bound. The SRP session cache is made available for use through this binding. The authentication JNDI cache defaults to <literal>srp/AuthenticationCache</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ServerPort</term>
+ <listitem>
+ <para>
+ RMI port for the <literal>SRPRemoteServerInterface</literal>. The default value is 10099.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ClientSocketFactory</term>
+ <listitem>
+ <para>Optional custom <literal>java.rmi.server.RMIClientSocketFactory</literal> implementation class name used during the export of the <literal>SRPServerInterface</literal>. The default value is <literal>RMIClientSocketFactory</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ServerSocketFactory</term>
+ <listitem>
+ <para>Optional custom <literal>java.rmi.server.RMIServerSocketFactory</literal> implementation class name used during the export of the <literal>SRPServerInterface</literal>. The default value is <literal>RMIServerSocketFactory</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>AuthenticationCacheTimeout</term>
+ <listitem>
+ <para>Cache policy timeout (in seconds). The default value is 1800 (30 minutes).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>AuthenticationCacheResolution</term>
+ <listitem>
+ <para>Specifies the timed cache policy resolution (in seconds). This controls the interval between checks for timeouts. The default value is 60 (1 minute).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>RequireAuxChallenge</term>
+ <listitem>
+ <para>Set if the client must supply an auxiliary challenge as part of the verify phase. This gives control over whether the <literal>SRPLoginModule</literal> configuration used by the client must have the <literal>useAuxChallenge</literal> option enabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>OverwriteSessions</term>
+ <listitem>
+ <para>Specifies whether a successful user authentication for an existing session should overwrite the current session. This controls the behavior of the server SRP session cache when clients have not enabled the multiple session per user mode. If set to <literal>false</literal>, the second user authentication attempt will succeed, however the resulting SRP session will not overwrite the previous SRP session state.
+ The default value is <literal>false</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>VerifierStoreJndiName</term>
+ <listitem>
+ <para>Specifies the location of the SRP password information store implementation that must be provided and made available through JNDI. </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para><classname>org.jboss.security.srp.SRPVerifierStoreService</classname> is an example MBean service that binds an implementation of the <literal>SRPVerifierStore</literal> interface that uses a file of serialized objects as the persistent store. Although not realistic for a production environment, it does allow for testing of the SRP protocol and provides an example of the requirements for an <literal>SRPVerifierStore</literal> service. </para>
+ <para>The configurable <literal>SRPVerifierStoreService</literal> MBean attributes include the following:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>JndiName</term>
+ <listitem>
+ <para>JNDI name from which the <literal>SRPVerifierStore</literal> implementation should be available. If not specified it defaults to <literal>srp/DefaultVerifierSource</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>StoreFile</term>
+ <listitem>
+ <para>Location of the user password verifier serialized object store file. This can be either a URL or a resource name to be found in the classpath. If not specified it defaults to <literal>SRPVerifierStore.ser</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ The <literal>SRPVerifierStoreService</literal> MBean also supports <parameter>addUser</parameter> and <parameter>delUser</parameter> operations for addition and deletion of users. The signatures are:
+ </para>
+ <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"/>.
+ </para>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="sect-Understanding_The_Algorithm.xml" encoding="UTF-8"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="sect-Configure_Secure_Remote_Password_Information.xml" encoding="UTF-8"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="sect-Secure_Remote_Password_Example.xml" encoding="UTF-8"/>
+</chapter>
Added: projects/docs/community/6/Security_Guide/en-US/chap-Secure_Socket_Layer.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/chap-Secure_Socket_Layer.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/chap-Secure_Socket_Layer.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,380 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="chap-Secure_Socket_Layer">
+ <title>
+ Encrypting EJB connections with SSL
+ </title>
+
+<!-- Information for this chapter was gleaned from:
+http://community.jboss.org/wiki/SSLEJB21
+https://jira.jboss.org/browse/JBPAPP-442
+http://docs.jboss.org/jbossremoting/docs/guide/2.5/html/chapter-configuration.html#d0e4876
+
+Anil Saldhana, JBoss Security SME, contributed content
+Carlo de Wolf, JBoss EJB3 SME, gave input
+Bela Ban, JBoss Remoting SME, would also be an appropriate contact for some questions
+-->
+
+ <para>
+ JBoss Application Server uses a socket-based invoker layer for Remote Method Invocation (RMI) of EJB2 and EJB3 Beans. This network traffic is not encrypted by default. Follow the instructions in this chapter to use Secure Sockets Layer (SSL) to encrypt this network traffic.
+ </para>
+
+ <procedure>
+ <title>Configure SSL for EJB3 Overview</title>
+ <step>
+ <para>Generate encryption keys and certificate</para>
+ </step>
+ <step>
+ <para>Configure a secure remote connector</para>
+ </step>
+ <step>
+ <para>
+ Annotate EJB3 beans that will use the secure connector
+ </para>
+ </step>
+ </procedure>
+
+ <procedure>
+ <title>Configure SSL for EJB2 Overview</title>
+ <step>
+ <para>Generate encryption keys and certificate</para>
+ </step>
+ <step>
+ <para>Configure Unified Invoker for SSL
+ </para>
+ </step>
+ </procedure>
+
+
+ <section id="sect-keystore-background">
+ <title>SSL Encryption overview</title>
+
+ <section>
+ <title>Key pairs and Certificates</title>
+
+ <para>Secure Sockets Layer (SSL) encrypts network traffic between two systems. Traffic between the two systems is encrypted using a two-way key, generated during the <firstterm>handshake</firstterm> phase of the connection and known only by those two systems.
+ </para>
+ <para>
+ For secure exchange of the two-way encryption key, SSL makes use of Public Key Infrastructure (PKI), a method of encryption that utilizes a <firstterm>key pair</firstterm>. A key pair consists of two separate but matching cryptographic keys - a public key and a private key. The public key is shared with others and is used to encrypt data, and the private key is kept secret and is used to decrypt data that has been encrypted using the public key. When a client requests a secure connection a handshake phase takes place before secure communication can begin. During the SSL handshake the server passes its public key to the client in the form of a certificate. The certificate contains the identity of the server (its URL), the public key of the server, and a digital signature that validates the certificate. The client then validates the certificate and makes a decision about whether the certificate is trusted or not. If the certificate is trusted, the client generates the!
two-way encryption key for the SSL connection, encrypts it using the public key of the server, and sends it back to the server. The server decrypts the two-way encryption key, using its private key, and further communication between the two machines over this connection is encrypted using the two-way encryption key.
+ </para>
+
+ <para>
+ On the server, public/private key pairs are stored in a <firstterm>key store</firstterm>, an encrypted file that stores key pairs and trusted certificates. Each key pair within the key store is identified by an <firstterm>alias</firstterm> - a unique name that is used when storing or requesting a key pair from the key store. The public key is distributed to clients in the form of a <firstterm>certificate</firstterm>, a digital signature which binds together a public key and an identity. On the client, certificates of known validity are kept in the default key store known as a <firstterm>trust store</firstterm>.
+ </para>
+
+ <formalpara>
+ <title>CA-signed and self-signed certificates</title>
+
+ <para>Public Key Infrastructure relies on a chain of trust to establish the credentials of unknown machines. The use of public keys not only encrypts traffic between machines, but also functions to establish the identity of the machine at the other end of a network connection. A "Web of Trust" is used to verify the identity of servers. A server may be unknown to you, but if its public key is signed by someone that you trust, you extend that trust to the server. Certificate Authorities are commercial entities who verify the identity of customers and issue them signed certificates. The JDK includes a <filename>cacerts</filename> file with the certificates of several trusted Certificate Authorities (CAs). Any keys signed by these CAs will be automatically trusted. Large organizations may have their own internal Certificate Authority, for example using Red Hat Certificate System. In this case the signing certificate of the internal Certificate Authority is typically ins!
talled on clients as part of a Corporate Standard Build, and then all certificates signed with that certificate are trusted. CA-signed certificates are best practice for production scenarios.
+ </para>
+ </formalpara>
+
+ <para>
+ During development and testing, or for small-scale or internal-only production scenarios, you may use a <firstterm>self-signed certificate</firstterm>. This is certificate that is not signed by a Certificate Authority, but rather with a locally generated certificate. Since a locally generated certificate is not in the <filename>cacerts</filename> file of clients, you need to export a certificate for that key on the server, and import that certificate on any client that will connect via SSL.
+ </para>
+
+ <para>
+ The JDK includes <filename>keytool</filename>, a command line tool for generating key pairs and certificates. The certificates generated by <filename>keytool</filename> can be sent for signing by a CA or can be distributed to clients as a self-signed certificate.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Generating a self-signed certificate for development use and importing that certificate to a client is described in <xref linkend="sect-generate-self-signed-cert"/>.
+ </para>
+ </listitem>
+<!-- * Generating a certificate with keytool and having it signed by a CA is described in Procedure .-->
+ <listitem>
+ <para>Generating a certificate and having it signed by a CA for production use is beyond the scope of this edition. Refer to the manpage for keytool for further information on performing this task.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ <section id="sect-generate-keys-and-cert">
+ <title>Generate encryption keys and certificate</title>
+
+ <section id="sect-generate-self-signed-cert">
+ <title>Generate a self-signed certificate with keytool</title>
+
+ <section>
+ <title>Generate a keypair</title>
+
+ <para>
+ The <application>keytool</application> command, part of the JDK, is used to generate a new key pair. Keytool can either add the new key pair to an existing key store, or create a new key store at the same time as the key pair.
+ </para>
+
+ <para>
+ This key pair will be used to negotiate SSL encryption between the server and remote clients. The following procedure generates a key pair and stores it in a key store called <filename>localhost.keystore</filename>. You will need to make this key store available to the EJB3 invoker on the server. The key pair in our example will be saved in the key store under the alias 'ejb-ssl'. We will need this key alias, and the key pair password you supply (if any), when configuring the EJB3 Remoting connector in <xref linkend="sect-create-ejb3-remoting-connector"/>.
+ </para>
+
+ <procedure id="proc-generate-new-key-pair">
+ <title>Generate a new key pair and add it to the key store "localhost.keystore"</title>
+ <step>
+ <para>In your home directory, issue the following command, substituting a new password for <replaceable>EJB-SSL_KEYPAIR_PASSWORD</replaceable>:</para>
+ <screen><command>keytool -genkey -alias ejb-ssl -keypass <replaceable>EJB-SSL_KEYPAIR_PASSWORD</replaceable> -keystore localhost.keystore</command></screen>
+ </step>
+ <step>
+ <para>
+ Enter the key store password, if this key store already exists; otherwise enter and re-enter a password for a new key store that will be created.
+ </para>
+ </step>
+ <step>
+ <para>Issue the command:</para>
+ <screen><command>dir</command></screen>
+ <formalpara>
+ <title>Result:</title>
+ <para>You should now see the file <filename>localhost.keystore</filename>.</para>
+ </formalpara>
+ </step>
+ </procedure>
+
+ <note>
+ <para>Key store files should be stored on a secure file system, and should be readable only by the owner of the JBoss Application Server process.</para>
+ </note>
+
+ <para>
+ Note that if no key store is specified on the command line, <command>keytool</command> will add the key pair to a new key store called <filename>keystore</filename> in the current user's home directory. This key store file will be a hidden file.
+ </para>
+ </section>
+
+ <section id="sect-export-self-signed-cert">
+ <title>Export a self-signed certificate</title>
+
+ <para>
+ Once a key pair has been generated for the server to use, a certificate must be created. <xref linkend="proc-export-self-signed-cert"/> details the steps to export the <filename>ejb-ssl</filename> key from the key store named <filename>localhost.keystore</filename>.
+ </para>
+
+ <procedure id="proc-export-self-signed-cert">
+ <title>Export a certificate</title>
+ <step>
+ <para>Issue the following command:</para>
+ <screen><command>keytool -export -alias ejb-ssl -file mycert.cer -keystore localhost.keystore</command></screen>
+ </step>
+ <step>
+ <para>Enter the key store password</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>A certificate will be exported to the file <filename>mycert.cer</filename>.</para>
+ </formalpara>
+ </step>
+ </procedure>
+ </section>
+ </section>
+
+ <section>
+ <title>Configure a client to accept a self-signed server certificate</title>
+
+<!-- NOTE: in the next cut of this we will have a section on using signed certificates. Lots of this info is in man keytool -->
+<!-- Also, this relates to the generation of the key pair, but it also relates to client configuration, so it's not clear to me whether it should immediately precede "Importing the key on the client" -->
+
+ <para>
+ Any client machine that will make remote method invocations over SSL needs to trust the certificate of the server. Since the certificate we generated is self-signed, and has no chain of trust to a known certificate authority, the client must be explicitly configured to trust the certificate or the connection will fail. Configuring a client to trust a self-signed certificate requires importing the self-signed server certificate to a trust store on the client.
+ </para>
+
+ <para>
+ A trust store is a key store that contains trusted certificates. Certificates that are in the local trust store will be accepted as valid. If your server uses a self-signed certificate then any clients that will make remote method calls over SSL must have that certificate in their trust store. You must export your public key as a certificate, and then import that certificate to the trust store on those clients.
+ </para>
+
+ <para>
+ The certificate created in <xref linkend="sect-export-self-signed-cert"/> must be copied to the client in order to perform the steps detailed in <xref linkend="import-cert-to-trust-store"/>.
+ </para>
+
+ <procedure id="import-cert-to-trust-store">
+ <title>Import the certificate to the trust store "localhost.truststore"</title>
+ <step>
+ <para>Issue the following command on the client:</para>
+ <screen><command>keytool -import -alias ejb-ssl -file mycert.cer -keystore localhost.truststore</command></screen>
+ </step>
+ <step>
+ <para>Enter the password for this trust store if it already exists; otherwise enter and re-enter the password for the trust store that will be created.</para>
+ </step>
+ <step>
+ <para>Verify the details of the certificate, and if it is the correct one, type 'yes' to import it to the trust store.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The certificate will be imported to the trust store, and you will be able to establish a secure connection with a server that uses this certificate.</para>
+ </formalpara>
+ </step>
+ </procedure>
+
+ <para>
+ As with the key store, if the trust store specified does not already exist, it will be created. However, in contrast with the key store, there is no default trust store, and one must be specified.
+ </para>
+
+ <formalpara>
+ <title>Configure Client to use localhost.truststore</title>
+
+ <para>
+ Now that you have imported the self-signed server certificate to a trust store on the client, you must instruct the client to use this trust store. This is done by passing the <filename>localhost.truststore</filename> location to the application using the <classname>javax.net.ssl.trustStore</classname> property, and the trust store password using the <classname>javax.net.ssl.trustStorePassword</classname> property. <xref linkend="ex-Invoke-with-trust-store"/> is an example commandline that would be used to invoke the application <application>com.acme.RunClient</application>, which will make remote method calls to an EJB on a JBoss Application Server.
+ </para>
+ </formalpara>
+ <example id="ex-Invoke-with-trust-store">
+ <title>Invoking the com.acme.Runclient application with a specific trust store</title>
+
+ <screen><command>java -Djavax.net.ssl.trustStore=${resources}/localhost.truststore \
+ -Djavax.net.ssl.trustStorePassword=<replaceable>TRUSTSTORE_PASSWORD</replaceable> com.acme.RunClient</command></screen>
+ </example>
+ </section>
+ </section>
+
+ <section>
+ <title>EJB3 Configuration</title>
+ <section id="sect-create-ejb3-remoting-connector">
+ <title>Create a secure remoting connector for EJB3</title>
+
+ <para>
+ The file <filename>ejb3-connectors-jboss-beans.xml </filename> in a JBoss Application Server profile's <filename>deploy</filename> directory contains JBoss Remoting connector definitions for EJB3 remote method invocation. <xref linkend="example-ejb3-remoting-connector"/> is a sample configuration that defines a secure connector for EJB3 using the key pair created in <xref linkend="proc-generate-new-key-pair"/>. The <classname>keyPassword</classname> property in the sample configuration is the key pair password that was specified when the key pair was created.
+ </para>
+
+ <example id="example-ejb3-remoting-connector">
+ <title>Sample Secure EJB3 Connector</title>
+ <screen><![CDATA[<bean name="EJB3SSLRemotingConnector" class="org.jboss.remoting.transport.Connector">
+ <property name="invokerLocator">sslsocket://${jboss.bind.address}:3843</property>
+ <property name="serverConfiguration">
+ <inject bean="ServerConfiguration" />
+ </property>
+ <property name="serverSocketFactory">
+ <inject bean="sslServerSocketFactory" />
+ </property>
+ </bean>
+
+ <bean name="sslServerSocketFactory" class="org.jboss.security.ssl.DomainServerSocketFactory">
+ <constructor>
+ <parameter><inject bean="EJB3SSLDomain"/></parameter>
+ </constructor>
+ </bean>
+ <bean name="EJB3SSLDomain" class="org.jboss.security.plugins.JaasSecurityDomain">
+ <constructor>
+ <parameter>EJB3SSLDomain</parameter>
+ </constructor>
+ <property name="keyStoreURL">resource:localhost.keystore</property>
+ <property name="keyStorePass">KEYSTORE_PASSWORD</property>
+ <property name="keyAlias">ejb-ssl</property>
+ <property name="keyPassword">EJB-SSL_KEYPAIR_PASSWORD</property>
+ </bean>]]></screen>
+ </example>
+
+ <para>The sample configuration will create a connector that listens for SSL connections on port 3843. This port will need to be opened on the server firewall for access by clients.</para>
+
+ </section>
+
+ <section>
+ <title>Configure EJB3 Beans for SSL Transport</title>
+
+ <para>
+ All EJB3 beans use the unsecured RMI connector by default. In order to enabled a bean to be invoked via SSL, the bean needs to be annotated with <classname>@org.jboss.annotation.ejb.RemoteBinding</classname>.
+ </para>
+
+ <para>
+ The annotation in <xref linkend="example-ejb3-annotation"/> will bind an EJB3 bean to the JNDI name <classname>StatefulSSL</classname>. The proxy implementing the remote interface, returned to a client when the bean is requested from JNDI, will communicate with the server via SSL.
+ </para>
+
+ <example id="example-ejb3-annotation">
+ <title>EJB3 bean annotation to enable secure remote invocation</title>
+ <screen><![CDATA[@RemoteBinding(clientBindUrl="sslsocket://0.0.0.0:3843", jndiBinding="StatefulSSL"),
+ @Remote(BusinessInterface.class)
+ public class StatefulBean implements BusinessInterface
+ {
+ ...
+ }]]></screen>
+ </example>
+
+ <note>
+ <para>In <xref linkend="example-ejb3-annotation"/> the IP address is specified as 0.0.0.0, meaning "all interfaces". This should be changed in practice to the value of the ${jboss.bind.address} system property.</para>
+ </note>
+ <!-- Question here: are we saying that it has to be hard-coded in here? What about portability between servers? Can it be specified literally as "${jboss.bind.address}"? -->
+
+ <formalpara>
+ <title>Enabling both secure and insecure invocation of an EJB3 bean</title>
+
+ <para>
+ You can enable both secure and insecure remote method invocation of the same EJB3 bean. <xref linkend="example-secure-and-insecure-ejb3-annotation"/> demonstrates the annotations to do this.
+ </para>
+ </formalpara>
+
+ <example id="example-secure-and-insecure-ejb3-annotation">
+ <title>EJB3 Bean annotation for both secure and insecure remote invocation</title>
+ <screen><![CDATA[ @RemoteBindings({
+ @RemoteBinding(clientBindUrl="sslsocket://0.0.0.0:3843", jndiBinding="StatefulSSL"),
+ @RemoteBinding(jndiBinding="StatefulNormal")
+ })
+ @Remote(BusinessInterface.class)
+ public class StatefulBean implements BusinessInterface
+ {
+ ...
+ }]]>
+ </screen>
+ </example>
+
+ <para>
+ If a client requests <classname>StatefulNormal</classname> from JNDI, the returned proxy implementing the remote interface will communicate with the server via the unencrypted socket protocol; and if <classname>StatefulSSL</classname> is requested, the returned proxy implementing the remote interface will communicate with the server via SSL.
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>EJB2 Configuration</title>
+
+<!-- This section needs to be worked over. What's going on here? Are we making the unified invoker do everything over SSL? Or *adding* SSL support?
+Is this RMI over SSL? SSL over HTTP?
+It needs to be clearly explained.
+
+It looks like it changes the system such that all EJB2 invocations must be made via SSL, but I'm not sure
+-->
+
+ <para>EJB2 remote invocation uses a single unified invoker, which runs by default on port 4446. The configuration of the unified invoker used for EJB2 remote method invocation is defined in the <filename>deploy/remoting-jboss-beans.xml</filename> file of a JBoss Application Server profile. Add the following SSL Socket Factory bean and an SSL Domain bean in this file.</para>
+
+ <example>
+ <title>SSL Server Factory for EJB2</title>
+ <screen><![CDATA[<bean name="sslServerSocketFactoryEJB2" class="org.jboss.security.ssl.DomainServerSocketFactory">
+ <constructor>
+ <parameter><inject bean="EJB2SSLDomain"/></parameter>
+ </constructor>
+</bean>
+
+<bean name="EJB2SSLDomain" class="org.jboss.security.plugins.JaasSecurityDomain">
+ <constructor>
+ <parameter>EJB2SSLDomain</parameter>
+ </constructor>
+ <property name="keyStoreURL">resource:localhost.keystore</property>
+ <property name="keyStorePass">changeit</property>
+ <property name="keyAlias">ejb-ssl</property>
+ <property name="keyPassword">EJB-SSL_KEYPAIR_PASSWORD</property>
+</bean>]]>
+ </screen>
+ </example>
+
+ <formalpara>
+ <title>Configure SSL Transport for Beans</title>
+ <para>In the <filename>deploy/remoting-jboss-beans.xml</filename> file in the JBoss Application Server profile, update the code to reflect the information below:</para>
+ </formalpara>
+
+ <example>
+ <title>SSL Transport for Beans</title>
+ <screen><![CDATA[...
+<bean name="UnifiedInvokerConnector" class="org.jboss.remoting.transport.Connector">
+ <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.remoting:service=Connector,transport=socket", exposedInterface=org.jboss.remoting.transport.ConnectorMBean.class,registerDirectly=true)
+ </annotation>
+ <property name="serverConfiguration"><inject bean="UnifiedInvokerConfiguration"/></property>
+ <!-- add this to configure the SSL socket for the UnifiedInvoker -->
+ <property name="serverSocketFactory"><inject bean="sslServerSocketFactoryEJB2"/></property>
+ </bean>
+ ...
+<bean name="UnifiedInvokerConfiguration" class="org.jboss.remoting.ServerConfiguration">
+ <constructor>
+ <!-- transport: Others include sslsocket, bisocket, sslbisocket, http, https, rmi, sslrmi, servlet, sslservlet. -->
+ <parameter>sslsocket</parameter><!-- changed from socket to sslsocket -->
+ </constructor>
+ ...
+ </bean>
+ ...]]>
+ </screen>
+ </example>
+
+ </section>
+
+
+
+</chapter>
+
Added: projects/docs/community/6/Security_Guide/en-US/chap-Using_LdapExtLoginModule.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/chap-Using_LdapExtLoginModule.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/chap-Using_LdapExtLoginModule.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,51 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="Using_LdapExtLoginModule_with_JaasSecurityDomain">
+ <title>Using LdapExtLoginModule with JaasSecurityDomain</title>
+ <para>
+This chapter provides guidance on how the LdapExtLoginModule can be used with an encrypted password to be decrypted by a JaasSecurityDomain. This chapter assumes that the LdapExtLoginModule is already running correctly with a non-encrypted password. <!--#QUESTION Provide link to resource on configuring LdapExtLoginModule-->
+ </para>
+ <para>
+The first step is to define the JaasSecurityDomain MBean that is going to be used to decrypt the encrypted version of the password. This can then be added to the <filename>$JBOSS_HOME/server/$PROFILE/conf/jboss-service.xml</filename> or can be added to a *<filename>-service.xml</filename> descriptor in the deploy folder.
+ </para>
+ <programlisting language="XML">
+ <![CDATA[
+ <mbean code="org.jboss.security.plugins.JaasSecurityDomain"
+ name="jboss.security:service=JaasSecurityDomain,domain=jmx-console">
+ <constructor>
+ <arg type="java.lang.String" value="jmx-console"></arg>
+ </constructor>
+ <attribute name="KeyStorePass">some_password</attribute>
+ <attribute name="Salt">abcdefgh</attribute>
+ <attribute name="IterationCount">66</attribute>
+ </mbean>]]>
+ </programlisting>
+ <para>
+This is a simple configuration where the required password, Salt and Iteration Count used for the encryption or decryption are contained within the MBean definition. <!-- It is possible to use any of the methods to obtain the password as described in the JaasSecurityDomain article.-->
+ </para>
+ <para>
+It should be noted that the default cipher algorithm used by the JaasSecurityDomain implementation is "PBEwithMD5andDES". This can be modified using the "CipherAlgorithm" attribute.
+ </para>
+ <para>
+Ensure that you change the KeyStorePass, Salt, and IterationCount values for your own deployment.
+ </para>
+ <para>
+After this MBean has been defined, start the JBoss Enterprise Application Platform. Navigate to the JMX Console (<ulink url="http://localhost:8080/jmx-console/">http://localhost:8080/jmx-console/</ulink> by default) and select the <literal>org.jboss.security.plugins.JaasSecurityDomain</literal> MBean.
+ </para>
+ <para>
+ On the <literal>org.jboss.security.plugins.JaasSecurityDomain</literal> page, look for the <methodname>encode64(String password)</methodname> method. Pass the plain text version of the <varname>password</varname> being used by the LdapExtLoginModule to this method, and invoke it. The return value should be the encrypted version of the password encoded as Base64.
+ </para>
+ <para>
+Within the login module configuration, the following module-options should be set:
+ </para>
+ <programlisting language="XML"><![CDATA[
+ <module-option name="jaasSecurityDomain">jboss.security:service=JaasSecurityDomain,domain=jmx-console</module-option>
+ <module-option name="bindCredential">2gx7gcAxcDuaHaJMgO5AVo</module-option> ]]>
+ </programlisting>
+ <para>
+The first option is a new option to specify that the JaasSecurityDomain used previously should be used to decrypt the password.
+ </para>
+ <para>
+The bindCredential is then replaced with the encrypted form as Base64.
+ </para>
+</chapter>
Added: projects/docs/community/6/Security_Guide/en-US/extras/authorization-policy-specific-security-domain-1.xml_sample
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/extras/authorization-policy-specific-security-domain-1.xml_sample (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/extras/authorization-policy-specific-security-domain-1.xml_sample 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <application-policy xmlns="urn:jboss:security-beans:1.0" name="test-domain">
+ <authentication>
+ <login-module code = "org.jboss.security.auth.spi.UsersRolesLoginModule"
+ flag = "required">
+ <module-option name = "unauthenticatedIdentity">anonymous</module-option>
+ <module-option name="usersProperties">u.properties</module-option>
+ <module-option name="rolesProperties">r.properties</module-option>
+ </login-module>
+ </authentication>
+ <authorization>
+ <policy-module code="org.jboss.security.authorization.modules.JACCAuthorizationModule" flag="required"/>
+ </authorization>
+ </application-policy>
+
+
+</deployment>
Added: projects/docs/community/6/Security_Guide/en-US/extras/authorization-policy-specific-security-domain-2.xml_sample
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/extras/authorization-policy-specific-security-domain-2.xml_sample (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/extras/authorization-policy-specific-security-domain-2.xml_sample 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <application-policy xmlns="urn:jboss:security-beans:1.0" name="test-domain">
+ <authentication>
+ <login-module code = "org.jboss.security.auth.spi.UsersRolesLoginModule"
+ flag = "required">
+ <module-option name = "unauthenticatedIdentity">anonymous</module-option>
+ <module-option name="usersProperties">u.properties</module-option>
+ <module-option name="rolesProperties">r.properties</module-option>
+ </login-module>
+ </authentication>
+ <authorization>
+ <policy-module code="org.jboss.security.authorization.modules.JACCAuthorizationModule" flag="required"/>
+ </authorization>
+ </application-policy>
+
+ <application-policy xmlns="urn:jboss:security-beans:1.0" name="test-domain-inherited" extends="other">
+ <authorization>
+ <policy-module code="org.jboss.security.authorization.modules.XACMLAuthorizationModule" flag="required"/>
+ </authorization>
+ </application-policy>
+
+</deployment>
Added: projects/docs/community/6/Security_Guide/en-US/extras/jboss-beans.xml_sample
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/extras/jboss-beans.xml_sample (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/extras/jboss-beans.xml_sample 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <application-policy xmlns="urn:jboss:security-beans:1.0" name="web-test">
+ <authentication>
+ <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
+ <module-option name="unauthenticatedIdentity">anonymous</module-option>
+ <module-option name="usersProperties">u.properties</module-option>
+ <module-option name="rolesProperties">r.properties</module-option>
+ </login-module>
+ </authentication>
+ </application-policy>
+
+ <application-policy xmlns="urn:jboss:security-beans:1.0" name="ejb-test">
+ <authentication>
+ <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
+ <module-option name="unauthenticatedIdentity">anonymous</module-option>
+ <module-option name="usersProperties">u.properties</module-option>
+ <module-option name="rolesProperties">r.properties</module-option>
+ </login-module>
+ </authentication>
+ </application-policy>
+
+</deployment>
Added: projects/docs/community/6/Security_Guide/en-US/extras/security-policies-EJBJACCPolicyModuleDelegate.java
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/extras/security-policies-EJBJACCPolicyModuleDelegate.java (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/extras/security-policies-EJBJACCPolicyModuleDelegate.java 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,124 @@
+package org.jboss.security.authorization.modules.ejb;
+
+import java.lang.reflect.Method;
+import java.security.CodeSource;
+import java.security.Permission;
+import java.security.Policy;
+import java.security.Principal;
+import java.security.ProtectionDomain;
+import java.util.Map;
+
+import javax.security.auth.Subject;
+import javax.security.jacc.EJBMethodPermission;
+import javax.security.jacc.EJBRoleRefPermission;
+
+import org.jboss.logging.Logger;
+import org.jboss.security.authorization.AuthorizationContext;
+import org.jboss.security.authorization.PolicyRegistration;
+import org.jboss.security.authorization.Resource;
+import org.jboss.security.authorization.ResourceKeys;
+import org.jboss.security.authorization.modules.AbstractJACCModuleDelegate;
+import org.jboss.security.authorization.modules.AuthorizationModuleDelegate;
+import org.jboss.security.authorization.resources.EJBResource;
+import org.jboss.security.identity.Role;
+import org.jboss.security.identity.RoleGroup;
+
+
+//$Id$
+
+/**
+ * Authorization Module delegate that deals with the authorization decisions
+ * for the EJB Layer
+ * @author <a href="mailto:Anil.Saldhana at jboss.org">Anil Saldhana</a>
+ * @since Jul 6, 2006
+ * @version $Revision$
+ */
+public class EJBJACCPolicyModuleDelegate extends AbstractJACCModuleDelegate
+{
+ private String ejbName = null;
+ private Method ejbMethod = null;
+ private String methodInterface = null;
+ private CodeSource ejbCS = null;
+ private String roleName = null;
+ private Boolean roleRefCheck = Boolean.FALSE;
+
+ public EJBJACCPolicyModuleDelegate()
+ {
+ log = Logger.getLogger(getClass());
+ trace = log.isTraceEnabled();
+ }
+
+ /**
+ * @see AuthorizationModuleDelegate#authorize(Resource)
+ */
+ public int authorize(Resource resource, Subject callerSubject, RoleGroup role)
+ {
+ if(resource instanceof EJBResource == false)
+ throw new IllegalArgumentException("resource is not an EJBResource");
+
+ EJBResource ejbResource = (EJBResource) resource;
+
+ //Get the context map
+ Map<String,Object> map = resource.getMap();
+ if(map == null)
+ throw new IllegalStateException("Map from the Resource is null");
+
+ this.policyRegistration = (PolicyRegistration) map.get(ResourceKeys.POLICY_REGISTRATION);
+
+ this.ejbCS = ejbResource.getCodeSource();
+ this.ejbMethod = ejbResource.getEjbMethod();
+ this.ejbName = ejbResource.getEjbName();
+ this.methodInterface = ejbResource.getEjbMethodInterface();
+
+ //isCallerInRole checks
+ this.roleName = (String)map.get(ResourceKeys.ROLENAME);
+
+ this.roleRefCheck = (Boolean)map.get(ResourceKeys.ROLEREF_PERM_CHECK);
+ if(this.roleRefCheck == Boolean.TRUE)
+ return checkRoleRef(callerSubject, role);
+ else
+ return process(callerSubject, role);
+ }
+
+ //Private Methods
+ /**
+ * Process the request
+ * @param request
+ * @param sc
+ * @return
+ */
+ private int process(Subject callerSubject, Role role)
+ {
+ EJBMethodPermission methodPerm =
+ new EJBMethodPermission(ejbName, methodInterface, ejbMethod);
+ boolean policyDecision = checkWithPolicy(methodPerm, callerSubject, role);
+ if( policyDecision == false )
+ {
+ String msg = "Denied: "+methodPerm+", caller=" + callerSubject+", role="+role;
+ if(trace)
+ log.trace("EJB Jacc Delegate:"+msg);
+ }
+ return policyDecision ? AuthorizationContext.PERMIT : AuthorizationContext.DENY;
+ }
+
+ private int checkRoleRef(Subject callerSubject, RoleGroup callerRoles)
+ {
+ //This has to be the EJBRoleRefPermission
+ EJBRoleRefPermission ejbRoleRefPerm = new EJBRoleRefPermission(ejbName,roleName);
+ boolean policyDecision = checkWithPolicy(ejbRoleRefPerm, callerSubject, callerRoles);
+ if( policyDecision == false )
+ {
+ String msg = "Denied: "+ejbRoleRefPerm+", caller=" + callerSubject;
+ if(trace)
+ log.trace("EJB Jacc Delegate:"+msg);
+ }
+ return policyDecision ? AuthorizationContext.PERMIT : AuthorizationContext.DENY;
+ }
+
+ private boolean checkWithPolicy(Permission ejbPerm, Subject subject, Role role)
+ {
+ Principal[] principals = this.getPrincipals(subject, role);
+ ProtectionDomain pd = new ProtectionDomain (ejbCS, null, null, principals);
+ return Policy.getPolicy().implies(pd, ejbPerm);
+ }
+}
Added: projects/docs/community/6/Security_Guide/en-US/extras/security-policies-WebJACCPolicyModuleDelegate.java
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/extras/security-policies-WebJACCPolicyModuleDelegate.java (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/extras/security-policies-WebJACCPolicyModuleDelegate.java 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,271 @@
+package org.jboss.security.authorization.modules.web;
+
+import java.io.IOException;
+import java.security.CodeSource;
+import java.security.Permission;
+import java.security.Policy;
+import java.security.Principal;
+import java.security.ProtectionDomain;
+import java.util.Map;
+import java.util.Set;
+
+import javax.security.auth.Subject;
+import javax.security.jacc.WebResourcePermission;
+import javax.security.jacc.WebRoleRefPermission;
+import javax.security.jacc.WebUserDataPermission;
+import javax.servlet.http.HttpServletRequest;
+
+import org.jboss.logging.Logger;
+import org.jboss.security.authorization.AuthorizationContext;
+import org.jboss.security.authorization.PolicyRegistration;
+import org.jboss.security.authorization.Resource;
+import org.jboss.security.authorization.ResourceKeys;
+import org.jboss.security.authorization.modules.AbstractJACCModuleDelegate;
+import org.jboss.security.authorization.modules.AuthorizationModuleDelegate;
+import org.jboss.security.authorization.resources.WebResource;
+import org.jboss.security.identity.Role;
+import org.jboss.security.identity.RoleGroup;
+
+
+//$Id: WebJACCPolicyModuleDelegate.java 62923 2007-05-09 03:08:14Z anil.saldhana at jboss.com $
+
+/**
+ * JACC based authorization module helper that deals with the web layer
+ * authorization decisions
+ * @author <a href="mailto:Anil.Saldhana at jboss.org">Anil Saldhana</a>
+ * @since July 7, 2006
+ * @version $Revision: 62923 $
+ */
+public class WebJACCPolicyModuleDelegate extends AbstractJACCModuleDelegate
+{
+ private Policy policy = Policy.getPolicy();
+ private HttpServletRequest request = null;
+ private CodeSource webCS = null;
+
+ private String canonicalRequestURI = null;
+
+ public WebJACCPolicyModuleDelegate()
+ {
+ log = Logger.getLogger(WebJACCPolicyModuleDelegate.class);
+ trace = log.isTraceEnabled();
+ }
+
+ /**
+ * @see AuthorizationModuleDelegate#authorize(Resource)
+ */
+ @SuppressWarnings("unchecked")
+ public int authorize(Resource resource, Subject callerSubject, RoleGroup role)
+ {
+ if(resource instanceof WebResource == false)
+ throw new IllegalArgumentException("resource is not a WebResource");
+
+ WebResource webResource = (WebResource) resource;
+
+ //Get the context map
+ Map<String,Object> map = resource.getMap();
+ if(map == null)
+ throw new IllegalStateException("Map from the Resource is null");
+
+ //Get the Request Object
+ request = (HttpServletRequest) webResource.getServletRequest();
+
+ webCS = webResource.getCodeSource();
+ this.canonicalRequestURI = webResource.getCanonicalRequestURI();
+
+ String roleName = (String)map.get(ResourceKeys.ROLENAME);
+ Principal principal = (Principal)map.get(ResourceKeys.HASROLE_PRINCIPAL);
+ Set<Principal> roles = (Set<Principal>)map.get(ResourceKeys.PRINCIPAL_ROLES);
+ String servletName = webResource.getServletName();
+ Boolean resourceCheck = checkBooleanValue((Boolean)map.get(ResourceKeys.RESOURCE_PERM_CHECK));
+ Boolean userDataCheck = checkBooleanValue((Boolean)map.get(ResourceKeys.USERDATA_PERM_CHECK));
+ Boolean roleRefCheck = checkBooleanValue((Boolean)map.get(ResourceKeys.ROLEREF_PERM_CHECK));
+
+ validatePermissionChecks(resourceCheck,userDataCheck,roleRefCheck);
+
+ boolean decision = false;
+
+ try
+ {
+ if(resourceCheck)
+ decision = this.hasResourcePermission(callerSubject, role);
+ else
+ if(userDataCheck)
+ decision = this.hasUserDataPermission();
+ else
+ if(roleRefCheck)
+ decision = this.hasRole(principal, roleName, roles, servletName);
+ else
+ if(trace)
+ log.trace("Check is not for resourcePerm, userDataPerm or roleRefPerm.");
+ }
+ catch(IOException ioe)
+ {
+ if(trace)
+ log.trace("IOException:",ioe);
+ }
+ return decision ? AuthorizationContext.PERMIT : AuthorizationContext.DENY;
+ }
+
+ /**
+ * @see AuthorizationModuleDelegate#setPolicyRegistrationManager(PolicyRegistration)
+ */
+ public void setPolicyRegistrationManager(PolicyRegistration authzM)
+ {
+ this.policyRegistration = authzM;
+ }
+
+ //****************************************************************************
+ // PRIVATE METHODS
+ //****************************************************************************
+ /** See if the given JACC permission is implied using the caller as
+ * obtained from either the
+ * PolicyContext.getContext(javax.security.auth.Subject.container) or
+ * the info associated with the requestPrincipal.
+ *
+ * @param perm - the JACC permission to check
+ * @param requestPrincpal - the http request getPrincipal
+ * @param caller the authenticated subject obtained by establishSubjectContext
+ * @return true if the permission is allowed, false otherwise
+ */
+ private boolean checkPolicy(Permission perm, Principal requestPrincpal,
+ Subject caller, Role role)
+ {
+ // Get the caller principals, its null if there is no caller
+ Principal[] principals = getPrincipals(caller,role);
+
+ return checkPolicy(perm, principals);
+ }
+
+
+ /** See if the given permission is implied by the Policy. This calls
+ * Policy.implies(pd, perm) with the ProtectionDomain built from the
+ * active CodeSource set by the JaccContextValve, and the given
+ * principals.
+ *
+ * @param perm - the JACC permission to evaluate
+ * @param principals - the possibly null set of principals for the caller
+ * @return true if the permission is allowed, false otherwise
+ */
+ private boolean checkPolicy(Permission perm, Principal[] principals)
+ {
+ ProtectionDomain pd = new ProtectionDomain(webCS, null, null, principals);
+ boolean allowed = policy.implies(pd, perm);
+ if( trace )
+ {
+ String msg = (allowed ? "Allowed: " : "Denied: ") +perm;
+ log.trace(msg);
+ }
+ return allowed;
+ }
+
+ /**
+ * Ensure that the bool is a valid value
+ * @param bool
+ * @return bool or Boolean.FALSE (when bool is null)
+ */
+ private Boolean checkBooleanValue(Boolean bool)
+ {
+ if(bool == null)
+ return Boolean.FALSE;
+ return bool;
+ }
+
+
+ /**
+ * Perform hasResourcePermission Check
+ * @param request
+ * @param response
+ * @param securityConstraints
+ * @param context
+ * @param caller
+ * @return
+ * @throws IOException
+ */
+ private boolean hasResourcePermission(Subject caller, Role role)
+ throws IOException
+ {
+ Principal requestPrincipal = request.getUserPrincipal();
+ WebResourcePermission perm = new WebResourcePermission(this.canonicalRequestURI,
+ request.getMethod());
+ boolean allowed = checkPolicy(perm, requestPrincipal, caller, role );
+ if( trace )
+ log.trace("hasResourcePermission, perm="+perm+", allowed="+allowed);
+ return allowed;
+ }
+
+ /**
+ * Perform hasRole check
+ * @param principal
+ * @param role
+ * @param roles
+ * @return
+ */
+ private boolean hasRole(Principal principal, String roleName,
+ Set<Principal> roles, String servletName)
+ {
+ if(servletName == null)
+ throw new IllegalArgumentException("servletName is null");
+
+ WebRoleRefPermission perm = new WebRoleRefPermission(servletName, roleName);
+ Principal[] principals = {principal};
+ if( roles != null )
+ {
+ principals = new Principal[roles.size()];
+ roles.toArray(principals);
+ }
+ boolean allowed = checkPolicy(perm, principals);
+ if( trace )
+ log.trace("hasRole, perm="+perm+", allowed="+allowed);
+ return allowed;
+ }
+
+ /**
+ * Perform hasUserDataPermission check for the realm.
+ * If this module returns false, the base class (Realm) will
+ * make the decision as to whether a redirection to the ssl
+ * port needs to be done
+ * @param request
+ * @param response
+ * @param constraints
+ * @return
+ * @throws IOException
+ */
+ private boolean hasUserDataPermission() throws IOException
+ {
+ WebUserDataPermission perm = new WebUserDataPermission(this.canonicalRequestURI,
+ request.getMethod());
+ if( trace )
+ log.trace("hasUserDataPermission, p="+perm);
+ boolean ok = false;
+ try
+ {
+ Principal[] principals = null;
+ ok = checkPolicy(perm, principals);
+ }
+ catch(Exception e)
+ {
+ if( trace )
+ log.trace("Failed to checkSecurityAssociation", e);
+ }
+ return ok;
+ }
+
+ /**
+ * Validate that the access check is made only for one of the
+ * following
+ * @param resourceCheck
+ * @param userDataCheck
+ * @param roleRefCheck
+ */
+ private void validatePermissionChecks(Boolean resourceCheck,
+ Boolean userDataCheck, Boolean roleRefCheck)
+ {
+ if(trace)
+ log.trace("resourceCheck="+resourceCheck + " : userDataCheck=" + userDataCheck
+ + " : roleRefCheck=" + roleRefCheck);
+ if((resourceCheck == Boolean.TRUE && userDataCheck == Boolean.TRUE && roleRefCheck == Boolean.TRUE )
+ || (resourceCheck == Boolean.TRUE && userDataCheck == Boolean.TRUE)
+ || (userDataCheck == Boolean.TRUE && roleRefCheck == Boolean.TRUE))
+ throw new IllegalStateException("Permission checks must be different");
+ }
+}
Added: projects/docs/community/6/Security_Guide/en-US/extras/security-policies-authorization_delegate_example.java
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/extras/security-policies-authorization_delegate_example.java (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/extras/security-policies-authorization_delegate_example.java 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,47 @@
+package org.jboss.security.authorization.modules;
+
+import javax.security.auth.Subject;
+
+import org.jboss.logging.Logger;
+import org.jboss.security.authorization.AuthorizationModule;
+import org.jboss.security.authorization.PolicyRegistration;
+import org.jboss.security.authorization.Resource;
+import org.jboss.security.identity.RoleGroup;
+
+//$Id$
+
+/**
+ * Delegate for Authorization Module
+ * @author <a href="mailto:Anil.Saldhana at jboss.org">Anil Saldhana</a>
+ * @since Jun 19, 2006
+ * @version $Revision$
+ */
+public abstract class AuthorizationModuleDelegate
+{
+ protected static Logger log = Logger.getLogger(AuthorizationModuleDelegate.class);
+ protected boolean trace = false;
+
+ /**
+ * Policy Registration Manager Injected
+ */
+ protected PolicyRegistration policyRegistration = null;
+
+ /**
+ * @see AuthorizationModule#authorize(Resource)
+ * @param resource
+ * @param subject Authenticated Subject
+ * @param role RoleGroup
+ * @return
+ */
+ public abstract int authorize(Resource resource, Subject subject, RoleGroup role);
+
+ /**
+ * Set the PolicyRegistration manager
+ * Will be used to query for the policies
+ * @param authzManager
+ */
+ public void setPolicyRegistrationManager(PolicyRegistration pm)
+ {
+ this.policyRegistration = pm;
+ }
+}
Added: projects/docs/community/6/Security_Guide/en-US/extras/security-policies-jboss-beans_all_ejb_war.xml_sample
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/extras/security-policies-jboss-beans_all_ejb_war.xml_sample (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/extras/security-policies-jboss-beans_all_ejb_war.xml_sample 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <application-policy xmlns="urn:jboss:security-beans:1.0" name="jboss-web-policy" extends="other">
+ <authorization>
+ <policy-module code="org.jboss.security.authorization.modules.JACCAuthorizationModule" flag="required"/>
+ </authorization>
+ </application-policy>
+
+ <application-policy xmlns="urn:jboss:security-beans:1.0" name="jboss-ejb-policy" extends="other">
+ <authorization>
+ <policy-module code="org.jboss.security.authorization.modules.JACCAuthorizationModule" flag="required"/>
+ </authorization>
+ </application-policy>
+
+ <application-policy xmlns="urn:jboss:security-beans:1.0" name="jacc-test" extends="other">
+ <authorization>
+ <policy-module code="org.jboss.security.authorization.modules.JACCAuthorizationModule" flag="required"/>
+ </authorization>
+ </application-policy>
+
+</deployment>
Added: projects/docs/community/6/Security_Guide/en-US/extras/security-policies-jboss-beans_default.xml_sample
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/extras/security-policies-jboss-beans_default.xml_sample (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/extras/security-policies-jboss-beans_default.xml_sample 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <application-policy xmlns="urn:jboss:security-beans:1.0" name="jboss-web-policy" extends="other">
+ <authorization>
+ <policy-module code="org.jboss.security.authorization.modules.DelegatingAuthorizationModule"
+ flag="required"/>
+ </authorization>
+ </application-policy>
+
+ <application-policy xmlns="urn:jboss:security-beans:1.0" name="jboss-ejb-policy" extends="other">
+ <authorization>
+ <policy-module code="org.jboss.security.authorization.modules.DelegatingAuthorizationModule"
+ flag="required"/>
+ </authorization>
+ </application-policy>
+
+</deployment>
Added: projects/docs/community/6/Security_Guide/en-US/images/AS6_SecurityModel_Interface.png
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/AS6_SecurityModel_Interface.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/authsteps.png
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/authsteps.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap2-47.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap2-47.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-13.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-13.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-14.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-14.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-7.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-7.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-8.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-8.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-9.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/j2ee_chap8-9.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/j2ee_method.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/j2ee_method.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/j2ee_method_permission.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/j2ee_method_permission.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/j2ee_security_identity.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/j2ee_security_identity.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/j2ee_security_role.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/j2ee_security_role.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/j2ee_security_role_ref.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/j2ee_security_role_ref.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/security_config_login_module.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/security_config_login_module.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/security_config_policy.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/security_config_policy.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/webapp_login_config.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/webapp_login_config.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/images/webapp_security_constraint.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/community/6/Security_Guide/en-US/images/webapp_security_constraint.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/community/6/Security_Guide/en-US/sect-Configure_Secure_Remote_Password_Information.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/sect-Configure_Secure_Remote_Password_Information.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/sect-Configure_Secure_Remote_Password_Information.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,108 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<section id="sect-Configure_Secure_Remote_Password_Information">
+ <title>Configure Secure Remote Password Information</title>
+ <para>You must create a 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>
+ <note>
+ <para>
+ The default implementation of the <literal>SRPVerifierStore</literal> interface is not recommended for a production security environment because it requires all password hash information to be available as a file of serialized objects. </para>
+ </note>
+ <example id="Providing_Password_Information_for_SRP-The_SRPVerifierStore_Interface">
+ <title>The SRPVerifierStore interface</title>
+ <programlisting language="Java" role="JAVA">package org.jboss.security.srp;
+
+import java.io.IOException;
+import java.io.Serializable;
+import java.security.KeyException;
+
+public interface SRPVerifierStore
+{
+ public static class VerifierInfo implements Serializable
+ {
+
+ public String username;
+
+
+ public byte[] salt;
+ public byte[] g;
+ public byte[] N;
+ }
+
+
+ public VerifierInfo getUserVerifier(String username)
+ throws KeyException, IOException;
+
+ public void setUserVerifier(String username, VerifierInfo info)
+ throws IOException;
+
+
+ public void verifyUserChallenge(String username, Object auxChallenge)
+ throws SecurityException;
+}
+</programlisting>
+ <para>
+ The primary function of a <literal>SRPVerifierStore</literal> implementation is to provide access to the <literal>SRPVerifierStore.VerifierInfo</literal> object for a given username. The <literal>getUserVerifier(String)</literal> method is called by the <literal>SRPService</literal> at that start of a user SRP session to obtain the parameters needed by the SRP algorithm. The elements of the <literal>VerifierInfo</literal> objects are:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <markup>username</markup>
+ </term>
+ <listitem>
+ <para>The user's name or id used to login.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <markup>verifier</markup>
+ </term>
+ <listitem>
+ <para>One-way hash of the password or PIN the user enters as proof of identity. The <classname>org.jboss.security.Util</classname> class has a <methodname>calculateVerifier</methodname> method that performs that password hashing algorithm. The output password takes the form <literal>H(salt | H(username | ':' | password))</literal>, where <literal>H</literal> is the SHA secure hash function as defined by RFC2945. The username is converted from a string to a <literal>byte[]</literal> using UTF-8 encoding.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>salt</term>
+ <listitem>
+ <para>Random number used to increase the difficulty of a brute force dictionary attack on the verifier password database in the event that the database is compromised. The value should be generated from a cryptographically strong random number algorithm when the user's existing clear-text password is hashed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>g</term>
+ <listitem>
+ <para>SRP algorithm primitive generator. This can be a well known fixed parameter rather than a per-user setting. The <classname>org.jboss.security.srp.SRPConf</classname> utility class provides several settings for <literal>g</literal>, including a suitable default obtained via <literal>SRPConf.getDefaultParams().g()</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>N</term>
+ <listitem>
+ <para>SRP algorithm safe-prime modulus. This can be a well known fixed parameter rather than a per-user setting. The <classname>org.jboss.security.srp.SRPConf</classname> utility class provides several settings for <literal>N</literal> including a good default which can obtained via <literal>SRPConf.getDefaultParams().N()</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <procedure>
+ <title>Integrate Existing Password Store</title>
+ <para>Read this procedure to understand the steps involved to integrate your existing password store.</para>
+ <step>
+ <title>Create Hashed Password Information Store</title>
+ <para>If your passwords are already stored in an irreversible hashed form, then this can only be done on a per-user basis (for example, as part of an upgrade procedure).</para>
+ <para>You can implement <literal>setUserVerifier(String, VerifierInfo)</literal> as a <methodname>noOp</methodname> method, or a method that throws an exception stating that the store is read-only. </para>
+ </step>
+ <step>
+ <title>Create SRPVerifierStore Interface</title>
+ <para>You must create a custom <literal>SRPVerifierStore</literal> interface implementation that understands how to obtain the <literal>VerifierInfo</literal> from the store you created. </para>
+ <para>The <methodname>verifyUserChallenge(String, Object)</methodname> can be used to integrate existing hardware token based schemes like SafeWord or Radius into the SRP algorithm. This interface method is called only when the client <literal>SRPLoginModule</literal> configuration specifies the <literal>hasAuxChallenge</literal> option.</para>
+ </step>
+ <step>
+ <title>Create JNDI MBean</title>
+ <para>You must create a MBean that exposes the <literal>SRPVerifierStore</literal> interface available to JNDI, and exposes any configurable parameters required.</para>
+ <para>The default <literal>org.jboss.security.srp.SRPVerifierStoreService</literal> will allow you to implement this, however you can also implement the MBean using a Java properties file implementation of <literal>SRPVerifierStore</literal> (refer to <xref linkend="sect-Secure_Remote_Password_Example"/>). </para>
+ </step>
+ </procedure>
+ </example>
+</section>
Added: projects/docs/community/6/Security_Guide/en-US/sect-Secure_Remote_Password_Example.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/sect-Secure_Remote_Password_Example.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/sect-Secure_Remote_Password_Example.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,117 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<section id="sect-Secure_Remote_Password_Example">
+ <title>Secure Remote Password Example</title>
+ <para>
+ The example presented in this section 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. </para>
+ <para>The server side login module configuration is dynamically installed using the <literal>SecurityConfig</literal> MBean. A custom implementation of the <literal>SRPVerifierStore</literal> interface is also used in the example. The interface 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>. </para>
+ <para>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>
+ <screen>[examples]$ jar tf output/security/security-ex3.jar
+META-INF/MANIFEST.MF
+META-INF/ejb-jar.xml
+META-INF/jboss.xml
+org/jboss/book/security/ex3/Echo.class
+org/jboss/book/security/ex3/EchoBean.class
+org/jboss/book/security/ex3/EchoHome.class
+roles.properties
+users.properties
+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 <filename>jboss-service.xml</filename> descriptor of the <filename>security-ex3.sar</filename> is described in <xref linkend="An_SRP_example-The_security_ex3.sar_jboss_service.xml_descriptor_for_the_SRP_services"/>. </para>
+ <para>The example client side and server side login module configurations are described in <xref linkend="An_SRP_example-The_client_side_standard_JAAS_configuration"/> and <xref linkend="An_SRP_example-The_server_side_XMLLoginConfig_configuration"/> give .
+ </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</title>
+ <programlisting language="XML" role="XML"><server>
+ <!-- The custom JAAS login configuration that installs
+ a Configuration capable of dynamically updating the
+ config settings -->
+
+ <mbean code="org.jboss.book.security.service.SecurityConfig"
+ name="jboss.docs.security:service=LoginConfig-EX3">
+ <attribute name="AuthConfig">META-INF/login-config.xml</attribute>
+ <attribute name="SecurityConfigName">jboss.security:name=SecurityConfig</attribute>
+ </mbean>
+
+ <!-- The SRP service that provides the SRP RMI server and server side
+ authentication cache -->
+ <mbean code="org.jboss.security.srp.SRPService"
+ name="jboss.docs.security:service=SRPService">
+ <attribute name="VerifierSourceJndiName">srp-test/security-ex3</attribute>
+ <attribute name="JndiName">srp-test/SRPServerInterface</attribute>
+ <attribute name="AuthenticationCacheJndiName">srp-test/AuthenticationCache</attribute>
+ <attribute name="ServerPort">0</attribute>
+ <depends>jboss.docs.security:service=PropertiesVerifierStore</depends>
+ </mbean>
+
+ <!-- The SRP store handler service that provides the user password verifier
+ information -->
+ <mbean code="org.jboss.security.ex3.service.PropertiesVerifierStore"
+ name="jboss.docs.security:service=PropertiesVerifierStore">
+ <attribute name="JndiName">srp-test/security-ex3</attribute>
+ </mbean>
+</server>
+</programlisting>
+ </example>
+ <para>
+ The example services are the <literal>ServiceConfig</literal> and the <literal>PropertiesVerifierStore</literal> and <literal>SRPService</literal> MBeans. Note that the <literal>JndiName</literal> attribute of the <literal>PropertiesVerifierStore</literal> is equal to the <literal>VerifierSourceJndiName</literal> attribute of the <literal>SRPService</literal>, and that the <literal>SRPService</literal> depends on the <literal>PropertiesVerifierStore</literal>. This is required because the <literal>SRPService</literal> needs an implementation of the <literal>SRPVerifierStore</literal> interface for accessing user password verification information.
+ </para>
+ <example id="An_SRP_example-The_client_side_standard_JAAS_configuration">
+ <title>The client side standard JAAS configuration</title>
+ <programlisting>srp {
+ org.jboss.security.srp.jaas.SRPLoginModule required
+ srpServerJndiName="srp-test/SRPServerInterface"
+ ;
+
+ org.jboss.security.ClientLoginModule required
+ password-stacking="useFirstPass"
+ ;
+};
+</programlisting>
+ </example>
+ <para>The client side login module configuration makes use of the <literal>SRPLoginModule</literal> with a <literal>srpServerJndiName</literal> option value that corresponds to the JBoss server component <literal>SRPService</literal> JndiName attribute value(<literal>srp-test/SRPServerInterface</literal>). The <literal>ClientLoginModule</literal> must also be configured with the <literal>password-stacking="useFirstPass"</literal> value to propagate the user authentication credentials generated by the <literal>SRPLoginModule</literal> to the EJB invocation layer.
+ </para>
+ <example id="An_SRP_example-The_server_side_XMLLoginConfig_configuration">
+ <title>The server side XMLLoginConfig configuration</title>
+ <programlisting language="XML" role="XML"><application-policy name="security-ex3">
+ <authentication>
+ <login-module code="org.jboss.security.srp.jaas.SRPCacheLoginModule"
+ flag = "required">
+ <module-option name="cacheJndiName">srp-test/AuthenticationCache</module-option>
+ </login-module>
+ <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
+ flag = "required">
+ <module-option name="password-stacking">useFirstPass</module-option>
+ </login-module>
+ </authentication>
+</application-policy>
+</programlisting>
+ </example>
+ <para>There are two issues to note about the server side login module configuration: </para>
+ <orderedlist>
+ <listitem>
+ <para>The <literal>cacheJndiName=srp-test/AuthenticationCache</literal> configuration option tells the <literal>SRPCacheLoginModule</literal> the location of the <literal>CachePolicy</literal> that contains the <literal>SRPServerSession</literal> for users who have authenticated against the <literal>SRPService</literal>. This value corresponds to the <literal>SRPService</literal><literal>AuthenticationCacheJndiName</literal> attribute value. </para>
+ </listitem>
+ <listitem>
+ <para>The configuration includes a <literal>UsersRolesLoginModule</literal> with the <literal>password-stacking=useFirstPass</literal> configuration option. You must use a second login module with the <literal>SRPCacheLoginModule</literal> because SRP is only an authentication technology. To set the principal's roles that in turn determine the associated permissions, a second login module must be configured to accept the authentication credentials validated by the <literal>SRPCacheLoginModule</literal> . </para>
+ </listitem>
+ </orderedlist>
+ <para>The <literal>UsersRolesLoginModule</literal> is augmenting the SRP authentication with properties file based authorization. The user's roles are obtained from the <literal>roles.properties</literal> file included in the EJB JAR.
+ </para>
+ <para>Run the example 3 client by executing the following command from the book examples directory:
+ </para>
+ <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</screen>
+ <para>In the <literal>examples/logs</literal> directory, the <literal>ex3-trace.log</literal> file contains 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>
+ <para>Observe that the client takes a long time to run, relative to the other simple examples. The reason for this is the construction of the client's public key. This involves the creation of a cryptographically strong random number, and this process takes longer when it first executes. Subsequent authentication attempts within the same VM are much faster. </para>
+ <para>Note that <literal>Echo.echo()#2</literal> fails with an authentication exception. The client code sleeps for 15 seconds after making the first call to demonstrate the behavior of the <literal>SRPService</literal> cache expiration. The <literal>SRPService</literal> cache policy timeout has been set to 10 seconds to force this issue. As discussed in <xref linkend="sect-Secure_Remote_Password_Example"/> you must set the cache timeout correctly, or handle re-authentication on failure.
+ </para>
+</section>
Added: projects/docs/community/6/Security_Guide/en-US/sect-Understanding_The_Algorithm.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/sect-Understanding_The_Algorithm.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/sect-Understanding_The_Algorithm.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,75 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<section id="sect-Understanding_The_Algorithm">
+ <title>Understanding the Algorithm</title>
+ <para>The appeal of the SRP algorithm is that is allows for mutual authentication of client and server using simple text passwords without a secure communication channel. </para>
+ <note>
+ <para>Additional information on the SRP algorithm and its history can be found at <ulink url="http://srp.stanford.edu/"/>.
+ </para>
+ </note>
+<!--TODO: Perhaps make this epic orderedlist a procedure and summarize each step. --> <para>There are six steps that are performed to complete authentication:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The client side <literal>SRPLoginModule</literal> retrieves from the naming service the SRPServerInterface instance for the remote authentication server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The client side <literal>SRPLoginModule</literal> next requests the SRP parameters associated with the username attempting the login. There are a number of parameters involved in the SRP algorithm that must be chosen when the user password is first transformed into the verifier form used by the SRP algorithm. Rather than hard-coding the parameters (which could be done with minimal security risk), the JBossSX implementation allows a user to retrieve this information as part of the exchange protocol. The <literal>getSRPParameters(username)</literal> call retrieves the SRP parameters for the given username.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The client side <literal>SRPLoginModule</literal> begins an SRP session by creating an <literal>SRPClientSession</literal> object using the login username, clear-text password, and SRP parameters obtained from step 2. The client then creates a random number A that will be used to build the private SRP session key. The client then initializes the server side of the SRP session by invoking the <literal>SRPServerInterface.init</literal> method and passes in the username and client generated random number <literal>A</literal>. The server returns its own random number <literal>B</literal>. This step corresponds to the exchange of public keys.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The client side <literal>SRPLoginModule</literal> obtains the private SRP session key that has been generated as a result of the previous messages exchanges. This is saved as a private credential in the login <literal>Subject</literal>. The server challenge response <literal>M2</literal> from step 4 is verified by invoking the <literal>SRPClientSession.verify</literal> method. If this succeeds, mutual authentication of the client to server, and server to client have been completed. The client side <literal>SRPLoginModule</literal> next creates a challenge <literal>M1</literal> to the server by invoking <literal>SRPClientSession.response</literal> method passing the server random number <literal>B</literal> as an argument. This challenge is sent to the server via the <literal>SRPServerInterface.verify</literal> method and server's response is saved as <literal>M2</literal>. This step corresponds to an exchange of challenges. At this point the server has verified t!
hat the user is who they say they are.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The client side <literal>SRPLoginModule</literal> saves the login username and <literal>M1</literal> challenge into the <literal>LoginModule</literal> sharedState map. This is used as the Principal name and credentials by the standard JBoss <literal>ClientLoginModule</literal>. The <literal>M1</literal> challenge is used in place of the password as proof of identity on any method invocations on Java EE components. The <literal>M1</literal> challenge is a cryptographically strong hash associated with the SRP session. Its interception via a third partly cannot be used to obtain the user's password.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ At the end of this authentication protocol, the SRPServerSession has been placed into the SRPService authentication cache for subsequent use by the <literal>SRPCacheLoginModule</literal>.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>Although SRP has many interesting properties, it is still an evolving component in the JBossSX framework and has some limitations of which you should be aware. Issues of note include the following:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>Where authentication is performed, the way in which JBoss detaches the method transport protocol from the component container could allow a user to snoop the SRP <literal>M1</literal> challenge and effectively use the challenge to make requests as the associated username. Custom interceptors can be used to prevent the issue, by encrypting the challenge using the SRP session key.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The SRPService maintains a cache of SRP sessions that time out after a configurable period. Once they time out, any subsequent Java EE component access will fail because there is currently no mechanism for transparently renegotiating the SRP authentication credentials. You must either set the authentication cache timeout quite high, or handle re-authentication in your code on failure. </para>
+ <note>
+ <para>The SRPService supports timeout durations up to 2,147,483,647 seconds, or approximately 68 years.</para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>There can only be one SRP session for a given username by default. The session is classed as stateful, because the negotiated SRP session produces a private session key that can be used for encryption and decryption between the client and server. JBoss supports multiple SRP sessions per user, however it is not possible to encrypt data with one session key, and decrypt it with another.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ To use end-to-end SRP authentication for Java EE component calls, you must configure the security domain under which the components are secured to use the <classname>org.jboss.security.srp.jaas.SRPCacheLoginModule</classname>. The <literal>SRPCacheLoginModule</literal> has a single configuration option named <literal>cacheJndiName</literal> that sets the JNDI location of the SRP authentication <literal>CachePolicy</literal> instance. This must correspond to the <literal>AuthenticationCacheJndiName</literal> attribute value of the <literal>SRPService</literal> MBean. </para>
+ <para>The <literal>SRPCacheLoginModule</literal> authenticates user credentials by obtaining the client challenge from the <literal>SRPServerSession</literal> object in the authentication cache and comparing this to the challenge passed as the user credentials. <xref linkend="fig-SRPCacheLoginModule_with_SRP_Session_Cache"/> illustrates the operation of the SRPCacheLoginModule.login method implementation.
+ </para>
+ <figure id="fig-SRPCacheLoginModule_with_SRP_Session_Cache">
+ <title>SRPCacheLoginModule with SRP Session Cache</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/j2ee_chap8-14.jpg"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+</section>
Added: projects/docs/community/6/Security_Guide/en-US/template.xml
===================================================================
--- projects/docs/community/6/Security_Guide/en-US/template.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/en-US/template.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+ <chapter id="">
+
+ </chapter>
Added: projects/docs/community/6/Security_Guide/pom.xml
===================================================================
--- projects/docs/community/6/Security_Guide/pom.xml (rev 0)
+++ projects/docs/community/6/Security_Guide/pom.xml 2010-09-14 20:27:04 UTC (rev 108142)
@@ -0,0 +1,115 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>org.jboss.jbossas</groupId>
+ <artifactId>security-guide-${translation}</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jdocbook</packaging>
+ <name>Security Guide (${translation})</name>
+
+ <distributionManagement>
+ <repository>
+ <id>docs.jboss.org</id>
+ <name>JBoss AS Doco Repo</name>
+ <url>sftp://jbossas@filemgmt.jboss.org:/docs_htdocs/jbossas/6/Security_Guide</url>
+ </repository>
+ </distributionManagement>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jdocbook-plugin</artifactId>
+ <version>2.1.2</version>
+ <extensions>true</extensions>
+ <dependencies>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-docbook-xslt</artifactId>
+ <version>1.1.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-jdocbook-style</artifactId>
+ <version>1.0.0</version>
+ <type>jdocbook-style</type>
+ </dependency>
+ </dependencies>
+ <configuration>
+ <!--minmemory>1024m</minmemory>
+ <maxmemory>1024m</maxmemory -->
+ <sourceDocumentName>Security_Guide.xml</sourceDocumentName>
+ <sourceDirectory>en-US</sourceDirectory>
+ <imageResource>
+ <directory>en-US</directory>
+ <includes>
+ <include>images/*</include>
+ </includes>
+ </imageResource>
+ <!-- <cssResource>
+ <directory>src/main/css</directory>
+ </cssResource> -->
+ <!--put back css -->
+
+ <formats>
+ <format>
+ <formatName>pdf</formatName>
+ <!--<stylesheetResource>classpath:/xslt/org/jboss/main-pdf.xsl</stylesheetResource>-->
+ <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
+ <finalName>Security_Guide.pdf</finalName>
+ </format>
+ <format>
+ <formatName>html</formatName>
+ <!--<stylesheetResource>classpath:/xslt/org/jboss/main-html.xsl</stylesheetResource>-->
+ <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+
+ <format>
+ <formatName>html_single</formatName>
+ <!--<stylesheetResource>classpath:/xslt/org/jboss/nochunk-html.xsl</stylesheetResource>-->
+ <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+
+ <!--<format>
+ <formatName>eclipse</formatName>
+ <stylesheetResource>classpath:/xslt/main-eclipse.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>-->
+ </formats>
+ <options>
+ <xincludeSupported>true</xincludeSupported>
+ <!-- <xmlTransformerType>saxon</xmlTransformerType>-->
+ <!-- needed for uri-resolvers; can be ommitted if using 'current' uri scheme -->
+ <!-- could also locate the docbook dependency and inspect its version... -->
+ <!--docbookVersion>1.72.0</docbookVersion -->
+ <!--
+ <docbookVersion>1.72.0</docbookVersion>
+ <transformerParameters>
+ <property>
+ <name>javax.xml.parsers.DocumentBuilderFactory</name>
+ <value>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</value>
+ </property>
+ <property>
+ <name>javax.xml.parsers.SAXParserFactory</name>
+ <value>org.apache.xerces.jaxp.SAXParserFactoryImpl</value>
+ </property>
+ -->
+ <!--<javax.xml.parsers.DocumentBuilderFactory>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</javax.xml.parsers.DocumentBuilderFactory>
+ <javax.xml.parsers.SAXParserFactory>org.apache.xerces.jaxp.SAXParserFactoryImpl</javax.xml.parsers.SAXParserFactory>
+ <javax.xml.validation.SchemaFactory:http\://www.w3.org/2001/XMLSchema>org.apache.xerces.jaxp.validation.XMLSchemaFactory</javax.xml.validation.SchemaFactory:http\://www.w3.org/2001/XMLSchema>-->
+ <!-- </transformerParameters> -->
+ </options>
+ </configuration>
+ </plugin>
+</plugins>
+</build>
+
+<properties>
+ <translation>en-US</translation>
+</properties>
+</project>
More information about the jboss-cvs-commits
mailing list