Web Services Authentication

Online Marketing Suite Web services provide a secure authentication layer to ensure that access to your company information and transfer of data is secure. The Authentication procedure is based on the OASIS Web Services Security Username Token Profile 1.0 specification.

To support authentication, each Web service request must include an authentication header. The main components of Web Services authentication include:

Username: A concatenation of the user’s SiteCatalyst username and company..

Nonce: A unique, random alphanumeric string generated for each SOAP request. If you attempt to use the same nonce for multiple web services requests, the Online Marketing Suite returns an error indicating the nonce is no longer valid. Use your preferred tool for generating the nonce value. For example: java.security.SecureRandom, MD5, etc.

Created: The current ISO-8601 timestamp. For example: 2010-01-15T16:20:47-07:00.

Secret: A value generated by SiteCatalyst when a user is granted Web Service access to SiteCatalyst. You should keep this value confidential.

Password: A digest password generated with the following algorithm: base64Encode(sha1Hash(<Nonce><TimeStamp><Secret>))

If Online Marketing Suite servers successfully create the same password digest using the three public pieces of information and the shared secret then the request is authenticated. Otherwise the client receives an HTTP 401 Unauthorized response.

You must include an authentication header when using either the SOAP or the REST interface to the Online Marketing Suite Web services.

Sample SOAP Authentication Header

      <wsse:Security SOAP-ENV:mustUnderstand="1">
        <wsse:UsernameToken wsu:Id="User">
          <wsse:Username>jdoe:Corp1</wsse:Username>
          <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">
            NDFmNmIzNjNkOWQ3MmQyNTNmODJmMGI4ODI2ZTg5OGNhYjU4NzIzMg==
          </wsse:Password>
          <wsse:Nonce>72cc11a1cefd1f218f34cc1e576bb65b</wsse:Nonce>
          <wsu:Created>2010-01-15T16:20:47-07:00</wsu:Created>
        </wsse:UsernameToken>
      </wsse:Security>

Sample REST Authentication Header

      X-WSSE: UsernameToken Username="jode:Corp1", PasswordDigest="NDFmNmIzNjNkOWQ3MmQyNTNmODJmMGI4ODI2ZTg5OGNhYjU4NzIzMg==", Nonce="72cc11a1cefd1f218f34cc1e576bb65b", Created="2010-01-15T16:20:47-07:00" 
      Alternatively, you can add the authentication credentials to the REST URL as the following query string parameters:
        auth_username
        auth_digest
        auth_nonce
        auth_created

To generate a digest password

  1. Create a nonce.
    You must create a unique nonce for every web services SOAP request to prevent man-in-the-middle attacks.
  2. Generate a current timestamp (string format).
    Use the ISO-8601 date/time format to specify the timestamp. For example: 2010-01-15T16:20:47-07:00. For more information, visit www.iso.org/iso/date_and_time_format.
  3. Retrieve your shared secret from SiteCatalyst.
    1. In the Online Marketing Suite, select Admin > Admin Console.
    2. In the left-side navigation, select Admin Console > Company > Web Services.
    3. Locate your username, then copy the value in the Shared Secret column.
      If there is no Shared Secret value for your username, you do not have Web Services access rights (see Enabling Web Services Access).
  4. Concatenate the nonce, timestamp, and shared secret, in that order.
    For example: combined_string = concat(nonce, time, secret)
  5. Create an SHA1 hash of the string created in Step 4.
    Using openssl, the command is: echo -n combined_string | openssl | dgst -sha1
  6. Create a Base64 encoding of the SHA1 hash.
  7. Include the Base64 encoded value as the Password value in the authentication header of the Web Services request.