Monday, December 8, 2014

Handling Message-level Security Requirements

When thinking about security it's important to distinguish between Transport and
Message-level security.
Transport-level security represents a technique where the underlying operating system or
application servers are handling security features. Recipes for transport-level security are
covered in the next chapter.
Message-level security represents a technique where all information related to security is
encapsulated in the message. This is what WS-Security specifies for web services. Securing
messages using message-level security instead of using transport-level security has several
advantages that include:
f Flexibility – parts of the message can be signed or encrypted. This means that
intermediary nodes can see parts of the message that are indented for them. This
might be necessary in a routing scenario, so that the intermediary can determine
where to send the message to.
f Supports multiple protocols – secured messages can be sent over different protocols
such as FTP, HTTP, or e-mail without having to use the protocol level security.
Oracle Service Bus (OSB) supports both Transport and Message-level security. The level of
security available on the OSB is dependent on the transport protocol used.
In this chapter, we will only cover Message-level security related recipes. The recipes for
Transport-level security are covered in the next chapter.
Security in the OSB is handled by the Oracle Web Service Manager (OWSM). OWSM was
introduced in the 11gR1 version of the OSB. Before 11gR1, we could only use the WLS 9.2
policies. Oracle recommends using the OWSM policies because in the next major releases
of OSB, the old WLS 9.2 policies will no longer be supported.
Preparing OSB server to work with OWSM
Before OWSM can be used, we need to create a Metadata Service (MDS) database repository.
The OWSM policies will be stored in the MDS and these policies can be used at design time by
Eclipse OEPE or the Service Bus console, and at runtime by the OSB server. The second step
is to extend our OSB domain with the OWSM and the Enterprise Manager options.
This recipe will show how to create an OWSM-enabled OSB domain.
Getting ready
1. For this recipe, you will need the following in place. A WebLogic domain which has the
OSB version 11gR1 option will need to be enabled.
2. An Oracle Database in version 10g R2, 11g R1, or 11g R2. The database should be
on the latest patch set.
3. A database schema user which has the sysdba privilege that can be used by the
Repository Creation Utility (RCU).
4. Download the Repository Creation Utility. It can be downloaded from http://www.
oracle.com/technetwork/middleware/soasuite/downloads/index.
html, here we should accept license agreement and open the Prerequisites &
Recommended Install Process of the SOA Suite. The version of SOA Suite should
match with the OSB version we are using in this cookbook.

How to do it...
First we need to start the Repository Creation Utility which we will use to create the Metadata
Service schema in the Oracle Database.
1. Extract the ofm_rcu_win_11.1.1.4.0_disk1_1of1.zip file to the following
folder c:\temp\ofm_rcu_win_11.1.1.4.0_disk1_1of1.
2. Open Windows Explorer and browse to c:\temp\ofm_rcu_win_11.1.1.4.0_
disk1_1of1\rcuHome\BIN.
3. Double-click on the rcu.bat command file to start the Repository Creation Utility
and click Next.
4. Choose Create at the Create Repository step.
5. Choose Oracle Database as the value of the Database Type drop-down listbox.
6. Enter the name of the server where the database is running into the Host Name field.
7. Enter the port on which the database listener is listening (often 1521) into the
Port field.
8. Enter the service name for the database into the Service Name field.
9. Enter the username for the database into the Username field. The user must have
the SYSDBA privilege.
10. Enter the password of the database user into the Password field and click Next.
11. This will open the Checking Prerequisites window and some checks are started. A
pop-up window will indicate if the wrong database version has been specified.
12. Click OK.
13. Select Create a new Prefix in the Select Components step.
14. Type COOKBOOK as the value in the Create a new Prefix field.
15. Expand the AS Common Schemas item in the component tree and enable the
Metadata Services option and click Next.
16. This will again open the Checking Prerequisites window and some checks are
started. All checks should be ok this time.
17. Click OK.
18. In the Schema Passwords step, select Use same passwords for all schemas and
type welcome as the value for the Password and Confirm Password field.
19. Click Next twice.
20. Click OK to confirm the creation of the tablespaces for the Metadata Services
repository.
21. A check will run to see if the RCU can create the tablespaces.
22. Click OK.
23. On the Summary step, click Create.
24. After the creation of the Metadata Services schema and tablespaces, the RCU will
show a completion summary. The status column should have the value Success.
25. Finish the RCU by clicking Close.
Next we will add the OWSM product to an existing WebLogic domain. Start the configuration
wizard config.cmd located in the [OSB-HOME]\wlserver_10.3\common\bin folder and
perform the following steps:
26. Choose Extend an existing WebLogic domain and click Next.
27. In the Select a WebLogic Domain Directory window, navigate to user_projects\
domains\, choose osb_cookbook_domain and click Next.
28. In the Select Extension Source window, choose the following products, if not already
selected and click Next:
Oracle WSM Policy Manager
Oracle Service Bus OWSM Extension
Oracle Enterprise Manager
29. In the Configure JDBC Component Schema window, select the OWSM MDS Schema
checkbox. Enter COOKBOOK_MDS for the Schema Owner field.
30. Enter welcome into the Schema Password field.
31. Provide the database details in the DBMS/Service, Host Name and the Port fields.
32. Click Next to test the JDBC connection.
33. The test should return the Test Successful! message.
34 Click Next twice.
35. In the Configuration Summary window, click Extend.
36. After reaching 100 percent in the progress bar, click Done.
We have successfully added the OWSM schema to the database repository and extended the
existing OSB domain by OWSM.
How it works...
The WebLogic domain configuration wizard configures the Metadata Services with the OWSM
policies by adding the OWSM product to the WebLogic domain. The Metadata Services is
a database repository and is created by the RCU. The WebLogic domain now contains a
reference to these OWSM policies and at design time, the Eclipse OEPE or the Service Bus
console can retrieve these policies from our WebLogic domain.

