IDENTIKEY Authentication Server SDK Programmer's Guide

IDENTIKEY Authentication Server
SDK Programmer's Guide
3.14
Disclaimer of Warranties and Limitations of Liabilities
Intellectual Property
VASCO Software, documents and related materials (“Materials”) made available on the Site contain pro-
prietary and confidential information. All title, rights and interest in VASCO Software and Materials,
updates and upgrades thereof, including software rights, copyrights, patent rights, trade secret rights,
sui generis database rights, and all other intellectual and industrial property rights, vest exclusively in
VASCO or its licensors. No VASCO Software or Materials published in this Site may be downloaded,
copied, transferred, disclosed, reproduced, redistributed, or transmitted in any form or by any means,
electronic, mechanical or otherwise, for any commercial or production purpose, except as otherwise
marked or when expressly permitted by VASCO in writing.
Disclaimer
VASCO accepts no liability for the accuracy, completeness, or timeliness of Site content, or for the reli-
ability of links to and content of external or third party websites.
VASCO shall have no liability under any circumstances for any loss, damage, or expense incurred by
you, your company, or any third party arising from the use or inability to use VASCO Software or Mater-
ials, or any third party material available or downloadable from the Site. VASCO will not be liable in rela-
tion to any loss/damage caused by modification of these Legal Notices or Site content.
Reservation
VASCO reserves the right to modify these Notices and the content at any time. VASCO likewise reserves
the right to withdraw or revoke consent or otherwise prohibit use of the VASCO Software or Materials if
such use does not conform to the terms of any written agreement between VASCO and you, or other
applicable terms that VASCO publishes from time to time.
Trademarks
VASCO®, VACMAN®, IDENTIKEY®, aXsGuard®, DIGIPASS®, CertiID®, CRONTO™, MYDIGIPASS.COM™,
the MYDIGIPASS.COM MD Lock logo, the DP+ logo, the VASCO ‘V’ logo, and the CRONTO logo are
registered or unregistered trademarks of VASCO Data Security, Inc. and/or VASCO Data Security Inter-
national GmbH in the U.S. and other countries.
VASCO reserves all rights to the trademarks, service marks and logos of VASCO and its subsidiaries.
Copyright
Copyright © 2008–2017 VASCO Data Security, Inc., VASCO Data Security International GmbH. All rights
reserved.
Date last modified: 11/30/2017

Table of Contents
Table of Contents
1. Introduction 7
1.1. Who should read this guide? 7
1.2. IDENTIKEY Authentication Server Documentation Suite 8
1.3. SDK Overview 9
1.4. IDENTIKEY Authentication Server Integration 10
2. Client Integration Overview 12
2.1. Web Service 12
2.2. High-Level API in Java or .NET 12
2.3. SOAP API 13
2.4. Wrappers 14
3. SDK Installation 15
3.1. System Requirements 15
3.2. Prerequisites 15
3.3. SDK Sample Websites 16
4. Client Integration of Authentication Functionality 19
4.1. Authentication Integration Via SOAP API 19
4.2. Response-Only User Authentication Operation 35
4.3. getChallenge User Authentication Operation 38
4.4. Challenge/Response DIGIPASS Authentication Operation 42
4.5. Change Server PIN Operation 47
4.6. Update Static Password Operation 49
4.7. Change Back-End Password Operation 51
4.8. Authentication Using the Secure Channel Operations 52
5. Authentication Back-End Integration 54
5.1. Authentication Engine 54
IDENTIKEY Authentication Server 3.14 – SDK Programmer's Guide iii

Table of Contents
5.2. Authentication Engine Definition Via Configuration File 55
5.3. Authentication Engine Definition Via Configuration Utility 56
5.4. Custom Authentication Engine Startup and Shutdown Process 61
6. Client Integration of Signature Validation 63
6.1. Signature Validation Integration Via SOAP API 63
6.2. Real-Time Signature Validation Operation 68
6.3. Deferred-Time Signature Validation Operation 70
6.4. Current Event Signature Validation Operation 71
6.5. Deferred Event Signature Validation Operation 71
6.6. Signature Validation Using the Secure Channel Operations 72
7. Integration of Provisioning Functionality 74
7.1. Provisioning Integration Via SOAP API 74
7.2. Standard Provisioning Operations 80
7.3. Multi-Device Licensing Provisioning Operations 89
8. Client Integration of Administrative Functions 93
8.1. Logon/Logoff Operation Via SOAP API 94
8.2. Execute Operation Via SOAP API 98
8.3. Query Operation Via SOAP API 103
8.4. File Upload/Download Operation Via SOAP API 109
8.5. User Administration Commands Via SOAP API 109
8.6. Other Administration Commands Supported by the SOAP API 111
8.7. Multi-Device Activation Operations 114
9. DIGIPASS for Mobile 117
9.1. DIGIPASS for Mobile 4.0 Configuration 117
9.2. DIGIPASS for Mobile Functions 124
9.3. DIGIPASS for Mobile 3.5 127
IDENTIKEY Authentication Server 3.14 – SDK Programmer's Guide iv

Table of Contents
10. Error and Status Codes 128
10.1. IDENTIKEY Authentication Server Error Codes 128
10.2. Status Codes 137
IDENTIKEY Authentication Server 3.14 – SDK Programmer's Guide v

Table of Contents
Table Index
Table 1: SDK integration requirements 16
Table 2: Error Code List 128
Table 3: Status Codes List 137
IDENTIKEY Authentication Server 3.14 – SDK Programmer's Guide vi

1. Introduction
1. Introduction
The IDENTIKEY Authentication Server SDK Programmer's Guide provides information for developers using the
IDENTIKEY Authentication Server Software Development Kit (SDK), including both administration and authentication
aspects. This guide provides the information on creating custom client applications that integrate IDENTIKEY
Authentication Server functionality, or integrating custom authentication mechanisms into IDENTIKEY Authentic-
ation Server.
This guide serves as an introduction to dedicated SDK guides for .NET, Java and SOAP.
This guide also provides information on integrating custom authentication mechanisms into IDENTIKEY Authentic-
ation Server. This implies the development of an IDENTIKEY Authentication Server authentication engine.
Warning
The SDK cannot be used to administer user and DIGIPASS information for IDENTIKEY Authentication Server when
Active Directory is used as the data store.
1.1. Who should read this guide?
This guide is designed for developers using IDENTIKEY Authentication Server products. It is designed primarily for
software developers who design and develop IDENTIKEY Authentication Server authentication engines, or custom
client applications integrating IDENTIKEY Authentication Server functionality.
The reader should be familiar with:
n Online authentication and authorisation tools and protocols, including SOAP, RADIUS, WSDL, SSL, XML,
HTML and TCP/IP.
n Windows and Linux security software environments including IIS, Active Directory and ODBC.
n Administration tasks including user management , policy, scheduling, reports, and performance mon-
itoring.
n Password management and encryption techniques.
n EMV-CAP and other e-commerce transaction standards.
n Programming languages, especially Java and ASP.NET.
Custom client application developers using this document should, at a minimum, be familiar with one of the fol-
lowing programming languages:
n Java
n ASP.NET
Readers should also be familiar with following Internet technologies:
n TCP/IP
n HTTP
n SSL
IDENTIKEY Authentication Server 3.14 – SDK Programmer's Guide 7

1. Introduction
In addition, custom application developers connecting their application directly to the IDENTIKEY Authentication
Server SOAP interface should be familiar with the following technologies/standards:
n Web services
n XML
n XML schema
n SOAP
Custom authentication engine developers should also to be familiar with the C programming language and the
development of dynamic linked libraries.
Terms and Definitions

n SOAP: Simple Object Access Protocol. A protocol for exchanging XML -based messages over computer net-
works, normally using one of the following transport protocols HTTP/HTTPS.
n WSDL: Web Service Description Language
n SSL: Secure Sockets Layer. Standard security technology for establishing an encrypted link between a cli-
ent and server application.
Users of the IDENTIKEY Authentication Server SDK are required to have working knowledge of key IDENTIKEY
Authentication Server concepts, in addition to any API knowledge requirements. As such, VASCO assumes that you
have read and understood the IDENTIKEY Authentication Server Product Guide, with emphasis on the following
chapters:
n Overview
n User Authentication
n Software DIGIPASS Provisioning
n EMV-CAP
n Reporting
1.2. IDENTIKEY Authentication Server Documentation Suite
The following product documentation is available:
n IDENTIKEY Authentication Server Product Guide: introduces the features and concepts of IDENTIKEY
Authentication Server and explains various usage options.
n IDENTIKEY Authentication Server Getting Started Guide: provides a walkthrough on deploying a standard
setup of IDENTIKEY Authentication Server and testing its key features.
n IDENTIKEY Authentication Server Installation Guide for Windows: provides comprehensive instructions
about installing IDENTIKEY Authentication Server on a Windows platform.
n IDENTIKEY Authentication Server Installation Guide for Linux: provides comprehensive instructions about
installing IDENTIKEY Authentication Server on a supported Linux distribution.
n IDENTIKEY Authentication Server Administrator Guide: in-depth information about the administration and
management of IDENTIKEY Authentication Server.
n IDENTIKEY Authentication Server Administrator Reference: detailed IDENTIKEY Authentication Server ref-
erences, including data attributes, utility commands, schema information, and other related information.

1. Introduction
n IDENTIKEY Authentication Server Performance and Deployment Guide: information about common deploy-
ment models and performance statistics.
n IDENTIKEY Authentication Server Release Notes: latest information about corresponding IDENTIKEY
Authentication Server releases.
n IDENTIKEY Authentication Server Data Migration Guide: provides comprehensive information about the vari-
ous paths available when updating IDENTIKEY Authentication Server to a higher version.
n IDENTIKEY Authentication Server SDK Programmer's Guide: in-depth information required to develop using
the IDENTIKEY Authentication Server Software Development Kit (SDK), with dedicated guides for .NET,
Java, and SOAP:
n IDENTIKEY Authentication Server SDK Programmer's Guide for Java
n IDENTIKEY Authentication Server SDK Programmer's Guide for .NET
n IDENTIKEY Authentication Server SDK SOAP Reference
n IDENTIKEY Authentication Server SDK Plug-In Engine Guide
n IAS Authentication SDK Programmer's Guide: in-depth information required to develop using the
IAS Authentication SDK, with dedicated guides for .NET, Java, and SOAP:
n IAS Authentication SDK Programmer's Guide for .NET
n IAS Authentication SDK Programmer's Guide for Java
n IAS Authentication SDK SOAP Reference
n DIGIPASS App Getting Started Guide: provides general information on the DIGIPASS App and how to install
it.
n DIGIPASS Gateway Getting Started Guide: provides general information on DIGIPASS Gateway and how to
install it.
n DIGIPASS Gateway Integration Guide: provides information how to configure DIGIPASS Gateway and how
to integrate it with mobile devices.
n Push Notification Getting Started Guide: provides information about the Push Notification feature in gen-
eral and details on the required components and the system setup.
1.2.1. Further assistance
Comprehensive Help Files including context-sensitive assistance are available via IDENTIKEY Authentication Server
user interfaces. For more information, please visit http://www.vasco.com.
1.3. SDK Overview
Using the SDK, you can create custom client applications that integrate the following IDENTIKEY Authentication
Server functionality:
n Authentication
n EMV-CAP compliant authentication
n Digital signatures
n Administration
n Provisioning
n Reporting

1. Introduction
Image 1: SOAP Interface
Image 2: SOAP Interface -- Custom Authentication Application
You can create authentication engines and load these engines into IDENTIKEY Authentication Server. These authen-
tication engines allow you to integrate custom authentication mechanisms into IDENTIKEY Authentication Server,
and they can be used to integrate custom back-end systems or as a stand-alone module.
1.4. IDENTIKEY Authentication Server Integration
The SDK supports integration of several IDENTIKEY Authentication Server functionalities into custom client applic-
ations. For more information about client integration, see 2. Client Integration Overview

1. Introduction
The SDK also supports integration of back-end authentication. Back-end integration involves integration of custom
authentication mechanisms into IDENTIKEY Authentication Server. These custom authentication mechanisms can
then be referred to in authentication policies, and thus be included in processing user authentication requests. For
more information about back-end integration, see 5. Authentication Back-End Integration.

2. Client Integration Overview

Client integration involves integrating IDENTIKEY Authentication Server functionality into custom applications that
act as clients for the IDENTIKEY Authentication Server. This integration type supports the integration of the fol-
lowing IDENTIKEY Authentication Server functionalities into custom applications:
n Authentication (4. Client Integration of Authentication Functionality)

n Signature Validation (6. Client Integration of Signature Validation)
n Provisioning (7. Integration of Provisioning Functionality)
n EMV-CAP Authentication
n Administration (8. Client Integration of Administrative Functions)
n Report generation
These IDENTIKEY Authentication Server functions are implemented as a web service.
Two API types are available for this client integration:
n High-level APIs in Java or .NET (2.2. High-Level API in Java or .NET)

n Low-level SOAP APIs (2.3. SOAP API )
Integration via low-level SOAP APIs should only be performed by experienced users.
2.1. Web Service
A Web Service is an application allowing client appplications to perform remote procedure calls on servers. The cli-
ent applications and the server communicate with each other using XML messages formatted following the SOAP
standard. The server publishes its supported remote operations via the WSDL standard for self description.
IDENTIKEY Authentication Server supports the communication with client applications via SOAP over HTTP or
HTTPS.
IDENTIKEY Authentication Server comes with WSDL files for each of its supported SOAP interfaces.
2.2. High-Level API in Java or .NET
VASCO provides high-level Application Programming Interfaces to simplify the integration of IDENTIKEY Authentic-
ation Server functionality into client applications. These high-level APIs wrap the IDENTIKEY Authentication Server
SOAP interfaces, and are bundled into an integration module.
This wrapper module abstracts the developer from all low-level SOAP and HTTP related details, and is available in
the following high-level programming languages:
n Java
n .NET

Keep in mind that a developer is still required to understand key IDENTIKEY Authentication Server concepts such as
component type, password format, and the like.
2.3. SOAP API
This type of client integration method requires the client application developer to generate SOAP client applications
based on the IDENTIKEY Authentication Server WSDL files. IDENTIKEY Authentication Server comes with the fol-
lowing WSDL files describing the different SOAP interfaces:
n Authentication.wsdl - specifies the supported user authentication operations.

n EMVCAPAuthentication.wsdl – specifies the supported EMV-CAP authentication operations.
n Signature.wsdl - specifies the supported transaction authentication operations.
n Administration.wsdl - specifies the supported administration operations. This file also specifies the report
generation operation.
n Provisioning.wsdl - specifies the supported Software DIGIPASS or Software/Hardware DIGIPASS pro-
visioning operations.
You can find these files in <sdk_install_dir>/wsdl/ (e.g. C:\Program Files\VASCO\IDENTIKEY Authentication Server
SDK 3.14\wsdl\ in Windows).
This client integration type requires a developer to understand SOAP-related details on top of IDENTIKEY Authentic-
ation 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 IDENTIKEY Authentication Server.
2.3.1. 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 ele-
ments:
n Header element (optional): contains header information

n Body element: 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 fol-
lowing format:
xmlns:<namespace>
2.4. Wrappers
VASCO provides standard interface wrappers for the following programming languages as part of the SDK:
n Java
n ASP.NET
These standard wrappers provide a high-level interface to the following IDENTIKEY Authentication Server authen-
tication functionalities:
n Authentication (1.4. IDENTIKEY Authentication Server Integration)

n Signature Validation (6. Client Integration of Signature Validation)
These standard wrappers abstract the developer from all details relating to SOAP and XML. Additionally, these
standard wrappers provide a basic fail-over mechanism.
These wrappers rely on SOAP client stubs that have been generated based on the IDENTIKEY Authentication Server
authentication wsdl file.
For more information about Java and ASP.NET wrappers for IDENTIKEY Authentication Server, refer to either the
IDENTIKEY Authentication Server SDK Programmer's Guide for Java or IDENTIKEY Authentication Server
SDK Programmer's Guide for .NET.

3. SDK Installation
3. SDK Installation
The IDENTIKEY Authentication Server SDK is distributed as a ZIP archive. This archive includes platform and archi-
tecture-independent libraries for both ASP.NET and Java color QR code technologies.
3.1. System Requirements
3.1.1. Operating systems for server components
The IDENTIKEY Authentication Server SDK is supported on the following operating systems
Windows
n Windows Server 2012 R2
n Windows Server 2012
n Windows Server 2008 R2 with Service Pack 1
Linux
n CentOS 7, 64-bit
n CentOS 6, 64-bit
n Red Hat Enterprise Linux 7, 64-bit
n Red Hat Enterprise Linux 6, 64-bit
n SUSE Linux Enterprise Server 11, 64-bit
n Ubuntu Server 16.04 LTS, 64-bit
n Ubuntu Server 14.04 LTS, 64-bit
3.1.2. Operating systems for client components
Windows
n Windows 8.1
n Windows 8
n Windows 7 Service Pack 1
3.2. Prerequisites
The following table summarizes the prerequisites for this SDK, depending on integration type and the level of SDK
usage:

3. SDK Installation
Table 1: SDK integration requirements

Integration Type Run Samples Modify Samples /
Create Your Own Solution
Client Integration - Java Web server and servlet container supporting Java Servlet Java IDE of your choice
specification 2.4 and JavaServer Pages specification (JSP)
2.0 . (Example: NetBeans or Eclipse with
JDK integrated)
(Example: Apache Tomcat 7.0)
Client Integration - ASP.NET Internet Information Services (IIS) 7.0, IIS 7.5, IIS 8.0, or IIS Microsoft Visual Studio 2010
8.5 with .NET Framework 3.0 support enabled.
Client Integration - SOAP Generic SOAP client A SOAP library of your choice which you
integrate into your client applications.
(Example: SoapUI)
(Example: gSOAP)
Back-end Integration IDENTIKEY Authentication Server 3.14 A C compiler of your choice, capable of
generating a .dll or .so file, depending
(Plug-In Engine) on the selected platform.
3.3. SDK Sample Websites
The IDENTIKEY Authentication Server SDK provides the following sample Websites:
n Java sample Website

n ASP.NET sample Website
3.3.1. Java Sample Website Requirements
The Java sample Website provided in this SDK requires the following:
n Web server and servlet container compliant with:

n Java Servlet specification 2.4
n JavaServer Pages (JSP) specification 2.0
n Oracle Java SE Development Kit (JDK) 7
The Java sample Website has been tested successfully in the following environment:
n Microsoft Windows 8.1

n Apache Tomcat 8.5.23
n Oracle Java SE Development Kit (JDK) 8 Update 25

3. SDK Installation
3.3.2. ASP.NET Sample Website Requirements
The ASP.NET sample Website provided in this SDK requires the following:
n Microsoft Internet Information Services (IIS) 7.0, IIS 7.5, IIS 8.0, or IIS 8.5
n Microsoft .NET Framework 3.0
The ASP.NET sample Website has been tested successfully in the following environment:
n Microsoft Windows 8.1

n Microsoft Internet Information Services (IIS) 8.0
n Microsoft .NET Framework 3.5
3.3.3. IDENTIKEY Authentication Server Preparation for SDK Sample Website Installation
Before setting up a sample website, ensure that IDENTIKEY Authentication Server is installed properly. For instruc-
tions, refer to the IDENTIKEY Authentication Server Windows Installation Guide or IDENTIKEY Authentication Server
Linux Installation Guide.
IDENTIKEY Authentication Server must also be configured accordingly in order to install the SDK sample website.
You can apply all the required settings via Configuration Utility. These settings are as follows:
n Communicators: in the SOAP tab, the SOAP protocol must be enabled.

