[gatein-commits] gatein SVN: r9086 - in epp/docs/branches/6.0/Reference_Guide/en-US: modules and 1 other directory.
do-not-reply at jboss.org
do-not-reply at jboss.org
Sat Jan 26 13:06:10 EST 2013
Author: aakanksha_writer
Date: 2013-01-26 13:06:09 -0500 (Sat, 26 Jan 2013)
New Revision: 9086
Added:
epp/docs/branches/6.0/Reference_Guide/en-US/modules/ServerIntegration.xml
Modified:
epp/docs/branches/6.0/Reference_Guide/en-US/Reference_Guide.xml
epp/docs/branches/6.0/Reference_Guide/en-US/modules/WSRP.xml
Log:
Updated chapters WSRP Security and Server Integration
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Reference_Guide.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/Reference_Guide.xml 2013-01-25 05:36:48 UTC (rev 9085)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/Reference_Guide.xml 2013-01-26 18:06:09 UTC (rev 9086)
@@ -30,4 +30,8 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/Advanced.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/eXoJCR.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/>
+<part>
+<title>Server Integration</title>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/ServerIntegration.xml"/>
+</part>
</book>
Added: epp/docs/branches/6.0/Reference_Guide/en-US/modules/ServerIntegration.xml
===================================================================
(Binary files differ)
Property changes on: epp/docs/branches/6.0/Reference_Guide/en-US/modules/ServerIntegration.xml
___________________________________________________________________
Added: svn:mime-type
+ application/xml
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/WSRP.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/modules/WSRP.xml 2013-01-25 05:36:48 UTC (rev 9085)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/WSRP.xml 2013-01-26 18:06:09 UTC (rev 9086)
@@ -166,18 +166,152 @@
</section>
<section>
<title><remark>BZ#856432</remark>Securing WSRP</title>
+ <para>There are two main ways to secure the communication between a producer and consumer:</para>
+ <orderedlist>
+ <listitem>
+ <para>
+ <emphasis role="underline">Securing the Transport Layer</emphasis>
+
+ This requires using SSL and a HTTPS endpoint. By using this, the communication between the consumer and producer will be encrypted.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="underline">Securing the Contents of the SOAP message</emphasis>
+
+ This option requires using ws-security to handle parts of the SOAP message. With this option you can specify things like encryption, signing, timestamps, etc as well as passing across user credentials to perform a login on the producer side. WS-Security is more powerful and has more options, but is requires more complex configurations.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>Depending on requirements, an HTTPs endpoint or/and ws-security can be used.</para>
<section>
- <title>Considerations to use WSRP with SSL</title>
+ <title>WSRP over SSL with HTTPS endpoints</title>
<para>
+ It is possible to use WSRP over SSL for a secure exchange of data. Since GateIn Portal does not come initially configured for HTTPS connectors, we will need to configure the producer's server for this first. This is a global configuration change to JBoss AS and will affect more than just GateIn Portal and WSRP. Please see the
+ <ulink url="http://www.jboss.org/jbossas/docs">JBoss AS documentation</ulink>
+ for how to configure HTTPS connectors for the server.
+ </para>
+ <para>
+ Once the producer is configured for HTTPS connections, on the consumer you will just need to modify the URL for the WSRP endpoint to point to the new https based url. This will require either manually updating the value in the WSRP admin application, or by specifying it using the
+ <emphasis role="italics">wsrp-consumers-config.xml</emphasis>
+ configuration file before the server is first started.
+ </para>
+ <section id="sid-54264620_SecuringWSRP-SampleConfigurationForEnablingSSLWithWSRP">
+ <title>Sample Configuration For Enabling SSL With WSRP</title>
+ <warning>
+ <para>
+ This is just a simple, test configuration to be used as an example as to how its possible to setup the https/ssl with wsrp. It is not meant to show best practices for configuring https with JBoss AS and does things which should not be used in a production server (such as self-signed certificates). Please see the
+ <ulink url="http://www.jboss.org/jbossas/docs">JBoss AS documentation</ulink>
+ for full configuration options.
+ </para>
+ </warning>
+ <section id="sid-54264620_SecuringWSRP-ConfiguretheProducertoUseHTTPS">
+ <title>Configure the Producer to Use HTTPS</title>
+ <para>First we will need to configure the producer's server to use https. This is handled in the same manner that you would configure any JBoss AS server for HTTPS.</para>
+ <orderedlist>
+ <listitem>
+ <para>Generate the keystore for the producer</para>
+ <informalexample>
+ <programlisting>keytool -genkey -alias tomcat -keyalg RSA -keystore producerhttps.keystore -dname "cn=localhost" -keypass changeme -storepass changeme</programlisting>
+ </informalexample>
+ </listitem>
+ <listitem>
+ <para>
+ Configure the server to add an https connection. This requires modifying the
+ <emphasis role="italics">standalone/configuration/standalone.xml</emphasis>
+ file with the following content in bold:
+ </para>
+ <sidebar>
+ <para>
+ ...
+
+ <subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false">
+
+ <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
+
+ <emphasis role="strong"><connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" secure="true"></emphasis>
+
+ <emphasis role="strong"><ssl certificate-key-file="/path/to/producerhttps.keystore" password="changeme"/></emphasis>
+
+ <emphasis role="strong"></connector></emphasis>
+
+ <virtual-server name="default-host" enable-welcome-root="true">
+
+ <alias name="localhost"/>
+
+ <alias name="example.com"/>
+
+ </virtual-server>
+
+ ...
+ </para>
+ </sidebar>
+ </listitem>
+ <listitem>
+ <para>
+ Start the server and verify that
+ <ulink url="https://localhost:8443/portal"/>
+ is accessible. Note that since you are using a self-signed certificate that your browser will give a warning that the certificate cannot be trusted.
+ </para>
+ <note>
+ <para>In this example case we are accessing the portal using 'localhost' hence why we are using "cn=localhost" in the keytool command. If you are using this across another domain, you will need to make the necessary change.</para>
+ </note>
+ </listitem>
+ </orderedlist>
+ </section>
+ <section id="sid-54264620_SecuringWSRP-ConfiguretheConsumertoAccesstheWSRPEndpointoverHTTPS">
+ <title>Configure the Consumer to Access the WSRP Endpoint over HTTPS</title>
+ <para>Ideally we should be able to just change the URL for the producer in the wsrp admin to use https, but we need to tell the consumer's server to trust our self-signed certificate first.</para>
+ <orderedlist>
+ <listitem>
+ <para>Export the producer's public key from the producer's keystore</para>
+ <informalexample>
+ <programlisting>keytool -export -alias tomcat -file producerkey.rsa -keystore producerhttps.keystore -storepass changeme</programlisting>
+ </informalexample>
+ </listitem>
+ <listitem>
+ <para>Import the producer's public key into a new keystore for the consumer</para>
+ <informalexample>
+ <programlisting>keytool -import -alias tomcat -file producerkey.rsa -keystore consumerhttps.keystore -storepass changeme -noprompt</programlisting>
+ </informalexample>
+ </listitem>
+ <listitem>
+ <para>
+ Configure the
+ <emphasis role="italics">bin/standalone.conf</emphasis>
+ file to add the following line at the end of the file:
+ </para>
+ <informalexample>
+ <programlisting>JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=/path/to/consumerhttps.keystore -Djavax.net.ssl.trustStorePassword=changeme"</programlisting>
+ </informalexample>
+ </listitem>
+ <listitem>
+ <para>
+ Start the consumer and change the selfv2 producer url to
+ <ulink url="https://localhost:8443/wsrp-producer/v2/MarkupService?wsdl"/>
+ and verify that the consumer can access the producer.
+ </para>
+ </listitem>
+ </orderedlist>
+ <note>
+ <para>
+ It is also possible to modify the
+ <emphasis role="italics">wsrp-consumers-config.xml</emphasis>
+ configuration file to change the URL instead of modifying it in the admin gui
+ </para>
+ </note>
+ <para>
It is possible to use WSRP over SSL for secure exchange of data. Configure your server appriopriately as described in the <citetitle>HTTPS Configuration</citetitle> section of the <citetitle>Installation Guide</citetitle>.
</para>
+ </section>
+ </section>
</section>
<section>
<title>WSRP and WS-Security</title>
<para>Portlets may present different data or options depending on the currently authenticated user. For remote
portlets, this means having to propagate the user credentials from the consumer back to the producer in
a safe and secure manner. The WSRP specification does not directly specify how this should be
- accomplished, but delegates this work to the existing WS-Security standards.
+ accomplished, but delegates this work to the existing WS-Security standards. The WS-Security standards can also be used to secure the soap message, such as encryption and signing the message.
</para>
<note>
<title>Web Container Compatibility</title>
@@ -194,48 +328,53 @@
sent in plain text. <emphasis role="bold">Use of encryption is strongly recommended.</emphasis>
</para>
</warning>
- <important>
- <title>Credentials</title>
- <para>When the consumer sends the user credentials to the producer, it is sending the credentials for the
+ </section>
+ <section>
+ <title>Credentials</title>
+ <para>When the consumer sends the user credentials to the producer, it is sending the credentials for the
currently authenticated user in the consumer. This makes signing in to remote portlets transparent
to end users, but also requires that the producer and consumer use the same credentials. This means
that the username and password must be the same and valid on both servers.
</para>
- <para>The recommended approach for this situation would be to use a common LDAP configuration. Please
+ <para>The recommended approach for this situation would be to use a common LDAP configuration. Please
see the user guide on how to configure LDAP for use with JBoss Portal Platform
</para>
- </important>
- <para>The GateIn Wiki article, <ulink url="http://community.jboss.org/wiki/GateInWSRPAndWebServiceSecurity"> GateIn WSRP and Web Service Security</ulink>, also provides a step-by-step example on how to configure
- WSRP with WS-Security.
- </para>
<section id="wss_configuration">
<title><remark>BZ#839355</remark>WS-Security Configuration</title>
- <para>
-JBoss Portal Platform uses JBossWS CXF instead of the JBossWS Native to handle ws-security. Due to these changes, the configuration for WS-Security with JBoss Portal Platform on JBoss Enterprise Application Platform is changed. </para>
- <note>
- <para>We only support one ws-security configuration option for the producer. All consumers accessing the producer will have to conform to this security constraint. This means if the producer requires encryption, all consumers will be required to encrypt their messages when accessing the producer.
-</para>
+ <section id="sid-54264620_SecuringWSRP-Introduction">
+ <title>Introduction</title>
+ <para>JBoss AS7 uses a different web service implementation than the previous versions: it is now uses the JBossWS CXF Stack instead of the JBossWS Native Stack. Due to these changes, the way we configure WS-Security for WSRP with GateIn Portal on JBossAS 7 has changed.</para>
+ <note>
+ <para>We only support one ws-security configuration option for the producer. All consumers accessing the producer will have to conform to this security constraint. This means if the producer requires encryption, all consumers will be required to encrypt their messages when accessing the producer.</para>
+ <para>We only support one ws-security configuration option to be used by all the consumers. A consumer has the option to enable or disable ws-security, which allows for one or more consumers to use ws-security while the others do not.</para>
+ </note>
+ </section>
+ <section id="sid-54264620_SecuringWSRP-Overview">
+ <title>Overview</title>
+ <para>CXF uses interceptors to extend and configure its behaviour. There are two main types of interceptors: inInterceptors and outInterceptors. InInterceptors are invoked for communication coming into the client or server, while outInterceptors are invoked when the client or server sends a message.</para>
+ <para>So for the WSRP case, the communication from the consumer to the producer is governed by the consumer's OutInterceptor and the producer's InIntereceptor. The communication from the producer to the consumer is governed by the producer's OutInterceptor and the consumer's InInterceptor. This may mean having to configure 4 Interceptors.</para>
+ <note>
+ <para>When dealing with WS-Security, there are some things to consider here:</para>
+ <orderedlist>
+ <listitem>
+ <para>When dealing with user propagation, only the consumer sends the user credentials to the producer. So Username Tokens only need to be configured for the consumer's OutInterceptor and the producer's InInterceptor.</para>
+ </listitem>
+ </orderedlist>
+ <orderedlist>
+ <listitem>
+ <para>When dealing with things like encryption, you will most likely want to encrypt the message from the consumer to the producer and also the message from the producer to the consumer. This means that encryption properties must be configured for all 4 interceptors.</para>
+ </listitem>
+ </orderedlist>
+ </note>
<para>
-We only support one ws-security configuration option to be used by all the consumers. A consumer has the option to enable or disable ws-security, which allows for one or more consumers to use ws-security while the others do not.</para>
- </note>
- <para>Note that since the consumer passes its credentials to the producer, the consumer acts as the wss client and the producer acts as the wss server.
- </para>
- <para>CXF uses interceptors to extend and configure its behaviour. There are two main types of interceptors: inInterceptors and outInterceptors. </para>
- <para>InInterceptors are invoked for communication coming into the client or server, while outInterceptors are invoked when the client or server sends a message.
-
-So for the WSRP, the communication from the consumer to the producer is governed by the consumer's OutInterceptor and the producer's InIntereceptor. </para>
- <para>The communication from the producer to the consumer is governed by the producer's OutInterceptor and the consumer's InInterceptor. This means having to configure four Interceptors.</para>
- <para>Important points to be considered while dealing with WS-Security</para>
- <itemizedlist>
- <listitem>
- <para>In case of user propagation, only the consumer sends the user credentials to the producer. So Username Tokens only need to be configured for the consumer's OutInterceptor and the producer's InInterceptor.</para>
- <para>For encryption, you will most likely want to encrypt the message from the consumer to the producer and also the message from the producer to the consumer. This means that encryption properties must be configured for all four interceptors.</para>
- </listitem>
- </itemizedlist>
- <para>For more details on types of interceptors refer</para>
- <para><ulink url="http://cxf.apache.org/docs/interceptors.html"/></para>
- <para>To support ws-security, JBoss Portal Platform uses CXF's WSS4J Interceptors which handle all ws-security related tasks, for more details on CXF documentation refer</para>
- <para><ulink url="http://cxf.apache.org/docs/ws-security.html"/></para>
+ Please see the CXF Documentation for more details on interceptors and their types:
+ <ulink url="http://cxf.apache.org/docs/interceptors.html"/>
+ </para>
+ <para>
+ To support ws-security, GateIn Portal uses CXF's WSS4J Interceptors which handle all ws-security related tasks. Please see the CXF Documentation for more details:
+ <ulink url="http://cxf.apache.org/docs/ws-security.html"/>
+ </para>
+ </section>
</section>
<section>
<title>WSS4J Interceptors and WSRP</title>
@@ -295,12 +434,11 @@
</section>
<section>
<title><remark>BZ#839355</remark>WS-Security Consumer Configuration</title>
- <para>To configure ws-security on the consumer side, configure the WSS4JInInterceptor and/or WSS4JOutInterceptor.</para>
- <para>In the WSRP Configuration portlet <guilabel>Consumers Configuration</guilabel> options, check the 'Enable WS Security' checkbox if you want credentials to be sent to the producer.
- </para>
- <note>
- <para>You do not need to enable this option if you want to use ws-security to encrypt the communication between the producer and consumer only, and not use it for identity propagation.</para>
- </note>
+ <para>
+ In order to configure ws-security on the consumer side, you will have to configure the WSS4J Interceptors as seen above. This will require having to configure the WSS4JInInterceptor and/or WSS4JOutInterceptor.
+
+ You will also need to check the 'Enable WS-Security' checkbox on the WSRP Admin Portlet for the consumer configuration to take effect.
+ </para>
<mediaobject>
<imageobject>
<imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_wss_selected.png" format="PNG"/>
@@ -335,11 +473,9 @@
</section>
</section>
</section>
- <section>
- <title>WS-Security Producer Configuration</title>
- <para>
-The configuration of the producer is similar to that of the consumer. It also requires having to configure the WSS4JInInterceptor and/or WSS4JOutInterceptor.
- </para>
+ <section id="sid-54264620_SecuringWSRP-ProducerConfiguration">
+ <title>Producer Configuration</title>
+ <para>The configuration of the producer is similar to that of the consumer. It also requires having to configure the WSS4JInInterceptor and/or WSS4JOutInterceptor.</para>
<section>
<title>Special GateIn Portal Configuration Options for User Propagation</title>
<para>
@@ -360,7 +496,7 @@
<para>When this option is activated, the interceptor will set the action to 'UsernameToken' when the received SOAP message contains ws-security headers. If no ws-security header is included in the message, then no action is taken and the interceptor is not run. This is useful for dealing with authenticated and unauthentcated users trying to access the producer.</para>
</section>
</section>
- <section>
+ <section id="sid-54264620_SecuringWSRP-SampleConfigurationusingtheUsernameTokenandUserPropagation">
<title>Sample Configuration using the UsernameToken and User Propagation</title>
<warning>
<para>This example configuration does not encrypt the message. This means the username and password will be sent between the producer and consumer in plain text. This is a security concern and is only being shown as a simple example. It is up to administrators to properly configure the WSS4J Interceptors to encrypt messages or to only use https communication between the producer and consumer.</para>
@@ -388,19 +524,6 @@
<para>start the producer server</para>
</listitem>
</orderedlist>
- <section>
- <title>Sample Configuration Securing the Endpoints using Encryption and Signing</title>
- <para>The following steps outline how to configure the producer and consumer to encrypt and sign SOAP messages passed between the producer and consumer. This example only deals with SOAP messages being sent between the producer and consumer, and not with user propagation.</para>
- <note>
- <para>
- Some of the configuration options specified here are based on the content at
- <ulink url="http://cxf.apache.org/docs/ws-security.html"/>
- and
- <ulink url="http://www.jroller.com/gmazza/entry/cxf_x509_profile"/>
- More information may be available at these sites.
- </para>
- </note>
- </section>
</section>
<section>
<title>Consumer Setup</title>
@@ -436,7 +559,7 @@
</orderedlist>
</section>
</section>
- <section>
+ <section id="sid-54264620_SecuringWSRP-SampleConfigurationSecuringtheEndpointsusingEncryptionandSigning">
<title>Sample Configuration Securing the Endpoints using Encryption and Signing</title>
<para>The following steps outline how to configure the producer and consumer to encrypt and sign SOAP messages passed between the producer and consumer. This example only deals with SOAP messages being sent between the producer and consumer, and not with user propagation.</para>
<note>
@@ -460,7 +583,6 @@
<programlisting>package test;
 
