Execute operations (SOAP API)

An execute operation is a SOAP operation to perform administrative actions on specified objects that exist within the OneSpan Authentication Server data model. Each administrative SOAP operation requires service user credentials or a successful administrative logon.

OneSpan Authentication Server provides an administrative session identifier (sessionID) as a response to a successful administrative logon request. Alternatively, when working with service users, the sessionID value is constructed using the service user’s credentials. Each administrative operation on the OneSpan Authentication Server requires the sessionID.

Execute operations are either executed immediately, or scheduled and effectively executed only after approval via maker–checker authorization.

Immediate execution

Immediate execution means that the operation is performed instantly when the request is submitted. This is the regular execution mode.

To perform an execute operation via SOAP immediately

1. Create a SOAP request for the object upon which you want to perform an operation.

2. Specify the administrative session identifier (sessionID) in the SOAP request.

3. Specify the command you want to execute in the SOAP request.

4. Specify one or more attributes as parameters for the SOAP operation. Attributes are key/value pairs.

5. Import the OneSpan Authentication Server SSL server certificate as trusted root certificate on the machine where your client application is running.

   This will allow your SOAP client application to connect to OneSpan Authentication Server securely via SSL.

6. Send the SOAP request to OneSpan Authentication Server. By default, the SOAP request should be transmitted over HTTPS with the OneSpan Authentication Server.

   By default, OneSpan Authentication Server is configured to accept SOAP requests on port 8888.

7. Receive the SOAP response.

8. Process the SOAP response.

For more information about the structure of SOAP messages, see SOAP message structure.

Execution using maker–checker authorization

If maker–checker authorization is enabled, an execute operation is not executed immediately. It is deferred and can only be executed after approval by another administrator.

In this case, the execute operation is to be performed twice:

1. The operation is performed as usual (see Immediate execution), but additionally passing information about the approving administrator, i.e. the *_CHECKER_USERID and *_CHECKER_DOMAIN parameters.

   The operation is scheduled and returns a pending operation identifier (POID) to identify the scheduled operation. The approving administrator receives a notification to either approve or reject the pending operation using approvePendingOperation or rejectPendingOperation, respectively.

   The maker administrator can pass an auto-execution parameter (*_AUTO_EXECUTE). If set to true, the pending operation will be executed automatically on behalf of the maker administrator upon approval by the checker administrator. In that case, the next step is performed implicitly.

2. Once the pending operation has been approved and auto-execution is not set, the execute operation is performed a second time, this time passing the POID.

   The pending operation is executed normally.

SOAP request structure

An <object>execute SOAP request typically uses the following format:

<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:adm="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Administration">
    <soapenv:Header/>
    <soapenv:Body>
        <adm:????Execute>
            <sessionID>session identifier string</sessionID>
            <cmd>?????CMD_!!!!!!</cmd>
            <attributeSet>
                <!--Zero or more repetitions:-->
                <attributes>
                    <value xsi:type="xsd:!!!!!!">?????</value>
                    <attributeID>?????</attributeID>
                </attributes>
            </attributeSet>
        </adm:????Execute>
    </soapenv:Body>
</soapenv:Envelope>

The SOAP body element should only contain an <object>execute element, where object specifies the requested object (line 8). This element is defined in the namespace adm. Therefore, adm needs to be declared in the Envelope element as an attribute.

A valid <object>execute request needs to follow these additional rules:

• The <object>execute element should contain only one attributeSet element.

• The attributeSet element should contain zero or more attribute elements.

• The <object>execute element should contain one sessionID element. To get a session identifier, an administrative logon has to be executed. Alternatively, when working with service users, sessionID is constructed using the service user's credentials (see Administrative logon/logoff (SOAP API)).

• The <object>execute element should contain one cmd element.

Each attribute element should contain the following sub-elements:

• attributeID (required). The attribute identifier. The supported credential attribute identifiers are listed in SOAP authentication (Overview).

• value (required). The attribute value. This element also requires the specification of the value type using the following attribute definition xsi=type=”xsd:type.

• attributeOptions (optional). This element provides directive information about how OneSpan Authentication Server should handle the attribute value during request processing. Following options are supported for this element:

  • NULL. Indicates that the specified attribute should be set to zero.

  • NEGATIVE. Used for search criteria to say NO when searching for a specific attribute.

  • MASKED. Used to indicate OneSpan Authentication Server to mask the attribute value (e.g. when auditing the SOAP request).

To set an attribute option, add the option element in the attributeOptions element and give the option element the value true.

To set the MASKED option, add the following:

<attributeOptions><masked>true</masked></attributeOptions>

SOAP response structure

An <object>execute SOAP response typically uses the following format:

<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:adm="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Administration">
    <!-- ... Additional namespace declarations -->
    <soapenv:Header/>
    <soapenv:Body>
        <adm:????ExecuteResponse>
            <results xsi:type="USER-TYPES:?????Results">
                <resultCodes xsi:type="BASIC-TYPES:ResultCodes">
                    <returnCodeEnum>RET_SUCCESS</returnCodeEnum>
                    <statusCodeEnum>STAT_SUCCESS</statusCodeEnum>
                    <returnCode>0</returnCode>
                    <statusCode>0</statusCode>
                </resultCodes>
                <resultAttribute xsi:type="USER-TYPES:?????AttributeSet">
                    <attributes xsi:type="USER-TYPES:????Attribute">
                        <value xsi:type="xsd:string">?????????</value>
                        <attributeID>!!!!!!!!!</attributeID>
                   </attributes>
               </resultAttribute>
               <errorStack xsi:type="BASIC-TYPES:ErrorStack"/>
            </results>
        </adm:??????ExecuteResponse>
    </soapenv:Body>
</soapenv:Envelope>

The SOAP body element should only contain an <object>ExecuteResponse element, where object specifies the requested object (line 9). The <object>ExecuteResponse element always contains a results element, which contains the following elements:

• resultCodes (required). This element contains the following sub-elements:

  • returnCode. The operation return code indicating the overall result of the request processing.

  • statusCode. The operation status code indicating the reason for failure of any returnCode different from success (0).

  • returnCodeEnum. The identifier corresponding to the returnCode.

  • statusCodeEnum. The identifier corresponding to the statusCode.

• resultAttribute (required). This element contains zero or more attributes elements.

• errorStack (required). Contains zero or more errors elements.

  • errors. Each errors element contains the following sub-elements:

    • errorCode. The error code integer.

    • errorDesc. A string representation of the error code.

For a complete list of possible error codes, see Error codes and messages.

In this case, the resultAttribute element is used to refer to attributes elements for the specified object (object).