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
1 Overview of Web Services Security 4
1.1 Identification/Authentication 4
1.2 Integrity/Digital Signatures 4
1.3 Confidentiality/Cryptography 4
2 Getting Started 4
2.1 X.509 Certificates from TIBCO Enterprise Message Service 4
2.2 Java Keystore Tool - Recommended 4
2.3 TIBCO Runtime Agent 4
2.4 TIBCO Administrator 4
2.5 Optional: Tools to view the WSS SOAP Payload 4
3 Building a Simple Web Service in BusinessWorks 5.3 4
3.1 Setup Folders 5
3.2 Building a Schema 5
3.3 Building a Process for a Service 6
3.4 Adding Communications 8
3.5 Using the Wizard 9
3.6 Building the Companion Web Services Client 12
3.7 Testing the Web Service 15
4 Assemble Security Tokens 15
4.1 Identity Objects 16
4.2 Trusted Certificate Folders 17
5 Using the Policy Palette – UserName Token 18
5.1 Utilizing the UserName Token to create an Identification Policy 18
5.1.1 Configure the Inbound Security Policy 18
5.1.2 Configure the Outbound Security Policy 18
5.2 Policy Association with Services 19
5.2.1 Configure the Inbound Security Policy Association 19
5.2.2 Configure the Outbound Security Policy Association 19
6 First Test – UserName Identification 20
6.1 Test 21
6.1.1 Request Contents – UserName Token 22
6.1.2 Troubleshooting – Bad ID or Password 23
6.1.3 Troubleshooting – Administrator is unavailable 24
6.1.4 Troubleshooting – Mismatched Configurations 24
7 Change Project from UserName to X.509 for Identification 25
8 Second Test – X.509 Identification 26
8.1 Request Contents – BinarySecurityToken 26
8.2 Troubleshooting – Bad X.509 Private Key Password 27
8.3 Troubleshooting – Missing Trusted CA Cert in Trusted Certificates Folder 27
8.4 Troubleshooting – Mismatched Token Types 28
9 Adding Integrity and Confidentiality 28
10 Third Test – Identification, Integrity, and Confidentiality 28
10.1 Troubleshooting 28
1 Overview of Web Services Security
Discuss the Profiles – TIBCO currently supports X.509 and Username profiles and their respective tokens.
1.1 Identification/Authentication
Discuss the “Nonce”, timeouts
1.2 Integrity/Digital Signatures
Discuss Direct Reference vs. Subject Key Identities
1.3 Confidentiality/Cryptography
All FIPS 140-2 approved cipher suites – 3DES, AES-128, AES-256.
2 Getting Started
2.1 X.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/certs directory.
2.2 Java 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.3 TIBCO 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.4 TIBCO 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.5 Optional: 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: http://ws.apache.org/commons/tcpmon/download.cgi
3 Building 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.1 Setup 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.2 Building a Schema
Using the XML Tools Palette, drag and drop a Schema Object into the Schema folder, and configure with two string elements as shown in the diagram below.
3.3 Building a Process for a Service
Drag and Drop a Process into the Process Folder, and simply connect the Start to the End Activities. 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.4 Adding 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.5 Using 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.6 Building 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.7 Testing 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!
4 Assemble 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.1 Identity Objects
Drag and Drop two Identity 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.2 Trusted 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:
5 Using the Policy Palette – UserName Token
Open up the Security Policies Folder and drag and drop two Security Policy objects and two Security 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.1 Utilizing the UserName Token to create an Identification Policy
5.1.1 Configure the Inbound Security Policy
· Config Tab:
o Name: Inbound
o Policy Type: inbound
o Authentication: checked (do not check any other boxes!)
· Authentication Tab:
o Highlight UserNameToken – leave Trusted Certificates Folder Blank
5.1.2 Configure the Outbound Security Policy
· Config Tab:
o Name: Outbound
o Policy Type: outbound
o Authentication: checked (do not check any other boxes!)
· Authentication Tab:
o Security Token: Pull-down menu to UserNameToken
o Username Password Identity: pick - /Security/Identities/UserNameToken.id
o Password Type: Text
5.2 Policy Association with Services
5.2.1 Configure the Inbound Security Policy Association
· Configuration Tab:
o Name: Inbound
o Apply Policy to: (navigate to the service as shown below)
o Inbound Message Policy: (navigate to the policy as shown below)
5.2.2 Configure the Outbound Security Policy Association
· Configuration Tab:
o Name: Outbound
o Apply Policy to: (navigate to the SOAP Request/Reply as shown below)
o 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.
6 First 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.1 Test
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.1 Request 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="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header>
<wsse:Security SOAP-ENV:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:Username xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">admin</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">admin</wsse:Password>
<wsu:Created xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">2006-08-07T17:09:13.005Z</wsu:Created>
<wsse:Nonce xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">Y7/sTGnv1b3+LLvd4EVPIA==</wsse:Nonce>
</wsse:UsernameToken
</wsse:Security>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns0:Inquiry xmlns:ns0="http://xmlns.example.com/unique/default/namespace/1154630967053">What 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.2 Troubleshooting – 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.3 Troubleshooting – 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.