{section}
{column}
This document contains all the use cases related to the Petals-BC-SOAP component.
Use cases are ordered by their complexity, from the most simple to the most complex ones.
h1. Simple Use Cases
h2. Proxy SOAP using SSL et WS-Security
{tip}This use case runs with the Petals BC SOAP 5.0.0+. Its source code is available [here|https://svn.petalslink.org/svnroot/branches-legacy/petals-samples-soap-5.0.x].{tip}
The goal of this use-case is to show you how to configure the service units of BS Soap on both sides:
* to import into Petals, an external service secured with WS-Security,
* to export to outside an internal Petals service, secured with SSL and WS-Security.
{code}
|--------------------|
|---------| HTTP/HTTPS |----------------------| HTTP | External |
| SOAP UI |-------------------------| Petals ESB |-------------------------| service provider |
|---------| WS-Security |----------------------| WS-Security |--------------------|
{code}
The WS-Security parts will be based on:
* a time-stamp to avoid request re-injection, for the Petals service consumer re-exposing the external service provider. No timestamp used for the external service provider.
* and authentication based on username and password:
** for the external service provider: `user/petals`
** for Petals service consumer re-exposing the external service provider to outside: `user-petals/petals`
This sample using SSL requires the following key stores:
* a key store 'external': keystore-external.jks (password: keystoreextpwd), containing the private and public key of the external service provider. The private key is protected by the password `keyextpwd`,
* a key store 'petals': keystore-petals.jks (password: keystorepetals), containing the private and public key of Petals service consumer re-exposing the external service provider to outside.
{column}
{column:width=35%}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list|showAnonymous=true|showCount=true|showLastTime=true}{panel}
{column}
{section}
h3. About the external service provider
An external service provider 'ArticleServiceContinuation' is available as [CXF webservice secured by WSS|https://svn.petalslink.org/svnroot/branches-legacy/petals-samples-soap-5.0.x/cxf-server] at [http://localhost:8450/articleServiceWSS_UsernameToken?wsdl].
To start it, just execute the following Maven command line in its directory project:
{code}
mvn clean verify exec:java
{code}
h3. About the proxified service provider
The proxified service provider is the Petals service consumer re-exposing the external service provider to outside.
The external service is re-exposed in 4 ways:
* with protocol HTTP and without WS-Security enabled,
* with protocol HTTP and WS-Security enabled,
* with protocol HTTPS and without WS-Security enabled,
* with protocol HTTPS and WS-Security enabled,
h3. Generate the key store 'Petals'
A specific keystore 'Petals' containing the private/public key pair of the proxified service provider to configure its SSL part is needed, and can be generated with the following command line:
{code}
keytool -genkey -alias petals-service-provider -keyalg RSA -keysize 2048 \
-dname "CN=SSL Proxyfied Service Provider, OU=Petals, O=Linagora, L=Grasse, ST=AM, C=FR" \
-storetype PKCS12 -storepass keystorepetalspwd -keystore /tmp/keystore-petals.pfx
{code}
h3. Configure SSL at Petals BC Soap level
Not only, SSL is configured at Petals BC Soap level, but also at service consumer level:
* at component level to inject the keystore configuration through the installation parameters:
** `https-keystore-file`: The keystore file generated as described below,
** `https-keystore-password`: The keystore file password,
** `https-key-password`: the private key password.
* at service consumer level to define which transport (http, https or jms) must be used to expose the service provider.
h3. Running the use case
Launch a freshly installed Petals ESB:
{code}
~/petals-esb-default-zip-5.2.0/bin$ ./petals-esb.sh
___ ____ __ ___ __ ____ ____ ____ ___
/ _ \ / __// /_ / _ | / / / __/ / __// __// _ )
/ ___// _/ / __// __ | / /__ _\ \ / _/ _\ \ / _ |
/_/ /___/ \__//_/ |_|/____//___/ /___//___//____/
Initializing logging subsystem
2024/02/19 11:12:26,005 GMT+0100 INFO [Petals.Launcher] : Logging system initialised
2024/02/19 11:12:26,016 GMT+0100 INFO [Petals.Launcher] : Initializing container's classloader...
2024/02/19 11:12:26,040 GMT+0100 INFO [Petals.Launcher] : Initializing server...
2024/02/19 11:12:26,529 GMT+0100 INFO [Petals.Launcher] : Starting server...
sample-0 2024/02/19 11:12:26,538 GMT+0100 INFO [Petals.System.Extensions.PreExtensionsManager] : Pre-extension found but not activated: Petals Embedded Registry Overlay
sample-0 2024/02/19 11:12:26,669 GMT+0100 INFO [Petals.Communication.RMIConnector] : JMX RMI server started at : service:jmx:rmi:///jndi/rmi://localhost:7700/PetalsJMX
sample-0 2024/02/19 11:12:26,684 GMT+0100 INFO [Petals.Communication.TopologyService] : Using standalone shared area implementation for static one-container domain: org.ow2.petals.microkernel.communication.sharedarea.StandaloneSharedAreaImpl
sample-0 2024/02/19 11:12:26,709 GMT+0100 INFO [Petals.Communication.TopologyService] : Shared area loaded
sample-0 2024/02/19 11:12:26,722 GMT+0100 INFO [Petals.Extensions.AutoLoaderService] : Petals extension "Autoloader" started.
sample-0 2024/02/19 11:12:26,723 GMT+0100 INFO [Petals.System.Extensions.PostExtensionsManager] : Post-extension loaded: Petals ESB Autoloader
sample-0 2024/02/19 11:12:26,740 GMT+0100 INFO [Petals.Transporter.NioTransportProtocol.NioServerAgent] : The NIO transporter server is ready to process requests on /0.0.0.0:7800.
sample-0 2024/02/19 11:12:26,753 GMT+0100 INFO [Petals.Server] : Server STARTED
{code}
Create a configuration file for the Petals BC Soap:
{code}
echo "httpsEnabled=true" >> /tmp/petals-bc-soap.cfg
echo "httpsKeystoreFile=/tmp/keystore-petals.pfx" >> /tmp/petals-bc-soap.cfg
echo "httpsKeystoreType=PKCS12" >> /tmp/petals-bc-soap.cfg
echo "httpsKeystorePassword=keystorepetalspwd" >> /tmp/petals-bc-soap.cfg
echo "httpsKeyPassword=keystorepetalspwd" >> /tmp/petals-bc-soap.cfg
{code}
Deploy Petals artifacts:
{code}
petals-cli.sh -c -- deploy -u mvn:org.ow2.petals/petals-bc-soap/5.0.1/zip --file /tmp/petals-bc-soap.cfg
petals-cli.sh -c -- deploy -u mvn:org.ow2.petals.samples.soap/sa-SOAP-samples-Proxy-SSL-WSS/5.0.1-1.0.0-SNAPSHOT/zip
{code}
Two services are exposed through HTTP (see http://localhost:8084/petals/services/listServices):
* {{ArticleServiceContinuation}}
* {{ArticleServiceContinuationSecuredByWSS}}
and 2 others through HTTPS (https://localhost:8083/petals/services/listServices):
* {{ArticleServiceContinuationSecuredBySSL}}
* {{ArticleServiceContinuationSecuredByWSSAndSSL}}
Use SoapUI to invoke your secured proxified service ! Sample requests are available into the SoapUI project.
h2. Securing a service running into Petals using 2-Way SSL and WS-Security
{tip}This use case runs with the Petals BC SOAP 5.0.0+. Its source code is available [here|https://svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/petals-samples/petals-samples-soap].{tip}
The goal of this use-case is to show you that it is possible to mixed SSL and WS-Security to secure an internal endpoint as a webservice using several certificats:
* a transport certificate identifying the webservice client,
* a transport certificate to crypt the communication between the serveur and the client,
* a message certificate to sign the message sent by the client and to warranty its integrity,
* a message certificate to crypt the SOAP body content,
* a user name and a password to identify the user of the client,
* a time-stamp to avoid request re-injection.
So, it is needed to have the following key stores:
* a key store 'client': keystore-clt.jks (password: keystoreclt), containing:
** the private keys of the client,
** the public keys of the serveur
* a key store 'server': keystore-srv.jks (password: keystoresrv), containing:
** the private key used to crypt the SOAP body content,
** the public key of the client used to sign
* a specific key store 'ssl': keystore-srv-ssl.jks (password: keystoresrv), containing:
** the SSL private key of the server
** the SSL public key of the client
The private keys of the client (symetrically, public keys of the server) are:
* 'sslclt': the private key identifying the client at SSL level (2-way SSL), password: 'keystoreclt',
* 'wsseclt-sign': the private key to sign the message, password: 'keystoreclt'.
The private keys of the server (symetrically, public keys of the server) are:
* 'sslsrv': the private key to crypt the communication between the server and the client, password: 'pwsslsrv',
* 'wsseclt-crypt': the private key to crypt the message, password: 'keystoresrv'.
{tip}Although encrypted message is generated by the client, the private key is located on the server side.{tip}
{tip}To simplify the use-case, all keys are auto-signed.{tip}
{tip}The version of the SoapUI used as client needs to have keys with the same password than their keystore.{tip}
h3. About the service provider
A service provider 'Math' is available as a SoapUI mock at [http://localhost:8088/mockMathBinding?wsdl]. Just import the [SoapUI project|https://svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/petals-samples/petals-samples-soap/sa-ssl-wss/src/main/resources/SOAP-with-SSL---WSS-soapui-project.xml] and start the mocked service 'mathBinding MockService'.
h3. Importing the service provider into Petals
Using the Petals Studio, create a service unit to deploy on the BC SOAP and provide the service 'Math'. You should have a service unit JBI descriptor as following:
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:soap="http://petals.ow2.org/components/soap/version-4"
xmlns:math="http://petals.ow2.org/samples/bc/soap/math">
<jbi:services binding-component="true">
<jbi:provides
interface-name="math:math"
service-name="math:mathService"
endpoint-name="autogenerate">
<!-- CDK specific elements -->
<petalsCDK:timeout>3000</petalsCDK:timeout>
<petalsCDK:validate-wsdl>true</petalsCDK:validate-wsdl>
<petalsCDK:forward-security-subject>false</petalsCDK:forward-security-subject>
<petalsCDK:forward-message-properties>false</petalsCDK:forward-message-properties>
<petalsCDK:forward-attachments>true</petalsCDK:forward-attachments>
<petalsCDK:wsdl>math.wsdl</petalsCDK:wsdl>
<!-- Component specific elements -->
<soap:address>http://localhost:8088/mockMath</soap:address>
<soap:soap-version>1.1</soap:soap-version>
<soap:mode>SOAP</soap:mode>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}
h3. Exporting the service provider outside Petals
Before to write the service unit that consume the internal service associated to the service provider 'Math', we need:
* to generate SSL, encryption and signature keys,
* to write the right WS-Policy.
h4. Creation of keys and key stores
h5. Creation of private keys
Open a command shell and go into the directory $PETALS_HOME/https. $PETALS_HOME/https is not a directory provided by Petals, it is used by this tutorial, so don't forget to create it manually.
* Creation and auto-sign of the private key 'sslclt':
{code}
keytool -genkey -validity 731 -keystore keystore-clt.jks -storepass keystoreclt -storetype JKS -keyalg RSA -alias sslclt -keypass keystoreclt -dname "CN=SSL Client, OU=Petals, O=Linagora, L=Nice, ST=AM, C=FR"
keytool -selfcert -validity 731 -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias sslclt -keypass keystoreclt
{code}
* Creation and auto-sign of the private key 'wsseclt-sign':
{code}
keytool -genkey -validity 731 -keystore keystore-clt.jks -storepass keystoreclt -storetype JKS -keyalg RSA -alias wsseclt-sign -keypass keystoreclt -dname "CN=WSSE Signature, OU=Petals, O=Linagora, L=Nice, ST=AM, C=FR"
keytool -selfcert -validity 731 -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias wsseclt-sign -keypass keystoreclt
{code}
* Creation and auto-sign of the private key 'wsseclt-crypt':
{code}
keytool -genkey -validity 731 -keystore keystore-srv.jks -storepass keystoresrv -storetype JKS -keyalg RSA -alias wsseclt-crypt -keypass keystoresrv -dname "CN=WSSE Encryption-In, OU=Petals, O=Linagora, L=Nice, ST=AM, C=FR"
keytool -selfcert -validity 721 -keystore keystore-srv.jks -storetype JKS -storepass keystoresrv -alias wsseclt-crypt -keypass keystoresrv
{code}
* Creation and auto-sign of the private key 'sslsrv':
{code}
keytool -genkey -validity 731 -keystore keystore-srv-ssl.jks -storepass keystoresrv -storetype JKS -keyalg RSA -alias sslsrv -keypass pwsslsrv -dname "CN=SSL Server, OU=Petals, O=Linagora, L=Nice, ST=AM, C=FR"
keytool -selfcert -validity 721 -keystore keystore-srv-ssl.jks -storetype JKS -storepass keystoresrv -alias sslsrv -keypass pwsslsrv
{code}
h5. Generation and export/import of public keys
* Export/Import of public key 'sslclt':
{code}
keytool -export -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias sslclt -file sslclt.crt
keytool -import -keystore keystore-srv-ssl.jks -storetype JKS -storepass keystoresrv -alias sslclt -file sslclt.crt
{code}
* Export/Import of public key 'wsseclt-sign':
{code}
keytool -export -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias wsseclt-sign -file wsseclt-sign.crt
keytool -import -keystore keystore-srv.jks -storetype JKS -storepass keystoresrv -alias wsseclt-sign -file wsseclt-sign.crt
{code}
* Export/Import of public key 'wsseclt-crypt':
{code}
keytool -export -keystore keystore-srv.jks -storetype JKS -storepass keystoresrv -alias wsseclt-crypt -file wsseclt-crypt.crt
keytool -import -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias wsseclt-crypt -file wsseclt-crypt.crt
{code}
* Export/Import of public key 'sslsrv':
{code}
keytool -export -keystore keystore-srv-ssl.jks -storetype JKS -storepass keystoresrv -alias sslsrv -file sslsrv.crt
keytool -import -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias sslsrv -file sslsrv.crt
{code}
h4. Writing the WS-Policy
The following WS-Policy contains assertions about our requirement:
* 2-Way SSL,
* and WS-Security with:
** authentication based on a timestamped username token,
** encryption of the body part,
** and signature of the body part.
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?><wsp:Policy wsu:Id="SigEncr"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsp:ExactlyOne>
<wsp:All>
<sp:TransportBinding>
<wsp:Policy>
<sp:TransportToken>
<wsp:Policy>
<sp:HttpsToken>
<wsp:Policy>
<sp:RequireClientCertificate />
</wsp:Policy>
</sp:HttpsToken>
</wsp:Policy>
</sp:TransportToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic256 />
</wsp:Policy>
</sp:AlgorithmSuite>
<!-- sp:Layout>
<wsp:Policy>
<sp:Strict />
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp /-->
</wsp:Policy>
</sp:TransportBinding>
<sp:SupportingTokens>
<wsp:Policy>
<sp:UsernameToken/>
</wsp:Policy>
</sp:SupportingTokens>
<sp:SymmetricBinding>
<wsp:Policy>
<sp:ProtectionToken>
<wsp:Policy>
<sp:X509Token
sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never" />
</wsp:Policy>
</sp:ProtectionToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic128 />
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Strict />
</wsp:Policy>
</sp:Layout>
<sp:EncryptBeforeSigning />
<sp:OnlySignEntireHeadersAndBody />
</wsp:Policy>
</sp:SymmetricBinding>
<sp:SignedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<sp:Body />
</sp:SignedParts>
<sp:EncryptedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<sp:Body />
</sp:EncryptedParts>
<ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy">
<!-- Username of UsernameToken to be used -->
<ramp:user>ssl-wss-client-username</ramp:user>
<!-- Key alias used to sign -->
<ramp:userCertAlias>wsseclt-sign</ramp:userCertAlias>
<!-- Key alias used to encrypt -->
<ramp:encryptionUser>wsseclt-crypt</ramp:encryptionUser>
<ramp:passwordCallbackClass>org.ow2.petals.samples.bc.soap.ssl_wss.PasswordCallback</ramp:passwordCallbackClass>
<ramp:signatureCrypto>
<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.file">keystore-srv.jks</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">keystoresrv</ramp:property>
</ramp:crypto>
</ramp:signatureCrypto>
<ramp:encryptionCypto>
<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.file">keystore-srv.jks</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">keystoresrv</ramp:property>
</ramp:crypto>
</ramp:encryptionCypto>
</ramp:RampartConfig>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>
{code}
h4. Creation of the consumer service unit
Using the Petals Studio, create a service unit to deploy on the BC SOAP and consume the internal service 'Math'.
Next update its JBI descriptor to add the right configuration about SSL and WS-Security:
{code}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:soap="http://petals.ow2.org/components/soap/version-4"
xmlns:math="http://petals.ow2.org/samples/bc/soap/math">
<jbi:services binding-component="true">
<jbi:consumes
interface-name="math:math">
<!-- CDK specific elements -->
<petalsCDK:timeout>30000</petalsCDK:timeout>
<petalsCDK:mep xsi:nil="true" />
<!-- Component specific elements -->
<soap:service-name>MathServiceWithSSLAndWSS</soap:service-name>
<soap:mode>SOAP</soap:mode>
<soap:enable-http-transport>false</soap:enable-http-transport>
<soap:enable-https-transport>true</soap:enable-https-transport>
<soap:enable-jms-transport>false</soap:enable-jms-transport>
<soap:modules>rampart</soap:modules>
<soap:wss-policy>ws-policy.xml</soap:wss-policy>
</jbi:consumes>
</jbi:services>
</jbi:jbi>
{code}
where '{{ws-policy.xml}}' is the WS-Policy previously defined.
Add the class 'PasswordCallback' as password callback:
{code:lang=java}
public class PasswordCallback implements CallbackHandler {
public void handle(final Callback[] callbacks) throws IOException, UnsupportedCallbackException {
for (int i = 0; i < callbacks.length; i++) {
final WSPasswordCallback pwcb = (WSPasswordCallback) callbacks[i];
final String username = pwcb.getIdentifier();
if (username.equals("ssl-wss-client-username")) {
// Retrieve the password associated to the username of the UsernameToken
pwcb.setPassword("ssl-wss-client-password");
} else if (username.equals("wsseclt-crypt")) {
// Retrieve the password associated to the key used to encrypt
pwcb.setPassword("keystoresrv");
}
}
}
}
{code}
h3. Running the use case
Launch a freshly installed Petals ESB. Launch your SoapUI and start the mocked service.
Launch the script '{{deploy.sh}}' available [here|https://svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/petals-samples/petals-samples-soap/sa-ssl-wss/src/main/scripts/deploy.sh] after to have adjusted the environment with '{{env.sh}}'.
Use SoapUI to invoke your secured service ! Sample requests are available into the SoapUI project.
h1. Complex Use Cases
These use cases involve several Petals components including the Petals-BC-SOAP component.
{contentbylabel:labels=uc-soap|showLabels=false|showSpace=false}
{column}
This document contains all the use cases related to the Petals-BC-SOAP component.
Use cases are ordered by their complexity, from the most simple to the most complex ones.
h1. Simple Use Cases
h2. Proxy SOAP using SSL et WS-Security
{tip}This use case runs with the Petals BC SOAP 5.0.0+. Its source code is available [here|https://svn.petalslink.org/svnroot/branches-legacy/petals-samples-soap-5.0.x].{tip}
The goal of this use-case is to show you how to configure the service units of BS Soap on both sides:
* to import into Petals, an external service secured with WS-Security,
* to export to outside an internal Petals service, secured with SSL and WS-Security.
{code}
|--------------------|
|---------| HTTP/HTTPS |----------------------| HTTP | External |
| SOAP UI |-------------------------| Petals ESB |-------------------------| service provider |
|---------| WS-Security |----------------------| WS-Security |--------------------|
{code}
The WS-Security parts will be based on:
* a time-stamp to avoid request re-injection, for the Petals service consumer re-exposing the external service provider. No timestamp used for the external service provider.
* and authentication based on username and password:
** for the external service provider: `user/petals`
** for Petals service consumer re-exposing the external service provider to outside: `user-petals/petals`
This sample using SSL requires the following key stores:
* a key store 'external': keystore-external.jks (password: keystoreextpwd), containing the private and public key of the external service provider. The private key is protected by the password `keyextpwd`,
* a key store 'petals': keystore-petals.jks (password: keystorepetals), containing the private and public key of Petals service consumer re-exposing the external service provider to outside.
{column}
{column:width=35%}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list|showAnonymous=true|showCount=true|showLastTime=true}{panel}
{column}
{section}
h3. About the external service provider
An external service provider 'ArticleServiceContinuation' is available as [CXF webservice secured by WSS|https://svn.petalslink.org/svnroot/branches-legacy/petals-samples-soap-5.0.x/cxf-server] at [http://localhost:8450/articleServiceWSS_UsernameToken?wsdl].
To start it, just execute the following Maven command line in its directory project:
{code}
mvn clean verify exec:java
{code}
h3. About the proxified service provider
The proxified service provider is the Petals service consumer re-exposing the external service provider to outside.
The external service is re-exposed in 4 ways:
* with protocol HTTP and without WS-Security enabled,
* with protocol HTTP and WS-Security enabled,
* with protocol HTTPS and without WS-Security enabled,
* with protocol HTTPS and WS-Security enabled,
h3. Generate the key store 'Petals'
A specific keystore 'Petals' containing the private/public key pair of the proxified service provider to configure its SSL part is needed, and can be generated with the following command line:
{code}
keytool -genkey -alias petals-service-provider -keyalg RSA -keysize 2048 \
-dname "CN=SSL Proxyfied Service Provider, OU=Petals, O=Linagora, L=Grasse, ST=AM, C=FR" \
-storetype PKCS12 -storepass keystorepetalspwd -keystore /tmp/keystore-petals.pfx
{code}
h3. Configure SSL at Petals BC Soap level
Not only, SSL is configured at Petals BC Soap level, but also at service consumer level:
* at component level to inject the keystore configuration through the installation parameters:
** `https-keystore-file`: The keystore file generated as described below,
** `https-keystore-password`: The keystore file password,
** `https-key-password`: the private key password.
* at service consumer level to define which transport (http, https or jms) must be used to expose the service provider.
h3. Running the use case
Launch a freshly installed Petals ESB:
{code}
~/petals-esb-default-zip-5.2.0/bin$ ./petals-esb.sh
___ ____ __ ___ __ ____ ____ ____ ___
/ _ \ / __// /_ / _ | / / / __/ / __// __// _ )
/ ___// _/ / __// __ | / /__ _\ \ / _/ _\ \ / _ |
/_/ /___/ \__//_/ |_|/____//___/ /___//___//____/
Initializing logging subsystem
2024/02/19 11:12:26,005 GMT+0100 INFO [Petals.Launcher] : Logging system initialised
2024/02/19 11:12:26,016 GMT+0100 INFO [Petals.Launcher] : Initializing container's classloader...
2024/02/19 11:12:26,040 GMT+0100 INFO [Petals.Launcher] : Initializing server...
2024/02/19 11:12:26,529 GMT+0100 INFO [Petals.Launcher] : Starting server...
sample-0 2024/02/19 11:12:26,538 GMT+0100 INFO [Petals.System.Extensions.PreExtensionsManager] : Pre-extension found but not activated: Petals Embedded Registry Overlay
sample-0 2024/02/19 11:12:26,669 GMT+0100 INFO [Petals.Communication.RMIConnector] : JMX RMI server started at : service:jmx:rmi:///jndi/rmi://localhost:7700/PetalsJMX
sample-0 2024/02/19 11:12:26,684 GMT+0100 INFO [Petals.Communication.TopologyService] : Using standalone shared area implementation for static one-container domain: org.ow2.petals.microkernel.communication.sharedarea.StandaloneSharedAreaImpl
sample-0 2024/02/19 11:12:26,709 GMT+0100 INFO [Petals.Communication.TopologyService] : Shared area loaded
sample-0 2024/02/19 11:12:26,722 GMT+0100 INFO [Petals.Extensions.AutoLoaderService] : Petals extension "Autoloader" started.
sample-0 2024/02/19 11:12:26,723 GMT+0100 INFO [Petals.System.Extensions.PostExtensionsManager] : Post-extension loaded: Petals ESB Autoloader
sample-0 2024/02/19 11:12:26,740 GMT+0100 INFO [Petals.Transporter.NioTransportProtocol.NioServerAgent] : The NIO transporter server is ready to process requests on /0.0.0.0:7800.
sample-0 2024/02/19 11:12:26,753 GMT+0100 INFO [Petals.Server] : Server STARTED
{code}
Create a configuration file for the Petals BC Soap:
{code}
echo "httpsEnabled=true" >> /tmp/petals-bc-soap.cfg
echo "httpsKeystoreFile=/tmp/keystore-petals.pfx" >> /tmp/petals-bc-soap.cfg
echo "httpsKeystoreType=PKCS12" >> /tmp/petals-bc-soap.cfg
echo "httpsKeystorePassword=keystorepetalspwd" >> /tmp/petals-bc-soap.cfg
echo "httpsKeyPassword=keystorepetalspwd" >> /tmp/petals-bc-soap.cfg
{code}
Deploy Petals artifacts:
{code}
petals-cli.sh -c -- deploy -u mvn:org.ow2.petals/petals-bc-soap/5.0.1/zip --file /tmp/petals-bc-soap.cfg
petals-cli.sh -c -- deploy -u mvn:org.ow2.petals.samples.soap/sa-SOAP-samples-Proxy-SSL-WSS/5.0.1-1.0.0-SNAPSHOT/zip
{code}
Two services are exposed through HTTP (see http://localhost:8084/petals/services/listServices):
* {{ArticleServiceContinuation}}
* {{ArticleServiceContinuationSecuredByWSS}}
and 2 others through HTTPS (https://localhost:8083/petals/services/listServices):
* {{ArticleServiceContinuationSecuredBySSL}}
* {{ArticleServiceContinuationSecuredByWSSAndSSL}}
Use SoapUI to invoke your secured proxified service ! Sample requests are available into the SoapUI project.
h2. Securing a service running into Petals using 2-Way SSL and WS-Security
{tip}This use case runs with the Petals BC SOAP 5.0.0+. Its source code is available [here|https://svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/petals-samples/petals-samples-soap].{tip}
The goal of this use-case is to show you that it is possible to mixed SSL and WS-Security to secure an internal endpoint as a webservice using several certificats:
* a transport certificate identifying the webservice client,
* a transport certificate to crypt the communication between the serveur and the client,
* a message certificate to sign the message sent by the client and to warranty its integrity,
* a message certificate to crypt the SOAP body content,
* a user name and a password to identify the user of the client,
* a time-stamp to avoid request re-injection.
So, it is needed to have the following key stores:
* a key store 'client': keystore-clt.jks (password: keystoreclt), containing:
** the private keys of the client,
** the public keys of the serveur
* a key store 'server': keystore-srv.jks (password: keystoresrv), containing:
** the private key used to crypt the SOAP body content,
** the public key of the client used to sign
* a specific key store 'ssl': keystore-srv-ssl.jks (password: keystoresrv), containing:
** the SSL private key of the server
** the SSL public key of the client
The private keys of the client (symetrically, public keys of the server) are:
* 'sslclt': the private key identifying the client at SSL level (2-way SSL), password: 'keystoreclt',
* 'wsseclt-sign': the private key to sign the message, password: 'keystoreclt'.
The private keys of the server (symetrically, public keys of the server) are:
* 'sslsrv': the private key to crypt the communication between the server and the client, password: 'pwsslsrv',
* 'wsseclt-crypt': the private key to crypt the message, password: 'keystoresrv'.
{tip}Although encrypted message is generated by the client, the private key is located on the server side.{tip}
{tip}To simplify the use-case, all keys are auto-signed.{tip}
{tip}The version of the SoapUI used as client needs to have keys with the same password than their keystore.{tip}
h3. About the service provider
A service provider 'Math' is available as a SoapUI mock at [http://localhost:8088/mockMathBinding?wsdl]. Just import the [SoapUI project|https://svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/petals-samples/petals-samples-soap/sa-ssl-wss/src/main/resources/SOAP-with-SSL---WSS-soapui-project.xml] and start the mocked service 'mathBinding MockService'.
h3. Importing the service provider into Petals
Using the Petals Studio, create a service unit to deploy on the BC SOAP and provide the service 'Math'. You should have a service unit JBI descriptor as following:
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:soap="http://petals.ow2.org/components/soap/version-4"
xmlns:math="http://petals.ow2.org/samples/bc/soap/math">
<jbi:services binding-component="true">
<jbi:provides
interface-name="math:math"
service-name="math:mathService"
endpoint-name="autogenerate">
<!-- CDK specific elements -->
<petalsCDK:timeout>3000</petalsCDK:timeout>
<petalsCDK:validate-wsdl>true</petalsCDK:validate-wsdl>
<petalsCDK:forward-security-subject>false</petalsCDK:forward-security-subject>
<petalsCDK:forward-message-properties>false</petalsCDK:forward-message-properties>
<petalsCDK:forward-attachments>true</petalsCDK:forward-attachments>
<petalsCDK:wsdl>math.wsdl</petalsCDK:wsdl>
<!-- Component specific elements -->
<soap:address>http://localhost:8088/mockMath</soap:address>
<soap:soap-version>1.1</soap:soap-version>
<soap:mode>SOAP</soap:mode>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}
h3. Exporting the service provider outside Petals
Before to write the service unit that consume the internal service associated to the service provider 'Math', we need:
* to generate SSL, encryption and signature keys,
* to write the right WS-Policy.
h4. Creation of keys and key stores
h5. Creation of private keys
Open a command shell and go into the directory $PETALS_HOME/https. $PETALS_HOME/https is not a directory provided by Petals, it is used by this tutorial, so don't forget to create it manually.
* Creation and auto-sign of the private key 'sslclt':
{code}
keytool -genkey -validity 731 -keystore keystore-clt.jks -storepass keystoreclt -storetype JKS -keyalg RSA -alias sslclt -keypass keystoreclt -dname "CN=SSL Client, OU=Petals, O=Linagora, L=Nice, ST=AM, C=FR"
keytool -selfcert -validity 731 -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias sslclt -keypass keystoreclt
{code}
* Creation and auto-sign of the private key 'wsseclt-sign':
{code}
keytool -genkey -validity 731 -keystore keystore-clt.jks -storepass keystoreclt -storetype JKS -keyalg RSA -alias wsseclt-sign -keypass keystoreclt -dname "CN=WSSE Signature, OU=Petals, O=Linagora, L=Nice, ST=AM, C=FR"
keytool -selfcert -validity 731 -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias wsseclt-sign -keypass keystoreclt
{code}
* Creation and auto-sign of the private key 'wsseclt-crypt':
{code}
keytool -genkey -validity 731 -keystore keystore-srv.jks -storepass keystoresrv -storetype JKS -keyalg RSA -alias wsseclt-crypt -keypass keystoresrv -dname "CN=WSSE Encryption-In, OU=Petals, O=Linagora, L=Nice, ST=AM, C=FR"
keytool -selfcert -validity 721 -keystore keystore-srv.jks -storetype JKS -storepass keystoresrv -alias wsseclt-crypt -keypass keystoresrv
{code}
* Creation and auto-sign of the private key 'sslsrv':
{code}
keytool -genkey -validity 731 -keystore keystore-srv-ssl.jks -storepass keystoresrv -storetype JKS -keyalg RSA -alias sslsrv -keypass pwsslsrv -dname "CN=SSL Server, OU=Petals, O=Linagora, L=Nice, ST=AM, C=FR"
keytool -selfcert -validity 721 -keystore keystore-srv-ssl.jks -storetype JKS -storepass keystoresrv -alias sslsrv -keypass pwsslsrv
{code}
h5. Generation and export/import of public keys
* Export/Import of public key 'sslclt':
{code}
keytool -export -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias sslclt -file sslclt.crt
keytool -import -keystore keystore-srv-ssl.jks -storetype JKS -storepass keystoresrv -alias sslclt -file sslclt.crt
{code}
* Export/Import of public key 'wsseclt-sign':
{code}
keytool -export -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias wsseclt-sign -file wsseclt-sign.crt
keytool -import -keystore keystore-srv.jks -storetype JKS -storepass keystoresrv -alias wsseclt-sign -file wsseclt-sign.crt
{code}
* Export/Import of public key 'wsseclt-crypt':
{code}
keytool -export -keystore keystore-srv.jks -storetype JKS -storepass keystoresrv -alias wsseclt-crypt -file wsseclt-crypt.crt
keytool -import -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias wsseclt-crypt -file wsseclt-crypt.crt
{code}
* Export/Import of public key 'sslsrv':
{code}
keytool -export -keystore keystore-srv-ssl.jks -storetype JKS -storepass keystoresrv -alias sslsrv -file sslsrv.crt
keytool -import -keystore keystore-clt.jks -storetype JKS -storepass keystoreclt -alias sslsrv -file sslsrv.crt
{code}
h4. Writing the WS-Policy
The following WS-Policy contains assertions about our requirement:
* 2-Way SSL,
* and WS-Security with:
** authentication based on a timestamped username token,
** encryption of the body part,
** and signature of the body part.
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?><wsp:Policy wsu:Id="SigEncr"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsp:ExactlyOne>
<wsp:All>
<sp:TransportBinding>
<wsp:Policy>
<sp:TransportToken>
<wsp:Policy>
<sp:HttpsToken>
<wsp:Policy>
<sp:RequireClientCertificate />
</wsp:Policy>
</sp:HttpsToken>
</wsp:Policy>
</sp:TransportToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic256 />
</wsp:Policy>
</sp:AlgorithmSuite>
<!-- sp:Layout>
<wsp:Policy>
<sp:Strict />
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp /-->
</wsp:Policy>
</sp:TransportBinding>
<sp:SupportingTokens>
<wsp:Policy>
<sp:UsernameToken/>
</wsp:Policy>
</sp:SupportingTokens>
<sp:SymmetricBinding>
<wsp:Policy>
<sp:ProtectionToken>
<wsp:Policy>
<sp:X509Token
sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never" />
</wsp:Policy>
</sp:ProtectionToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic128 />
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Strict />
</wsp:Policy>
</sp:Layout>
<sp:EncryptBeforeSigning />
<sp:OnlySignEntireHeadersAndBody />
</wsp:Policy>
</sp:SymmetricBinding>
<sp:SignedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<sp:Body />
</sp:SignedParts>
<sp:EncryptedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<sp:Body />
</sp:EncryptedParts>
<ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy">
<!-- Username of UsernameToken to be used -->
<ramp:user>ssl-wss-client-username</ramp:user>
<!-- Key alias used to sign -->
<ramp:userCertAlias>wsseclt-sign</ramp:userCertAlias>
<!-- Key alias used to encrypt -->
<ramp:encryptionUser>wsseclt-crypt</ramp:encryptionUser>
<ramp:passwordCallbackClass>org.ow2.petals.samples.bc.soap.ssl_wss.PasswordCallback</ramp:passwordCallbackClass>
<ramp:signatureCrypto>
<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.file">keystore-srv.jks</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">keystoresrv</ramp:property>
</ramp:crypto>
</ramp:signatureCrypto>
<ramp:encryptionCypto>
<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.file">keystore-srv.jks</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">keystoresrv</ramp:property>
</ramp:crypto>
</ramp:encryptionCypto>
</ramp:RampartConfig>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>
{code}
h4. Creation of the consumer service unit
Using the Petals Studio, create a service unit to deploy on the BC SOAP and consume the internal service 'Math'.
Next update its JBI descriptor to add the right configuration about SSL and WS-Security:
{code}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:soap="http://petals.ow2.org/components/soap/version-4"
xmlns:math="http://petals.ow2.org/samples/bc/soap/math">
<jbi:services binding-component="true">
<jbi:consumes
interface-name="math:math">
<!-- CDK specific elements -->
<petalsCDK:timeout>30000</petalsCDK:timeout>
<petalsCDK:mep xsi:nil="true" />
<!-- Component specific elements -->
<soap:service-name>MathServiceWithSSLAndWSS</soap:service-name>
<soap:mode>SOAP</soap:mode>
<soap:enable-http-transport>false</soap:enable-http-transport>
<soap:enable-https-transport>true</soap:enable-https-transport>
<soap:enable-jms-transport>false</soap:enable-jms-transport>
<soap:modules>rampart</soap:modules>
<soap:wss-policy>ws-policy.xml</soap:wss-policy>
</jbi:consumes>
</jbi:services>
</jbi:jbi>
{code}
where '{{ws-policy.xml}}' is the WS-Policy previously defined.
Add the class 'PasswordCallback' as password callback:
{code:lang=java}
public class PasswordCallback implements CallbackHandler {
public void handle(final Callback[] callbacks) throws IOException, UnsupportedCallbackException {
for (int i = 0; i < callbacks.length; i++) {
final WSPasswordCallback pwcb = (WSPasswordCallback) callbacks[i];
final String username = pwcb.getIdentifier();
if (username.equals("ssl-wss-client-username")) {
// Retrieve the password associated to the username of the UsernameToken
pwcb.setPassword("ssl-wss-client-password");
} else if (username.equals("wsseclt-crypt")) {
// Retrieve the password associated to the key used to encrypt
pwcb.setPassword("keystoresrv");
}
}
}
}
{code}
h3. Running the use case
Launch a freshly installed Petals ESB. Launch your SoapUI and start the mocked service.
Launch the script '{{deploy.sh}}' available [here|https://svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/petals-samples/petals-samples-soap/sa-ssl-wss/src/main/scripts/deploy.sh] after to have adjusted the environment with '{{env.sh}}'.
Use SoapUI to invoke your secured service ! Sample requests are available into the SoapUI project.
h1. Complex Use Cases
These use cases involve several Petals components including the Petals-BC-SOAP component.
{contentbylabel:labels=uc-soap|showLabels=false|showSpace=false}