Understanding WSS 2009

http://www.tibco.com

Global Headquarters3303 Hillview AvenuePalo Alto, CA 94304Tel: +1 650-846-1000Toll Free: 1 800-420-8450Fax: +1 650-846-1005

© 2009, TIBCO Software Inc. All rights

reserved. TIBCO, the TIBCO logo, The

Power of Now, and TIBCO Software are

trademarks or registered trademarks of

TIBCO Software Inc. in the United States

and/or other countries. All other product and

company names and marks mentioned in

this document are the property of their

respective owners and are mentioned for

identification purposes only.

DRAFT

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.

Carlo MilonoDirector of Engineering – Program Management

Version 0.9August 2006

http://www.tibco.com/

Document

Table of Contents

1 Overview of Web Services Security.................................................................41.1 Identification/Authentication.................................................................................41.2 Integrity/Digital Signatures...................................................................................41.3 Confidentiality/Cryptography................................................................................4

2 Getting Started...............................................................................................42.1 X.509 Certificates from TIBCO Enterprise Message Service...............................42.2 Java Keystore Tool - Recommended...................................................................42.3 TIBCO Runtime Agent.........................................................................................42.4 TIBCO Administrator............................................................................................42.5 Optional: Tools to view the WSS SOAP Payload.................................................4

3 Building a Simple Web Service in BusinessWorks 5.3...............................43.1 Setup Folders......................................................................................................53.2 Building a Schema...............................................................................................53.3 Building a Process for a Service..........................................................................63.4 Adding Communications......................................................................................83.5 Using the Wizard.................................................................................................93.6 Building the Companion Web Services Client....................................................123.7 Testing the Web Service....................................................................................15

4 Assemble Security Tokens..........................................................................154.1 Identity Objects..................................................................................................164.2 Trusted Certificate Folders.................................................................................17

5 Using the Policy Palette – UserName Token.............................................185.1 Utilizing the UserName Token to create an Identification Policy........................185.1.1 Configure the Inbound Security Policy...............................................................185.1.2 Configure the Outbound Security Policy............................................................185.2 Policy Association with Services........................................................................195.2.1 Configure the Inbound Security Policy Association............................................195.2.2 Configure the Outbound Security Policy Association.........................................19

6 First Test – UserName Identification..........................................................206.1 Test....................................................................................................................216.1.1 Request Contents – UserName Token..............................................................226.1.2 Troubleshooting – Bad ID or Password.............................................................236.1.3 Troubleshooting – Administrator is unavailable.................................................246.1.4 Troubleshooting – Mismatched Configurations..................................................24

7 Change Project from UserName to X.509 for Identification.....................25

8 Second Test – X.509 Identification.............................................................268.1 Request Contents – BinarySecurityToken.........................................................268.2 Troubleshooting – Bad X.509 Private Key Password........................................278.3 Troubleshooting – Missing Trusted CA Cert in Trusted Certificates Folder.......278.4 Troubleshooting – Mismatched Token Types....................................................28

9 Adding Integrity and Confidentiality..........................................................28

TIBCO BusinessWorks™: Understanding Web Services Security 2

Document

10 Third Test – Identification, Integrity, and Confidentiality.........................2810.1 Troubleshooting..............................................................................................28


Document

1 Overview of Web Services SecurityDiscuss the Profiles – TIBCO currently supports X.509 and Username profiles and their respective tokens.

1.1 Identification/AuthenticationDiscuss the “Nonce”, timeouts

1.2 Integrity/Digital SignaturesDiscuss Direct Reference vs. Subject Key Identities

1.3 Confidentiality/CryptographyAll FIPS 140-2 approved cipher suites – 3DES, AES-128, AES-256.

2 Getting Started

2.1 X.509 Certificates from TIBCO Enterprise Message ServiceWe 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 - RecommendedIt 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 AgentWe 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 AdministratorIn 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 PayloadWeb 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


http://ws.apache.org/commons/tcpmon/download.cgi

Document

3 Building a Simple Web Service in BusinessWorks 5.3Create 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 FoldersDrag 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 SchemaUsing 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.


Document

3.3 Building a Process for a ServiceDrag 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.


Document

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.


Document

3.4 Adding CommunicationsHighlight 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.


Document

3.5 Using the WizardNow 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:


Document

Notice that we now have three new objects in the Processes Folder:

infTellingTime WSDL

wsTellingTime Process

infTellingTime Service


Document

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.


Document

Here is the resulting Concrete WSDL source:

3.6 Building the Companion Web Services Client


Document

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.


Document

As the elements are “Required”, you will need to open the Input Tab and ask for the Time!


Document

3.7 Testing the Web ServiceNow 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 TokensWe will be using X.509 Certificates from the TIBCO Enterprise Message Service distribution, which can be found in the

<tibco>/bin/certs directory.


Document

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:


Document

4.2 Trusted Certificate FoldersNext, 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:


Document

5 Using the Policy Palette – UserName TokenOpen 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


Document

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: OutboundTIBCO BusinessWorks™: Understanding Web Services Security 19

Document

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 IdentificationAs 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:


Document

#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 TestStart the Tester and pick both services:

Nothing unusual – this looks just like it did when we tested without any Web Services Security!


Document

6.1.1 Request Contents – UserName TokenIn 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.


Document

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 PasswordNow, 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:


Document

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 unavailableStop 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>




<faultactor/>


</Data>


Document

6.1.4 Troubleshooting – Mismatched ConfigurationsLet’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>




<faultactor/>


</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.

7 Change Project from UserName to X.509 for IdentificationModify 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:


Document

Authentication Tab – pick X509Token as the Security Token, and pick the Identity we created as shown below:

8 Second Test – X.509 IdentificationLike the previous successful test, this won’t look any different than a plain SOAP process.

8.1 Request Contents – BinarySecurityToken<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:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">

MIICMzCCAd0CAQIwDQYJKoZIhvcNAQEEBQAwgasxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxp

m9ybmlhMRMwEQYDVQQHEwp1cy1lbmdsaXNoMRUwEwYDVQQKEwxUZXN0IENvbXBhbnkxGTAXBgNV

BAsUEGNsaWVudF9yb290IFVuaXQxFDASBgNVBAMUC2NsaWVudF9yb290MSowKAYJKoZIhvcNAQkB

FhtjbGllbnRfcm9vdEB0ZXN0Y29tcGFueS5jb20wHhcNMDMwNDI0MjE0NDIzWhcNMTMwNDIxMjE0

NDIzWjCBnDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExEzARBgNVBAcTCnVzLWVu

Z2xpc2gxFTATBgNVBAoTDFRlc3QgQ29tcGFueTEUMBIGA1UECxMLY2xpZW50IFVuaXQxDzANBgNV

BAMTBmNsaWVudDElMCMGCSqGSIb3DQEJARYWY2xpZW50QHRlc3Rjb21wYW55LmNvbTBcMA0GCSqG

SIb3DQEBAQUAA0sAMEgCQQC9biqm9QKA/ltM3syV7sqS+eBKWu433MpqMGH90wzyH780CjpaRrjm

ck+jqIurPBSR7Sn491M2335oWV/+3epLAgMBAAEwDQYJKoZIhvcNAQEEBQADQQBxjIk+4i0qhiiS


Document

LzuvG1G+CuU6AyLVKhlTOylVb2v+21qfjIaDBN2P9ohfQlYdjjnqZIICuk07cREgTwFMv1cm

</wsse:BinarySecurityToken>

</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>

8.2 Troubleshooting – Bad X.509 Private Key PasswordChange 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.3 Troubleshooting – Missing Trusted CA Cert in Trusted Certificates FolderYou 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>




<faultactor/>



Document

</Data>

8.4 Troubleshooting – Mismatched Token TypesEdit 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>




<faultactor/>


</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>




<faultactor/>


</Data>

9 Adding Integrity and ConfidentialityShould I do these one-at-a-time?

10 Third Test – Identification, Integrity, and Confidentiality

10.1 TroubleshootingOne 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.


Document


Understanding WSS 2009

Documents

tibco businessworks

simple web service

web services security

web services wizard

tibco administrator

identification policy

tibco logo

service palette