Query operations (SOAP API)

A query is a SOAP operation to perform searches 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.

To perform a query operation via SOAP

1. Prepare a query SOAP request for the object upon which you want to perform a search:

   1. Specify sessionID in the SOAP request.

   2. Specify one or more search attributes as parameters for the SOAP operation.

      Attributes are key/value pairs. These search attributes define the search criteria for the SOAP query.

   3. Specify one or more object attributes that should be returned by the query.

      Optionally, you can specify various query options, e.g.:

      • distinctive

      • rowoffset

      • rowcount

      • count

2. 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.

3. 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.

4. Receive the SOAP response.

5. Process the SOAP response.

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

After upgrading OneSpan Authentication Server, server data is continuously migrated while the already upgraded OneSpan Authentication Server service/daemon is running. Until data migration has been completed, the result of a query command may be incomplete and may include both migrated and non-migrated data. This means that, for instance, values for new data fields or policy default settings may be missing or not set correctly in the query result.

SOAP request structure

An <object>query 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:????Query>
            <sessionID>?</sessionID>
            <attributeSet>
                <!--Zero or more repetitions:-->
                <attributes>
                    <!--Optional:-->
                    <attributeOptions>
                        <!--Optional:-->
                        <negative>?</negative>
                        <!--Optional:-->
                        <masked>?</masked>
                        <!--Optional:-->
                        <null>?</null>
                    </attributeOptions>
                    <value>?</value>
                    <attributeID>?</attributeID>
                </attributes>
            </attributeSet>
            <!--Optional:-->
            <fieldSet>
                <!--Zero or more repetitions:-->
                <attributeID>?</attributeID>
            </fieldSet>
            <!--Optional:-->
            <queryOptions>
                <!--Optional:-->
                <distinct>?</distinct>
                <!--Optional:-->
                <rowoffset>?</rowoffset>
                <!--Optional:-->
                <rowcount>?</rowcount>
                <!--Optional:-->
                <count>?</count>
            </queryOptions>
        </adm:??????Query>
    </soapenv:Body>
</soapenv:Envelope>

The SOAP body element should only contain an <object>query 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>query request needs to follow these additional rules:

• The <object>query element should contain only one AttributeSet element.

• The AttributeSet element should contain zero or more attribute elements. These attribute elements define the query search criteria.

• The <object>query element should contain one sessionID element. To get an administrative session identifier (sessionID), 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>query element should contain one cmd element.

Search fields specified using the AttributeSet elements are interpreted as follows:

• Wildcards are always accepted when indicated, except for user and authenticator searches. For these requests, they are accepted only if the toUserID or toSerial parameters are not set.

• A wildcard character (*) can be added to the values at the start, the end, or both. They will be interpreted as the SQL LIKE statement.

• A list of comma-separated values can be specified for the attribute that specifies the domain name. In this case it will be interpreted as the logical OR of the given values.

  You cannot use wildcard characters in comma-separated values.

• If none of the above applies, the search will be done using the exact match of the given value.

Optionally, a valid <object>query request can contain one of each of the following elements:

• fieldSet. If specified, the fieldSet element should contain zero or more object attribute elements. These elements specify the object fields that OneSpan Authentication Server should return for the each of the objects matching the search criteria.

• queryOptions. This element determines which results should be returned. The following optionas are supported:

  • distinct. A flag to request query results with no duplicate entries. This option is of type boolean.

  • rowoffset. Option to request results starting from the specified offset. This option is of type unsignedInt.

  • rowcount. Option to request to return the specified number of records in the results. This option is of type unsignedInt.

  • count. A flag to request the count of the results only, not the results themselves. This option is of type boolean.

SOAP response structure

An objectquery 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">
    <!-- ... Additional namespace declarations -->
    <soapenv:Header/>
    <soapenv:Body>
        <adm:????QueryResponse>
            <results xsi:type="USER-TYPES:????QueryResults">
                <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:???AttributeList">
                    <attributeList xsi:type="USER-TYPES:???AttributeSet">
                        <attributes xsi:type="USER-TYPES:???Attribute">
                            <value xsi:type="xsd:string">?????</value>
                            <attributeID>!!!!</attributeID>
                        </attributes>
                    </attributeList>
                </resultAttribute>
                <resultCount>??????</resultCount>
                <errorStack xsi:type="BASIC-TYPES:ErrorStack"/>
            </results>
        </adm:????QueryResponse>
    </soapenv:Body>
</soapenv:Envelope>

The SOAP body element should only contain an <object>QueryResponse element, where object specifies the requested object (line 9). The <object>QueryResponse element always contains a results element, which in turn 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.

• ResultCount. Required. This element specifies the number of objects that matched the specified search criteria. If queryOption.count is set to true in the query request, then only the ResultCount element will be returned in the response.

In this case, the resultattribute element is used to refer to attributeList elements for the specified object (object). Each attributeList element specifies one search result row.