Optional HTTP Headers for Correlation ID

OneSpan Authentication Server SDK supports the use of a correlation ID, also known as the transit ID. This correlation ID contains a unique identifier value which is attached to requests and messages to designate a particular transaction or event. This ID is defined using a common non-standard HTTP header request field that correlates requests between a client and server. The provided correlation ID is part of the audit in OneSpan Authentication Server that can for example be used to track corresponding operations in the auditing data.

OneSpan Authentication Server verifies whether a correlation ID value exists in the request header of a SOAP command. If not, it automatically generates a unique correlation ID.

SOAP client

The SOAP client classes have been extended with a new method that is used to append the extra HTTP parameters to the message.

C# .NET

The following needs to be called before the WebService client command call:

/// <summary>
/// Append additional parameters to the HTTP header
/// </summary>
/// <param name="additionalHTTPHeaderParameters">Extra parameters for the HTTP's message header</param>
public void SetHTTPHeaderParameters(HTTPHeaderParameters additionalHTTPHeaderParameters);

Below is an example how to append the correlation ID before the command call:

public PolicyResults doView(string policyId, HTTPHeaderParameters headerParameters = null, Guid? correlationId = null)
{
  AdministrationSession session = adminHandler.getSession();

  setValue(PolicyAttributeIDEnum.POLICYFLD_POLICY_ID, policyId);

  HTTPHeaderParameters headerParams = headerParameters ?? HTTPHeaderParameters.Create();
  Guid id = correlationId ?? Guid.NewGuid();

  PolicyResults res = session
                        .getAdminService(headerParams.withCorrelationId(id.ToString()))
                        .policyExecute(
                          session.getSessionID(),
                          PolicyCmdIDEnum.POLICYCMD_VIEW,
                          attributes.ToArray()
                        );

  return res;
}

Java

Extra steps need to be performed when preparing the binding context with the new header parameter to call the command. Below is an example how to append the correlation ID before the command call:

// Service URL
String soapURL = "http://localhost:8888";

// Attribute collection containing the Correlation Id
final String correlationID = java.util.UUID.randomUUID().toString();
HTTPHeaderParameters headerParams = HTTPHeaderParameters.Create().withCorrelationId(correlationID);

// SOAP CLIENT
AuthenticationPortType authenticationPortType = new Authentication().getAuthenticationPortType();

// Get Request Context
Map<String, Object> context = ((javax.xml.ws.BindingProvider) authenticationPortType).getRequestContext();
context.put(javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY, soapURL);

// Get the HTTP request header
Map<String, List<String>> requestHeaders = (Map<String, List<String>>) context.get(javax.xml.ws.handler.MessageContext.HTTP_REQUEST_HEADERS);

// Include Correlation Id
if (requestHeaders != null) {
  // If not empty the Correlation Id is appended
  requestHeaders.putAll(headerParams.getHTTPHeaderParameters());
  context.put(javax.xml.ws.handler.MessageContext.HTTP_REQUEST_HEADERS, requestHeaders);
} else {
  context.put(javax.xml.ws.handler.MessageContext.HTTP_REQUEST_HEADERS, headerParams.getHTTPHeaderParameters());
}

SOAP handlers

The interface of each of the commands mapped by the SOAP handlers have been extended in such a way that an instance of the HTTPHeaderParameters class can be optionally included.

C# .NET

/// <summary>
/// Get a one step challenge
/// </summary>
/// <param name="headerParameters">Extra parameters for the HTTP's message header</param>
/// <returns>AuthenticationCommandResponse</returns>
public AuthenticationCommandResponse getChallenge(HTTPHeaderParameters headerParameters = null)

Java

/**
 * Administration logon: - static password - response only - challenge
 * response (first stage)
 *
 * @param domain user domain
 * @param userID user ID
 * @param pin DIGIPASS PIN
 * @param dpResponse DIGIPASS response
 * @param staticPwd user static password
 * @param requestHostCode request host code
 * @param headerParams extra HTTP request parameters
 * @return CredentialsResponse
 */
public AdministrationCommandResponse logon(String domain,
                                          String userID,
                                          String pin,
                                          String dpResponse,
                                          String staticPwd,
                                          Credentials.RequestHostCode requestHostCode,
                                          HTTPHeaderParameters headerParams)