n IDENTIKEY Authentication Server Component: a component must be defined for the IP address of the
IDENTIKEY Authentication Server.
n License: a license must be loaded for the IDENTIKEY Authentication Server component. This license should
have SOAP enabled, along with the different SOAP features you want to test using the sample website.
EMV-CAP Authentication requires a separate licensing option to other authentication functionality.
If you want to use the authentication or EMV-CAP authentication functionality of the sample websites, check that
an authentication SOAP client component has been defined on the IDENTIKEY Authentication Server with the fol-
lowing properties:
n IP address: IP address of the machine hosting the sample website.

n Component Type: Authentication Sample Client
n Policy: Identikey Local Authentication Policy
If you want to use the signature validation functionality of the sample websites, check that a signature validation
SOAP client component has been defined on the IDENTIKEY Authentication Server with the following properties:

n Component Type: Signature Sample Client
n Policy: Identikey Real-time Signature Verification Policy 1

3. SDK Installation
If you want to use the Secure Channel authentication functionality of the sample websites, check that a Secure
Channel authentication SOAP client component has been defined on IDENTIKEY Authentication Server with the fol-
lowing properties:

n Component Type: Authentication with Secure Channel Sample Client
n Policy: IDENTIKEY Authentication with Secure Channel
If you want to use the Secure Channel signature functionality of the sample websites, check that a Secure Channel
signature SOAP client component has been defined on IDENTIKEY Authentication Server with the following prop-
erties:

n Component Type: Signature Secure Channel Sample Client
n Policy: IDENTIKEY Signature Validation with Secure Channel
If you want to use the Multi-Device Licensing Provisioning functionality of the sample websites, check that a Multi-
Device Licensing Provisioning SOAP client component has been defined on IDENTIKEY Authentication Server with
the following properties:

n Component Type: Multi-Device Licensing Provisioning Sample Client
n Policy: IDENTIKEY Provisioning for Multi-Device Licensing
Once these settings are applied, you can now install the sample websites as required. For more information about
installing sample websites, refer to the IDENTIKEY Authentication Server SDK Programmer's Guide for Java or
IDENTIKEY Authentication Server SDK Programmer's Guide for .NET, respectively.
3.3.4. SDK Sample Websites Usage
Each sample website comes with a default homepage providing an overview of the functionality that can be
tested.
The functionality provided by the sample websites is divided into the following functional groups:
n Authentication
n EMV-CAP Authentication
n Signature Validation
n Administration
n DP110 provisioning
n DP4 mobile provisioning

4. Client Integration of Authentication Functionality

The IDENTIKEY Authentication Server authentication functionality can be integrated into any application that sup-
ports SOAP. This integration can be done by either:
n Using authentication client interface wrappers

n Sending SOAP requests directly
VASCO also provides standard wrappers for integrating IDENTIKEY Authentication Server features into custom
applications. For more information about wrappers provided by VASCO in the IDENTIKEY Authentication Server SDK,
see 2.4. Wrappers.
The Authentication SOAP interface supports the following command types to be sent to the IDENTIKEY Authentic-
ation Server:
n Response-Only (RO) User authentication

n Challenge/Response (CR) User authentication
n GetChallenge
n Change Server PIN
n Update Static Password
n Change the user's Active Directory static back-end password
n Secure challenge user authentication with Get Secure Challenge
Users attempting to perform this type of integration should be familiar with the following standards:
n XML
n XML Schema
n SOAP
4.1. Authentication Integration Via SOAP API
To integrate IDENTIKEY Authentication Server authentication functionality with a custom application via SOAP API,
you will need to be familiar with the following standards:
n XML
n XML Schema
n SOAP
The SOAP authentication API exposes the following SOAP operations that can be used to perform the authen-
tication commands specified above:
n authUser
n cancelAuthUser
n getChallenge
n getSecureChallenge
n getPreparedSecureChallenge
n updatePassword

n changeEncStatPwd
n changeBackendPassword
To perform any of these authentication commands, refer to the following procedure:
Procedure 1: Executing a supported SOAP authentication command
1. Create a SOAP request.

2. Specify the correct SOAP authentication operation in the SOAP request.
3. Specify one or more authentication attributes as parameters for the SOAP operation. Attributes are key-
value pairs.
4. Import the IDENTIKEY 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 IDENTIKEY Authentication Server securely via SSL.
5. Send the SOAP request to IDENTIKEY Authentication Server. By default, the SOAP request should be com-
municated over HTTPS with the IDENTIKEY Authentication Server.
IDENTIKEY Authentication Server is configured by default to accept SOAP requests on port 8888.
6. Receive the SOAP response.
7. Process the SOAP response.
For more information about the structure of SOAP messages, see 2.3.1. SOAP Message Structure.
4.1.1. SOAP authUser Request Structure
A SOAP authUser 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:aut="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Authentication">
<soapenv:Header/>
<soapenv:Body>
<aut:authUser>
<credentialAttributeSet>

<attributes>
<value xsi:type="xsd:!!!!!!">?????</value>
<attributeID>?????</attributeID>
</attributes>
</credentialAttributeSet>
</aut:authUser>
</soapenv:Body>
</soapenv:Envelope>
The SOAP Body element should only contain an authUser element (line 8). This element has been defined in the
namespace aut. Therefore, the aut namespace should be declared in the Envelope element as an attribute.
A valid authUser request also follows these additional rules:
n The authUser element should contain only one credentialAttributeSet element.

n The credentialAttributeSet element should contain zero or more credential attributes elements.
Each attribute element should contain the following sub-elements:
n attributeID (required): the attribute identifier. The supported credential attribute identifiers are lis-
ted in the IDENTIKEY Authentication Server SDK SOAP Reference.
n value (required): the attribute value. This element also requires the specification of the value type using
the following attribute definition xsi=type=”xsd:<type>.
n attributeOptions (optional): this element provides directive information about how IDENTIKEY
Authentication Server should handle the attribute value during request processing. Following options are
supported for this element:
n NULL: indicates that the specified attribute should be set to zero.
n NEGATIVE: used for search criteria to say NO when searching for a specific attribute.

n MASKED: used to indicate IDENTIKEY 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 a value true.
Example
To set the MASKED option, add the following:
<attributeOptions><masked>true</masked> </attributeOptions>
4.1.2. SOAP authUser Response Structure
A SOAP authUser response typically uses the following format:

<soapenv:Envelope
.... (additional namespace declarations)
<soapenv:Header/>
<soapenv:Body>
<aut:authUserResponse>
<authUserResults xsi:type="AUTH-TYPES:AuthUserResults">
<results xsi:type="CREDENTIAL-TYPES:CredentialResults">
<resultCodes xsi:type="BASIC-TYPES:ResultCodes">
<returnCodeEnum>RET_SUCCESS</returnCodeEnum>
<statusCodeEnum>STAT_SUCCESS</statusCodeEnum>
<returnCode>0</returnCode>
<statusCode>0</statusCode>
</resultCodes>
<resultAttribute xsi:type="CREDENTIAL-TYPES:CredentialAttributeSet">
<attributes xsi:type="CREDENTIAL-TYPES:CredentialAttribute">
<attributeOptions xsi:type="BASIC-TYPES:AttributeOptions">
<masked>true</masked>
</attributeOptions>
<value xsi:type="xsd:string">1234</value>
<attributeID>CREDFLD_STATIC_PASSWORD</attributeID>
</attributes>
</resultAttribute>
<errorStack xsi:type="BASIC-TYPES:ErrorStack"/>
</results>
<userattributelist>
<value xsi:type="xsd:string">master</value>

<attributeID>CREDFLD_DOMAIN</attributeID>
</attributes>
</userattributelist>
</aut:authUserResponse>
</soapenv:Body>
</soapenv:Envelope>
The SOAP body element of an authUser SOAP response only contains an authUserResponse element (line 9).
This element always contains the following elements:
n results (required)
n userattributelist (optional)
The results element contains the following sub-elements:
n resultCodes (required): this element contains the following sub-elements:

n returnCode: the operation return code indicating the overall result of the request processing
n statusCode: the operation status code indicating the reason for failure of any
returnCode different from success (0)
n returnCodeEnum: the identifier corresponding to the returnCode
n statusCodeEnum: the identifier corresponding to the statusCode
n resultAttribute (required): this element contains zero or more attributes elements
n errorStack (required): contains zero or more errors elements.
n errors: each errors element contains the following sub-elements:
n errorCode: the error code integer
n errorDesc: a string representation of the error code.
For a complete list of possible error codes, see 10. Error and Status Codes.
Note
The resultattribute element, in this case, is used to refer to credential attributes elements.
The userattributelist contains zero or more user attributes elements. This element is only specified if the following
conditions are met:
n A userattribute group attribute has been specified in the corresponding SOAP request.
n User authentication was successful.
n User attributes with the specified user attribute group have been defined for the specified user.
For more information on how attribute elements are structured, refer to 4.1.1. SOAP authUser Request Structure.
4.1.3. SOAP getChallenge Request Structure
A SOAP getChallenge request typically uses the following format:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<aut:getChallenge>
<attributes>
</attributes>
</aut:getChallenge>
</soapenv:Body>
</soapenv:Envelope>
The SOAP body element should only contain a getChallenge element (line 8). This element has been defined in the
namespace aut. Therefore, the aut namespace should be declared in the Envelope element as an attribute.
A valid getChallenge request also follows these additional rules:
n The getChallenge element should contain one credentialAttributeSet element.

4.1.4. SOAP getChallenge Response Structure
A SOAP getChallenge response typically uses the following format:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<aut:getChallengeResponse>
</resultCodes>
<value xsi:type="xsd:string">????</value>
<attributeID>!!!!!!!!!!!!!</attributeID>
</attributes>
</resultAttribute>
</results>
</aut:getChallengeResponse>
</soapenv:Body>
</soapenv:Envelope>
The SOAP body element should only contain a getChallengeResponse element (line 9). The getChal-
lengeResponse element always contains a results element, which in turn contains the following elements:


Note
4.1.5. SOAP updatePassword Request Structure
A SOAP updatePassword request typically uses the following format:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<aut:updatePassword>
<attributes>
</attributes>
</aut:updatePassword>
</soapenv:Body>
</soapenv:Envelope>
The SOAP body element should only contain a updatePassword element (line 8). This element has been defined in
the namespace aut. Therefore, the aut namespace should be declared in the Envelope element as an attribute.
A valid updatePassword request also follows these additional rules:
n The UpdatePassword element should contain only one credentialAttributeSet element.

4.1.6. SOAP updatePassword Response Structure
A SOAP updatePassword response typically uses the following format:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<aut:updatePasswordResponse>
</resultCodes>
<value xsi:type="xsd:string">????</value>
<attributeID>!!!!!!!!!!!!!</attributeID>
</attributes>
...
</resultAttribute>
</results>
</aut:updatePasswordResponse>
</soapenv:Body>
</soapenv:Envelope>
The SOAP body element should only contain a getChallengeResponse element (line 9). The getChal-
lengeResponse element always contains a results element, which in turn contains the following elements:


Note
4.1.7. SOAP getSecureChallenge Request Structure
A SOAP getSecureChallenge request typically uses the following format:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<aut:getSecureChallenge>
<attributes>
<value xsi:type="xsd:unsignedInt">0</value>
<attributeID>CREDFLD_PASSWORD_FORMAT</attributeID>
</attributes>
<attributes>
<value xsi:type="xsd:string">user1</value>
<attributeID>CREDFLD_USERID</attributeID>
</attributes>
<attributes>
<value xsi:type="xsd:string">VDS0000001-1</value>
<attributeID>CREDFLD_SERIAL_NO</attributeID>
</attributes>
<attributes>
<value xsi:type="xsd:string">test message</value>
<attributeID>CREDFLD_CHALLENGE_MESSAGE</attributeID>
</attributes>
<attributes>
<value xsi:type="xsd:string">Authentication with Secure Channel Sample Client</value>
<attributeID>CREDFLD_COMPONENT_TYPE</attributeID>
</attributes>
</aut:getSecureChallenge>

</soapenv:Body>
</soapenv:Envelope>
The SOAP body element must only contain a single getSecureChallenge element. This element has been defined
in the namespace aut. Therefore, the aut namespace must be declared in the Envelope element as an attribute.
A valid getSecureChallenge request also follows these additional rules:
n The getSecureChallenge element must contain one attributeSet.

n The attributeSet element must contain the minimum number of required attribute elements.
n Either a CREDFLD_REQUEST_BODY element or a CREDFLD_CHALLENGE_MESSAGE element
with, optionally, a CREDFLD_TRANSACTION_TITLE element must exist.
4.1.8. SOAP getSecureChallenge Response Structure
A SOAP getSecureChallenge response typically uses the following format:

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:BASIC-TYPES="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/BasicTypes.xsd"
xmlns:AUTH-TYPES="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Authentication"
xmlns:CREDENTIAL-TYPES="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/CredentialTypes.xsd"
<soapenv:Body>
<AUTH-TYPES:getSecureChallengeRespond>
</resultCodes>
<value xsi:type="xsd:string">user1</value>
</attributes>
<attributeID>CREDFLD_DOMAIN</attributeID>
</attributes>
<attributeID>CREDFLD_CHALLENGE_KEY</attributeID>
</attributes>

<value xsi:type="xsd:string">VDS0000001-7</value>
<attributeID>CREDFLD_SERIAL_NO</attributeID>
</attributes>
<value
xsi:type="xsd:string">00C1C3E400000128202D43FCAE28021F7B7195F9073C3B5B096B1EEAFEE89BBD
5949</value>
<attributeID>CREDFLD_REQUEST_MESSAGE</attributeID>
</attributes>
</resultAttribute>
<errorStack xsi:type="BASIC-TYPES:ErrorStack"></errorStack>
</results>
</AUTH-TYPES:getSecureChallengeRespond>
</soapenv:Body>
</soapenv:Envelope>
The SOAP body element must only contain a single getSecureChallengeRespond element. This element always
contains a single result element, which in turn contains the following sub-elements:

Note
For this SOAP response, the resultAttribute element refers to credential attribute elements.

4.2. Response-Only User Authentication Operation
A Response-Only operation performs user authentication using an OTP and/or a static password. To execute this
operation, the registered client application should send an authUser SOAP request to the IDENTIKEY Authentic-
ation Server.
This operation can be used to perform the following types of user authentication:
n Response-Only mode, one-time password

n Response-Only mode, one-time password combined with Server PIN
n Response-Only mode, static password
n Response-Only mode, one-time password combined with static password
n Response-Only mode, one-time password combined with static password and Server PIN
For all supported types of Response-Only user authentication, the one-time password, static password, and Server
PIN have to be specified, if used, as credential attributes for the authUser request. For more information on the
structure of an authUser request, refer to 4.1.1. SOAP authUser Request Structure.
The authUser SOAP request supports two formats to specify the static password or one-time password. To
indicate the password format in the authUser SOAP request, the credential attribute CREDFLD_PASSWORD_
FORMAT should be included with the correct value.
The following password format specification methods in the authUser SOAP request are supported:
n One password attribute combining all user credentials: this attribute will hold a password string which is a
concatenation of all different authentication elements (static password and/or one-time password and/or
Server PIN). This concatenated password string should be specified via the credential field attribute
CREDFLD_PASSWORD. The password format attribute should be included with value 0.
n A separate attribute for each user credential: this method requires specifying a credential attribute for
each authentication information element like static password, one-time password, Server PIN. The pass-
word format attribute CREDFLD_PASSWORD_FORMAT should be included with value 4.
Response Only (RO) Mode, OTP

In order to verify a Response-Only one-time password using several password attributes, the authUser
command requires the following minimum set of credential field attributes:
n CREDFLD_USERID
n CREDFLD_COMPONENT_TYPE: indicates the client application component type
n CREDFLD_PASSWORD_FORMAT
n OTP specified either via credential attribute CREDFLD_PASSWORD or via credential attribute CREDFLD_
DP_RESPONSE depending on the chosen password format.
Example
A client application with component type SOAP Auth Client will typically send the following SOAP command to

authenticate user test1 using a Response-Only OTP 312469 :

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<aut:authUser>
<attributes>
<value xsi:type="xsd:string">SOAP Auth Client</value>
</attributes>
<attributes>
<value xsi:type="xsd:string">test1</value>
</attributes>
<attributes>
</attributes>
<attributes>
<attributeID>CREDFLD_DP_RESPONSE</attributeID>
</attributes>
</aut:authUser>
</soapenv:Body>
</soapenv:Envelope>

Response-Only Mode, with Server PIN

In order to verify a static password using one combined password attribute, the authUser command
requires the following minimum set of credential field attributes:
n CREDFLD_USERID
n Static password specified either via credential attribute CREDFLD_PASSWORD or via credential attribute
CREDFLD_STATIC_PASSWORD depending on the chosen password format
n Server PIN specified either via credential attribute CREDFLD_PASSWORD or via credential attribute
CREDFLD_CURRENT_PIN.
Response-Only Mode, Static Password

In order to verify a static password using one combined password attribute, the authUser command
requires the following minimum set of credential field attributes:
n CREDFLD_USERID
n Static password specified either via credential attribute CREDFLD_PASSWORD or via credential attribute
CRED_STATIC_PASSWORD
Other supported authentication types combine functions such as Response-Only one-time password, Static pass-
word and Server PIN. The combination authentication types will not be described in detail.
4.3. getChallenge User Authentication Operation
The getChallenge operation sends a requests to IDENTIKEY Authentication Server to generate a server chal-
lenge. The returned challenge could then be used in a one-step Challenge/Response user authentication.
Two types of server challenges can be generated with the getChallenge operation:
1. General server challenge: a server challenge not tied to a specific user

2. User-specific server challenge
In order for a getChallenge operation to succeed, the following administrative tasks should be performed on
the IDENTIKEY Authentication Server:
Procedure 2: Configuring IDENTIKEY Authentication Server for getChallenge operations
1. Define an authentication policy that supports the generation of a 1-step server-based challenge.
2. Register a client application, assigning the newly defined authentication policy
3. Import DIGIPASS supporting Challenge/Response (CR) user authentication
4. Define users and assign the DIGIPASS.

For more information on how to perform these tasks, refer to the IDENTIKEY Authentication Server Administrator
Guide.
To execute a getChallenge operation, the registered client application should send a getChallenge
SOAP command to the IDENTIKEY Authentication Server. For more information, refer to 4.1.3. SOAP getChallenge
Request Structure.
In order for the IDENTIKEY Authentication Server to generate a server challenge, the getChallenge command
should specify the CREDFLD_COMPONENT_TYPE. This credential field attribute indicates the client application
type.
For user-specific server challenges, the getChallenge command should specify the CREDFLD_COMPONENT_
TYPE and CREDFLD_USERID. The latter is the user ID for which a server challenge should be generated
Example
request a challenge for user test1:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<aut:getChallenge>
<attributes>
</attributes>
<attributes>
</attributes>
</aut:getChallenge>
</soapenv:Body>
</soapenv:Envelope>
This, in turn, would generate the following getChallenge SOAP response:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<aut:getChallengeResponse>
</resultCodes>
<attributeID>CREDFLD_CHALLENGE</attributeID>
</attributes>
<attributeID>CREDFLD_CHALLENGE_KEY</attributeID>
</attributes>
</resultAttribute>
</results>
</aut:getChallengeResponse>
</soapenv:Body>

</soapenv:Envelope>
In this example, the result attribute CREDFLD_CHALLENGE_KEY specifies the challenge identifier used by the
IDENTIKEY Authentication Server. A Challenge/Response authentication operation for this challenge should add
this attribute into its authentication request.
4.4. Challenge/Response DIGIPASS Authentication Operation
This operation performs a user authentication using a Challenge/Response DIGIPASS Application.
The following types of Challenge/Response operations are supported:
n 1-Step Challenge Response

