wssecusertok

While ServiceNow does support the Signing of a SOAP Payload via WS-Security in the SOAP Consumer library, it does not provide out-of-the-box support for the UsernameToken profile of WS-Security.

The other day, a colleague of mine was creating an integration between ServiceNow and Workday, but the Workday instance was requiring WS-Security with the Username token profile. At first, we were worried that this would be an issue. However, after looking at the profile, I realized that there is an easy workaround for basic username profile WS-Security in ServiceNow.

In order to cover this workaround, let me first explain some of the very basics of the Username token as I understand it in WS-Security.

The username token is additional XML that is found in the SOAP Envelope Header. There are four main possible elements that I have seen most often. These are: Username, Password, Timestamp, and Nonce.

Username
This is just a plain text element that represents the username to be authenticated in the request.

Password
Typically this is just a plain text element that represents the password to the username. However, some web services will require this to be a digest hash using a shared secret hashed together with other information for security purposes (see the Oasis specification for more details)

Timestamp
This is a timestamp string in ISO-8601 format that gives the time of the request (you can generate this in ServiceNow by following the steps in my blog post on “Generating an ISO-8601 timestamp in ServiceNow“. The timestamp element may be optional.

Nonce
This is a unique string that will never be used again in a web service call. It depends on the web service whether this will be used, and how it will be used. Sometimes it is a hash, other times it is just a guid-type string. This element may be optional.

In the case of the Workday Authentication, the WS-Security only required the Username and Password elements. Therefore, the WS-Security string would need to look something like:

1
2
3
4
<wsse:UsernameToken>  
 <wsse:Username>MyWorkdayUser</wsse:Username>  
 <wsse:Password>MyPassword</wsse:Password>  
</wsse:UsernameToken>

In order to code this up, we added the following XML into the SOAP Envelope Header:

1
2
3
4
5
6
7
8
9
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bsvc="urn:com.workday/bsvc">
<soapenv:Header>
  <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <wsse:UsernameToken wsu:Id="UsernameToken-3">
      <wsse:Username>${username}</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">${password}</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
</soapenv:Header>

We then were able to pass variable values in for the “${username}” and “${password}” macro variables in the request.

With this, we were able to make SOAP requests with the UsernameToken WS-Security profile.