This type of client integration method requires the client application developer to generate SOAP client applications based on the OneSpan Authentication Server WSDL files. OneSpan Authentication Server comes with the following WSDL files describing the different SOAP interfaces:
Authentication.wsdl. Specifies the supported user authentication operations. auth-sdk full-sdk
Signature.wsdl. Specifies the supported transaction authentication operations. auth-sdk full-sdk
Administration.wsdl. Specifies the supported administration operations. This file also specifies the report generation operation. full-sdk
Provisioning.wsdl. Specifies the supported software authenticators or software/hardware authenticators provisioning operations. full-sdk
You can find these files in sdk_install_dir/wsdl/.
This client integration type requires advanced understanding of SOAP-related details on top of OneSpan Authentication Server concepts. Because of the required level of SOAP knowledge, this API is more appropriate for advanced users who want to have low level access to OneSpan Authentication Server.
For more information about the structure of SOAP messages, see SOAP message structure.
If your organization is impacted by the General Data Protection Regulation (GDPR), ensure that the SOAP communicator interface is configured to use SSL. If an OneSpan Authentication Server component does not support SSL, the SOAP interface must be configured without SSL; however, to be GDPR-compliant, you must set up an encrypted VPN tunnel to secure the communication.
For more information about GDPR, refer to the OneSpan Authentication Server General Data Protection Regulation Compliance Guide.
SOAP message structure
A typical SOAP message has the following skeleton:
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope">
<soap:Header>
...
</soap:Header>
<soap:Body>
...
<soap:Fault>
...
</soap:Fault>
</soap:Body>
</soap:Envelope>This message structure is used both in SOAP requests and SOAP responses.
The root element of a SOAP message is the Envelope XML element. This element contains the following other elements:
Header (optional). Contains the header information.
Body. Contains call and response information. This body element can optionally contain a Fault element, which contains information about errors that occurred while processing the SOAP message.
The Envelope element can specify one or more namespace reference attributes. These attributes have the following format:
xmlns:namespace
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)Optional HTTP authorization header for service users
When using a service user to perform administrative operations, the service user’s credentials can be provided in the HTTP authorization header:
Authorization: Apikey serviceUserId:1234567890abcdef
When working with the .NET or Java SDK, it is simpler (and has the same effect) to provide service user credentials in the sessionID SOAP field.