n 2-Step Challenge Response
The following administrative tasks should be performed on the IDENTIKEY Authentication Server in order for this
getChallenge operation to succeed:
Procedure 3: Configuring IDENTIKEY Authentication Server for Challenge/Response DIGIPASS authentication oper-
ations
1. Register client application.

2. Define/assign an authentication policy that supports of a 1-step server-based challenge.
3. Define users and assign DIGIPASS supporting Challenge/Response authentication
Guide.
1-Step Challenge/Response
This operation type assumes that a DIGIPASS challenge has already been generated before. This challenge
might be generated by the IDENTIKEY Authentication Server via the getChallenge operation (Server chal-
lenge), or it might be generated by the client application (Any challenge).
To execute this operation, the registered client application should send an authUser SOAP command to
IDENTIKEY Authentication Server. This authUser should, at a minimum, specify the following credential
field attributes:
n CREDFLD_USERID
n CREDFLD_CHALLENGE_KEY (in case the challenge has been generated by the IDENTIKEY Authentication
Server)
n CREDFLD_CHALLENGE (in case the challenge has NOT been generated by the IDENTIKEY Authentication
Server)

n one-time password specified either via credential attribute CREDFLD_PASSWORD or CREDFLD_DP_

RESPONSE, depending on the chosen password format.
Example
A client application with component type SOAP Auth Client will typically send the following SOAP command to per-
form a Challenge/Response-based DIGIPASS authentication for user test1:

<SOAP-ENV:Envelope
xmlns:AUTH-TYPES="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Authentication">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<AUTH-TYPES:authUser>
<attributes>
<value xsi:type="xsd:string">testuser</value>
</attributes>
<attributes>
<attributeID>CREDFLD_CHALLENGE</attributeID>
</attributes>
<attributes>
</attributes>
<attributes>
<attributeID>CREDFLD_PASSWORD</attributeID>
</attributes>
<attributes>
<value xsi:type="xsd:string">SOAP Client</value>

</attributes>
</AUTH-TYPES:authUser>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
2-Step Challenge/Response
This operation request a server challenge as a first step. In its second step, a user authentication is per-
formed. This second step is identical to a 1-step Challenge/Response request described earlier.
To perform the first step in the 2-step Challenge/Response operation, the registered client application should
send an authUser SOAP command to IDENTIKEY Authentication Server, requesting the generation of a chal-
lenge keyword. This keyword should be specified in the authentication policy associated with the registered
client application.
For this step to succeed, the authUser command should, at a minimum, specify the following set of cre-
dential field attributes:
n CREDFLD_USERID
n Keyword specified either via credential attribute CREDFLD_PASSWORD or CREDFLD_STATIC_PASSWORD,
depending on the chosen password format.
Example
A client application with component type SOAP Auth Client will typically send the following SOAP command
to perform step 1 in a 2-step Challenge/Response -based DIGIPASS authentication for user test1:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<aut:authUser>
<attributes>
</attributes>
<attributes>
<value xsi:type="xsd:string">getchallenge</value>
</attributes>
<attributes>
<value xsi:type="xsd:string">SOAP Client</value>
</attributes>
<attributes>
</attributes>
</aut:authUser>>
</soapenv:Body>

</soapenv:Envelope>
For this request, it assumed that specified client application component has an associated policy that has the 2-
step Challenge/Response keyword set to getChallenge.
4.5. Change Server PIN Operation
This operation requests IDENTIKEY Authentication Server the to change the Server PIN of a specified user. Such a
request always has to be confirmed with Response-Only one-time password, to be specified as credential attrib-
ute in the SOAP request.
To execute this operation, the registered client application should send an authUser SOAP command to
IDENTIKEY Authentication Server. This authUser command should, at a minimum, specify the following cre-
dential field attributes:
n CREDFLD_USERID
n CREDFLD_CURRENT_PIN
n New PIN specified either via credential attribute CREDFLD_PASSWORD or via credential attribute
CREDFLD_NEW_PIN depending on the chosen password format.
n New PIN Confirmation specified either via credential attribute CREDFLD_PASSWORD or via credential attrib-
ute CREDFLD_CONFIRM_NEW_PIN depending on the chosen password format.
n one-time password specified either via credential attribute CREDFLD_PASSWORD or CREDFLD_DP_
RESPONSE, depending on the chosen password format.
Example
request a Server PIN change for user test1:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<aut:authUser>
<attributes>
</attributes>
<attributes>
</attributes>
<attributes>
</attributes>
<attributes>
<attributeID>CREDFLD_DP_RESPONSE</attributeID>
</attributes>
<attributes>
<attributeID>CREDFLD_NEW_PIN</attributeID>

</attributes>
<attributes>
<attributeID>CREDFLD_CONFIRM_NEW_PIN</attributeID>
</attributes>
</aut:authUser>
</soapenv:Body>
</soapenv:Envelope>
4.6. Update Static Password Operation
This operation requests IDENTIKEY Authentication Server to update the static password for a specified user. To
execute this operation, the registered client application should send an updatePassword SOAP command to
IDENTIKEY Authentication Server. This updatePassword command should, at a minimum, specify the fol-
lowing credential field attributes:
n CREDFLD_USERID
n Current static password specified via credential attribute CREDFLD_PASSWORD
n New static password specified via credential attribute CREDFLD_NEW_STATIC_PASSWORD
n New static password confirmation specified via credential attribute CREDFLD_CONFIRM_NEW_STATIC_
PASSWORD
Example
request a static password change for user test1:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<aut:updatePassword>
<attributes>
</attributes>
<attributes>
</attributes>
<attributes>
<value xsi:type="xsd:string">oldpassword</value>
</attributes>
<attributes>
<value xsi:type="xsd:string">newpassword</value>
<attributeID>CREDFLD_NEW_STATIC_PASSWORD</attributeID>
</attributes>
<attributes>
<value xsi:type="xsd:string">newpassword</value>
<attributeID>CREDFLD_CONFIRM_NEW_STATIC_PASSWORD</attributeID>

</attributes>
</aut:updatePassword>
</soapenv:Body>
</soapenv:Envelope>
4.7. Change Back-End Password Operation
This operation requests IDENTIKEY Authentication Server to change the user's static Active Directory password with
a configured back end of IDENTIKEY Authentication Server. To execute this operation, the
changeBackendPassword SOAP command is sent to IDENTIKEY Authentication Server. This
changeBackendPassword command should, at a minimum, specify the following parameters:
n componentType : indicates the client application component type

n userID: the ID of the user who changes their password.
n staticPassword: current static password
n newStaticPassword: new static password
Example
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<aut:changeBackendPassword xmlns:aut="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Authentication">
<componentType>SOAP-LocalAuth</componentType>
<user>
<userID>user_pws</userID>
<domain>MASTER</domain>
</user>
<credential>
<staticPassword>Test1234</staticPassword>
</credential>
<newStaticPassword>newPass1</newStaticPassword>

</aut:changeBackendPassword>
</soapenv:Body>
</soapenv:Envelope>
Note
If the Password Randomization feature of IDENTIKEY Authentication Server is used, the policy used in IDENTIKEY
Authentication Server must not apply password proxying for the changeBackendPassword SOAP com-
mand because this would lead to a user with a randomized password being able to change their password.
4.8. Authentication Using the Secure Channel Operations
To perform authentication using the Secure Channel feature, the following two operations must be executed in
this order:
1. Get Secure Challenge

2. Authenticate User
In order for this operation to succeed, the following administrative tasks should be performed in IDENTIKEY
Authentication Server:
Procedure 4: Configuring IDENTIKEY Authentication Server for the Get Secure Challenge operations
1. Use the ( IDENTIKEY Authentication with Secure Channel) policy or define a policy that inherits from this
policy.
2. Register a client component and assign the policy to it.
3. Import DIGIPASS devices that are compliant with the Multi-Device Licensing and support the Secure Chan-
nel feature.
4. Create users, assign a DIGIPASS license to them, and activate a new DIGIPASS instance for their device.
For more information on how to perform these tasks, refer to the IDENTIKEY Authentication ServerAdministrator
Guide.
4.8.1. Get Secure Challenge Operation
The Get Secure Challenge operation enables a user to generate a request message which can be used to initiate
an authentication process using the Secure Channel feature.
The Get Secure Challenge operation can send two types of requests to IDENTIKEY Authentication Server:
1. A request which includes a challenge message and, optionally, a transaction title (which will be used to
generate a request body and the request message).

2. A request which includes a custom request body (which will be transparently used to generate the request
message).
For more information on how to generate a custom request body, refer to the Secure Messaging SDK Server Integ-
ration Guide, which is included in the DIGIPASS for APPS SDK.
At a minimum, the getSecureChallenge command requires the following set of authentication field attrib-
utes in order to perform this operation:
n CREDFLD_COMPONENT_TYPE
n CREDFLD_USERID
To execute a Get Secure Challenge operation, the request must also include a CREDFLD_ CHALLENGE_
MESSAGE authentication field attribute with, optionally, a CREDFLD_ TRANSACTION_ TITLE authen-
tication field attribute, or include a CREDFLD_REQUEST_BODY authentication field attribute. For more inform-
ation, refer to 4.1.7. SOAP getSecureChallenge Request Structure .
For more information on the required and optional attributes for this command, refer to the IDENTIKEY Authentic-
ation Server SDK SOAP Reference.
4.8.2. Secure Channel Authenticate User Operation
The Secure Channel Authenticate User operation enables a user to perform user authentication using the Secure
Channel feature.
At a minimum, the authUser command requires the following set of authentication field attributes in order to
perform user authentication:
n CREDFLD_USERID
n CREDFLD_DOMAIN
n CREDFLD_CHALLENGE_KEY
n CREDFLD_PASSWORD
CREDFLD_PASSWORD is the password that is generated by the DIGIPASS device.

5. Authentication Back-End Integration

Back-end integration involves integration of custom authentication mechanisms into IDENTIKEY Authentication
Server. These custom authentication mechanisms can then be referred to in authentication policies, and thus be
included in processing user authentication requests.
Back-end integration is typically used for the following purposes:
Integration with or migration from legacy authentication system

This type of integration is typically used in combination with Dynamic User Registration (DUR) and
DIGIPASS Auto-Assignment. For example, Software DIGIPASS provisioning using a legacy authentication
system is used for the authentication of an historical password. The historical password in this case is a
credential that the user has to provide in order to get a Software DIGIPASS assigned.
IDENTIKEY Authentication Server can be integrated with the legacy system to pass details back to the leg-
acy authentication system and receive a reply. The provisioning will depend on the reply from the legacy
authentication system.
Password Replacement
This allows the user to log in with just a one-time password in an environment where the password of a leg-
acy authentication system is required.
In order to integrate back-end authentication into IDENTIKEY Authentication Server, the following administrative
tasks should be performed:
Procedure 5: Configuring IDENTIKEY Authentication Server for back-end authentication
1. Design and implement of an authentication engine.

2. Install the authentication engine into the IDENTIKEY Authentication Server.
3. Define the policies which use the authentication engine as back-end authentication protocol.
5.1. Authentication Engine
Developing an IDENTIKEY Authentication Server authentication engine requires the creation of a dynamically-
loaded library which implements the IDENTIKEY Authentication Server Authentication engine API.
Under Windows, the dynamically-loaded library should be implemented as a dynamic linked library (.dll).
Under Linux, the dynamically-loaded library should be implemented as a shared object file (.so).
The dynamically loaded library should expose following C functions:

ikey_initialize
This function should initialize the custom authentication engine. This function implementation could retrieve
custom engine configuration settings by calling the function pointer getProperty specified as first para-
meter.
Custom authentication engine configuration settings should be specified during installation of the authen-
tication engine using the IDENTIKEY Authentication Server Configuration Utility or directly into the IDENTIKEY
Authentication Server Configuration file (identikeyconfig.xml). For more information, refer to 5.3. Authentic-
ation Engine Definition Via Configuration Utility or 5.2. Authentication Engine Definition Via Configuration File.
ikey_authenticate
This function verifies the specified password for the identified user. The user is identified by the following
mandatory parameters:
n szUserID
n szDomain
ikey_terminate
This function is called when the dynamically loaded library is about to be unloaded by the IDENTIKEY
Authentication Server.
5.2. Authentication Engine Definition Via Configuration File
You can define an authentication engine for back-end authentication via IDENTIKEY Authentication Server con-
figuration file, i.e. identikeyconfig.xml. This file is located in:
/etc/vasco/ias/ (Linux)
<install_dir>\bin\ (Windows)
where <install_dir> is the installation directory of IDENTIKEY Authentication Server (typically C:\Program
Files\VASCO\IDENTIKEY Authentication Server)
In the IDENTIKEY Authentication Server configuration file, all custom authentication engines are defined in the
Engines main section. The following snippet shows a typical Engines section containing a custom engine
entry:
Example
<Engines>


<Enabled type="bool" data="true"/>

<Engine01>

<Enabled type="bool" data="true"/>

<Display-Name type="string" data="A special custom authentication DLL"/>

<Protocol-Name type="string" data="MySpecialProtocol"/>

<Library-Path type="string" data="DummyEngine.dll"/>

<Plugin-Config>

<My-Custom-Bit-Of-Data type="string" data="Hello world!"/>
</Plugin-Config>
</Engine01>
</Engines>
Such an entry would typically be nested under the BackEndAuthenticators section.
5.3. Authentication Engine Definition Via Configuration Utility
You can define an authentication engine for back-end authentication via the Configuration Utility. To do so, per-
form the following procedure:

Procedure 6: Defining an authentication engine for back-end authentication via the IDENTIKEY Authentication
Server Configuration Utility
1. Launch the Configuration Utility.

2. Access the Plugin Engines menu. To do so, click on the Engines button on the left pane.
Image 3: Plugin Engines menu

3. Click the Add button. Doing so should open an Add Plugin Engine dialogue.
Image 4: Add Plugin Engine dialogue

4. On the Add Plugin Engine dialogue, enter the following:
n Display Name
n Library Path
n Protocol
Enter the Custom Fields and Values.
5. Click OK to add the specified plugin engine. The Configuration Utility features test facilities through which
you can test these plugin engines later on.
6. After adding a plugin engine, it should now be available in the Available Engines section of the Plugin
Engines menu. Select the plugin engine you just added.

Image 5: Available plugin engines

7. Click the Test button. Doing so will open the Authenticate Plugin Engine dialogue.
Image 6: Authenticate Plugin Engine

8. On the Authenticate Plugin Engine dialogue, enter the following information of the user for which you will
be testing the plugin engine:
n Domain
n User ID
n Password
9. Click the Authenticate button. Doing so will open a pop-up message informing you whether or not the Plu-
gin Engine worked.

Image 7: Plugin Engine Authentication test result

10. Click OK to continue.
5.4. Custom Authentication Engine Startup and Shutdown Process
During startup and shutdown, IDENTIKEY Authentication Server will perform steps to load and unload the custom
authentication engine and associated libraries.
IDENTIKEY Authentication Server performs the following startup actions for each defined custom authentication
engine:

1. Load the engine plugin library to the server process.

2. If step 1 succeeds, call the engine plugin initialize function.
If step 2 succeeds, register the engine in the system.
If step 2 fails, unload the engine plugin library from the server process.
During shutdown, IDENTIKEY Authentication Server performs the following actions for each defined custom authen-
tication engine:
1. De-register the custom authentication engine from the system.

2. Call the terminate engine plugin function.
3. Unload the engine library from the server process.

6. Client Integration of Signature Validation

The IDENTIKEY Authentication Server signature validation functionality can be integrated into any application that
supports SOAP. This integration can be done via either of the following:
n Signature validation client interface wrappers, or

see 2.4. Wrappers.
Integrating the signature validation can be done by using the standard operations or the Secure Channel
operations; for more information on these different signature validation operations, refer to the relevant sections
below.
6.1. Signature Validation Integration Via SOAP API
6.1.1. SOAP genRequest Request Structure
A SOAP genRequest request typically uses the following format:

<soapenv:Envelope
xmlns:sig="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Signature"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header/>
<soapenv:Body>
<sig:genRequest>
<attributeSet>
<attributes>
<attributeID>SIGNFLD_COMPONENT_TYPE</attributeID>
<value xsi:type="xsd:string">[ClientApplication]</value>
</attributes>
<attributes>
<attributeID>SIGNFLD_USERID</attributeID>
<value xsi:type="xsd:string">[UserID]</value>
</attributes>
<attributes>
<attributeID>SIGNFLD_DOMAIN</attributeID>
<value xsi:type="xsd:string">[UserDomain]</value>
</attributes>

</attributeSet>
<dataFieldList>
<dataField>
<key>[key1]</key>
<value>[value1]</value>
</dataField>


</dataFieldList>
</sig:genRequest>
</soapenv:Body>
</soapenv:Envelope>
The SOAP body element must only contain a single genRequest element. This element has been defined in the
namespace sig. Therefore, the sig namespace must be declared in the Envelope element as an attribute.
A valid genRequest request also follows these additional rules:
n The genRequest element must contain one attributeSet.

n The attributeSet element must contain the minimum number of required attribute elements.
n Either one dataFieldList element or an attribute element containing an attributeID element with the value
SIGNFLD_REQUEST_BODY must exist.
n The dataFieldList element must contain at least one dataField element.
6.1.2. SOAP genRequest Response Structure
A SOAP genRequest response typically uses the following format:

<SOAP-ENV:Envelope
xmlns:SIGN-TYPES="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Signature"
xmlns:SIGNATURE-TYPES="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/SignatureTypes.xsd"
... (additional namespace declarations)
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<SIGN-TYPES:genRequestResponse>
<results xsi:type="SIGNATURE-TYPES:SignatureResults">
</resultCodes>
<resultAttribute xsi:type="SIGNATURE-TYPES:SignatureAttributeSet">
<attributes xsi:type="SIGNATURE-TYPES:SignatureAttribute">
<value xsi:type="xsd:string">[userID]</value>
</attributes>
<attributeID>SIGNFLD_DOMAIN</attributeID>
<value xsi:type="xsd:string">[UserDomain]</value>
</attributes>
<attributeID>SIGNFLD_SERIAL_NO</attributeID>
<value xsi:type="xsd:string">[SerialNumberOfApplicableDIGIPASS]</value>
</attributes>

<attributeID>SIGNFLD_REQUEST_KEY</attributeID>
</attributes>
<attributeID>SIGNFLD_REQUEST_MESSAGE</attributeID>
<value xsi:type="xsd:string">00C1C3E40F42B83CF9148F387513B69524E30A22
8FA9D81970B517266302E474E05CFCB03CA81DDBD79BCAC4AD521B90DCDCC0D27AD7A
940881E989971DAADEC327CAEFC418C66C356659148136BBD73EAB4A6D18440658530
E6F8ACD8F00D4F943B</value>
</attributes>
</resultAttribute>
</results>
</SIGN-TYPES:genRequestResponse>
</SOAP-ENV:Body>
The SOAP body element must only contain a single genRequestResponse element. This element always contains
a single result element, which in turn contains the following sub-elements:

Note
For this SOAP response, the resultAttribute element refers to signature attribute elements.

6.2. Real-Time Signature Validation Operation
This operation performs a time-based signature validation on a real-time signature. Signature validation is per-
formed within the current time window.

