Message-Based Security for SOAP in webMethods: Part 1 (Username_Token)

webMethods Integration Server provides message-based security for SOAP messages using WS-Security. In contrast to transport-based authentication frameworks such as HTTPS,
which secure the endpoints of a connection against threats, WS-Security secures the
message transmission environment 
between endpoints.

When using WS-Security, the security information is carried inside header portion of the SOAP envelope. There are many security options that Integration Server supports via WS-Security like Signing the message content, Encryption, Message Replay detection, Authentication tokens etc..

In this post, we will see a simple and most basic security option – Username Token. Using this option, we can replace the typical “Basic Authentication”, where credentials are carried over HTTP transport headers, with “Message-Based Authentication”. Here, the credentials are carried inside header portion of the SOAP envelope.

Implementation in webMethods

Starting with Integration Server 8.2, you can implement WS-Security using standard
WS-SecurityPolicy. This policy file is a set of security assertions that describes the security options to be used. So, any web service that attaches a WS-Security policy expects that all the security options that are mentioned in the policy should be validated.

In this post, we will use a simple “Username_Token” policy which will help us to perform message based authentication. Below is how this policy content looks:

<wsp:Policy wsu:Id=”Username_Token” Name=”Username and Token”

Creating and Uploading the “Username_Token” Policy

  1. Create an empty file using any of your favorite editors.
  2. Copy the content shown in the above-quoted block into the file.
  3. Rename the file as “Username_Token.policy”
  4. Now, copy the file and paste it under


    Tip: The WS-Policies that you can attach to web service descriptors must reside in this location. Integration Server provides pre-defined WS-Policies with settings for a number of standard security configurations.  You can use the out-of -the-box policies as is, or use them as templates for creating custom WS-Policies 

  5. Once you paste the policy file in above-mentioned location, wait for a second and refresh the folder.
    • If you do not see your policy file then check if it is moved to a subfolder named “invalid” in the same location. If you see it inside “invalid” folder, then it means there is some issue with your policy file. Either the content is invalid or the security assertions aren’t placed right. Please recheck.
    • If your policy does not disappear, then it is good news. Your policy file has been accepted and uploaded by Integration Server.

Attaching the Policy

If you correctly followed the steps in the previous section then your policy is ready. Now, let’s see how to use it when creating web services.

  1. Open any existing web service provider descriptor or create one if you do not have any.
  2. Click on the “Policies” tab as shown in below picture:
  3. Now, click on “Attach Policy” icon from the designer toolbar. Choose the ‘Username_Token’ policy from all the available policies that are listed.
  4. Save your web service provider descriptor.

Consuming and Invoking the service

We will now see, how to pass on credentials as part of SOAP message in two clients:

  • webMethods Consumer Connector


  1. Create a project using the WSDL from web service provider descriptor on Integration Server.
  2. Open the “Request” from operation you are planning to invoke
  3. Do not set any transport header “basic authentication” like you usually do. Leave it as ‘No Authorization’ only.
  4. Navigate and scroll through the “Request Properties” section on the left side panel of SOAP UI. When you find, set below properties with values as shown below
    • WSS-Password Type = PasswordText
    • Username = . Example: Administrator
    • Password = <Password_to_access_Integration_Server>. Example: manage
  5. Submit your request with valid inputs and it should work smoothly without any “Access Denied” issues.
  6. Here, you may want to notice how the WS-Security is carrying the credentials in SOAP header. To see that, click on the “RAW” tab on the left side of your request panel as shown below:
  7. The complete SOAP header in the above message looks like below:; xmlns:wsu=”“>


CLIENT 2 – webMethods Consumer Connector:

  1. Create a webMethods consumer on any Integration Server using the provider WSDL URL
  2. After creation, OPEN and RUN the connector. As usual, an input prompt appears. Fill in the authentication details under “auth/message/user” and “auth/message/password” instead of filling under “auth/transport”
  3. Submit the request by clicking on ‘OK’
  4. You should get the response as expected without any issues

That’s it. You’ve now learned following things today:

  1. How to place policies under Integration Server.
  2. How to attach a policy to web service descriptor.
  3. How to pass a simple message based authentication credentials with web service using SOAP UI and webMethods Consumer Connector.

Thank you for reading this post. I will publish another one soon as a continuation of this topic. Till then, #happy_integration


3 thoughts on “Message-Based Security for SOAP in webMethods: Part 1 (Username_Token)

  1. So as per the instructions, this should work with out creating handlers right? Please let me know what is the use of creating handler in case if we want to pass creds in header.

    Liked by 1 person

    1. Hi Rohit, just adding credentials into soap header using a handler on consumer side does not do any good. Your webservice provider should be ready and well aware that it should expect the credentials inside soap header and not via transport header. So, there should be a policy enforcement that will be part of the WSDL contract to set the expectations to all the contract holding consumers and provider too. This way, consumer knows what provider is expecting and provider knows the constraints on the WSDL


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s