import java.io.IOException;
- 
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
@@ -690,7 +812,7 @@
<title>Configure the Producer</title>
<para>
Follow the steps outlined in the
- Sample Configuration Securing the Endpoints using Encryption and Signing
+ <link linkend="sid-54264620_SecuringWSRP-SampleConfigurationSecuringtheEndpointsusingEncryptionandSigning">Sample Configuration Securing the Endpoints using Encryption and Signing</link>
section but make the following changes:
</para>
<orderedlist>
@@ -724,11 +846,11 @@
</listitem>
</orderedlist>
</section>
- <section id="sid-54264620_SecuringWSRP-ConfiguretheConsumer">
+ <section>
<title>Configure the Consumer</title>
<para>
Follow the steps outlined in the
- Sample Configuration Securing the Endpoints using Encryption and Signing
+ <link linkend="sid-54264620_SecuringWSRP-SampleConfigurationSecuringtheEndpointsusingEncryptionandSigning">Sample Configuration Securing the Endpoints using Encryption and Signing</link>
section but make the following changes:
</para>
<orderedlist>
@@ -1864,7 +1986,7 @@
<para>If you deployed the example <literal>RegistrationPolicy</literal> provided from the github repository (<filename>registration-policy-example.wsrp.jar</filename>) to the <filename>JPP_HOME/gatein/extensions</filename> directory, it will appear in the list of available policies in the producer configuration screen.</para>
</section>
</section>
- <section id="strict-mode">
+ <section>
<title>WSRP validation mode</title>
<para>The lack of conformance kit, and the wording of the WSRP specification leaves room for differing
interpretations, resulting in interoperability issues. It is therefore possible to encounter issues when
@@ -1994,7 +2116,7 @@
</tbody>
</tgroup>
</informaltable>
- <section id="sid-55477864_WorkingwithWSRPextensions-Example">
+ <section>
<title>Example</title>
<informalexample>
<programlisting>./standalone.sh -Dorg.gatein.wsrp.consumer.handlers.delegate=com.example.FooInvocationHandlerDelegate</programlisting>
@@ -2008,7 +2130,7 @@
</para>
</section>
</section>
- <section id="sid-55477864_WorkingwithWSRPextensions-Accessingextensionsfromclientcode">
+ <section>
<title>Accessing extensions from client code</title>
<para>
You can access extensions from client code using
More information about the gatein-commits
mailing list