2. Define/assign a real-time signature validation policy to this client application.
3. Define users and assign DIGIPASS supporting time-based transaction authentication.
Guide.
At a minimum, the authSignature command requires the following set of signature field attributes in order
to perform signature validation:
n SIGNFLD_COMPONENT_TYPE
n SIGNFLD_USERID
n SIGNFLD_SIGNATURE
Example
A client application with component type SOAP Signature Client will typically send the following SOAP command
to perform a real-time signature validation operation for user test1:

<soapenv:Envelope
xmlns:sig="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Signature">
<soapenv:Header/>
<soapenv:Body>
<sig:authSignature>
<attributeSet>
<attributes>
<value xsi:type="xsd:string">SOAP Signature Client</value>
<attributeID>SIGNFLD_COMPONENT_TYPE</attributeID>
</attributes>
<attributes>
<attributeID>SIGNFLD_DATA_FIELD_1</attributeID>
</attributes>
<attributes>
</attributes>
<attributes>
</attributes>
<attributes>
</attributes>

<attributes>
<attributeID>SIGNFLD_SIGNATURE</attributeID>
</attributes>
</attributeSet>
</sig:authSignature>
</soapenv:Body>
</soapenv:Envelope>
If the transaction authentication is successful, IDENTIKEY Authentication Server will return the verified datetime in
the SOAP response if the following conditions are met:
1. The used DIGIPASS authenticator must have the Time Base Algorithm enabled for the signature applic-
ation. This can be verified in the application details for the relevant authenticator in the IDENTIKEY
Authentication Server Web Administration Interface.
2. For the policy used the Online Signature mode must be enabled (i.e. not set to Disabled) in the
DP Control Parameters tab of the relevant policy.
This information will be specified as signature attribute SIGNFLD_VERIFIED_DATETIME in the resultattribute ele-
ment.
6.3. Deferred-Time Signature Validation Operation
This operation performs a time-based signature validation on a signature that has been generated in deferred
time. Signature validation is performed within the time window for the specified deferred time.

2. Define/assign a deferred-time signature validation policy to this client application.
3. Define users and assign DIGIPASS supporting time-based transaction authentication.
Guide.
n SIGNFLD_USERID
n SIGNFLD_SIGNATURE

n SIGNFLD_DEFERRED_DATETIME: datetime when the digital signature has been generated.
If the transaction authentication is successful, IDENTIKEY Authentication Server will return the verified datetime in
the SOAP response if the following conditions are met:
1. The used DIGIPASS authenticator must have the Time Base Algorithm enabled for the signature applic-
ation. This can be verified in the application details for the relevant authenticator in the IDENTIKEY
Authentication Server Web Administration Interface.
2. For the policy used the Online Signature mode must be enabled (i.e. not set to Disabled) in the DP Control
Parameters tab of the relevant policy.
This information will be specified as signature attribute SIGNFLD_VERIFIED_DATETIME in the resultattribute ele-
ment.
6.4. Current Event Signature Validation Operation
This operation performs an event-based signature validation on a current event signature. Signature validation is
performed within the current event window.

2. Define/assign a current event signature validation policy to this client application.
3. Define users and assign DIGIPASS supporting event-based transaction authentication.
Guide.
n SIGNFLD_USERID
n SIGNFLD_SIGNATURE
If the transaction authentication is successful, IDENTIKEY Authentication Server will return the verified event
counter in the SOAP response. This information will be specified as signature attribute SIGNFLD_VERIFIED_EVENT_
VALUE in the resultattribute element.
6.5. Deferred Event Signature Validation Operation
This operation performs an event-based signature validation on a signature. Signature validation is performed
within the event window of the specified deferred event count.


2. Define/assign a current event signature validation policy.
3. Define users and assign DIGIPASS supporting event-based transaction authentication.
For more information about performing these tasks, refer to the IDENTIKEY Authentication Server Administrator
Guide.
n SIGNFLD_USERID
n SIGNFLD_SIGNATURE
n SIGNFLD_DEFERRED_EVENT_COUNT: event count used to generate the deferred event signature.
For more information about required and optional signature validation attributes for authSignature, refer to
the IDENTIKEY Authentication Server SDK SOAP Reference, Section "Signature".
If the transaction authentication is successful, IDENTIKEY Authentication Server will return the verified event
counter in the SOAP response. This information will be specified as signature attribute SIGNFLD_VERIFIED_EVENT_
VALUE in the resultattribute element.
6.6. Signature Validation Using the Secure Channel Operations
To perform signature validation using the Secure Channel feature, the following two operations must be executed
in this order:
1. Get Signing Request

2. Secure Channel Message Signature Validation
Procedure 7: Configuring IDENTIKEY Authentication Server for the Get Signing Request operations
1. Use the ( IDENTIKEY Signature Validation with Secure Channel) policy or define a policy that inherits from
this policy.
2. Register a client component and assign the policy to it.
3. Import DIGIPASS devices that are compliant with the Multi-Device Licensing and support the Secure Chan-
nel feature.
4. Create users, assign a DIGIPASS license to them, and activate a new DIGIPASS instance for their device.
For more information on how to perform these tasks, refer to the IDENTIKEY Authentication ServerAdministrator
Guide.

6.6.1. Get Signing Request Operation
The Get Signing Request operation enables a user to generate a signed request message which can be used to ini-
tiate a signature validation operation using the Secure Channel feature.
The Get Signing Request operation can send two types of requests to IDENTIKEY Authentication Server:
1. A request which includes a list of key/value data fields (which will be used to generate a request body and
the signed request message).
2. A request which includes a custom request body (which will be transparently used to generate the signed
request message).
For more information on how to generate a custom request body, refer to the Secure Messaging SDK Server Integ-
ration Guide, which is included in the DIGIPASS for APPS SDK.
At a minimum, the genRequest command requires the following set of signature field attributes in order to per-
form this operation:
n SIGNFLD_USERID
To execute a Get Signing Request operation, the request must also include at least one key/value dataField in the
dataFieldList element, or include a SIGNFLD_REQUEST_BODY signature field attribute. For more inform-
ation, refer to Section 6.1.1. SOAP genRequest Request Structure.
6.6.2. Secure Channel Message Signature Validation Operation
The Secure Channel Message Signature Validation operation enables a user to verify a signature against a signed
request message using the Secure Channel feature.
n SIGNFLD_USERID
n SIGNFLD_SIGNATURE
n SIGNFLD_REQUEST_KEY

7. Integration of Provisioning Functionality

Provisioning can be integrated via client integration or in the context of back-end authentication, and can be pro-
cessed as standard provisioning or Multi-Device Licensing (MDL) provisioning. For information on standard pro-
visioning, refer to Section 7.2. Standard Provisioning Operations; for information on MDL provisioning, refer to
Section 7.3. Multi-Device Licensing Provisioning Operations.
Client Integration
The IDENTIKEY Authentication Server Provisioning functionality can be integrated into any application that sup-
ports SOAP. This integration can be done at the client level by either:
n Using provisioning client interface wrappers

applications. For more information about wrappers provided by VASCO in the IDENTIKEY Authentication Server
SDK, see 2.4. Wrappers.
Back-End Authentication
You can also integrate back-end authentication in the context of Software DIGIPASS provisioning (standard
and MDL provisioning) or compliant Hardware DIGIPASS (MDL provisioning - DIGIPASS 760).
Integrating provisioning via back-end authentication is useful when a legacy authentication system is used
for the authentication of a historical password. With this type of integration, the historical password is used as
a user credential that must be provided as part of the registration request. Once the historical password is
provided, a Software DIGIPASS is assigned to that user.
For more information, refer to the IDENTIKEY Authentication Server SDK Plug-In Engine Guide.
7.1. Provisioning Integration Via SOAP API
The SOAP provisioning validation API provides the provisioningExecute SOAP operation. This operation

can be used to execute different provisioning commands.
Procedure 8: Using the provisioningExecute SOAP operation
1. Create a SOAP request for the provisioningExecute command.

2. Specify the correct SOAP provisioning operation (register or activate) to be executed in the SOAP request.
3. Specify one or more provisioning attributes as parameters for the SOAP operation. Attributes are key-value
pairs.

7.1.1. SOAP provisioningExecute Request Structure
A SOAP provisioningExecute request typically uses the following format:

<SOAP-ENV:Envelope
xmlns:PROV-TYPES="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Provisioning">
<SOAP-ENV:Body>
<PROV-TYPES:provisioningExecute>
<cmd>PROVISIONCMD_REGISTER</cmd>
<attributeSet>
<attributes>
<value xsi:type="xsd:string">DP4Mobile Provisioning Sample Client</value>
<attributeID>PROVFLD_COMPONENT_TYPE</attributeID>
</attributes>
<attributes>
<attributeID>PROVFLD_USERID</attributeID>
</attributes>
<attributes>
<attributeID>PROVFLD_DOMAIN</attributeID>
</attributes>
<attributes>
<value xsi:type="xsd:string">1.Password</value>
<attributeID>PROVFLD_STATIC_PASSWORD</attributeID>
</attributes>
<attributes>
<attributeID>PROVFLD_CUSTOM_ENCRYPT_PWD</attributeID>
</attributes>
</attributeSet>

</PROV-TYPES:provisioningExecute>
The SOAP Body element should only contain a provisioningExecute element (line 7). This element has been
defined in the namespace prov. Therefore, the prov should be declared in the Envelope element as an attribute.
A valid provisioningExecute request also follows these additional rules:
n The provisioningExecute element should contain only one AttributeSet element.

n The provisioningExecute element should contain only one cmd element.
n The AttributeSet element should contain zero or more provisioning attributes elements.
Example
7.1.2. SOAP provisioningExecute Response Structure
A SOAP provisioningExecute response typically uses the following format:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xop="http://www.w3.org/2004/08/xop/include"
xmlns:PROVISIONING-TYPES="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/ProvisioningTypes.xsd"
xmlns:PROV-TYPES="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Provisioning">
<SOAP-ENV:Body>
<PROV-TYPES:provisioningExecuteResponse>
<results>
<resultCodes>
</resultCodes>
<resultAttribute>
<attributes>
</attributes>
<attributes>
<attributeID>PROVFLD_DOMAIN</attributeID>
</attributes>
<attributes>
<value xsi:type="xsd:string"/>

<attributeID>PROVFLD_ORGANIZATIONAL_UNIT</attributeID>
</attributes>
<attributes>
<value xsi:type="xsd:string">VDS1000140</value>
<attributeID>PROVFLD_SERIAL_NO</attributeID>
</attributes>
<attributes>
<attributeOptions>
<masked>true</masked>
</attributeOptions>
<value
xsi:type="xsd:string">380801940103564453021010101010101010100123456789ABCDEF030101040
10405011006010107010108010309010F0A01000B01010C01000E01000F0101100101112F12010013
0101140101150C4170706C312020202020202016010117044080F8021801002901062A01062B01002
C01021135120100130101140102150C4170706C32202020202020201601011704408BF8D21801011
901062101062901062A01062B01002C01021141120100130101140103150C4170706C33202020202
020201601011704408BF8D21801031901011A01011B01012101102201102301102901062A01062B0
1002C0102112F120100130101140104150C4170706C342020202020202016010117044080F8021801
002901062A01062B01002C01021135120100130101140105150C4170706C35202020202020201601
011704408BF8D21801011901062101062901062A01062B01002C0102114112010013010114010615
0C4170706C36202020202020201601011704408BF8D21801031901011A01011B0101210110220110
2301102901062A01062B01002C01021000140016583966016262910891</value>
<attributeID>PROVFLD_ACTIVATION_CODE</attributeID>
</attributes>
</resultAttribute>
<errorStack/>
</results>
</PROV-TYPES:provisioningExecuteResponse>
</SOAP-ENV:Body>
The SOAP Body element should only contain a provisioningExecuteResponse element (line 12). The pro-
visioningExecuteResponse element always contains results element, which in turn contains the following sub-ele-
ments:


returnCodeEnum: the identifier corresponding to the returnCode

n
statusCodeEnum: the identifier corresponding to the statusCode
n
Note
The resultattribute element, in this case, is used to refer to provisioning attributes elements.
7.2. Standard Provisioning Operations
Standard provisioning consists of the following operations:
n Provisioning registration
n Provisioning activation
A provisioning registration operation is the first step in the provisioning process for DIGIPASS devices; it registers
the specified user for device provisioning. Refer to Section 7.2.1. Provisioning Registration Operation for more
information.
The registration operation is followed by a provisioning activation operation. Refer to 7.2.2. Provisioning Activation
Operation for more information.
7.2.1. Provisioning Registration Operation
Standard provisioning registration can involve the following optional processes:
n Assignment of a Software DIGIPASS device to the user

n Creation of an activation code for the assigned Software DIGIPASS device
IDENTIKEY Authentication Server requires prior user authentication before generating an activation code for the
assigned DIGIPASS device. The following registration types are supported, based on the type of user authen-
tication:
n Local authentication with the pre-loaded static password

n Activation Code gets encrypted with the pre-loaded static password
n Dynamic User Registration using a back-end system for authentication
Local authentication and activation code encryption with the pre-loaded static password are registration types
assuming that user accounts and static passwords have been pre-loaded into IDENTIKEY Authentication Server.
For more information about supported provisioning scenarios, refer to the IDENTIKEY Authentication Server Product
Guide.

7.2.1.1. Local Authentication with Pre-Loaded Static Password

Procedure 9: Configuring IDENTIKEY Authentication Server for Local Authentication (with pre-loaded static pass-
words)
1. Register the client application.

2. Define a policy with the following settings
n Local Authentication set to Digipass Only, DIGIPASS/Password during Grace Period, or DIGIPASS or
Password
n Back-end authentication set to None
3. Register the client component.
4. Assign the policy defined in Step 1 to the registered client application.
5. Import Software DIGIPASS.
6. Pre-load users with their static passwords.
Guide.
To perform local authentication with pre-loaded static passwords, the registered client application should send a
provisioningExecute SOAP command to IDENTIKEY Authentication Server, where the value for the cmd
element is PROVISIONCMD_REGISTER.
At a minimum, this SOAP command requires the following set of field attributes in order to perform this operation:
n PROVFLD_STATIC_PASSWORD
n PROVFLD_USERID
n PROVFLD_COMPONENT_TYPE
Example
A client application with component type DP4Web Provisioning Sample Client will typically send the following
SOAP command to register user test1 for this provisioning scenario:

<soapenv:Envelope
xmlns:prov="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Provisioning">
<soapenv:Header/>
<soapenv:Body>
<prov:provisioningExecute>
<attributeSet>
<attributes>
<value
xsi:type="xsd:string">233655275246515E5336245456302C2D55335D5720455A2952335C5254475
A53</value>
<attributeID>PROVFLD_ALEA</attributeID>
</attributes>
<attributes>
<value xsi:type="xsd:string">DP4Web Provisioning Sample Client</value>
</attributes>
<attributes>
</attributes>
<attributes>
<value xsi:type="xsd:string">passwd</value>
</attributes>
</attributeSet>
</prov:provisioningExecute>

</soapenv:Body>
</soapenv:Envelope>
In this example, the specified user's password is passwd. IDENTIKEY Authentication Server will verify this loc-
ally before generating an activation code.
7.2.1.2. Activation Code Encrypted With Pre-Loaded Static Password

Procedure 10: Configuring IDENTIKEY Authentication Server to provide Activation Codes encrypted with pre-loaded
static passwords
1. Register the client application.

2. Define a provisioning policy with the following settings
n Local Authentication set to None
n Back-end authentication set to None
4. Import Software DIGIPASS.
5. Pre-load users with their static passwords.
Guide.
To execute this operation, the registered client application should send a provisioningExecute SOAP
command to IDENTIKEY Authentication Server, where the value for the cmd element is PROVISIONCMD_REGISTER.
n PROVFLD_USERID
Example

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<attributeSet>
<attributes>
<value
A53</value>
</attributes>
<attributes>
</attributes>
<attributes>
<value xsi:type="xsd:string">test</value>
</attributes>
</attributeSet>
</soapenv:Body>
</soapenv:Envelope>

7.2.1.3. Dynamic User Registration Using a Back-End System for Authentication

Procedure 11: Configuring IDENTIKEY Authentication Server for Dynamic User Registration (using a back-end sys-
tem for authentication)
1. Import Software DIGIPASS

2. Define a provisioning policy with the following settings
n Local Authentication set to DIGIPASS/Password during Grace Period or DIGIPASS or Password
n Back-end authentication set to If Needed
n Back-end protocol set to Windows, RADIUS, or Custom Name
n Dynamic User Registration enabled
5. Define users.
Guide.
For more information about supported provisioning scenarios, refer to the IDENTIKEY Authentication Server Product
Guide.
To perform Dynamic User Registration using a back-end system for authentication, the registered client applic-
ation should send a provisioningExecute SOAP command to IDENTIKEY Authentication Server, where the
value for the cmd element is PROVISIONCMD_REGISTER.
n PROVFLD_USERID
Example

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<attributeSet>
<attributes>
<value
A53</value>
</attributes>
<attributes>
</attributes>
<attributes>
</attributes>
<attributes>
<value xsi:type="xsd:string">passwd</value>
</attributes>
</attributeSet>

</soapenv:Body>
</soapenv:Envelope>
In this example, IDENTIKEY Authentication Server will verify the specified user's password (i.e. passwd) with
the configured back-end system before generating an activation code.
7.2.2. Provisioning Activation Operation
This operation activates a previously-registered Software DIGIPASS for a specified user. Provisioning activation
includes a verification of the OTP generated with the Software DIGIPASS assigned to the specified user.
This operation is the second step in a Software DIGIPASS provisioning. This step is preceded by a provisioning regis-
tration operation (refer to 7.2.1. Provisioning Registration Operation for more information).
The registered client application should send a provisioningExecute SOAP command to IDENTIKEY
Authentication Server, where the value for the cmd element is PROVISIONCMD_ACTIVATE.
n PROVFLD_DP_RESPONSE
n PROVFLD_USERID
Example
A DP4Web client application with component type DP4Web Provisioning Sample Client will typically send the fol-
lowing SOAP command to activate a previously-assigned DIGIPASS for Web:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<cmd>PROVISIONCMD_ACTIVATE</cmd>
<attributeSet>
<attributes>
</attributes>
<attributes>
</attributes>
<attributes>
<attributeID>PROVFLD_DP_RESPONSE</attributeID>
</attributes>
</attributeSet>
</soapenv:Body>
</soapenv:Envelope>

7.2.3. Provisioning Activation Operation with Device-Binding
This operation activates a previously- registered Software DIGIPASS for a specified user and binds the
DIGIPASS authenticator to a selected device. Refer to Section 7.2.2. Provisioning Activation Operation for inform-
ation on carrying out provisioning activation that includes a verification of the OTP generated with the Software
DIGIPASS assigned to the specified user.
To execute provisioning activation with device-binding, The registered client application should send a pro-
visioningExecute SOAP command to IDENTIKEY Authentication Server, where the value for the cmd ele-
ment is PROVISIONCMD_ACTIVATE.
To carry out device- binding, PROVFLD_ DERIVATION_ CODE must be provided and the value for PROVFLD_
REQUEST_TYPE must be 0.
n PROVFLD_DERIVATION_CODE
n PROVFLD_REQUEST_TYPE
n PROVFLD_USERID
n PROVFLD_COMPONENT_TYPE: indicates the client application type
For more information about the required and optional provisioning attributes for the provisioningExecute
command, refer to the IDENTIKEY Authentication Server SDK SOAP Reference.
7.3. Multi-Device Licensing Provisioning Operations
Provisioning for DIGIPASS devices that are compliant with the Multi-Device Licensing (MDL) model is a process
which consists of the following operations:
n Multi-Device Licensing user registration