Configuring OSB server for OWSM
After installing the OWSM component to our WebLogic domain, we will be configuring the OSB
server for OWSM. For this, we need to generate a custom Java keystore which contains the
server certificates and configure it in Enterprise Manager (EM).

How to do it...
First, let's create a Java keystore which will be used by OWSM. On the command line, perform
the following steps:
1. Navigate to the bin folder of the JDK used by the OSB:
cd c:\[FMWHome]\jrockit-jdk1.6.0_20-R28.1\bin
2. Generate a new Java keystore with a self-signed server key:
keytool -genkey -alias serverKey -keyalg "RSA" -sigalg
"SHA1withRSA" -dname "CN=server, C=US"
-keypass welcome -keystore c:\server.jks -storepass welcome
3. Copy the Java keystore server.jks located at c:\ to the config\fmwconfig
folder of the OSB domain:
cd ..\..
cd user_projects\domains\osb_cookbook_domain\config\fmwconfig
copy c:\server.jks .
Next, we have to import the Java keystore into Enterprise Manager. Open Enterprise
Manager in a browser window (http://localhost:7001/em) and perform the
following steps:
4. Login with the weblogic user account.
5. In the tree to the left, expand the WebLogic Domain tree node.
6. Click on osb_cookbook_domain.
7. In the right window, click on the WebLogic Domain to open the drop-down menu.
8. Select Security | Security Provider Configuration.
9. In the Security Provider Configuration page, expand the Keystore option.
435
10. Click Configure….
11. Enter ./server.jks into the Keystore Path field.
12. Enter welcome into the Password and Confirm Password field.
13. Enter serverKey into the Key Alias field in the Signature Key section.
14. Enter welcome into the Signature Password and Confirm Password field.
15. Enter serverKey into the Crypt Alias field in the Encryption Key section.
16. Enter welcome into the Crypt Password and Confirm Password field.
17. Click OK.
18. Restart the server.
We have successfully created a Java keystore and configured it for our OSB domain.
Now, let's create a user we will use for the authentication later. In the Service Bus console,
perform the following steps:
19. Navigate to the Security Configuration using the menu on the left side.
20. Select the Users menu item and click Add New.
21. Enter osbbook into the User Name field and welcome1 into the New Password and
Confirm Password fields.
22. Leave DefaultAuthenticator for the Authentication Provider and click Save.
Adding a new user through the Service Bus console can be done outside a change session.
Next we need to add the osbbook user to the domain credential store. A credential store is
a repository of security data. The credential is used later by the Service Bus test console in
order to look up the username and password. In Enterprise Manager, perform the following
steps to add a credential to the credential store:
23. In the tree to the left, expand the WebLogic Domain entry and select the domain.
24. From the WebLogic Domain drop-down list, select Security | Credentials.
25. In the Credentials page, expand the oracle.wsm.security node.
26. Click Create Key and the Create Key pop-up window will be shown.
27. Enter osbbook-key into the Key field
28. Enter osbbook into the User Name field and welcome1 into the Password and
Confirm Password field.
29. Click OK.
We have now set up the OSB server to work with OWSM and also created and configured the
osbbook user which we will use later.
How it works...
In this recipe, we created a Java keystore and this keystore contains a self-signed Server Key
which will be used by OWSM. For production it is better to use a certificate which is signed by
a known Certificate Authority (CA). The Server Key consists of two parts: the private key part
will be used by the receiver to decrypt the incoming messages and to sign the messages and
the public key part is used by the sender to encrypt the message and to check the signature.
Enterprise Manager uses the Credential Store Framework (CSF) to store the credentials,
such as username/password combinations, tickets, and public key certificates. The
configuration of the CSF is maintained in the jps-config.xml file in the domain folder.

There's more…
A credential can also be created from the command line using Web Logic Scripting Toolkit
(WLST). In a command window, perform the following steps:
1. Run wlst.cmd located in the [FMWHome]\oracle_common\common\bin folder.
2. Connect to the domain:
connect('weblogic','welcome1','t3://localhost:7001')
3. Create the osbbook-key credential:
createCred(map="oracle.wsm.security", key="osbbook-key",
user="osbbook", password="welcome1",desc="osbbook-key")
4. Disconnect from WLST:
disconnect()
exit()
Securing a proxy service by Username
Token authentication
In this recipe, we will secure a proxy service with an OWSM server policy using Eclipse OEPE.
For this recipe, we will use a simple OSB project with one proxy. Import the getting-ready
project into Eclipse OEPE from \chapter-11\getting-ready\\securing-a-proxyservice-
with-username-token.
The OSB Server must be up and running and configured using the first two recipes of this
chapter. This server needs to be defined in the Eclipse OEPE for this recipe to work.
In Eclipse OEPE, perform the following steps to add an OWSM policy to a proxy service:
1. Open the CustomerManagement.proxy in the proxy folder of the securing-a-proxyservice-
with-username-token project.
2. Navigate to the Policy tab.
3. Enable From OWSM Policy Store.
4. Click Service Level Policies, which will enable the Add button.
5. Click Add and the OWSM Policy Configuration window will open.
6. Click Browse.
7. In the Select OWSM Policy window we need to choose a security or
management policy.
8. Enter *username* into the Name field and click Search.
9. Select the oracle/wss_username_token_service_policy from the list of policies and
click OK.
10. The Username Token policy will be displayed in the Policy tab of the proxy service.
11. Save the project and deploy it to the OSB server.
We have successfully secured our proxy service using UsernameToken WS-Security SOAP
headers to authenticate users.
Now let's test it first using the Service Bus test console. In the Service Bus console, perform
the following steps:
12. Navigate to the CustomerManagement proxy service (in Project Explorer, click on
the project and then on the proxy folder) and click on the Launch Test Console icon
(with the bug).
13. Click Execute (the value passed in the ID does not have an effect; the answer of the
proxy service is hardcoded).
14. We get an error because we have not passed a username and password.
15. Click Back to specify the username and password.
16. In the test console, scroll down until the Security area is visible.
17. Enter osbbook-key into the Override Value field and click Execute.
18. The test should now work and a valid response should be returned by the proxy
service. The test console also shows the SOAP header with the Username Token
necessary for the authentication.
The Username Token authentication policy uses the credentials in the UsernameToken
WS-Security header to authenticate users. Only the plain text mechanism is supported. The
credentials are authenticated against the configured identity store on WebLogic server.
The usernames used in the user authentication policies will be validated against the users
of the WebLogic security realm and the SOAP body will not be encrypted.
To add the OWSM policy to the proxy service, Eclipse OEPE needs to contact the OSB
WebLogic server to retrieve the available OWSM server policies. We can add one or more
OWSM policy references to a proxy service. These policies can only be added or verified
when the OSB WebLogic server is running.
When the proxy service is deployed to the OSB Server, we can retrieve the WSDL of the proxy
service. This WSDL will contain the WS security policies which can be used by the clients of
this proxy service.
There's more…
SoapUI can also be used to test secured web services. To test the proxy service just created
previously, perform the following steps in soapUI:
1. Create a new soapUI project by consuming the WSDL from the proxy service, which
is available under: http://[OSBServer]:[port]/securing-a-proxyservice-
with-username-token/proxy/CustomerManagement?wsdl.
2. Double-click on the new project in the project tree.
3. Navigate to the WS-Security Configurations tab.
4. Within the WS-Security Configurations, navigate to the Outgoing WS-Security
Configurations tab.
5. Click on the + button to create a new outgoing configuration.
6. Enter UsernameToken into the Name cell and click OK.
7. Click on the + button below the new configuration to add a WSS entry.
8. From the drop-down list, select Username.
9. Click OK.
10. Enter osbbook into the Username filed and welcome1 into the Password field.
11. Select PasswordText for the Password Type.
12. Close the window.
13. Open Request 1 for the FindCustomer operation.
14. Replace the ? with 1 in the ID element.
15. Run the test by clicking on the green arrow icon. A security error will be returned,
because the WSS configuration is not yet used.
16. Click the Aut button in the lower-left corner (marked red in the following screenshot):
17. Select UsernameToken in the Outgoing WSS drop-down list.
18. Rerun the test and a valid response should be returned.
Securing a proxy service by protecting the
messageApart from requiring the user to authenticate themselves to the proxy service, we can also
enforce that a message be encrypted and signed using the message protection policies. In
this recipe, we will enable the message protection to guarantee message integrity through
digital signature and message confidentiality through XML encryption.
For this to work, we need to have the public key of the server certificate.

For this we will use the same simple OSB project as in the previous Securing a proxy service
using Username Token authentication recipe.
Import the getting-ready project into Eclipse from \chapter-11\getting-ready\
securing-a-proxy-service-with-message-protection.

The steps to execute in this recipe are the same as in the previous Securing a proxy service
using Username Token Authentication recipe, only another policy needs to be selected. In the
Eclipse OEPE, perform the following steps:
1. Open the CustomerManagement.proxy in the proxy folder of the securing-a-proxyservice-
with-message-protection project.
2. Navigate to the Policy tab.
3. Enable From OWSM Policy Store.
4. Click Service Level Policies, which will enable the Add button.
5. Click Add and the OWSM Policy Configuration window will open.
6. Click Browse.
7. In the Select OWSM Policy window, we need to choose a security or
management policy.
8. Enter *message_protection_service* in the Name field and click Search.
9. Select the oracle/wss11_message_protection_service_policy from the list
of policies.
10. Click OK.
11. The message protection policy will be displayed in the Policy tab of the proxy service.
12. Save the project and deploy it to the OSB server.
Instead of oracle/wss11_message_protection_service_policy, we could also use
oracle/wss10_message_protection_service_policy on this proxy service.
In the Service Bus console, perform the following steps for testing the service:
13. Navigate to the CustomerManagement proxy service (in Project Explorer, click on
the securing-a-proxy-service-with-message-protection project and then on the
proxy folder) and click on the Launch Test Console icon (the bug).
14. Click on Execute (the value passed in the ID does not have an effect; the answer
of the proxy service is hardcoded).
15. We may get an error because we have not defined a certificate.
16. Click Back to specify the username and password.
17. In the test console, scroll down until the Security area is visible.
18. Enter serverkey into the Override Value field for the property
keystore.recipient.alias.
19. Enter enc-csf-key into the Override Value field for the property
keystore.enc.csf.key.
20. Click Execute.
21. The test should now work and a valid response should be returned by the proxy
service. The test console also shows the SOAP headers passed in the request
message with the encrypted key.
How it works...
With the message protection policy, the public key of the server is used to encrypt the SOAP
body. OWSM will use the private key of the server to decrypt the SOAP body.
The CSF keys used in the Service Bus test console match the entries we have seen when
setting up the credential store (WebLogic Domain | Security | Credentials)
Policies can also be directly manipulated on the OSB server through the OSB console.
To remove the old policy and add the new one for the message protection used in this recipe,
perform the following steps in the Service Bus console:
1. Click on the Project Explorer.
2. Click on the securing-a-proxy-service-with-username-token project.
3. Click on the proxy folder.
4. Click on Create in the Change Center in the upper-left corner, to start a new
change session.
5. Click on the CustomerManagement proxy service.
6. Navigate to the Policies tab.
7. Click on the garbage bin icon to delete the oracle/wss_username_token_
policy service-level policies.
8. Click Add.
9. The Select OWSM Policy window is shown.
10. Enter *message_protection_service* into the Name field of the Search section
and click Search.
11. Select oracle/wss11_message_protection_service_policy and click Submit.
12. Click Update.
13. Click Activate in the Change Center section to apply the changes.
14. Enter Replaced wss_username_token_policy by message_protection_
service_policy into the Description field to document the change and
click Submit.


6. Navigate to the Policies tab.
7. Click on the garbage bin icon to delete the oracle/wss_username_token_
policy service-level policies.
8. Click Add.
9. The Select OWSM Policy window is shown.
10. Enter *message_protection_service* into the Name field of the Search section
and click Search.
11. Select oracle/wss11_message_protection_service_policy and click Submit.
12. Click Update.
13. Click Activate in the Change Center section to apply the changes.
14. Enter Replaced wss_username_token_policy by message_protection_
service_policy into the Description field to document the change and
click Submit.

In this recipe, we will combine message protection with user authentication. For this we can
reuse the client Java keystore and the osbbook user from the preceding recipes.

For this we will use the same simple OSB project as in the previous Securing a proxy service
using username and password authentication through OWSM recipe.
Import the getting-ready project into Eclipse OEPE from \chapter-11\gettingready\
securing-a-proxy-service-with-auth-and-message-protection.
How to do it...
The steps to execute in this recipe are the same as in the previous Securing a proxy service
using username and password authentication through OWSM recipe, only another policy
needs to be selected. In the Eclipse OEPE, perform the following steps:
1. Open the CustomerManagement.proxy in the proxy folder of the securing-a-proxyservice-
with-auth-and-message-protection project.
2. Navigate to the Policy tab.
3. Enable From OWSM Policy Store.
4. Click Service Level Policies, which will enable the Add button.
5. Click Add and the OWSM Policy Configuration window will open.
6. Click Browse.
7. In the Select OWSM Policy window, we need to choose a security or
management policy.
8. Enter *username_token_with* into the Name field and click Search.
9. Select the oracle/wss11_username_token_with_message_protection_service_
policy from the list of policies and click OK.
The Username Token policy will be displayed in the Policy tab of the proxy service.
10. Save the project and deploy it to the OSB server.
Instead of the oracle/wss11_username_token_with_message_protection_
service_policy we could also use oracle/wss10_username_token_with_message_
protection_service_policy for this proxy service.
In the Service Bus console, perform the following steps for testing the service:
11. Navigate to the CustomerManagement proxy service (in the Project Explorer, click
on the securing-a-proxy-service-with-auth-and-message-protection project and then
on the proxy folder) and click on the Launch Test Console icon (with the bug).
12. Click Execute (the value passed in the ID does not have an effect; the answer of the
proxy service is hardcoded).
13. We will get an error saying that the username is missing.
14. Click Back to specify the username and password.
15. In the test console, scroll down until the Security area is visible.
16. Enter serverkey into the Override Value field for the property
keystore.recipient.alias.
17. Enter enc-csf-key into the Override Value field for the property
keystore.enc.csf.key.
18. Enter osbbook-key into the Override Value field for the property csf.key.
19. Click Execute.
20. The test should now work and a valid response should be returned by the proxy
service. The test console also shows the various SOAP headers passed in the
request message holding the security information.
How it works...
The Username Token authentication, together with message protection policy, authenticates
the service consumer using the Username Token and also encrypts the SOAP body.
The public key of the server is used to encrypt the SOAP body.

In this recipe, we will also use the message protection similar to the previous recipes but
replace the username/password authentication with a client certificate authentication. For
this, we need to generate a client certificate and add the public key of the client certificate
to the server Java keystore. This way, OWSM can verify the client signature which is added
to the SOAP message.

For this recipe, we will use the same simple OSB project as in the previous Securing a proxy
service using username and password authentication through OWSM recipe.
Import the getting-ready project into Eclipse OEPE from \chapter-11\gettingready\
securing-a-proxy-service-with-cert-auth-and-msg-protect.
How to do it...
The steps to execute in this recipe are the same as in the previous Securing a proxy service
using username and password authentication through OWSM recipe, only another policy
needs to be selected. In the Eclipse OEPE, perform the following steps:
1. Open the CustomerManagement.proxy in the proxy folder of the securing-a-proxyservice-
with-cert-auth-and-msg-protect project.
2. Navigate to the Policy tab.
3. Enable From OWSM Policy Store.
4. Click Service Level Policies, which will enable the Add button.
5. Click Add and the OWSM Policy Configuration window will open.
6. Click Browse.
7. In the Select OWSM Policy window, we need to choose a security or
management policy.
8. Enter *x509* into the Name field and click Search.
9. Select the /wss11_x509_token_with_message_protection_service_policy from the
list of policies.
10. Click OK.

11. The Username Token policy will be displayed in the Policy tab of the proxy service.
12. Save the project and deploy it to the OSB server.
Instead of the oracle/wss11_x509_token_with_message_protection_service_
policy we could also use oracle/wss10_x509_token_with_message_protection_
service_policy on this proxy service.
Now, we have to generate a client certificate and exchange the public certificates of the client
and the server. Open a command line window and perform the following steps:
13. Navigate to the bin folder of the JDK used by the OSB:
cd c:\[FMWHome]\jrockit-jdk1.6.0_20-R28.1\bin
14. Generate a new client certificate with client as common name (CN) attribute and
store it in the client_2.jks keystore:
keytool -genkey -alias clientKey -keyalg "RSA" -sigalg
"SHA1withRSA" -dname "CN=client, C=US" -keypass welcome
-keystore c:\client_2.jks -storepass welcome
15. Export the public key of the server certificate:
keytool -exportcert –alias serverKey -storepass welcome –keystore
c:\server.jks –file c:\server.cer
16. Import the public key:
keytool -import -file c:\server.cer -alias serverKey -keystore
c:\client_2.jks -storepass welcome -keypass welcome
17. Choose yes for the question about whether you trust the certificate:
18. Export the public key of the client certificate:
keytool -exportcert -alias clientKey -storepass welcome -keystore
c:\client_2.jks -file c:\client_2.cer
19. Import the key in the server Java keystore:
keytool -import -file c:\client_2.cer -alias clientKey -keystore
c:\server.jks -storepass welcome -keypass welcome
20. Copy the updated Java keystore server.jks located at c:\ to the config\
fmwconfig folder of the OSB domain:
cd ..\..
cd user_projects\domains\osb_cookbook_domain\config\fmwconfig
copy c:\server.jks .
21. Confirm the overwrite warning by entering yes.
22. Restart the WebLogic servers so that the updated server Java keystore is loaded.
Next we have to add the user called client to the myrealm security realm of the WebLogic
server. The name of the user must match with the common name (CN=client) of the client
certificate.
In the Service Bus console, perform the following steps:
23. Navigate to the Security Configuration using the menu on the left side.
24. Select the Users menu item and click Add New.
25. Enter client into the User Name field and welcome1 into the New Password and
Confirm Password fields.
26. Leave DefaultAuthenticator for the Authentication Provider.
27. Click Save.
The password of the client user is not important because we will use the public key of the
client certificate to verify the SOAP signature.
We can use the next recipe, Using JDeveloper to test a secured service to test the
implementation.
How it works...
The X509 Token authentication together with message protection policy authenticates the
service consumer using a client certificate.
The public key of the server is used to encrypt the SOAP body and the private key of the client
is used to sign the SOAP body. The signature of the SOAP message can be verified by OWSM
because it has the public key of the client and OWSM will use the private key of the server to
decrypt the SOAP body.
The common name of the client certificate is also checked against the users of the WebLogic
security realm.







1 comment: