Enabling WS-Security
Enterprise
When a Web service exposes private-network data to the outside world, that data travels through 4 - 7 separate protocol layers (see: TCP/IP or OSI) thus introducing potential security vulnerabilities. Implementing security at a higher layer on the protocol stack — the application layer, for instance — generally provides better protection than an implementation at the lower transport layer, which provides only HTTPS security.
To implement application-layer security, enable WS-security (a CXF configuration) on your Web service. WS-security defines a new SOAP header which is capable of carrying various security tokens that systems use to identify a Web service caller's identity and privileges, and can include the following:
- encryption
- digital signature
- time stamp
You can also add custom Token Validators to the SOAP Component.
Enabling WS-Security
To enable WS-security on a CXF Web service in your application, you must add WS-configurations to the SOAP Component in your flow. This approach enables WS-security locally within your flow, for one Web service only.
To the Mule flow that involves a Web service, add a SOAP Component to publish, consume, or proxy a Web service. Complete the following steps to configure WS-security on the SOAP component.
- Open the Pattern Properties panel, then click the Security tab.
Click the
icon in the Add Configuration Element pane to create a new key-value pair. 
In XML, this step mirrors the addition of a key-value pair inside the ws-config child element of a ws-security element. By adding configuration elements to your SOAP component, you are creating a map of key-value pairs that correspond to the CXF WSS4J security-configuration text strings in WSHandlerConstants and WSConstants.
- Enter a key, such as
action, in the open Key field and press Enter. - Double-click the new key-value line item you created to open the Add Configuration Property panel.
Enter information in either the Value field OR the Value Reference Field according to the table below.
Value Enter a WS Constant (a class to define the kind of access the server allows) or a WSHandlerConstant (a class to specify the names, actions, and other strings for data deployment of the WSS handler). For example, enter UsernameTokenin the value field.Value Reference Enter the bean that the key must reference. When the key must reference a bean (for instance, when the key is passwordCallbackRef), enter the name of the bean in the Value Reference field.Click Finish to save the key-value pair.
- Repeat the steps above to add as many ws-security configurations as you wish to your Web service, then click OK to save your configurations.
- To your CXF element (i.e. SOAP component), add a child element for
cxf:ws-security. - Within the
cxf:ws-securitychild element, add a child element forcxf:ws-config. - Within the
cxf:ws-configchild element, add a child element forcxf:property. Add two attributes to the cxf:property child element according to the table below. Be sure to enter either a
valueOR avalue-ref; the two are mutually exclusive.key Specify a name for the property. value Specify a WS Constant (a class to define the kind of access the server allows) or a WSHandlerConstant (a class to specify the names, actions, and other strings for data deployment of the WSS handler). For example, enter UsernameTokenin the value field.value- ref Specify the bean that the key must reference. When the key must reference a bean (for instance, when the key is passwordCallbackRef), specify the name of the bean as the value-ref.- Repeat the preceding step to add as many WS-security configurations as you wish to your Web service. Refer to sample code below.
Adding a Token Validator
If you have enabled WS-Security on your Web service in Mule, you can further configure the SOAP component to delegate authentication of the message credentials it transmits or receives.
A SOAP component may get bogged down with the tasks of both processing and authenticating messages. To lighten this load, you can instruct WS-security to delegate certain message authentication tasks to a Token Validator, including:
- validating the
UsernameTokenin cases where theCallbackHandlerimplementation does not have access to the password - validating the attributes of a received SAML assertion
- dispatching a received security token to a third-party security service for validation
Complete the following procedure to add token validators to your Web service.
In the Security tab of your SOAP component, click one or more of the check boxes to delegate message authentication tasks to token validators. Refer to the table below for the activity of each token validator.
Token Validator
Purpose
User Name
Authenticates the username and password credentials associated with each message in a manner similar to HTTP Digest authentication.
Checks messages against SAML 1.1 assertion statements in order to approve or reject access to the Web service.
Checks messages against SAML 2.0 assertion statements in order to approve or reject access to the Web service.
Timestamp
Examines the timeliness of messages – when they were created and received, and when they expire – to make decisions about which messages to process.
Signature
Examines the digital signature attached to messages to make decisions about which messages to process.
Binary Security Token
Examines binary encoded security tokens (such as Kerberos) to make decisions about which messages to process.
In the Bean field associated with the token validator you have selected, use the drop-down menu to select an existing bean that your token validator will reference to apply, replace, or extend the default behavior associated with a specific security token.
If you have not yet created any beans, click the
button to open a new properties panel in which you can create and configure a new bean. The bean imports the Java class you have built to specify the custom validator's override behavior.
- Click OK to save changes.
Above all flows in your Mule project, create a global
spring:beanelement to import the Java class you have built to specify the token validator's behavior. Refer to code sample below.- To the CXF element in your flow, add a child element (below any
cxf:ws-configelements you may have added) forcxf:ws-custom-validator. To the
cxf:ws-custom-validatorchild element, add a child element according to the type of action you want the validator to perform. Refer to the table below.Token Validator
Purpose
cxf:username-token-validator
Authenticates the username and password credentials associated with each message in a manner similar to HTTP Digest authentication.
cxf:saml1-token-validator
Checks messages against SAML 1.1 assertion statements in order to approve or reject access to the Web service.
cxf:saml2-token-validator
Checks messages against SAML 2.0 assertion statements in order to approve or reject access to the Web service.
cxf:timestamp-token-validator
Examines the timeliness of messages – when they were created and received, and when they expire – to make decisions about which messages to process.
cxf:signature-token-validator
Examines the digital signature attached to messages to make decisions about which messages to process.
cxf:bst-token-validator
Examines binary encoded security tokens (such as Kerberos) to make decisions about which messages to process.
- Add a
refattribute to the validator to reference the global spring:bean element which imports the Java class.
Complete Code Example
Go Further
- Learn more about configuring a SOAP component in your Mule application.
- Review an the Mule example application which demonstrates the use of WS-security.
- Review a Mule example application which demonstrates a SOAP Web service.
This page
Other pages
Account
Administration