n Multi-Device Licensing device registration
n Multi-Device Licensing activation
7.3.1. User Registration Operation
The Multi-Device Licensing (MDL) user registration operation enables a user to register a DIGIPASS device com-
pliant with the Multi-Device Licensing model for provisioning .
The MDL user registration operation can involve the following optional processes:
n Creating a user account in IDENTIKEY Authentication Server after successful back-end authentication
n Assigning a new DIGIPASS license to the user if this user does not yet have a DIGIPASSlicense matching the
assigned policy limits
n Generating the challenge for Activation Message 1

The user registration operation is the first step in the MDL provisioning process. This operation returns Activation
Message 1 which must be transferred to the DIGIPASS device to generate a device code. This operation is followed
by the MDL device registration operation - for more information on this operation, refer to Section7.3.2. Multi-
Device Licensing Device Registration Operation.
Activation Message 1 must be transferred to the DIGIPASS device; this can be done in the form of a QR-code or a
color QR code which the user scans with the camera of the device. For more information on how to generate a QR-
code or a color QR code, refer to the Image Generator SDK Integration Guide which is part of the DIGIPASS for APPS
or DIGIPASS for Mobile SDK.
IDENTIKEY Authentication Server requires prior user authentication before generating Activation Message 1 for the
assigned DIGIPASS license. The following registration types are supported, based on the type of user authen-
tication:
n Local authentication with a shared historical secret (static password)

n Dynamic User Registration using a back-end system for authentication
Local authentication with a shared historical secret is a registration type assuming that user accounts and static
passwords have been pre-loaded into IDENTIKEY Authentication Server. For more information about supported pro-
visioning scenarios, refer to the IDENTIKEY Authentication Server Product Guide.
7.3.1.1. Local Authentication with Historical Shared Secret

Procedure 12: Configuring IDENTIKEY Authentication Server for Multi-Device Licensing user registration using local
authentication with a historical shared secret
1. Define a policy with the following settings:

n Back-End Authentication set to None
n Assignment mode set to Auto-Assignment
n Check Challenge mode set to 0 - No Challenge Check
3. Assign the policy defined in Step 1 to the registered client component.
4. Import a DIGIPASS device compliant with Multi-Device Licensing.
5. Pre-load the user accounts and include static passwords.
Guide.
To perform the Multi-Device Licensing user registration operation using local authentication with historical secrets,
the registered client application should send a provisioningExecute SOAP command to IDENTIKEY
Authentication Server, where the value for the cmd element is PROVISIONCMD_MDL_REGISTER.

n PROVFLD_USERID
7.3.1.2. Dynamic User Registration Using a Back-End System for Authentication

Procedure 13: Configuring IDENTIKEY Authentication Server for Multi- Device Licensing user registration with
Dynamic User Registration using a back-end system for authentication
1. Register a back-end server for authentication (not required for a local Windows back end).
2. Define a policy with the following settings:
n Back-End Authentication set to If Needed
n Back-End Protocol set to the chosen back-end system (effectively, the setting must not be None)
n Dynamic User Registration enabled
n Assignment mode set to Auto-Assignment
n Check Challenge mode set to 0 - No Challenge Check
4. Assign the policy as defined in Step 1 to the registered client component.
5. Import a DIGIPASS device compliant with Multi-Device Licensing.
Guide.
To perform the Multi-Device Licensing user registration operation with Dynamic User Registration using a back-
end system for authentication, the registered client application should send a provisioningExecute SOAP
command to IDENTIKEY Authentication Server, where the value for the cmd element is PROVISIONCMD_MDL_
REGISTER.
n PROVFLD_USERID
7.3.2. Multi-Device Licensing Device Registration Operation
The Multi-Device Licensing (MDL) device registration operation enables a user to register a new device with
IDENTIKEY Authentication Server. The device must include DIGIPASS software and/or firmware which is compliant
with the Multi-Device Licensing model.

The MDL device registration operation is the second step in the MDL provisioning process. This operation verifies
the device code generated by the DIGIPASS device based on Activation Message 1. This operation creates a new
DIGIPASS instance for the DIGIPASS license, and returns Activation Message 2 which must then be transferred to
the DIGIPASS device to create the DIGIPASS instance on this device. This operation is optionally followed by the
MDL activation operation - for more information on this operation, refer to Section 7.3.3. Multi-Device Licensing
Activation Operation.
Activation Message 2 must be transferred to the DIGIPASS device; this can be done in the form of a QR-code or a
To perform the Multi-Device Licensing device registration, the registered client application should send a pro-
ment is PROVISIONCMD_MDL_ADD_DEVICE.
n PROVFLD_DEVICE_CODE
n PROVFLD_REGISTRATIONID
7.3.3. Multi-Device Licensing Activation Operation
The Multi-Device Activation (MDL) activation operation enables a user to validate the confirmation code generated
by the newly created DIGIPASS instance after Activation Message 2 has been processed by the DIGIPASS device.
The MDL activation operation is the optional final step in the MDL provisioning process. This operation verifies the
signature generated by the DIGIPASS device based on Activation Message 2.
To perform the MDL activation operation, the registered client application should send a pro-
ment is PROVISIONCMD_MDL_ACTIVATE.
n PROVFLD_SIGNATURE
n PROVFLD_REGISTRATIONID

8. Client Integration of Administrative Functions

The IDENTIKEY Authentication Server administration functions can be integrated into any application that supports
SOAP.
This integration can be done via one of the following:
n Administration client interface wrappers

see 2.4. Wrappers.
The following sections apply to both a standard administration scenario and a Multi-Device Licensing and Activ-
ation (MDL) administration scenario. For commands specific to an MDL administration scenario, see 8.7. Multi-
Device Activation Operations.
The SOAP interface for signature validation supports sending the following command types to IDENTIKEY Authentic-
ation Server:
n Administration logon/logoff commands

n User administration commands
n User attribute administration commands
n DIGIPASS administration commands
n DIGIPASS import commands
n DIGIPASS application administration commands
n Policy administration commands
n Component administration commands
n Backend administration commands
n Domain administration commands
n Organizational unit administration commands
n Report administration commands
n Report format administration commands
n Replication administration commands
n Admin session administration commands
The SOAP administration API provides various types of SOAP operations for the different administration commands:
n Logon/logoff SOAP operation

n Execute SOAP operation
n Query SOAP operation
n File upload/download operation
n Keep-admin-session-alive operation
Users attempting to perform this type of integration should be familiar with the following standards:
n XML
n XML Schema

n SOAP
n MIME
n MTOM
8.1. Logon/Logoff Operation Via SOAP API
Each SOAP administration operation requires a prior administrative logon. IDENTIKEY Authentication Server
provides an administrative sessionID as a response to a successful administrative logon request. Each admin-
istrative operation on the IDENTIKEY Authentication Server requires specifying this sessionID and must be per-
formed from the same client location.
To perform a logon or logoff operation, refer to the following procedure:
Procedure 14: Logging on/off via SOAP
1. Create a SOAP request.

2. Specify the logon or logoff SOAP operation in the SOAP request.
3. Specify one or more credential attributes as parameters for the SOAP operation. Attributes are key-value
pairs.
8.1.1. SOAP logon/logoff Request
A SOAP logon request typically uses the following format:

<soapenv:Envelope
xmlns:adm="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Administration">
<soapenv:Header/>
<soapenv:Body>
<adm:logon>
<attributeSet>
<attributes>
</attributes>
</attributeSet>
</adm:logon>
</soapenv:Body>
</soapenv:Envelope>
SOAP logon and logoff requests have the same format.
The SOAP body element should only contain a logon or logoff element (line 8). This element has been defined in
the namespace adm. Therefore, adm should be declared in the Envelope element as an attribute.
A valid logon or logoff request also follows these additional rules:
n The logon or logoff element should contain only one AttributeSet element.
n The AttributeSet element should contain zero or more provisioning attributes elements.


Example
8.1.2. SOAP logon/logoff Response
A SOAP logon request typically uses the following format:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<ADMIN-TYPES:logonResponse>
</resultCodes>
<attributes>
</attributes>
</resultAttribute>
</results>
</ADMIN-TYPES:logonResponse>
</soapenv:Body>
</soapenv:Envelope>
SOAP logon and logoff responses have the same format.

The SOAP body element should only contain a logonResponse element (line 9). The logonResponse element
always contains a results element, which in turn contains the following elements:

Note
8.2. Execute Operation Via SOAP API
An execute operation is a SOAP operation used to perform administrative actions on specified objects that exist
within the IDENTIKEY Authentication Server data model. Each SOAP administration operation requires a prior admin-
istrative logon.
IDENTIKEY Authentication Server provides an administrative sessionID as a response to a successful admin-

istrative logon request. Each administrative operation on the IDENTIKEY Authentication Server requires specifying
this sessionID.
Execute operations are either executed immediately or scheduled and effectively executed only after approval via
maker–checker authorization.
8.2.1. Immediate execution
To perform an execute operation immediately, perform the following procedure.
Procedure 15: Performing an execute operation via SOAP immediately
1. Create a SOAP request for the object upon which you wish to perform an action.
2. Specify the administration 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.
8.2.2. Execution using maker–checker authorization
If maker–checker authorization is enabled, an execute operation is not executed immediately. It is rather deferred
and can effectively be executed after approval by another administrator only.
In this case, the execute operation is to be performed twice:
1. The operation is performed as usual (see Procedure 15: Performing an execute operation via SOAP imme-
diately), but additionally passing information about the approving administrator, i.e. *_ CHECKER_
USERID and *_CHECKER_DOMAIN.
The operation is scheduled and returns a pending operation identifier (POID) to identify the scheduled oper-
ation. The approving administrator receives a notification to either approve or reject the pending operation
using approvePendingOperation or rejectPendingOperation, respectively.
2. Once the pending operation has been approved, it is performed a second time, this time passing the POID.
The pending operation is executed normally.
For more information about which commands support maker–checker authorization and how to use them, refer to
the IDENTIKEY Authentication Server SDK SOAP Reference.
For more information about maker–checker authorization, refer to the IDENTIKEY Authentication Server Product
Guide.
8.2.3. SOAP execute Request
A SOAP execute request typically uses the following format:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<adm:????Execute>
<sessionID>session identifier string</sessionID>
<cmd>?????CMD_!!!!!!</cmd>
<attributeSet>
<attributes>
</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 has been defined in the namespace adm . Therefore, adm should be
declared in the Envelope element as an attribute.
A valid execute request also follows these additional rules:
n The <object>execute element should contain only one attributeSet element.

n The attributeSet element should contain zero or more provisioning attributes elements.
n The <object>execute element should contain one sessionID element. To get a sessionID, an
administrative logon has to be executed (see 8.1. Logon/Logoff Operation Via SOAP API).
n The <object>execute element should contain one cmd element.

Example
8.2.4. SOAP execute Response
A SOAP execute request typically uses the following format:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<ADMIN-TYPES:????ExecuteResponse>
<results xsi:type="USER-TYPES:?????Results">
</resultCodes>
<resultAttribute xsi:type="USER-TYPES:?????AttributeSet">
<attributes xsi:type="USER-TYPES:????Attribute">
<value xsi:type="xsd:string">?????????</value>
<attributeID>!!!!!!!!!</attributeID>
</attributes>
</resultAttribute>
</results>
</ADMIN-TYPES:??????ExecuteResponse>
</soapenv:Body>
</soapenv:Envelope>
The SOAP body element should only contain an <object>ExecuteResponse element, where <object> spe-
cifies the requested object (line 9). The <object>ExecuteResponse element always contains a results
element, which contains the following elements:


Note
The resultAttribute element, in this case, is used to refer to attributes elements for the specified
<object>.
8.3. Query Operation Via SOAP API
A query is a SOAP administration operation used to perform searches on specified objects that exist within the
IDENTIKEY Authentication Server data model.
Each SOAP administration operation requires a prior administrative logon. IDENTIKEY Authentication Server
provides a session identifier, i.e. sessionID, as a response to a successful administrative logon request. Each
administrative operation on the IDENTIKEY Authentication Server requires specifying this session identifier.
Procedure 16: Performing a query operation via SOAP
1. Prepare a query SOAP request for the object upon which you wish to perform a search:
a. Specify sessionID in the SOAP request.
b. 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.
c. Specify one or more object attributes that should be returned by the query.
Optionally, you can specify query options such as:

n distinctive
n rowoffset
n rowcount
n count

Note
After upgrading IDENTIKEY Authentication Server, server data is continuously migrated while the already-
upgraded IDENTIKEY Authentication Server 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 res-
ult.
8.3.1. SOAP query Request
A SOAP query request typically uses the following format:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<adm:????Query>
<sessionID>?</sessionID>
<attributeSet>
<attributes>

<attributeOptions>

<negative>?</negative>

<masked>?</masked>

<null>?</null>
</attributeOptions>
<value>?</value>
<attributeID>?</attributeID>
</attributes>
</attributeSet>

<fieldSet>
<attributeID>?</attributeID>
</fieldSet>


<queryOptions>

<distinct>?</distinct>

<rowoffset>?</rowoffset>

<rowcount>?</rowcount>

<count>?</count>
</queryOptions>
</adm:??????Query>
</soapenv:Body>
</soapenv:Envelope>
The SOAP body element should only contain an objectquery element, where object specifies the requested object
(line 8). This element has been defined in the namespace adm . Therefore, adm should be declared in the
Envelope element as an attribute.
A valid query request also follows these additional rules:
n The objectquery element should contain only one AttributeSet element.

n The AttributeSet element should contain zero or more provisioning attributes elements. These attribute
elements define the query search criteria.
n The objectquery element should contain one sessionID element. In order to get a sessionID, an admin-
istrative logon has to be executed (refer to 8.1. Logon/Logoff Operation Via SOAP API for details).
n The objectquery element should contain one cmd element.
Search fields specified using the AttributeSet elements are interpreted as follows:
n Wildcards are always accepted when indicated, except for user and DIGIPASS searches. For these
requests, they are accepted only if the toUserID or toSerial parameters are not set.
n Wildcards can be placed at start, end or both of the values. In this case, they will be interpreted as the SQL
LIKE statement.
n A list of comma separated values can be specified, in this case it will be interpreted as the logical OR of
the given values.
n Otherwise, the search will be done using the exact match of the given value.
The objectquery could optionally contain one of each of the following elements:
n fieldSet: If specified, the fieldSet element should contain zero or more object attribute elements. These
elements specify the object fields that the IDENTIKEY Authentication Server should return for the each of
the objects matching the search criteria.

n queryOptions: This element provides directions to the IDENTIKEY Authentication Server on what results
should be returned. The following queryOptions are supported:
n distinct: flag to request the IDENTIKEY Authentication Server to return query results with no duplic-
ate entries. This option is of type boolean.
n rowoffset: option to request the IDENTIKEY Authentication Server to return results starting from
the specified offset. This option is of type unsignedInt.
n rowcount: option to request the IDENTIKEY Authentication Server to return the specified number of
results. This option is of type unsignedInt.
n count: flag to request the IDENTIKEY Authentication Server to return the count of the results not
the results themselves. This option is of type boolean.
8.3.2. SOAP query Response
A SOAP query request typically uses the following format:

<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<ADMIN-TYPES:????QueryResponse>
<results xsi:type="USER-TYPES:????QueryResults">
</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>
</results>
</ADMIN-TYPES:????QueryResponse>
</soapenv:Body>
</soapenv:Envelope>

The SOAP body element should only contain an objectQueryResponse element, where object specifies the reques-
ted object (line 9). The objectQueryResponse element always contains a results element, which in turn contains
the following elements:

n ResultCount (required): this element specifies the number of objects that matched the specified search cri-
teria. If the queryOption count was set to true in the query request, then only the ResultCount element
would be returned in the response.
Note
The resultattribute element, in this case, is used to refer to attributeList elements for the specified object. Each
attributeList element specifies one search result row.
8.4. File Upload/Download Operation Via SOAP API
This type of SOAP administration operation performs a file upload or download operation.
Examples of command that use this SOAP operation are:
n DPX file upload command

n Report download command
8.5. User Administration Commands Via SOAP API
The SOAP Administration interface supports the following SOAP operations to perform user administration com-
mands:
n userExecute
n userQuery
For more information on these commands, refer to the IDENTIKEY Authentication Server SDK SOAP Reference.

