Document
TIBCO BusinessWorks™ 5.3: Understanding Web Services Security
This document will cover the creation of a very simple Web Service using the Web Services Wizard and utilizing the Service Palette; immediately following the creation of the Service, we will configure the Service to support Web Services Security for Identification, Integrity, and Confidentiality, using two of the Web Services Security Profiles: the UserName Profile and the X.509 Profile.
It is assumed that the reader has some familiarity with the BusinessWorks product and has access to both BusinessWorks 5.3(+) and the TIBCO Enterprise Message Service product.
Table of Contents
1Overview of Web Services Security
1.1Identification/Authentication
1.2Integrity/Digital Signatures
1.3Confidentiality/Cryptography
2Getting Started
2.1X.509 Certificates from TIBCO Enterprise Message Service
2.2Java Keystore Tool - Recommended
2.3TIBCO Runtime Agent
2.4TIBCO Administrator
2.5Optional: Tools to view the WSS SOAP Payload
3Building a Simple Web Service in BusinessWorks 5.3
3.1Setup Folders
3.2Building a Schema
3.3Building a Process for a Service
3.4Adding Communications
3.5Using the Wizard
3.6Building the Companion Web Services Client
3.7Testing the Web Service
4Assemble Security Tokens
4.1Identity Objects
4.2Trusted Certificate Folders
5Using the Policy Palette – UserName Token
5.1Utilizing the UserName Token to create an Identification Policy
5.1.1Configure the Inbound Security Policy
5.1.2Configure the Outbound Security Policy
5.2Policy Association with Services
5.2.1Configure the Inbound Security Policy Association
5.2.2Configure the Outbound Security Policy Association
6First Test – UserName Identification
6.1Test
6.1.1Request Contents – UserName Token
6.1.2Troubleshooting – Bad ID or Password
6.1.3Troubleshooting – Administrator is unavailable
6.1.4Troubleshooting – Mismatched Configurations
7Change Project from UserName to X.509 for Identification
8Second Test – X.509 Identification
8.1Request Contents – BinarySecurityToken
8.2Troubleshooting – Bad X.509 Private Key Password
8.3Troubleshooting – Missing Trusted CA Cert in Trusted Certificates Folder
8.4Troubleshooting – Mismatched Token Types
9Adding Integrity and Confidentiality
10Third Test – Identification, Integrity, and Confidentiality
10.1Troubleshooting
1Overview of Web Services Security
Discuss the Profiles – TIBCO currently supports X.509 and Username profiles and their respective tokens.
1.1Identification/Authentication
Discuss the “Nonce”, timeouts
1.2Integrity/Digital Signatures
Discuss Direct Reference vs. Subject Key Identities
1.3Confidentiality/Cryptography
All FIPS 140-2 approved cipher suites – 3DES, AES-128, AES-256.
2Getting Started
2.1X.509 Certificates from TIBCO Enterprise Message Service
We will be using the Certificates in the TIBCO Enterprise Message Service 4.X+ distribution as found in the <tibco>/ems/bin/certsdirectory.
2.2Java Keystore Tool - Recommended
It will be useful to be able to create Java Keystores as they have a flexibility that will facilitate certain use-case scenarios.
2.3TIBCO Runtime Agent
We will need access to the files associated with the TRA of Designer so that we can simulate a deployed project in Designer for purposes of Authentication.
2.4TIBCO Administrator
In this document, we are assuming that there is an Administrative ID – “admin” with a password of “admin”, and that the administrator is running concurrently with your Designer.
2.5Optional: Tools to view the WSS SOAP Payload
Web Services Security creates a processing overhead as you would expect from any security processing, but it also inflates the SOAP Payload. I will use the Axis distribution of TCPMon as a proxy to capture the SOAP Message exchanges to illustrate the mechanics and instantiation of Authentication, Integrity, and Confidentiality aspects of Web Services Security.
TCPMon has been “externalized” from Axis, and is available here:
3Building a Simple Web Service in BusinessWorks 5.3
Create a new BusinessWorks project – in this example, I have called the project “UnderstandingWSS”. The scenario is very simple with a single field being sent as a string and a simple string as a reply. The Client will ask for the Time and the Server will respond accordingly.
3.1Setup Folders
Drag and Drop four Folders into the Project: Schema, Communications, Security, and Processes. Open up the Security folder and drag and drop three folders: Identities, Security Policies, and Trusted Certificates. These folders will provide the structure for our activities.
3.2Building a Schema
Using the XML Tools Palette, drag and drop a Schema Objectinto the Schema folder, and configure with two string elements as shown in the diagram below.
3.3Building a Process for a Service
Drag and Drop a Process into the Process Folder, and simply connect the Start to the EndActivities. Next, associate the XSD you just created with the Start Activity’s Output Editor, picking an XML Element Reference and selecting a resource – pick the Inquiry Element.
Continue on to the End Activity, again using an XML Element Reference in the Input Editor, but when you choose a Resource, pick the Answer Element as shown below. These elements will equate into Messages for the WSDL that the Wizard will create for you.
To provide some processing, and to have a valid process definition (elements were set as “required”), put a string in the output element. As we will be asking for the time, I have chosen to respond by concatenating some words with the XPath expression for the current-dateTime.
3.4Adding Communications
Highlight the Communications Folder and drag and drop an HTTP Connection object, configuring it with a free port – I have port 7177 free on my machine.
3.5Using the Wizard
Now we have a process with inputs and outputs that are compatible with a WSDL structure and a communications configuration for the bindings – so we are ready to use the Wizard! You can use the Tools Menu to “Generate Web Service”, or highlight the project and right-click and navigate the menu from Tools or Multi User -> Generate Web Service -> From Process.
The following pop-up appears with much of the defaults given. You will need to pick the Process with the Process Chooser (if you have multiple processes), the Transport, and the Location for the resulting WSDL. As we have built this project, the following screen should put everything in its proper place:
Notice that we now have three new objects in the Processes Folder:
- infTellingTime WSDL
- wsTellingTime Process
- infTellingTime Service
Open the intfTellingTime-service WSDL Source Tab to view the new WSDL based on your Service Definition, and highlight the source (Control-A) and copy to a buffer (Control-C). Next, open the Schema Folder, drag and drop a new WSDL object, go to the Menu Bar and open up with Display XML in Source View; now highlight the stub and replace it with the source you have in your buffer from the previous copy (using Control-V, the results are shown below). Save the new WSDL. This will be the Concrete WSDL for the Web Service Client.
Here is the resulting Concrete WSDL source:
3.6Building the Companion Web Services Client
Open up the Processes Folder and drag and drop a new Process Definition (we are calling it WhatTimeIsIt). Open up the process and put a SOAP Request Reply Activity in the Process and connect the Start Activity to the SOAP Request Reply Activity and hence on to the End Activity as shown below:
Pick a Namespace, Service, Port, and Operation – this time you want to pick from the newly created Concrete Client WSDL.
As the elements are “Required”, you will need to open the Input Tab and ask for the Time!
3.7Testing the Web Service
Now we are ready to Save the project and test the Services; Click the Tester Tab on the Left, and make sure that the intfTellingTime Service Icon’s checkbox and the Client Process Definition checkbox are both checked, then either Load Selected and initiate a Job by right-clicking the Client Process Definition -> Create a Job, or use the Load & Start Current.
You can see the results in the End Activity of the Client as it gets the response from the Web Service. We are now ready to focus on Web Services Security!
4Assemble Security Tokens
We will be using X.509 Certificates from the TIBCO Enterprise Message Service distribution, which can be found in the <tibco>/bin/certs directory.
4.1Identity Objects
Drag and Drop twoIdentity objects into the Identities Folder; these will be the two flavors for the WSS Client. The first one will be the UserNameToken Identity which will be authenticated against the Administrator. I have configured it in the screenshot below with the ID of “admin” and the password of “admin”:
The second Identity will be an X.509v3-based Token, so change the Type to Identity File and navigate to the TIBCO Enterprise Message Service folder that contains certificates and import the client_identity.p12; the private key password is “password”. Configure the File Type as PKCS12.
Screenshot is below:
4.2Trusted Certificate Folders
Next, we will prepare for the Server Side of using X.509v3 certificates by importing the Client certificate and the root Certificate Authority for the Client Certificate into the Trusted Certificates Folder. Highlight the Trusted Certificates Folder in the project and navigate Tools -> Trusted Certificates -> Import into PEM Format and pick the following TIBCO Enterprise Message Service Certificates:
client.cert.pem
client_root.cert.pem
When finished, your folder should look like this:
5Using the Policy Palette – UserName Token
Open up the Security Policies Folder and drag and drop twoSecurity Policy objects and twoSecurity Policy Association objects into this folder. Name them in pairs: Inbound and Outbound. The Security Policy will be configured to have a checkbox for Authentication only – later we will configure them for Integrity and Confidentiality.
5.1Utilizing the UserName Token to create an Identification Policy
5.1.1Configure the Inbound Security Policy
- Config Tab:
- Name: Inbound
- Policy Type: inbound
- Authentication: checked(do not check any other boxes!)
- Authentication Tab:
- Highlight UserNameToken – leave Trusted Certificates Folder Blank
- Configure the Outbound Security Policy
- Config Tab:
- Name: Outbound
- Policy Type: outbound
- Authentication: checked (do not check any other boxes!)
- Authentication Tab:
- Security Token: Pull-down menu to UserNameToken
- Username Password Identity: pick - /Security/Identities/UserNameToken.id
- Password Type: Text
5.2Policy Association with Services
5.2.1Configure the Inbound Security Policy Association
- Configuration Tab:
- Name: Inbound
- Apply Policy to: (navigate to the service as shown below)
- Inbound Message Policy: (navigate to the policy as shown below)
5.2.2Configure the Outbound Security Policy Association
- Configuration Tab:
- Name: Outbound
- Apply Policy to: (navigate to the SOAP Request/Reply as shown below)
- Outbound Message Policy: (navigate to the policy as shown below)
There is no need to configure any other Tabs in either Association at this time.
6First Test – UserName Identification
As we will be testing in the Test Mode of Designer without any deployment, we need to associate the Designer with a particular TIBCO Administrative Domain.
Here are the preparatory steps:
- Save your project.
- Stop BusinessWorks Designer completely.
- Navigate to <tibco>/tra/domain/<yourdomain> and locate the “AuthorizationDomain.properties” file and copy it to <tibco>/tra/<version>
- Make certain the your domain Administrator is running
- Restart Designer and bring up this project
Here is what my AuthorizationDomain.properties file looks like:
#Thu Jun 23 13:58:38 PDT 2005
Machine=CMILONO-NB
LogGenerationSize=5000
UserID=admin
Domain=AUTH_obscure
Credential=\#\!UZ2CX8eDpx42PHtpYP4kWFYKXBs88ilC
LogGenerations=5
notifier.rv.service=7500
TIB_REPO_ROOT=/TIBCO
TIB_REPO_URL=tibcr@AUTH_obscure\:daemon\=tcp\:7500\:service\=7500\:discoveryTime\=10
DomainImplementation=com.tibco.pof.authorization.AuthorizationDomain
EntityStoreImplementation=com.tibco.pof.entitystore.tibrepo.TibRepoEntityStore
LogDebug=false
notifier.rv.daemon=tcp\:7500
6.1Test
Start the Tester and pick both services:
Nothing unusual – this looks just like it did when we tested without any Web Services Security!
6.1.1Request Contents – UserName Token
In this particular test, the configuration is to use the UserName Token in Text Mode for Authentication.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="
<SOAP-ENV:Header>
<wsse:Security SOAP-ENV:mustUnderstand="1" xmlns:wsse="
<wsse:UsernameToken xmlns:wsse="
<wsse:Username xmlns:wsse="admin</wsse:Username>
<wsse:Password Type=" xmlns:wsse="admin</wsse:Password>
<wsu:Created xmlns:wsu="2006-08-07T17:09:13.005Z</wsu:Created>
<wsse:Nonce xmlns:wsse="Y7/sTGnv1b3+LLvd4EVPIA==</wsse:Nonce>
</wsse:UsernameToken
</wsse:Security>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns0:Inquiry xmlns:ns0=" Time is it?</ns0:Inquiry>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Notice the wsse and wsu namespaces (UsernameToken, Username, Password, Created, and Nonce), and the literal Username and Password (in clear text) with a timestamp – all of these are in bold. The timestamp (wsu:Created) is used with the timeout parameter to limit the useful time period for the nonce (wsse:Nonce); together, the Nonce and an explicit timestamp permit ID/Passwords to be used “in the clear” while not being reusable or subject to replay. The other form of password is Digest, which is more secure; for the best security using UserName Tokens, you should use TLS/SSL to encrypt the communications channel.
In order to capture this information, I used TCPMon to listen in on Port 7176 and relay everything to Port 7177. To do this, modify the SOAP Client’s Transport Details Tab info as shown below:
6.1.2Troubleshooting – Bad ID or Password
Now, let’s introduce an error into this situation – intentionally change the password on the UserNameToken Identity, so that it will fail authentication with the Administrator, and re-run the test and you will get a SOAPPLUGIN-100023 Error, indicating that a SOAP Fault was sent by the Service:
Go to “Show Console” and look at the stack trace. It is interesting and informative to see all the WSS headers in place, but if you scroll down to the bottom, you will see a WS Security Error:
<Data>
<defaultFaultElement>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>WS Security Error : 131901</faultstring>
<faultactor/>
</defaultFaultElement>
</Data>
6.1.3Troubleshooting – Administrator is unavailable
Stop the Administrator, retest and you won’t find any difference as Designer is doing some caching, so completely stop and restart Designer and test again.
You will get the same error - SOAPPLUGIN–100023, but the Fault will be different – WS Security Error: 111000.
<Data>
<defaultFaultElement>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>WS Security Error : 111000</faultstring>
<faultactor/>
</defaultFaultElement>
</Data>
6.1.4Troubleshooting – Mismatched Configurations
Let’s set it up so that the Client DOESN”T send any Authentication Data and the Server expects it. Change the Outbound Policy by un-checking the Authentication box.
Here is what we get:
<Data>
<defaultFaultElement>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>WS Security Error : 181001</faultstring>
<faultactor/>
</defaultFaultElement>
</Data>
The opposite mismatch doesn’t result in any errors as the Client is sending Authentication data, but the Server isn’t checking for it.
7Change Project from UserName to X.509 for Identification
Modify both the Inbound and Outbound Policies as follows:
Inbound Policy:
Authentication Tab - Highlight X509Token and pick the Trusted Certificates Folder as shown below:
Outbound Policy:
Authentication Tab –pick X509Token as the Security Token, and pick the Identity we created as shown below:
8Second Test – X.509 Identification
Like the previous successful test, this won’t look any different than a plain SOAP process.
8.1Request Contents – BinarySecurityToken
<SOAP-ENV:Envelope xmlns:SOAP-ENV="
<SOAP-ENV:Header>
<wsse:Security SOAP-ENV:mustUnderstand="1" xmlns:wsse="
<wsse:BinarySecurityToken EncodingType=" ValueType=" xmlns:wsse="
MIICMzCCAd0CAQIwDQYJKoZIhvcNAQEEBQAwgasxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxp
m9ybmlhMRMwEQYDVQQHEwp1cy1lbmdsaXNoMRUwEwYDVQQKEwxUZXN0IENvbXBhbnkxGTAXBgNV
BAsUEGNsaWVudF9yb290IFVuaXQxFDASBgNVBAMUC2NsaWVudF9yb290MSowKAYJKoZIhvcNAQkB
FhtjbGllbnRfcm9vdEB0ZXN0Y29tcGFueS5jb20wHhcNMDMwNDI0MjE0NDIzWhcNMTMwNDIxMjE0
NDIzWjCBnDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExEzARBgNVBAcTCnVzLWVu
Z2xpc2gxFTATBgNVBAoTDFRlc3QgQ29tcGFueTEUMBIGA1UECxMLY2xpZW50IFVuaXQxDzANBgNV
BAMTBmNsaWVudDElMCMGCSqGSIb3DQEJARYWY2xpZW50QHRlc3Rjb21wYW55LmNvbTBcMA0GCSqG
SIb3DQEBAQUAA0sAMEgCQQC9biqm9QKA/ltM3syV7sqS+eBKWu433MpqMGH90wzyH780CjpaRrjm
ck+jqIurPBSR7Sn491M2335oWV/+3epLAgMBAAEwDQYJKoZIhvcNAQEEBQADQQBxjIk+4i0qhiiS
LzuvG1G+CuU6AyLVKhlTOylVb2v+21qfjIaDBN2P9ohfQlYdjjnqZIICuk07cREgTwFMv1cm
</wsse:BinarySecurityToken>
</wsse:Security>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns0:Inquiry xmlns:ns0=" Time is it?</ns0:Inquiry>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
8.2Troubleshooting – Bad X.509 Private Key Password
Change the password from “password” to something else, and re-run the test – you will see that the Client fails to communicate with the Server, and you will get the following error:
8.3Troubleshooting – Missing Trusted CA Cert in Trusted Certificates Folder
You will get the same error as the inability to validate credentials with the Administrator when using UserName Tokens, though using X509 Tokens does NOT involve the Administrator in any fashion; just as the Administrator was a trusted authority for UserName Tokens, so is the Trusted Certificates Folder is the authority for X.509 Tokens.
<Data>
<defaultFaultElement>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>WS Security Error : 111000</faultstring>
<faultactor/>
</defaultFaultElement>
</Data>
8.4Troubleshooting – Mismatched Token Types
Edit the Outbound Policy back to UserNameToken and see what happens when it gets authenticated against an Inbound Policy that is expecting a Certificate – you get the SOAPPLUGIN–100023 error with this in the Console:
<Data>
<defaultFaultElement>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>WS Security Error : 181201</faultstring>
<faultactor/>
</defaultFaultElement>
</Data>
However, if you have a mismatch where a Certificate is sent by the Client and a UserName is expected by the Server, you get the same SOAPPLUGIN-100023, but a different WS Security Error:
<Data>
<defaultFaultElement>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>WS Security Error : 181101</faultstring>
<faultactor/>
</defaultFaultElement>
</Data>
9Adding Integrity and Confidentiality
Should I do these one-at-a-time?
10Third Test – Identification, Integrity, and Confidentiality
10.1Troubleshooting
One obvious trouble is mixing expected Direct Reference and Subject Key Identities, missing chain verification…Could be a good point to bring up the use of Java Keystore as a hybrid solution for explicit identities and trusted certificates as now being interchangeable.
TIBCO BusinessWorks™: Understanding Web Services Security1