From do-not-reply at jboss.org Tue Jan 29 11:07:56 2013 Content-Type: multipart/mixed; boundary="===============3915832714302936904==" MIME-Version: 1.0 From: do-not-reply at jboss.org To: gatein-commits at lists.jboss.org Subject: [gatein-commits] gatein SVN: r9086 - in epp/docs/branches/6.0/Reference_Guide/en-US: modules and 1 other directory. Date: Sat, 26 Jan 2013 13:06:10 -0500 Message-ID: <201301261806.r0QI6AP0019577@svn01.web.mwc.hst.phx2.redhat.com> --===============3915832714302936904== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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 =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 --- 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 @@ + +Server Integration + + Added: epp/docs/branches/6.0/Reference_Guide/en-US/modules/ServerIntegratio= n.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 (Binary files differ) Property changes on: epp/docs/branches/6.0/Reference_Guide/en-US/modules/Se= rverIntegration.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Modified: epp/docs/branches/6.0/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 --- 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 @@
<remark>BZ#856432</remark>Securing WSRP + There are two main ways to secure the communication between a pr= oducer and consumer: + + + + Securing the Transport Layer + = + This requires using SSL and a HTTPS endpoint. By using this, the= communication between the consumer and producer will be encrypted. + + + + + Securing the Contents of the SOAP m= essage + = + This option requires using ws-security to handle parts of the SO= AP message. With this option you can specify things like encryption, signin= g, 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 optio= ns, but is requires more complex configurations. + + + + Depending on requirements, an HTTPs endpoint or/and ws-security = can be used.
- Considerations to use WSRP with SSL + WSRP over SSL with HTTPS endpoints + It is possible to use WSRP over SSL for a secure exchange of data. S= ince 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 + JBoss AS documentat= ion + for how to configure HTTPS connectors for the server. + + + Once the producer is configured for HTTPS connections, on the consum= er you will just need to modify the URL for the WSRP endpoint to point to t= he new https based url. This will require either manually updating the valu= e in the WSRP admin application, or by specifying it using the + wsrp-consumers-config.xml + configuration file before the server is first started. + +
+ Sample Configuration For Enabling SSL With WSRP + + + This is just a simple, test configuration to be used as an examp= le 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 certi= ficates). Please see the + JBoss AS docume= ntation + for full configuration options. + + +
+ Configure the Producer to Use HTTPS + 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. + + + Generate the keystore for the producer + + keytool -genkey -alias tomcat -keyalg RSA = -keystore producerhttps.keystore -dname "cn=3Dlocalhost" -keypass= changeme -storepass changeme + + + + + Configure the server to add an https connection. This requir= es modifying the + standalone/configuration/standalo= ne.xml + file with the following content in bold: + + + + ... + = + <subsystem xmlns=3D"urn:jboss:domain:web:1.1"= default-virtual-server=3D"default-host" native=3D"false&quo= t;> + = + <connector name=3D"http" protocol=3D"HTT= P/1.1" scheme=3D"http" socket-binding=3D"http"/> + = + <connector name=3D"https= " protocol=3D"HTTP/1.1" scheme=3D"https" socket-bi= nding=3D"https" secure=3D"true"> + = + <ssl certificate-key-file=3D&= quot;/path/to/producerhttps.keystore" password=3D"changeme"/= > + = + </connector> + = + <virtual-server name=3D"default-host" enable-= welcome-root=3D"true"> + = + <alias name=3D"localhost"/> + = + <alias name=3D"example.com"/> + = + </virtual-server> + = + ... + + + + + + Start the server and verify that + + is accessible. Note that since you are using a self-signed c= ertificate that your browser will give a warning that the certificate canno= t be trusted. + + + In this example case we are accessing the portal usi= ng 'localhost' hence why we are using "cn=3Dlocalhost" = in the keytool command. If you are using this across another domain, you wi= ll need to make the necessary change. + + + +
+
+ Configure the Consumer to Access the WSRP Endpoint over H= TTPS + Ideally we should be able to just change the URL for the p= roducer in the wsrp admin to use https, but we need to tell the consumer&ap= os;s server to trust our self-signed certificate first. + + + Export the producer's public key from the produce= r's keystore + + keytool -export -alias tomcat -file produc= erkey.rsa -keystore producerhttps.keystore -storepass changeme + + + + Import the producer's public key into a new keyst= ore for the consumer + + keytool -import -alias tomcat -file produc= erkey.rsa -keystore consumerhttps.keystore -storepass changeme -noprompt + + + + + Configure the + bin/standalone.conf + file to add the following line at the end of the file: + + + JAVA_OPTS=3D"$JAVA_OPTS -Djavax.net.s= sl.trustStore=3D/path/to/consumerhttps.keystore -Djavax.net.ssl.trustStoreP= assword=3Dchangeme" + + + + + Start the consumer and change the selfv2 producer url to + + and verify that the consumer can access the producer. + + + + + + It is also possible to modify the + wsrp-consumers-config.xml + configuration file to change the URL instead of modifying it i= n the admin gui + + + It is possible to use WSRP over SSL for secure exchange of data. Con= figure your server appriopriately as described in the HTTPS Conf= iguration section of the Installation Guide. +
+
WSRP and WS-Security Portlets may present different data or options depending on th= e 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. + accomplished, but delegates this work to the existing WS-Sec= urity standards. The WS-Security standards can also be used to secure the s= oap message, such as encryption and signing the message. Web Container Compatibility @@ -194,48 +328,53 @@ sent in plain text. Use of encrypt= ion is strongly recommended. - - Credentials - When the consumer sends the user credentials to the producer= , it is sending the credentials for the +
+
+ Credentials + 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 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. - The recommended approach for this situation would be to use = a common LDAP configuration. Please + 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 JB= oss Portal Platform - - The GateIn Wiki article, GateIn WSRP and Web Service Secu= rity, also provides a step-by-step example on how to configure - WSRP with WS-Security. -
<remark>BZ#839355</remark>WS-Security Configuration - -JBoss Portal Platform uses JBossWS CXF instead of the JBossWS Native to= handle ws-security. Due to these changes, the configuration for WS-Securit= y with JBoss Portal Platform on JBoss Enterprise Application Platform is c= hanged. - - We only support one ws-security configuration option for t= he producer. All consumers accessing the producer will have to conform to t= his security constraint. This means if the producer requires encryption, al= l consumers will be required to encrypt their messages when accessing the p= roducer. - +
+ Introduction + 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-Securi= ty for WSRP with GateIn Portal on JBossAS 7 has changed. + + 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. + We only support one ws-security configuration option to = be used by all the consumers. A consumer has the option to enable or disabl= e ws-security, which allows for one or more consumers to use ws-security wh= ile the others do not. + +
+
+ Overview + CXF uses interceptors to extend and configure its behaviou= r. There are two main types of interceptors: inInterceptors and outIntercep= tors. InInterceptors are invoked for communication coming into the client o= r server, while outInterceptors are invoked when the client or server sends= a message. + So for the WSRP case, the communication from the consumer = to the producer is governed by the consumer's OutInterceptor and the p= roducer's InIntereceptor. The communication from the producer to the c= onsumer is governed by the producer's OutInterceptor and the consumer&= apos;s InInterceptor. This may mean having to configure 4 Interceptors. + + When dealing with WS-Security, there are some things to = consider here: + + + When dealing with user propagation, only the consume= r sends the user credentials to the producer. So Username Tokens only need = to be configured for the consumer's OutInterceptor and the producer&ap= os;s InInterceptor. + + + + + When dealing with things like encryption, you will m= ost likely want to encrypt the message from the consumer to the producer an= d also the message from the producer to the consumer. This means that encry= ption properties must be configured for all 4 interceptors. + + + -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, whi= ch allows for one or more consumers to use ws-security while the others do = not. - - Note that since the consumer passes its credentials to the p= roducer, the consumer acts as the wss client and the producer acts as the w= ss server. - - CXF uses interceptors to extend and configure its behaviour.= There are two main types of interceptors: inInterceptors and outIntercepto= rs. - InInterceptors are invoked for communication coming into the= client or server, while outInterceptors are invoked when the client or ser= ver sends a message. - -So for the WSRP, the communication from the consumer to the producer is g= overned by the consumer's OutInterceptor and the producer's InInt= ereceptor. - The communication from the producer to the consumer is gover= ned by the producer's OutInterceptor and the consumer's InInterce= ptor. This means having to configure four Interceptors. - Important points to be considered while dealing with WS-Secu= rity - - - In case of user propagation, only the consumer sends the= user credentials to the producer. So Username Tokens only need to be confi= gured for the consumer's OutInterceptor and the producer's InInte= rceptor. - For encryption, you will most likely want to encrypt the= message from the consumer to the producer and also the message from the pr= oducer to the consumer. This means that encryption properties must be confi= gured for all four interceptors. - - - For more details on types of interceptors refer - - To support ws-security, JBoss Portal Platform uses CXF'= s WSS4J Interceptors which handle all ws-security related tasks, for more d= etails on CXF documentation refer - = + Please see the CXF Documentation for more details on interceptor= s and their types: + + + + To support ws-security, GateIn Portal uses CXF's WSS4J Inte= rceptors which handle all ws-security related tasks. Please see the CXF Doc= umentation for more details: + + +
WSS4J Interceptors and WSRP @@ -295,12 +434,11 @@
<remark>BZ#839355</remark>WS-Security Consumer Configuratio= n - To configure ws-security on the consumer side, configure the= WSS4JInInterceptor and/or WSS4JOutInterceptor. - In the WSRP Configuration portlet Consumers Config= uration options, check the 'Enable WS Security' check= box if you want credentials to be sent to the producer. - - - You do not need to enable this option if you want to use w= s-security to encrypt the communication between the producer and consumer = only, and not use it for identity propagation. - + + In order to configure ws-security on the consumer side, you will h= ave to configure the WSS4J Interceptors as seen above. This will require ha= ving to configure the WSS4JInInterceptor and/or WSS4JOutInterceptor. + = + You will also need to check the 'Enable WS-Security' che= ckbox on the WSRP Admin Portlet for the consumer configuration to take effe= ct. + @@ -335,11 +473,9 @@
-
- WS-Security Producer Configuration - -The configuration of the producer is similar to that of the consumer. It a= lso requires having to configure the WSS4JInInterceptor and/or WSS4JOutInte= rceptor. - +
+ Producer Configuration + The configuration of the producer is similar to that of the = consumer. It also requires having to configure the WSS4JInInterceptor and/o= r WSS4JOutInterceptor.
Special GateIn Portal Configuration Options for User Prop= agation @@ -360,7 +496,7 @@ When this option is activated, the interceptor will set th= e action to 'UsernameToken' when the received SOAP message contai= ns 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 fo= r dealing with authenticated and unauthentcated users trying to access the = producer.
-
+
Sample Configuration using the UsernameToken and User Propa= gation This example configuration does not encrypt the message. T= his means the username and password will be sent between the producer and c= onsumer in plain text. This is a security concern and is only being shown a= s a simple example. It is up to administrators to properly configure the WS= S4J Interceptors to encrypt messages or to only use https communication bet= ween the producer and consumer. @@ -388,19 +524,6 @@ start the producer server -
- Sample Configuration Securing the Endpoints using Encry= ption and Signing - The following steps outline how to configure the produce= r and consumer to encrypt and sign SOAP messages passed between the produce= r and consumer. This example only deals with SOAP messages being sent betwe= en the producer and consumer, and not with user propagation. - - - Some of the configuration options specified here are based on = the content at - - and - - More information may be available at these sites. - - -
Consumer Setup @@ -436,7 +559,7 @@
-
+
Sample Configuration Securing the Endpoints using Encryptio= n and Signing The following steps outline how to configure the producer an= d consumer to encrypt and sign SOAP messages passed between the producer an= d consumer. This example only deals with SOAP messages being sent between t= he producer and consumer, and not with user propagation. @@ -460,7 +583,6 @@ 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 @@ Configure the Producer Follow the steps outlined in the - Sample Configuration Securing the Endpoints using Encryption a= nd Signing + Sample Configuration Securin= g the Endpoints using Encryption and Signing section but make the following changes: @@ -724,11 +846,11 @@
-
+
Configure the Consumer Follow the steps outlined in the - Sample Configuration Securing the Endpoints using Encryption a= nd Signing + Sample Configuration Securin= g the Endpoints using Encryption and Signing section but make the following changes: @@ -1864,7 +1986,7 @@ If you deployed the example RegistrationPolicy provided from the github repository (registration-policy-ex= ample.wsrp.jar) to the JPP_HOME/gatein/extensions directory, it will appear in the list of available policies in the = producer configuration screen.
-
+
WSRP validation mode The lack of conformance kit, and the wording of the WSRP speci= fication leaves room for differing interpretations, resulting in interoperability issues. It is t= herefore possible to encounter issues when @@ -1994,7 +2116,7 @@ -
+
Example ./standalone.sh -Dorg.gatein.wsrp.consumer.han= dlers.delegate=3Dcom.example.FooInvocationHandlerDelegate @@ -2008,7 +2130,7 @@
-
+
Accessing extensions from client code You can access extensions from client code using --===============3915832714302936904==--