12:06 p.m.
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"/></par...
- <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