From do-not-reply at jboss.org Tue Nov 22 14:27:44 2011
Content-Type: multipart/mixed; boundary="===============8093796241112943855=="
MIME-Version: 1.0
From: do-not-reply at jboss.org
To: gatein-commits at lists.jboss.org
Subject: [gatein-commits] gatein SVN: r8120 -
 portal/trunk/docs/reference-guide/en-US/modules.
Date: Tue, 22 Nov 2011 14:27:44 -0500
Message-ID: <201111221927.pAMJRiNH010260@svn01.web.mwc.hst.phx2.redhat.com>

--===============8093796241112943855==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: mwringe
Date: 2011-11-22 14:27:43 -0500 (Tue, 22 Nov 2011)
New Revision: 8120

Modified:
   portal/trunk/docs/reference-guide/en-US/modules/WSRP.xml
Log:
GTNPORTAL-2267: initial reference guide documentation for ws-security suppo=
rt with wsrp.

Modified: portal/trunk/docs/reference-guide/en-US/modules/WSRP.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- portal/trunk/docs/reference-guide/en-US/modules/WSRP.xml	2011-11-22 17:=
09:45 UTC (rev 8119)
+++ portal/trunk/docs/reference-guide/en-US/modules/WSRP.xml	2011-11-22 19:=
27:43 UTC (rev 8120)
@@ -103,7 +103,8 @@
                   contains files necessary for EAR packaging. The only fil=
e that is of interest from a user perspective
                   is
                   <filename>gatein-wsse-consumer.xml</filename>
-                  which allows you to configure WS-Security support for th=
e consumer. !!!TODO mwringe please detail !!!!
+                  which allows you to configure WS-Security support for th=
e consumer. Please see the =

+                  <link linkend=3D"wss_configuration">WSRP and WS-Security=
</link> section for more details.
                </para>
             </listitem>
             <listitem>
@@ -143,8 +144,10 @@
             </listitem>
             <listitem>
                <para><filename>wsrp-producer-jb5wsss-$WSRP_VERSION.war</fi=
lename>, which contains the producer-side
-                  support for WS-Security. !!!!TODO mwringe: please detail=
 if there are any user-modifiable
-                  configuration file there and how this files is different=
 in AS 6 !!!!
+                  support for WS-Security. The only file of interest from =
a user perspective is =

+                  <filename>gatein-wsse-producer.xml</filename> which allo=
ws you to configure WS-Security support for =

+                  the producer. Please see the <link linkend=3D"wss_config=
uration">WSRP and WS-Security</link> section =

+                  for more details.
                </para>
             </listitem>
          </itemizedlist>
@@ -175,7 +178,10 @@
             to learn how to do so.
          </para>
       </sect2>
+   </sect1>
 =

+   <sect1>
+      <title>Securing WSRP</title>
       <sect2>
          <title>Considerations to use WSRP with SSL</title>
          <para>It is possible to use WSRP over SSL for secure exchange of =
data. Please refer to the
@@ -184,6 +190,121 @@
             <ulink url=3D"http://community.jboss.org/wiki/GateIn">GateIn's=
 wiki</ulink>.
          </para>
       </sect2>
+      <sect2>
+        <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 credential=
s from the consumer back to the producer in =

+              a safe and secure manner. The WSRP specification does not di=
rectly specify how this should be =

+              accomplished, but delegates this work to the existing WS-Sec=
urity standards.
+        </para>
+        <note>
+          <title>Web Container Compatibility</title>
+          <para>WSRP and WS-Security is currently only supported on &PRODU=
CT_NAME; when running on top of JBoss =

+                AS 5.
+          </para>
+        </note>
+        <warning>
+          <title>Encryption</title>
+          <para>You will want to encrypt the credentials being sent betwee=
n the consumer and producer, otherwise they =

+                will be sent in plain text and could be easily intercepted=
. You can either configure WS-Security to =

+                encrypt and sign the SOAP messages being sent, or secure t=
he transport layer by using an https endpoint. =

+                Failure to encrypt the soap message or transport layer wil=
l result in the username and password being =

+                sent in plain text. <emphasis role=3D"bold">Use of encrypt=
ion is strongly recommended.</emphasis>
+          </para>
+        </warning>
+        <important>
+          <title>Credentials</title>
+          <para>When the consumer sends the user credentials to the produc=
er, it is sending the credentials for the =

+                currently authenticated user in the consumer. This makes s=
igning in to remote portlets transparent =

+                to end users, but also requires that the producer and cons=
umer 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
+               see the user guide on how to configure ldap for use with &P=
RODUCT_NAME;
+         </para>
+        </important>
+        <para>The GateIn Wiki article, <ulink url=3D"http://community.jbos=
s.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>
+        <sect3 id=3D"wss_configuration">
+          <title>WS-Security Configuration</title>
+          <para>&PRODUCT_NAME; uses JBossWS Native to handle ws-security. =
Please see the WS-Security section of the =

+                <ulink url=3D"http://www.jboss.org/jbossas/docs/5-x">JBoss=
 AS 5 Administration and Configuration Guide
+                </ulink> for indepth configuration options. Please note th=
at since the consumer passes its credentials
+                to the producer, the consumer will act at the wss client a=
nd the producer will act as the wss server.
+          </para>
+          <para> The following are the JBossWS Native configuration files =
which need to be configure for WSRP:
+          </para>
+          <itemizedlist>
+            <listitem>
+              <para>
+                <filename>gatein-wsrp-integration.ear/META-INF/gatein-wsse=
-consumer.xml</filename>: JBossWS =

+                configuration file for the consumer.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <filename>gatein-wsrp-integration.ear/wsrp-producer-jb5wss=
.war/WEB-INF/conf/gatein-wsse-producer.xml
+                </filename>: JBossWS configuration file for the producer.
+              </para>
+            </listitem>
+          </itemizedlist>
+        </sect3>
+        <sect3>
+          <title>WS-Security Producer Configuration</title>
+          <para>
+            Other than the JBossWS configuration file mention above, no ot=
her configuration changes should be necessary =

+            for the producer.
+          </para>
+        </sect3>
+        <sect3>
+          <title>WS-Security Consumer Configuration</title>
+          <para>The consumer requires a few changes before it will functio=
n properly with WS-Security. The consumer =

+                needs access to the current servlet request since this is =
used to retrieve the currently authenticated =

+                user. In order for the consumer to access this information=
, it needs a special servlet-filter added to =

+                the portal.
+          </para>
+          <para>In <filename>gatein.ear/02portal.war/WEB-INF/web.xml</file=
name> add the following information:
+          </para>
+<programlisting role=3D"XML"><![CDATA[<!-- Filter to put request and respo=
nse in ServletAccess -->
+   <filter>
+      <filter-name>ServletAccessFilter</filter-name>
+      <filter-class>org.gatein.wsrp.servlet.ServletAccessFilter</filter-cl=
ass>
+   </filter>
+   <filter-mapping>
+      <filter-name>ServletAccessFilter</filter-name>
+      <url-pattern>/*</url-pattern>
+   </filter-mapping>]]>
+</programlisting>
+          <para>
+            Finally, in the WSRP Configuration portlet, in the consumer co=
nfiguration options, you will need to check the 'Enable WS Security' checkb=
ox:
+          </para>
+          <mediaobject>
+            <imageobject>
+              <imagedata fileref=3D"images/WSRP/config_wss_selected.png" f=
ormat=3D"PNG" align=3D"center" valign=3D"middle" scalefit=3D"1"/>
+            </imageobject>
+          </mediaobject>
+        </sect3>
+        <note>
+          <title>WS-Security Consumer Checklist</title>
+          <para>
+            In order for the consumer to handle ws-security, the following=
 steps must be completed properly
+          </para>
+          <itemizedlist>
+            <listitem>
+              <para>The JBossWS configuration files must be configured</pa=
ra>
+            </listitem>
+            <listitem>
+              <para>The filter must be added to the portal's web.xml</para>
+            </listitem>
+            <listitem>
+              <para>the enable wss feature must be check in the wsrp admin=
</para>
+            </listitem>
+          </itemizedlist>
+          <para>The consumer will not properly handle ws-security unless a=
ll 3 are properly configured</para>
+        </note>
+      </sect2>
    </sect1>
 =

    <sect1>


--===============8093796241112943855==--