Example
A client administration application will typically send the following SOAP command to view the user attributes of
user test1 created under domain master:
<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<adm:userExecute>
<sessionID>ZWo~ORIG-SqrgLN[Y-he~jpbZjegoNxr</sessionID>
<cmd>USERCMD_VIEW</cmd>
<attributeSet>
<attributes>
<attributeID>USERFLD_USERID</attributeID>
</attributes>
<attributes>
<attributeID>USERFLD_DOMAIN</attributeID>
</attributes>
</attributeSet>
</adm:userExecute>
</soapenv:Body>
</soapenv:Envelope>
Example
In this example, a client administration application will typically send the following SOAP command to query

users whose userIDs start with f, only returning the userID in the search results.
<soapenv:Envelope
<soapenv:Header/>
<soapenv:Body>
<adm:userQuery>
<sessionID>wiy6ywXaFwR8wdzXsq7b4Jo5BPSfq4J6</sessionID>
<attributeSet>
<attributes>
<value xsi:type="xsd:string">f*</value>
</attributes>
</attributeSet>
<fieldSet>
</fieldSet>
</adm:userQuery>
</soapenv:Body>
</soapenv:Envelope>
8.6. Other Administration Commands Supported by the SOAP API
This section lists other SOAP operations supported by the SOAP administration interface. For a more detailed
description of each command, refer to the IDENTIKEY Authentication Server SDK SOAP Reference.
UserAttribute Administration Commands

The SOAP Administration interface supports the following SOAP operations to perform user attribute admin-
istration commands:

n userattributeExecute
n userattributeQuery
DIGIPASS Administration Commands

The SOAP Administration interface supports the following SOAP operations to perform DIGIPASS administration
commands:
n digipassExecute
n digipassQuery
DIGIPASS Import Commands

The SOAP Administration interface supports the following SOAP operations to perform DIGIPASS import com-
mands:
n dpxfileExecute
n dpxfileuploaddime
n dpxfileuploadmime
n dpxfileuploadmtom
DIGIPASS Application Administration Commands

The SOAP Administration interface supports the following SOAP operations to perform DIGIPASS Application
administration commands:
n digipassapplExecute
n digipassapplQuery
Policy Administration Commands

The SOAP Administration interface supports the following SOAP operations to perform policy administration
commands:
n policyExecute
n policyQuery
Component Administration Commands

The SOAP Administration interface supports the following SOAP operations to perform Component admin-
istration commands:
n componentExecute
n componentQuery
Back-end Administration Commands

The SOAP Administration interface supports the following SOAP operations to perform back-end admin-
istration commands:

n backendExecute
n backendQuery
Domain Administration Commands

The SOAP Administration interface supports the following SOAP operations to perform domain administration
commands:
n domainExecute
n domainQuery
OrgUnit Administration Commands

The SOAP Administration interface supports the following SOAP operations to perform DIGIPASS administration
commands:
n orgunitExecute
n orgunitQuery
Report Administration Commands

The SOAP Administration interface supports the following SOAP operations to perform report administration
commands:
n reportExecute
n reportdownloadmtom
n reportQuery
ReportFormat Administration Commands

The SOAP Administration interface supports the following SOAP operations to perform report format admin-
istration commands:
n reportformatExecute
n reportformatQuery
Replication Administration Commands

The SOAP Administration interface supports the following SOAP operations to perform replication admin-
istration commands:
n replicationserverExecute
n replicationserverQuery
Sessionalive Operation
The SOAP Administration interface supports the sessionalive operation. This operation is used to keep
an administrative session alive, avoiding that these admin sessions would time out due to session inactivity:

8.7. Multi-Device Activation Operations
The activation of DIGIPASS devices compliant with the Multi-Device Licensing model, as initiated by an IDENTIKEY
Authentication Server administrator, consists of the following administrative operations:
n Generate Activation Message

n Add Device
n Test Signature with Secure Channel
Once a DIGIPASS instance has been activated for a specific DIGIPASS device, that DIGIPASS instance can be deac-
tivated with the Deactivate operation. For more information on this operation, refer to Section 8.7.4. Deactivate
Operation.
8.7.1. Generate Activation Message Operation
The Generate Activation Message operation allows an administrator to generate Activation Message 1 for a par-
ticular DIGIPASS license. This operation is used as the first step in the Multi-Device Activation process; it returns
Activation Message 1. To generate the device code, Activation Message 1 must be transferred to the DIGIPASS
device; this can be done in the form of a QR-code or a color QR code which the user scans with the camera of the
device. For more information on how to generate a QR-code or a color QR code, refer to the Image Generator SDK
Integration Guide which is part of the DIGIPASS for APPS or DIGIPASS for Mobile SDK.
The Generate Activation Message operation is followed by the Add Device operation - refer to Section 8.7.2. Add
Device Operationfor more information.
To perform the Generate Activation Message operation, the registered client application should send a digi-
passExecute SOAP command to IDENTIKEY Authentication Server, where the value for the cmd element is
DIGIPASSCMD_GENERATE_ACTIVATION_MESSAGE.
n DIGIPASSFLD_SERNO
8.7.2. Add Device Operation
The Add Device operation allows an administrator to register a new or additional device for a particular DIGIPASS
license . The device must include DIGIPASS software and/or firmware which is compliant with the Multi-Device
Licensing model.

The Add Device operation is used as the second step in the Multi-Device Activation process. This operation verifies
the device code generated by the DIGIPASS device based on Activation Message 1. This operation creates a new
DIGIPASS instance for the DIGIPASS license, and returns Activation Message 2 which must then be transferred to
the DIGIPASS device to create the DIGIPASS instance on this device. This operation is optionally followed by theTest
Signature operation - for more information on this operation, refer to Section 8.7.3. Test Signature with Secure
Channel Operation.
Activation Message 2must be transferred to the DIGIPASS device; this can be done in the form of a QR-code or a
To perform the Add Device operation, the registered client application should send a digipassExecute SOAP
command to IDENTIKEY Authentication Server, where the value for the cmd element is DIGIPASSCMD_ADD_
DEVICE.
n DIGIPASSFLD_SERNO
n DIGIPASSFLD_DEVICE_CODE
8.7.3. Test Signature with Secure Channel Operation
The Test Signature with Secure Channel operation allows an administrator to validate the confirmation code gen-
erated by the newly created DIGIPASS instance after Activation Message 2 has been processed by the DIGIPASS
device.
The Test Signature with Secure Channel operation is the optional final step in the Multi-Device Activationprocess.
This operation verifies the signature generated by the DIGIPASS device based on Activation Message 2. In case the
DIGIPASS software running on the device is based on DIGIPASS for APPS, no signature may be returned after Activ-
ation Message 2 has been processed. Contact your vendor for more information on the DIGIPASS software running
on the relevant device.
To perform the Test Signature with Secure Channel operation, the registered client application should send a
digipassapplExecute SOAP command to IDENTIKEY Authentication Server, where the value for the cmd
element is DIGIPASSAPPLCMD_TEST_SIGNATURE.
n DIGIPASSAPPLFLD_SERNO
n DIGIPASSAPPLFLD_APPL_NAME
n DIGIPASSAPPLFLD_REQUEST_KEY
n DIGIPASSAPPLFLD_SIGNATURE

8.7.4. Deactivate Operation
The Deactivate operation allows an administrator to generate a deactivation message for a specific DIGIPASS
instance. This operation expires and deactivates all DIGIPASS applications for the selected DIGIPASS instance.
To perform the Deactivate operation, the registered client application should send a digipassExecute SOAP
command to IDENTIKEY Authentication Server, where the value for the cmd element is DIGIPASSCMD_
DEACTIVATE.
n DIGIPASSFLD_SERNO

9. DIGIPASS for Mobile

From IDENTIKEY Authentication Server 3.5, DIGIPASS for Mobile 4.0 will be supported. To enable DIGIPASS for
Mobile 4.0 on IDENTIKEY Authentication Server, some configuration steps need to be performed.
DIGIPASS for Mobile versions 3.0 and 3.5 will still be supported.
For detailed information about initial installation and configuration of DIGIPASS for Mobile 4.0, refer to the DIGIPASS
for Mobile 4.0 manuals.
9.1. DIGIPASS for Mobile 4.0 Configuration
To enable certain features of DIGIPASS for Mobile 4.0 with IDENTIKEY Authentication Server 3.5, some changes to
the DIGIPASS for Mobile configuration file are required. The DIGIPASS for Mobile configuration file can be found at
<DIGIPASS for Mobile install directory>\dp4mobile\4.0\tools\Customization Tool\input\xml\DIGIPASS.xml.
DIGIPASS must be registered and assigned before any of the following actions can be processed successfully.
Static Vector
The static vector in the configuration file will have to be updated using the contents of the <install_
dir>\dpx\Demo_DP4Mobile40.svf file. The static vector contained in the configuration file is for place-holding
purposes only, and MUST be changed before any DIGIPASS for Mobile functions will work.
User Principal Name (UPN)

The User Principal Name used in DIGIPASS for Mobile 4.0 with IDENTIKEY Authentication Server 3.5 has no
fixed format. You may use whatever format suits your requirements.
9.1.1. Advanced Online Activation
Advanced Online Activation for DIGIPASS for Mobile allows the use of the following features:
n Advanced Registration (including server generated ID and activation password)

n Advanced generateActivationData
n Online Post Activation (derivation or OTP)
n Can also support Manual Post Activation using Derivation Code
n Standard Response Only/Challenge Response/SG authentication
n Online Signature Authentication (Requires Registration UPN)
To configure DIGIPASS for Mobile 4.0 Advanced Online Activation for the IDENTIKEY Authentication Server SDK, the
following settings need to be amended:

Online Activation Settings

n enabled = "true"
n advancedMode = "true"
n useRegistrationIdentifier = "true"
n useActivationPassword = "true"
n checksumOnActivationPassword = "false"
n useAuthorizationCode = "false"
n checksumOnAuthorizationCode = "false"
n useUserIdentifier = "true"
Refer to the example below for the format and settings required. Pay special attention to the format of the sample
URLs, and use the correct one for your programming language. -
Example
DSAPP Online Authentication:
enabled = true
advancedMode = true, use DSAPP (DIGIPASS Software Advanced Provisioning Protocol)
useRegistrationIdentifier = true, server generated identifier, based on new Provisioning Scenario configuration
useActivationPassword = true, server generated activation password, based on new Provisioning Scenario con-
figuration
useUserIdentifier = true, SDK provided UPN user@domain
<OnlineActivation enabled="true" advancedMode="true" useRegistrationIdentifier="true" useActiv-

ationPassword="true" checksumOnActivationPassword="false" useAuthorizationCode="false" check-
sumOnAuthorizationCode="false" useUserIdentifier="true">
Java Sample URL

<URL method="GET" value="http://<ADDRESS>:8080/IdentikeySampleSite/-
provisioning/dp4mobile/DSAPPgenerateActivationData.jsp?registrationIdentifier=%_Regis-
trationIdentifier_%&publicKey=%_PublicKey_%&initialVector=%_InitialVector_%"/>
ASP.Net Sample URL

<URL method="GET" value="http://<ADDRESS>/IdentikeySampleSite/-
provisioning/dp4mobile/DSAPPgenerateActivationData.aspx?registrationIdentifier=%_Regis-
trationIdentifier_%&publicKey=%_PublicKey_%&initialVector=%_InitialVector_%"/> -->
9.1.2. Standard Online Activation
Standard Online Activation for DIGIPASS for Mobile allows the use of the following features:

n Standard Registration (serialno. Suffix ID and SDK generated custom encryption activation password)
n Get Activation Code (from the SDK)
n Online Post Activation
n Standard RO/CR/SG authentication
n No automatic online signature support
n No upn provided in the register/activation process, however it could be configured directly in the phone.
To configure DIGIPASS for Mobile 4.0 Advanced Online Activation for the IDENTIKEY Authentication Server SDK, the
following settings need to be amended:
Online Activation Settings

n enabled = "true"
n advancedMode = "false"
n useRegistrationIdentifier = "true"
n useActivationPassword = "true"
n checksumOnActivationPassword = "false"
n useAuthorizationCode = "false"
n checksumOnAuthorizationCode = "false"
n useUserIdentifier = "false"
Refer to the example below for the format and settings required. Pay special attention to the format of the sample
URLs, and use the correct one for your programming language.
Example
Standard Online Authentication:
enabled = true
advancedMode = false, use standard provisioning (custom encryption password)
useRegistrationIdentifier = true, stripped serial number i.e. VDS1000140 => 1000140
useActivationPassword = true, SDK generated password
useUserIdentifier = false, not supported by the SDK samples in this mode
<OnlineActivation enabled="true" advancedMode="false" useRegistrationIdentifier="true" useActiv-

ationPassword="true" checksumOnActivationPassword="false" useAuthorizationCode="false" check-
sumOnAuthorizationCode="false" useUserIdentifier="false">
Java Sample URL

<URL method="GET" value-
="h-
ttp://<ADDRESS>:8080/IdentikeySampleSite/provisioning/dp4mobile/getActivationData.jsp?registrationIdentifier=%_
RegistrationIdentifier_%"/>
ASP.Net Sample URL

<URL method="GET" value-

="h-
ttp://<ADDRESS>/IdentikeySampleSite/provisioning/dp4mobile/getActivationData.aspx?registrationIdentifier=%_
RegistrationIdentifier_%"/>
-->
9.1.2.1. Offline Manual Activation

Offline Manual Activation for DIGIPASS for Mobile allows the use of the following features:
n Manual Assignment
n Manual getActivationCode via the Administration Web Interface or MDC
n Manual Post Activation using derivation code
n Standard RO/CR/SG Auth
To configure DIGIPASS for Mobile 4.0 for Offline Manual for the IDENTIKEY Authentication Server SDK, the following
settings need to be amended:
Offline Activation Settings

n enabled = "true"
n useERC = "true"
n useUserIdentifier = "false
Example
Offline Manual Activation
<OfflineActivation enabled="true" useERC="true" useUserIdentifier="false">
9.1.2.2. Offline QR Code Activation

Offline QR Code Activation for DIGIPASS for Mobile allows the use of the following features:
n Manual Assignment
n Manual getActivationCode via the Administration Web Interface using QR code scan
n Manual Post Activation using derivation code
n Standard RO/CR/SG Auth
To configure DIGIPASS for Mobile 4.0 for Offline QR code Activation for the IDENTIKEY Authentication Server SDK,
the following settings need to be amended:

Offline Activation Settings

n QRCodeActivation enabled="true"
n useActivationPassword="false"
n useERC = "false"
n useUserIdentifier = "false"
n displayQRCodeContent="false"
Example
Offline QR Code Activation
<QRCodeActivation enabled="true" useActivationPassword="false" checksumOnActivationPassword="false"

useERC="false" useUserIdentifier="false" displayQRCodeContent="false">
9.1.3. Post Activation
9.1.3.1. DSAPP Online Post Activation

To use Online Post Activation using DSAPP on DIGIPASS for Mobile 4.0, the following settings must be changed:
PostActivation
n enabled = "true"
n derivation = "true"
n serverActivation = "true"
n cryptoAppIndex = "1"
n regenerate = "false"
n responsePattern = "XXXXXX" (provide the correct pattern)
n hostCodePattern = "XXXXXX" (provide the correct pattern)
n displaySerialNumber = "true"
Example
DSAPP Online Post Activation
enabled = true
derivation = true, Generate and activation using Derivation Code or false, Generate and activation using OTP.
Either choice can be used, depending on your requirements.
serverActivation = true, Perform online activation
NOTE: In this context the Advanced Provisioning SDK activation Sample must be configured along with the
required parameters:

<PostActivation enabled="true" derivation="true" serverActivation="true" cryptoAppIndex="1" regen-

erate="false" responsePattern="XXXXXX" hostCodePattern="XXXXXX" displaySerialNumber="true" >
Java Sample URL

<URL method="POST" value-
e="http://<ADDRESS>:8080/IdentikeySampleSite/provisioning/dp4mobile/DSAPPactivate.jsp">
ASP.Net Sample URL

e="http://<ADDRESS>/IdentikeySampleSite/provisioning/dp4mobile/DSAPPactivate.aspx">
Required Parameters
<PayloadParameter key="registrationIdentifier" value="%_RegistrationIdentifier_%" />
<PayloadParameter key="initialVector" value="%_InitialVector_%" />
<PayloadParameter key="serverNonce" value="%_Nonce_%" />
<PayloadParameter key="otp" value="%_OTP_%" />
<PayloadParameter key="derivationCode" value="%_DerivationCode_%" />
</URL>
-->
9.1.3.2. Online Post Activation

To perform Post Activation processes without using DSAPP, the following changes must be made:
PostActivation
n enabled = "true"
n derivation = "false"
n serverActivation = "true"
n response Pattern = "XXXXXX" (provide the correct pattern)
Example
Online Post Activation

enabled = true
derivation = false, Generate and activation using OTP
serverActivation = true, Perform online activation
NOTE: In this context the standard Provisioning SDK activation Sample must be configured along with the
required parameters:
<PostActivation enabled="true" derivation="false" serverActivation="true" cryptoAppIndex="1" regen-

ASP.Net Sample URL

e="http://<ADDRESS>/IdentikeySampleSite/provisioning/dp4mobile/activate.aspx">
Java Sample URL

e="http://<ADDRESS>:8080/IdentikeySampleSite/provisioning/dp4mobile/activate.jsp">
Required Parameters
<PayloadParameter key="registrationIdentifier" value="%_RegistrationIdentifier_%" />
<PayloadParameter key="otp" value="%_OTP_%" />
</URL>
-->
9.1.3.3. Offline Post Activation

To perform Post Activation processes offline, the following changes must be made:
PostActivation
n enabled = "true"
n derivation = "true"
n serverActivation = "false"
n responsePattern = "XXXXXX" (provide the correct pattern)

Example
Offline Post Activation
enabled = true
Server activation must be false
<PostActivation enabled="true" derivation="true" serverActivation="false" cryptoAppIndex="1" regen-

9.1.4. Post Configuration
After the DIGIPASS.xml file has been configured to your requirements, it is used as the input to the DIGIPASS for
Mobile midlet customization tool.
Once the midlet has been generated, it must be placed in the correct location for the phone Operating System
type. Use the following directories:
n Default : SDK Installation directory/IdentikeySampleSite/provisioning/dp4mobile/pkg/

n For Java SDK where sample site is deployed under Tomcat installed by IDENTIKEY Authentication
Server:C:\Program Files\VASCO\Tomcat 8.5\webapps\IdentikeySampleSite\provisioning\dp4mobile\pkg\
n For ASP .Net :c:\inetpub\IdentikeySampleSite\provisioning\dp4mobile\pkg\
Place the midlet in the correct folder, according to type:
android/ for Android phones

blackberry/ for BlackBerry
midp/ for Java phone
wm/ for Windows mobile
Note
The provisioning process for iPhones is not the same as the process described above. See the DIGIPASS for
Mobile 4.0 documentation for further details.
9.2. DIGIPASS for Mobile Functions
The following functions can be performed for DIGIPASS for Mobile using the Administration Web Interface. Refer to
the DIGIPASS for Mobile documentation for further explanations.

9.2.1. Bind Device
After a DIGIPASS for Mobile authenticator has been assigned, you can bind it to a particular mobile device.
Procedure 17: Binding a DIGIPASS for Mobile authenticator:
1. Log in to the Administration Web Interface.
2. Navigate to DIGIPASS > List.
3. Select the relevant DIGIPASS for Mobile authenticator.
4. On the DIGIPASS tab, select Bind Device from the Other Actions menu.
5. Type the derivation code generated by the mobile device and click VERIFY.
9.2.2. Unbind Device
Procedure 18: Unbinding a DIGIPASS for Mobile authenticator:
1. Log in to the Administration Web Interface.
2. Navigate to DIGIPASS > List.
3. Select the relevant DIGIPASS for Mobile authenticator.
4. On the DIGIPASS tab, click UNBIND DEVICE or select Unbind Device from the Other Actions menu.
Warning
Because OTPs generated by a DIGIPASS for Mobile authenticator on a device that has been unbound are valid,
authentication issues may occur if the authenticator is bound to a different mobile device. To avoid these issues,
the DIGIPASS for Mobile authenticator needs to be removed from the unbound device.
9.2.3. Generate Activation Data
For an assigned DIGIPASS, select Generate Activation Data from the drop down list. The activation data will be
shown on a new window, with the QR code.
9.2.4. Send Activation Data
To send Activation Data in one of the supported formats, select Send Activation Data from the drop down menu for
assigned DIGIPASS. Select Email, SMS or Voice, and supply the email address of phone number. Click Generate to
send the Activation Data.

9.2.5. Configurable fields
For DIGIPASS for Mobile certain fields are configurable at provisioning time. Use the System > Server Configuration
> Scenarios > Provisioning Scenario tab to configure the Registration Identifier and Activation Password.
9.2.6. DIGIPASS for Mobile Re-Activation
One of the main features of DIGIPASS for Mobile which is used by IDENTIKEY Authentication Server is the re-activ-
ation feature. For IDENTIKEY Authentication Server, re-activation means that after a DIGIPASS for Mobile has
become inactive, it can be re-activated either online or offline.
During reactivation, DIGIPASS which are event- driven have the event counter synchronized with IDENTIKEY
Authentication Server for each application on the DIGIPASS. This enables each application to have the correct event
counter when the DIGIPASS is re-activated.
Online re-activation
To re-activate a DIGIPASS for Mobile online, the user will need to have access to the provisioning web site.
The actions involved in re-activation take place on the mobile phone and on the web site.
Procedure 19: DIGIPASS for Mobile re-activation (online)
1. On the user's mobile phone, navigate to Settings > Reactivate.

2. On the provisioning web site, go to Register and Download. A code will appear on the provisioning web
site which will have to be entered into the user's mobile phone.
3. On the user's mobile phone, enter the following:
n The DIGIPASS for Mobile ID. This is usually the numeric part of the serial number of the DIGIPASS
for Mobile on the user's mobile phone
n The code shown on the provisioning web site
Offline re-activation
A DIGIPASS for Mobile will need to be reactivated offline if the DIGIPASS for Mobile is inactive and the user
does not have access to the provisioning website. For this, the user will need to be able to phone Technical
Support (i.e. an administrator with the proper access rights to the Administration Web Interface) and supply
the following:
n User ID
n DIGIPASS for Mobile serial number

Procedure 20: DIGIPASS for Mobile re-activation (offline)
These instructions should be performed by an administrator with the proper Administration Web Interface priv-
ileges.
1. After being supplied with the user ID and DIGIPASS for Mobile serial number, log in to the Administration
Web Interface.
2. Look up the user's DIGIPASS details.
3. Go to any application tab on the DIGIPASS details and select Generate Activation Data from the drop down
menu. A pop-up window will appear showing Activation Data and the Event Reactivation Counter.
4. Supply the Event Reactivation Counter and the Activation Data to the user. Instruct the user to enter the fol-
lowing on his mobile phone and press Enter:
a. Local Password: This is the PIN the user uses to access the DIGIPASS for Mobile on their phone.
b. Reactivation Password: This is the Event Reactivation Counter from the Administration Web Inter-
face that will have to be read over the phone by the administrator.
c. Activation Data. Either read the activation data to the user, or send it to the phone so the cus-
tomer can enter it into the DIGIPASS for Mobile application.
9.3. DIGIPASS for Mobile 3.5
While IDENTIKEY Authentication Server supports DIGIPASS for Mobile 4.x, you can still use DIGIPASS for Mobile 3.5
DIGIPASS if you have them.
If DIGIPASS for Mobile 3.5 is to be used, the DIGIPASS policies must be updated. Set the Default DIGIPASS Type to
MOB35 in the Administration Web Interface. If both DIGIPASS for Mobile 3.5 and DIGIPASS for Mobile 4.0 are to be
used, separate policies must be created.
To provision DIGIPASS for Mobile 3.5 where DIGIPASS for Mobile 4.0 is also present, you must be able to dif-
ferentiate between the requests. The mobile application is different for each version of DIGIPASS for Mobile and it
must match the assigned DIGIPASS. From your provisioning website use the component name and source of
request to determine which DIGIPASS for Mobile version is required.

10. Error and Status Codes

This section lists the standard IDENTIKEY Authentication Server error and status codes with the associated mes-
sages and some further explanation. These lists only include codes generated specifically by IDENTIKEY Authentic-
ation Server, and may not map to error codes from other sources (e.g. Windows) in trace and audit messages.
10.1. IDENTIKEY Authentication Server Error Codes
Refer to the following tables for information on specific error and status codes.
Table 2: Error Code List

Error Error Message Description Notes
Code
0 STAT_SUCCESS (No error)
-1 STAT_ERROR An unspecified error occurred This error code may occur when a more spe-
cific error code is not available or was recor-
ded separately.
-2 STAT_INVPARAM The parameters supplied were invalid Parameters supplied to a function or com-
mand were invalid.
-3 STAT_MEMORY A memory error occurred Memory allocation failed. This is normally due
to the system running low on memory.
-10 STAT_COMMS A communications error occurred Inter-process or inter-component com-

munication failed. This may also occur with
communications to Active Directory or a data-
base. This error is normally accompanied by
further details.
-11 STAT_LICENCE A license error has occurred General-purpose license failure when a more
specific code is not available or was recorded
separately.
-12 STAT_OS_FAILURE An operating system call failed A system call failed. This may include file
handling, Active Directory Services Interface
and other calls. It is normally accompanied by
further details.
-13 STAT_NOT_FOUND The object was not found An attempt was made to perform an oper-
ation on an object, such as an Active Dir-
ectory object, but the object did not exist. For
example, this may occur when one admin-
istrator deletes a record that another admin-
istrator is about to update, when the update
operation is attempted.

Table 2: Error Code List (continued)

Code
-14 STAT_EXISTS The object already exists An attempt was made to create an object,
such as an Active Directory object, but the
object already exists. For example, this may
occur when two administrators try to create
the same record at the same time.
-15 STAT_OVERFLOW The supplied buffer was of the incor- An internal data buffer was of insufficient
rect size length to hold the data required.
-16 STAT_VERSION A version error has occurred A version mismatch has occurred. Further
details in the error record will indicate which
versions were mismatched.
-17 STAT_INVDATA The supplied data are invalid General-purpose error when input data to an
operation is incorrect. Further details of the
error will be recorded.
-18 STAT_INVOBJECT The object is invalid An attempt was made to perform an oper-
ation upon an object type that was not recog-
nized.
-19 STAT_INVCOMMAND The command is invalid An attempt was made to perform an oper-
ation using a command that was not recog-
nized.
-20 STAT_INUSE The object is in use An attempt was made to delete an object,
such as an Active Directory object, but that
object was in use.
This may occur when you try to delete a

policy, but another policy inherits from the
one you are deleting, or a component uses
the policy.
-21 STAT_NOSUPPORT The operation is not supported General-purpose error when an operation is
attempted on an object that does not support
it. For example, an attempt is made to gen-
erate a Virtual DIGIPASS OTP using a
DIGIPASSthat is not enabled for Virtual
DIGIPASS.
-22 STAT_OBJERR An object error has occurred General-purpose error on an operation on an

object. This should be supplemented with
more specific details.
-23 STAT_MISSINGFLD A required field was missing An operation was attempted without spe-
cifying one or more mandatory input fields.


Code
-24 STAT_AUDITFAILURE Auditing failed An operation failed because auditing was

mandatory, but failed.
-30 STAT_INVCONFIG The configuration is invalid The configuration data in the configuration
file are invalid. The error record should indic-
ate which specific data were invalid.
-31 STAT_INVTYPE A type mismatch has occurred General-purpose error when one data type is
expected but a different data type was
provided.
-32 STAT_NOT_INITIALISED One or more objects were not initialized Internal initialization error. More specific error
details will be recorded.
-33 STAT_CACHE_FULL The cache is full An attempt was made to add an entry to a
cache, but the cache has reached its con-
figured maximum size.
-34 STAT_CACHE_MAX_REF_COUNT The cache entry has reached the max- An attempt was made to retrieve an item
imum reference count from a cache, but the item was already in use
and the configuration indicates a limit on the
number of times an item can be retrieved
from the cache at one time.
-35 STAT_BUSY The system is currently too busy to ser- The system received a new request for pro-
vice the request cessing, but hit a resource usage limit of
some type. This indicates that the system is
too loaded to handle the request. For
example, there may be no spare database
connection to use, even after waiting a short
time for one to become available.
-80 STAT_TIMEOUT A timeout has occurred An operation failed because of a timeout.
-100 VDSERR_INVPLUGIN An invalid plug-in was supplied Audit configuration specifies a plug-in
method that is unknown or that could not be
successfully loaded.
-101 VDSERR_NOSPACE There is no space left to write the mes- While auditing to text file, the server was
sage unable to write. This would normally occur if
disk space has run out.
-102 VDSERR_USERCANCEL User cancelled authentication process The user chose to cancel a request rather
than provide credentials when prompted.


Code
-140 STAT_DPERROR A DIGIPASS error has occurred General-purpose failure of a DIGIPASS oper-
ation such as OTP verification, Reset PIN,
Unlock, etc. This is normally accompanied by
a more specific error code and message from
the IDENTIKEY Authentication Server library.
-141 STAT_MISSING_STATE_DATA Offline state data was required but not

supplied
-142 STAT_IDENT_ERROR_ The threshold for identifying errors has

THRESHOLD_REACHED been reached.
-143 STAT_CHANGE_PIN_MANDATORY An error with the mandatory change of

the DIGIPASS authenticator PIN has
occurred.
-150 STAT_VDP_DELIVERY_FAILED Delivery of the Virtual DIGIPASS one- A Virtual DIGIPASS OTP was generated suc-
time password failed cessfully, but delivery by text message failed.
A separate message will give more details
about the failure.
-200 STAT_LICENCE_EXP The license has expired The license key has an expiration date set,
and the date has passed. A permanent
license key must be obtained.
-201 STAT_INVLICENCE The license data are invalid One of the details embedded into the license
key is invalid for the component in which it is
being loaded. The component will not be able
to use the license key. This may be the IP
address, the component type, or any other
detail that can be seen in the license key text.
-202 STAT_LICENCE_INVSIG The License Key is corrupted The signature at the bottom of the license key
is invalid. This would typically occur if the
license key details were modified in any way.
-250 STAT_NEEDSKEY Decryption has failed - no Storage Key Some encrypted data has been created or
is specified in the Encryption Settings modified using configured, rather than
default, encryption settings. This error
occurs when that data is read by a com-
ponent that does not have configured encryp-
tion settings – the component is therefore
unable to decrypt the data.
It is necessary to configure the encryption set-

tings in the component. For more information
on encryption settings, refer to the Sensitive
Data Encryption chapter in the IDENTIKEY
Authentication Server Administrator Guide .


Code
-251 STAT_WRONG_CIPHER Decryption has failed - an incorrect Some encrypted data has been created or
Cipher is specified in the Encryption modified using differently configured
Settings encryption settings. This error occurs when
that data is read by a component with con-
figured encryption settings that use a dif-
ferent Cipher Name – the component is
therefore unable to decrypt the data.
It is necessary to make sure that the encryp-

tion settings in all components are identical.
For more information on encryption settings,
refer to the Sensitive Data Encryption chapter
in the IDENTIKEY Authentication Server
Administrator Guide.
-252 STAT_DECRYPT_FAILURE Decryption has failed - an incorrect Some encrypted data has been created or
Storage Key is specified in the Encryp- modified using differently configured
tion Settings encryption settings. This error occurs when
that data is read by a component with con-
figured encryption settings that use a dif-
ferent Storage Key – the component is
therefore unable to decrypt the data.
It is necessary to make sure that the encryp-

tion settings in all components are identical.
For more information on encryption settings,
refer to the Sensitive Data Encryption chapter
in the IDENTIKEY Authentication Server
Administrator Guide.
-300 STAT_DB_ERROR A database error occurred General-purpose error on a database oper-

ation. This should be supplemented with
more specific details.
-350 STAT_DISCARD_REQUEST The request received was discarded A replication update that was received was
found to be superseded by a later change. In
this case, the update is discarded, as it is no
longer relevant.
This may occur when creating a record, after

a record has been deleted and then re-cre-
ated.
It may occur when modifying a record, if a

later modification occurred before replication
could apply the first change.


Code
-351 STAT_RETRY_REQUEST The request received must be retried A replication update that was received could
not be applied immediately. In this case, the
update is rejected. The retry mechanism at
the source server will re-send the update,
according to its configuration settings.
This may occur if a record does not exist yet,

when trying to apply a modification or dele-
tion.
It may occur after a record has been deleted

and re-created, when a modification of the
record is replicated but the sequence of dele-
tion and re-creation has not been followed in
the correct order.
-352 STAT_INVHASH A replication queue entry had an invalid When an entry was read from the replication
hash value queue before sending, its integrity hash
value check failed. This suggests that the
queue entry may have been modified since it
was added to the queue. In this case, the
queue entry is not trusted, and an error is
reported.
-353 STAT_REPLQUEUE_FULL The replication queue is full An operation failed because it needed to
update the database, but the update could
not be added to the Replication queue. If the
queue is full, no database updates are
allowed, to avoid the databases from being
pushed too far out of synchronization.
Check the Replication Status dialog in the

Active Directory Users and Computers
Extension and the Replication audit mes-
sages to investigate why the queue has
become full. It is necessary to reduce the
queue size for the system to continue to func-
tion.
If this error occurs often, without good

reason, consider increasing the maximum
queue size. This can be configured in the
Replication tab of the Configuration Utility.
-400 STAT_NOTAVAIL There was no comms descriptor avail- The comms descriptor map has not been
able loaded. (Support)
-401 STAT_ADDR_RESOLVE The supplied address could not be Name resolution problem, i.e.a problem in
resolved the DNS, the netbios etc.


Code
-402 STAT_SOCKET_ERR A socket error occurred. Descriptor Communication protocol mismatch.

should be closed
-403 STAT_DESC_STATE Descriptor was in the wrong state Such a wrong state can for instance be to try
binding the socket twice.
-404 STAT_DESC_LIMIT The maximum number of open

descriptors has been reached
-405 VDSERR_CLOSED The connection has been closed by the

remote end
-406 VDSERR_WOULDBLOCK The command would block, use

'select'
-407 STAT_INPROGRESS The command is in progress, use

'select'
-408 STAT_INV_DESCRIPT The comms descriptor is not valid An invalid comms descriptor can for instance
be that the socket has not been created.
-450 STAT_INVKEY The key received was invalid The encryption key is invalid.
-500 STAT_ALREADY_STARTED The Service was already started When trying to start a service, the service
was already running.
-501 STAT_ALREADY_STOPPED The Service was already stopped When trying to stop a service, the service
was not running.
-550 STAT_MALFORMED_DATA The config file/registry data could not This error may be returned when a corrupt
be read configuration file is used.
-600 STAT_RAD_INVATTRIB One of the RADIUS attributes was the RADIUS attribute field layout is invalid.
invalid
-601 STAT_RAD_SIZE The action will result in a size limitation A buffer overflow would occur, this is only
being exceeded used within the RADIUS library
-602 STAT_RAD_INVDICT An invalid dictionary file was used
-650 STAT_INIT_FAILED Initialization of lock failed
-700 STAT_OPEN_FAILED Failed to open handle Normally occurs when a file cannot be
opened.
-800 VDSERR_BAD_PKT_LENGTH An invalid length was supplied
-801 VDSERR_MALLOC_FAIL Memory allocation failed


Code
-802 VDSERR_BLANK_PASSWORD Password was blank Can occur when attempting to verify a MS-
CHAP/MS-CHAP2 password when the sub-
sequently hashed password provided by the
used is equivalent to hashing a blank string,
i.e. the provided password is blank.
-803 VDSERR_INV_PASSWORD Password was invalid Occurs within MS-CHAP/MS-CHAP2 pass-

word verification when the provided pass-
word is incorrect and it is not a blank string.
-903 STAT_ENCRYPT_TYPE The MPPE encryption policy is not sup-

ported
-904 STAT_BAD_PROTOCOL Invalid MPPE protocol used
-999 STAT_NULL_PTR A null pointer was received
-1001 STAT_UNKNOWN_PKTSOURCE The packet is from an unknown source A client component does not exist for the cli-
ent who sent the packet.
-1002 VDSERR_NOSECRET The shared secret of the packet's There is no shared secret within the client
source is unknown component for the peer which sent this
packet.
-1003 STAT_RAD_BADAUTH Incorrect response authenticator The response packet returned from the
RADIUS server bears an incorrect authen-
ticator.
-1004 STAT_RAD_BADMSGAUTH The Message-Authenticator attribute

was not correct
-1005 STAT_RAD_BADADDRESS The packet is not from the address The response from the back end does not
sent to match the source address to which the
request was sent.
-5300 STAT_ADERROR Active Directory Error
-5301 STAT_INCSCHEMA
-10057 UA_USERID_TOO_LONG User ID is longer than 255 characters. The maximum user ID length has been
exceeded.
-10059 UA_PASSWORD_TOO_LONG Password is longer than 255 char- The maximum password length has been
acters. exceeded.
-10060 UA_UNAME_TOO_LONG User name is longer than 64 char- The maximum user name length has been
acters. exceeded.


Code
-10061 UA_SERIAL_TOO_LONG Serial Number is longer than 10 char- The maximum serial number length has
acters. been exceeded. The serial number must be
10 characters, with no dashes (-) and with
leading zeros (0) to make it up to 10 char-
acters.
-10062 UA_SERIAL_TOO_SHORT Serial Number is less than 10 char- The minimum Serial Number length has not
acters long. been provided. Serial Number must be 10
characters, with no dashes (-) and with lead-
ing zeros (0) to make it up to 10 characters.
-10063 UA_SERIAL_INVALID_CHARS Serial Number contains non-alpha- The Serial Number contains non-alpha-
numeric characters. numeric characters. Serial Number must be
10 alphanumeric characters, with no dashes
(-).
-10064 UA_ORGUNIT_TOO_LONG Organizational unit is longer than 255 The maximum organizational unit length has
characters. been exceeded.
-10065 UA_DOMAIN_TOO_LONG Domain is longer than 255 characters. The maximum domain length has been
exceeded.
-10066 UA_DN_TOO_LONG Distinguished Name is longer than The maximum LDAP Distinguished Name
1024 characters. (DN) length has been exceeded.
-10067 UA_MOBILE_TOO_LONG Mobile Number is longer than 64 char- The maximum length for the mobile phone
acters. number has been exceeded.
-10069 UA_USER_PARSE_ERROR A syntax error occurred reading from A syntax error occurred while reading lines
the file. from the import file: double-quotes were
missing; there are too many fields in the line;
a comma is missing between fields.
-10072 UA_PHONE_TOO_LONG Phone Number is longer than 64 char- The maximum phone number length has
acters. been exceeded.
-10073 UA_EMAIL_TOO_LONG Email Address is longer than 64 char- The maximum length for the e-mail address
acters. has been exceeded.
-10074 UA_INVALID_USER_DETAILS No user ID was given. Either the user A user ID must be supplied to import a user.
ID or, for Active Directory, the Distin- The only exception is when using Active Dir-
guished Name is needed to import a ectory, it is sufficient to give the distinguished
user. name instead of the user ID.
-10075 UA_MOBILE_INVALID_CHARS The Mobile No. is invalid. Only num- The mobile number is only allowed to include
bers, spaces, dashes (-) and brackets numeric characters, spaces, dashes(-) and
are allowed with a + at the start to indic- brackets (){}[]. In addition a + is allowed
ate a country code if needed. at the start for the country code.


Code
-10076 UA_PHONE_INVALID_CHARS The Phone No. is invalid. Only num- The phone number is only allowed to include
bers, spaces, dashes (-) and brackets numeric characters, spaces, dashes(-) and
are allowed with a + at the start to indic- brackets (){}[]. In addition a + is allowed
ate a country code if needed. at the start for the country code.
-10077 UA_EMAIL_INVALID_CHARS The specified email address contains The e-mail address is only allowed to include
invalid characters and is not in the form alphanumeric characters, @, dots (.), under-
user@domain. scores (_) and dashes (-).
-10078 UA_USER_HEADER_ERROR The Field Header was not found or The first line of an import file must be a
invalid when reading from the file. header line. The header line is a comma-sep-
arated list of field names, indicating which
fields are included in every other line of the
file.
This message indicates that the header line

was not found, that it included unknown field
names, or that it was not a comma-separated
list of field names.
See the Import User Records topic in the

online help for the Active Directory Users and
Computers Extension for a definition of the
import file header format.
10.2. Status Codes
Table 3: Status Codes List

Status Status Message Description Notes
Code
0 No error
<all neg- <Error Code> The status codes from -1 downwards match
ative to a corresponding error code.
codes>
1000 STAT_INVCREDENTIALS The credentials were invalid General-purpose failure due to invalid user
name or password, when a more specific
status is unavailable.

Table 3: Status Codes List (continued)

Code
1002 STAT_GROUPCHK The user failed the Windows Group The IDENTIKEY Authentication Server rejec-
Check ted an authentication request due to the Win-
dows Group Check failing. This can occur
when the effective Windows Group Check
option is Authenticate listed groups, reject
others.
Note that the effective setting is the effective

setting of the policy, unless the DIGIPASS
user account overrides the policy.
1004 STAT_EXP_CHALLENGE The challenge has expired A response to challenge has been given, but
the expiration time for the challenge has
expired. The default expiration time is one
minute, however this can be configured in
the configuration file VASCO/Challenge-
Cache/Max-Age setting (in seconds).
1005 STAT_PERMISSION The user does not have permission to General-purpose failure of an administration
perform the specified action command when the administrator does not
have sufficient privileges to carry out the com-
mand.
1006 STAT_LOCALAUTH The DIGIPASS Authentication Library is

not responsible for this authentication
1007 STAT_LOCKED The user account is locked The DIGIPASS user account is locked. This is
normally due to consecutive login failures, as
determined by the policy setting User Lock
Threshold. Alternatively, the administrator
can actively lock the account.
To unlock the user account, an administrator

has to uncheck the Locked check box on the
user record.
1008 STAT_REPLAY The one-time password has already This status code occurs specifically when an
been used OTP is rejected because it has already been
used. It may also occur when the OTP has not
been used but is older than the most recently
used OTP.
This can sometimes happen when an authen-

tication request is re-sent automatically.
1009 STAT_DISABLED The user account is disabled The DIGIPASS user account is disabled. This
may be because the administrator has act-
ively disabled the account, or because the cor-
responding Windows user account has
become disabled or expired.


Code
1010 STAT_USER_UNKNOWN No user account was found An authentication request was rejected
because no DIGIPASS user account was
found and the policy requires local authen-
tication.
1011 STAT_LOCAL_PASSWORD_ The static password was incorrect As part of local authentication, verification of
MISMATCH the static password failed.
1012 STAT_OTP_INCORRECT The one-time password was incorrect Verification of the OTP failed. More specific
details may be found in the VACMAN Con-
troller error code and message.
1013 STAT_CHALLENGE_INVALID The challenge was invalid A response to a challenge was given, but the
challenge was not the latest one issued for
that DIGIPASS. This is controlled by the Check
Challenge Policy setting.
1014 STAT_GRACE_PERIOD_ The DIGIPASS grace period has expired A user attempted to log in with their static
EXPIRED password, but their grace period had already
expired. They have to use a DIGIPASS to log
in.
If they do not have their DIGIPASS yet, the

administrator will have to allow them more
time by modifying the Grace Period End date
on their DIGIPASS record.


Code
1015 STAT_BVDP_NOT_ALLOWED Backup Virtual DIGIPASS is not allowed A user attempted to request a Backup Virtual
DIGIPASS OTP, but they were not permitted.
This would normally occur when either:
n The effective Backup Virtual

DIGIPASS Enabled setting is Yes –
Time Limited, and the DIGIPASS
Backup Virtual DIGIPASS Enabled
Until date is the current date or
before.
n The DIGIPASS Backup Virtual
DIGIPASS Uses Remaining
counter has reached 0.
In both cases, administrator intervention is

required to permit the user to continue to use
Backup Virtual DIGIPASS. The Enabled Until
or Uses Remaining limits need to be
increased to permit this.

record overrides the policy.
1016 STAT_DIGIPASS_NOT_ The DIGIPASS is not available A user attempted Self-Assignment, but the
AVAILABLE DIGIPASS they requested either could not be
found within the search scope or was already
assigned to someone else.
This may occur because of a mistyped Serial

Number. Otherwise, the search scope may
be incorrect, or the DIGIPASS may not be in
the correct location to be made available to the
user. See the DIGIPASS Records Location sec-
tion in the IDENTIKEY Authentication Server
Product Guide.
1017 STAT_INVALID_MDC_ The user account has no mobile number A user requested a Primary or Backup Virtual
SETTINGS / STAT_INVALID_ for Virtual DIGIPASS DIGIPASS OTP, but it could not be delivered
VDP_SETTINGS because the user account had no mobile
phone number. In Active Directory this is the
first mobile number in the record.
1018 STAT_VDP_PASSWORD_ No password was supplied for a Virtual A user attempted a Virtual DIGIPASS login,
MISSING DIGIPASS login but did not enter a password in the second
stage of the login.
1019 STAT_CONFIRM_PASSWORD_ The new password confirmation failed In a password change request, the new pass-
MISMATCH word was not confirmed correctly.


Code
1020 STAT_LOCAL_AUTH_REJECT Local authentication failed General-purpose failure of Local Authentic-

ation when a more specific status code is not
available. Additional information should
provide more specific details.
1021 STAT_BACKEND_PWD_ Back-end authentication reported that Back-End Authentication (e.g. Windows)
EXPIRED the password has expired failed because the password was correct but
it has expired.
1022 STAT_BACKEND_REJECT_ Back-end authentication failed Back-End Authentication (e.g. Windows)

STORED_PASS failed. A specific error code and message will
accompany this record.
1023 STAT_BACKEND_REJECT_ Back-end authentication failed with sup-

SUPPLIED_PASS plied password
1024 STAT_PASSWORD_FAIL_ The static password failed to comply with The following are violations of the password
STRENGTH_CHECK the strength rules of IDENTIKEY strength rules:
Authentication Server. Please check your
policy settings. n Password length is incorrect.
n Password does not contain a suf-
ficient number of unique char-
acters.
n The same password has already
been used (too) recently.
n The password does not comply
with any other of the password
policy requirements.
1025 STAT_DIGIPASS_EXPIRED The DIGIPASS authenticator has expired.
1026 STAT_PASSWORD_EXPIRED The static password for local authen- The user attempted to login but the static
tication in mode DIGIPASSor Password password has expired.
has expired.


Code
1030 STAT_INVALID_POLICY The policy was invalid An authentication request was rejected
because the applicable policy had invalid set-
tings or failed to load. This should not occur,
but is possible due to the delay in Active Dir-
ectory replication for example. The two main
ways in which a policy can become invalid
are:
One or more choice list settings are Default in

the policy, and its parent policy if it has one.
A circular chain of Policies has been created,

for example: Policy A inherits from Policy B;
Policy B inherits from Policy C; Policy C inher-
its from Policy A.
The policy must be fixed for authentication to

be permitted using that policy.
1031 STAT_SELF_ASSIGN_ The policy does not allow a self-assign- A user attempted Self-Assignment, but it is
DISABLED ment attempt not permitted under the policy.
1032 STAT_HASH_PWDS_ Hashed passwords cannot be verified by An authentication request could not be pro-
DISALLOWED Windows cessed successfully because Back-End
Authentication using Windows was
required, but the user's password was
hashed. It is not possible to verify hashed
passwords with Windows. This can occur
when a CHAP-based protocol is used – this
includes CHAP, MS-CHAP, MS-CHAP2, EAP-
MD5 and other more complex protocols that
utilize a one-way hash of the password
entered by the user.
Note that the effective back-end authen-

tication setting is the effective setting of the
policy, unless the DIGIPASS user account
overrides the policy.
1033 STAT_DIGIPASS_MUST_BE_ A DIGIPASS must be used The effective Local Authentication setting is
USED DIGIPASS Only and the user tried to log in
with a static password.



Code
1034 STAT_NO_CHALLRESP_FOR_ Challenge/Response is not supported by Challenge/Response is only supported in

CHAP CHAP-based protocols RADIUS using the PAP protocol. An attempt
was made to generate a challenge using a
CHAP-based protocol – this includes CHAP,
MS-CHAP, MS-CHAP2, EAP-MD5 and other
more complex protocols.
1035 STAT_NO_CHALLRESP_FOR_ Challenge/Response is not supported by This status code can only occur in the
W2K / STAT_NO_CHALLRESP_ Windows 2000 DIGIPASS plug-in for Microsoft Internet
FOR_W_2_K Authentication Service. For Windows 2000 a
product limitation inhibits the support of the
Challenge/Response mode. This will occur if
the user has attempted to request a chal-
lenge.
1036 STAT_1STEP_CR_DISABLED / 1-Step Challenge/Response is disabled A request was made to generate a random
STAT_1_STEP_CR_DISABLED challenge for 1-step Challenge/Response,
but the applicable policy does not have 1-step
Challenge/Response enabled or does not spe-
cify the challenge length and check digit indic-
ator.
1037 STAT_AUTOLEARN_DISABLED Password Autolearn is disabled A request was made to update a user's
stored password, but Password Autolearn is
disabled, so the update is not permitted. Pass-
word Autolearn must be enabled for the pass-
word update request to be processed.
1038 STAT_SOURCE_LOCATION_ The administration session ID is not An administration command has been
MISMATCH known at this location received, but the internal session ID is not
recognized at the location from which the
command came. This can only occur by
attempting to reuse a session ID from another
location.
1039 STAT_ADMIN_SESSION_ The administration session is no longer An administration command has been
STOPPED active received, but the session has stopped or is
unrecognized. This can occur due to an idle
timeout, a maximum session length timeout
or a restart of the IDENTIKEY Authentication
Server.


Code
1040 STAT_NO_CHALLRESP_FOR_ Back-end authentication returned a Chal- This can occur when the IDENTIKEY
PWDPROXY lenge that cannot be handled Authentication Server forwards a request to
a RADIUS Server and the RADIUS Server
responds with an Access-Challenge. An
Access-Challenge can only be handled when
the IDENTIKEY Authentication Server for-
wards the password unmodified to the
RADIUS Server. If the IDENTIKEY Authentic-
ation Server verifies an OTP and forwards
the static password to the RADIUS Server, it is
not possible to handle an Access-Challenge
from the RADIUS Server.
It can also occur if you use RADIUS Back-End

Authentication for a Microsoft IIS Module. In
that case, Access-Challenge is not supported
from the RADIUS Server.
1041 STAT_DIGIPASS_NOT_FOUND No DIGIPASS was found for the given During a Self-Assignment attempt, the serial
Serial Number number provided by the user was not found
in the data store. This mainly occurs when
the serial number is entered incorrectly. It
can also occur because the DIGIPASS record
is not in the user's domain or organizational
unit.
1042 STAT_NO_BACKEND_FOR_ Self-Assignment was attempted but Self-Assignment is not allowed without Back-
SELF_ASSIGN Back-End Authentication did not occur to End Authentication. This is required to val-
authenticate the static password idate the static password.


Code
1050 STAT_REACTIV_NOT_ Reactivation is not allowed A reactivation attempt was refused for one of
ALLOWED the following reasons:
n The DIGIPASS has already been

activated from the maximum num-
ber of allowed locations. This limit
is controlled by the configuration
setting Max Locations of the pro-
visioning scenario.
n The maximum number of allowed
activation attempts has already
been reached. This limit is con-
trolled by the Provisioning Scen-
ario configuration setting Max
Attempts.
n The minimum time interval
required between activation
attempts has not yet been reached
since the last activation attempt.
This limit is controlled by the con-
figuration setting Min Interval of
the provisioning scenario.
1051 STAT_TOO_MANY_DIGIPASS Multiple DIGIPASS found where a single An activation attempt was made where the
DIGIPASS was required user had two or more DIGIPASS that could be
used. The activation request did not specify
which DIGIPASS should be used to handle the
request.
1052 STAT_NO_PROV_ The user account has no static password If no Local Authentication or Back-End
PASSWORD_DEFINED to encrypt the activation code Authentication is done during an activation
request, a static password is required from
the DIGIPASS user account. The password is
used to encrypt the activation code.
1053 STAT_NO_DP_FOR_ASSIGN No DIGIPASS was available for assign- No available DIGIPASS was found for the Pro-
ment visioning Register request. The DIGIPASS
must be capable of activation and meet the
DIGIPASS restrictions in the policy settings if
any.
1054 STAT_GEN_ACTIVATION_ Error generating activation code Generation of an activation code for pro-
CODE visioning failed.
1055 STAT_READING_SVF Error reading SVF data
1060 STAT_SIGNATURE_ The Signature failed validation Verification of the signature failed.
INCORRECT


Code
1061 STAT_SIGNATURE_REPLAY The Signature has already been used This status code occurs specifically when a
signature is rejected because it has already
been used. It may also occur when the sig-
nature has not been used but is older than
the most recently used signature.
This behavior depends on the effective

Online Signature Level Policy setting.
1062 STAT_DP_NOT_HOSTCONF_ A Host/Confirmation Code is required but For an authentication request, a host code
CAPABLE the DIGIPASS Application is not able to was required to be returned. The DIGIPASS
generate it Application for which the OTP was validated
was not capable of generating a host code.
For a signature validation request, a con-

firmation code was required to be returned.
The DIGIPASS Application for which the sig-
nature was validated was not capable of gen-
erating a confirmation code.
The .dpx file that was used to import the

DIGIPASS Application controls whether the
host or confirmation code can be generated.
1070 STAT_CHANGE_ENCRYPTED_ Error while process changed encrypted

PASSWORD static password
1090 STAT_MISSING_BACKEND_ INPUT missing: Back-End Protocol ID The back- end server group is missing a
PROTOCOL back-end protocol ID.
1100 STAT_ERROR_GENERATE_ The DIGIPASS Software Advanced Pro-

REGISTRATION_ID visioning Protocol (DSAPP) server failed
to generate the registration identifier.
1101 STAT_ERROR_GENERATE_ The DIGIPASS Software Advanced Pro-

ACTIVATION_PASSWORD visioning Protocol (DSAPP) server failed
to generate the activation password.
1102 STAT_REGISTERID_NOT_IN_ The matching registration identifier

CACHE could not be found in the provisioning
system cache.
1103 STAT_FAIL_ENCRYPT_ The DIGIPASS Software Advanced Pro-

ACTIVATION_CODE visioning Protocol (DSAPP) server failed
to encrypt the activation data.
1104 STAT_FAIL_VERIFY_SERVER_ The encrypted server nonce received

NONCE from the client could not be validated.


Code
1105 STAT_FAIL_BIND_DEVICE This status code is returned in those

cases:
n The DIGIPASS authenticator is
already bound to a device.
n The device cannot be bound.
n The activation data cannot be
generated.
1107 STAT_FAIL_BIND_DEVICE_ The DIGIPASS authenticatordoes not sup-

NOT_SUPPORTED port device binding.
1108 STAT_NO_APPLICABLE_DP_ No DIGIPASS with the required prop-

FOUND erties could be found.
1120 STAT_NOTIFICATION_ A notification for delayed activation could In addition, an audit message W-009002 is
DELIVERY_FAILED not be sent, because no destination attrib- recorded.
ute is specified in the user account.
1121 STAT_USER_SYNC_FAILED User information attribute syn- In addition, an audit message W-016004 is
chronization failed. recorded.
1122 STAT_BACKEND_ The password does not comply with the The following are violations of the password
PASSWORD_FAIL_ strength rules of the back end. strength rules:
STRENGTH_CHECK
n Password length is incorrect.
n Password does not contain a suf-
ficient number of unique char-
acters.
n The same password has already
been used (too) recently.
n The password does not comply
with any other of the password
policy requirements.
1123 STAT_DATA_RECORD_ Data migration is enabled, but the migra- In addition, an audit message E-013004 is
VERSION_UNSUPPORTED tion subsystem is unable to handle the recorded.
data record. This usually happens if the
record data version is unsupported.
1124 STAT_DATA_RECORD_ Data migration is enabled, but the migra- In addition, an audit message E-013003 is
MIGRATION_FAILED tion subsystem cannot migrate the data recorded.
record. This usually happens if the data
migration failed due to an error.
1126 STAT_CANCEL The server is shutting down and has

sent the request to cancel the operation.


Code
1127 STAT_USER_CANCEL The operation was canceled by the user. When the user cancels the authentication on
the client-side, the relevant authentication
command is failed, and this status code is
returned.
1128 STAT_NEEDS_APPROVAL The operation is pending and awaiting If the respective command has been
approval by an entitled administrator executed the first time, in addition, an audit
(maker–checker authorization). message I-030010 is recorded.
1129 STAT_WRONG_ADMIN An administrator other than the one who In addition, an audit message I-001003 is
scheduled a pending operation request recorded.
attempted to finally execute the approved
pending operation. Only the admin-
istrator who initially created the pending
operation can complete it.
3001 STAT_DP_CHALLENGE A DIGIPASS Challenge was returned This status code is the standard code when a
challenge is issued and does not indicate any
kind of error.
3002 STAT_NO_CHALLENGE No challenge was identified for the A response to a challenge was given, but no
authentication challenge could be found. The most likely
reason for this to occur is that the challenge is
too old and has been removed from the chal-
lenge cache. It can also occur if no challenge
key was supplied with which to look up the
challenge.
3003 STAT_BACKEND_CHALLENGE Back-end authentication returned a Chal- This occurs when a RADIUS Server responds
lenge with an Access-Challenge, in a case where
IDENTIKEY Authentication Server can
handle it.
5001 STAT_NOT_IN_GROUPS The user failed the Windows Group IDENTIKEY Authentication Server decided
Check not to handle an authentication request due
to the Windows Group Check failing. This can
occur when the effective Windows Group
Check option is Pass requests for users not
in listed groups back to host system.



Code
5002 STAT_NO_LOCAL_OR_ Neither local nor back-end authentication IDENTIKEY Authentication Server decided
BACKEND_AUTH was done due to policy and/or user set- not to handle an authentication request
tings because the effective Local Authentication
and Back-End Authentication settings were
both None.
Note that the effective settings are the effect-

ive settings of the policy, unless the DIGIPASS
5003 STAT_DP_EXIST_AS_DIFF_ DIGIPASS exists as different DIGIPASS The DIGIPASS authenticator used exists as a
TYPE type different DIGIPASS type in the system.

IDENTIKEY Authentication Server SDK Programmer's Guide

Uploaded by

Copyright:

Available Formats

IDENTIKEY Authentication Server SDK Programmer's Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

IDENTIKEY Authentication Server SDK Programmer's Guide

Uploaded by

Copyright:

Available Formats

IDENTIKEY Authentication Server

SDK Programmer's Guide

Date last modified: 11/30/2017

1.1. Who should read this guide? 7

1.2. IDENTIKEY Authentication Server Documentation Suite 8

1.4. IDENTIKEY Authentication Server Integration 10

2. Client Integration Overview 12

2.1. Web Service 12

2.2. High-Level API in Java or .NET 12

3.1. System Requirements 15

3.3. SDK Sample Websites 16

4. Client Integration of Authentication Functionality 19

4.1. Authentication Integration Via SOAP API 19

4.2. Response-Only User Authentication Operation 35

4.3. getChallenge User Authentication Operation 38

4.4. Challenge/Response DIGIPASS Authentication Operation 42

4.5. Change Server PIN Operation 47

4.6. Update Static Password Operation 49

4.7. Change Back-End Password Operation 51

4.8. Authentication Using the Secure Channel Operations 52

5. Authentication Back-End Integration 54

5.1. Authentication Engine 54

IDENTIKEY Authentication Server 3.14 – SDK Programmer's Guide iii

5.2. Authentication Engine Definition Via Configuration File 55

5.3. Authentication Engine Definition Via Configuration Utility 56

5.4. Custom Authentication Engine Startup and Shutdown Process 61

6. Client Integration of Signature Validation 63

6.1. Signature Validation Integration Via SOAP API 63

6.2. Real-Time Signature Validation Operation 68

6.3. Deferred-Time Signature Validation Operation 70

6.4. Current Event Signature Validation Operation 71

6.5. Deferred Event Signature Validation Operation 71

6.6. Signature Validation Using the Secure Channel Operations 72

7. Integration of Provisioning Functionality 74

7.1. Provisioning Integration Via SOAP API 74

7.2. Standard Provisioning Operations 80

7.3. Multi-Device Licensing Provisioning Operations 89

8. Client Integration of Administrative Functions 93

8.1. Logon/Logoff Operation Via SOAP API 94

8.2. Execute Operation Via SOAP API 98

8.3. Query Operation Via SOAP API 103

8.4. File Upload/Download Operation Via SOAP API 109

8.5. User Administration Commands Via SOAP API 109

8.6. Other Administration Commands Supported by the SOAP API 111

8.7. Multi-Device Activation Operations 114

9. DIGIPASS for Mobile 117

9.1. DIGIPASS for Mobile 4.0 Configuration 117

9.2. DIGIPASS for Mobile Functions 124

9.3. DIGIPASS for Mobile 3.5 127

IDENTIKEY Authentication Server 3.14 – SDK Programmer's Guide iv

10. Error and Status Codes 128

10.1. IDENTIKEY Authentication Server Error Codes 128

10.2. Status Codes 137

IDENTIKEY Authentication Server 3.14 – SDK Programmer's Guide v

Table 1: SDK integration requirements 16

Table 2: Error Code List 128

Table 3: Status Codes List 137

IDENTIKEY Authentication Server 3.14 – SDK Programmer's Guide vi

1.1. Who should read this guide?

The reader should be familiar with: