DIGIPASS Gateway

Integration Guide

Version: 5.7
Copyright Notice
Copyright © 2012–2023 OneSpan North America, Inc. All rights reserved.

Trademarks
OneSpan™, DIGIPASS® and CRONTO® are registered or unregistered trademarks of OneSpan North America Inc.,
OneSpan NV and/or OneSpan International GmbH (collectively "OneSpan") in the U.S. and other countries.

OneSpan reserves all rights to the trademarks, service marks and logos of OneSpan and its subsidiaries.

All other trademarks or trade names are the property of their respective owners.

Intellectual Property
OneSpan Software, documents and related materials (“Materials”) contain proprietary and confidential information.
All title, rights and interest in OneSpan Software and Materials, updates and upgrades thereof, including software
rights, copyrights, patent rights, industrial design rights, trade secret rights, sui generis database rights, and all other
intellectual and industrial property rights, vest exclusively in OneSpan or its licensors. No OneSpan Software or Mater-
ials 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 OneSpan in writing.

Disclaimer
OneSpan accepts no liability for the accuracy, completeness, or timeliness of content, or for the reliability of links to
and content of external or third party websites.

OneSpan shall have no liability under any circumstances for any loss, damage, or expense incurred by you, your com-
pany, or any third party arising from the use or inability to use OneSpan Software or Materials, or any third party
material made available or downloadable. OneSpan will not be liable in relation to any loss/damage caused by modi-
fication of these Legal Notices or content.

Reservation
OneSpan reserves the right to modify these Notices and the content at any time. OneSpan likewise reserves the right
to withdraw or revoke consent or otherwise prohibit use of the OneSpan Software or Materials if such use does not
conform to the terms of any written agreement between OneSpan and you, or other applicable terms that OneSpan
publishes from time to time.

Contact us
Visit our website: https://www.onespan.com
Resource center: https://www.onespan.com/resource-center
Technical support and knowledge base: https://www.onespan.com/support

If there is no solution in the knowledge base, contact the company that supplied you with the OneSpan product.

Date: 2023-07-09
Contents

1 Introduction 10

1.1 DIGIPASS Gateway documentation suite 11

1.2 About this document 12

2 Integrate DIGIPASS Gateway 13

2.1 Overview 14

3 Provisioning 18

3.1 Online activation 20

3.2 DSAPPActivate (service) 23

3.3 DSAPPGenerateActivationData (service) 25

3.4 DSAPPMdlAddDevice (service) 28

3.5 DSAPPRegister (service) 30

3.6 DSAPPSRPGenerateActivationData (service) [v2] 32

3.7 DSAPPSRPGenerateActivationData (service) [v1] 34

3.8 DSAPPSRPGenerateEphemeralKey (service) [v2] 37

3.9 DSAPPSRPGenerateEphemeralKey (service) [v1] 39

3.10 getServerTime (service) 41

3.11 MdlActivate (service) [v2] 43

3.12 MdlActivate (service) [v1] 45

3.13 MdlAddDevice (service) [v2] 47

3.14 MdlAddDevice (service) [v1] 49

i
DIGIPASS Gateway Integration Guide
 3.15 MdlRegister (service) [v2] 51

3.16 activate (service) 53

3.17 addDevice (service) 55

3.18 bind (service) 57

3.19 instanceActivation (service) 59

3.20 licenseActivation (service) 61

3.21 postActivation (service) 63

3.22 register (service) 65

3.23 registerOffline (service) 67

3.24 registerOnline (service) 69

3.25 signature (service) 71

3.26 synchronize (service) 73

4 Online authentication 75

4.1 Online authentication 76

4.2 authUser (service) 77

4.3 online (service) 79

5 Push and login 81

5.1 Push and login 82

5.2 authUser (service) [v2] 86

5.3 cancelAuthUser (service) [v2] 88

5.4 getPreparedSecureChallenge (service) [v2] 90

5.5 cancelLogin (service) 92

ii
DIGIPASS Gateway Integration Guide
 5.6 retrieveLogin (service) 94

5.7 signLogin (service) 96

6 Push and sign 98

6.1 Push and sign 99

6.2 authSignature (service) 103

6.3 cancelAuthSignatureRequest (service) 106

6.4 getPreparedSignatureRequest (service) 108

7 Notification 110

7.1 Notification registration 111

7.2 sendNotification (service) [v2] 113

7.3 sendNotification (service) [v1] 115

7.4 updateNotificationID (service) [v2] 117

7.5 updateNotificationID (service) [v1] 119

8 Security recommendations 121

8.1 Configuration of SSL/TLS 122

8.2 Restricting source IP address ranges 124

9 Migrating previous versions of DIGIPASS Gateway 125

9.1 Changes in DIGIPASS Gateway 5 126

9.2 Migrating to DIGIPASS Gateway 5 services 130

iii
DIGIPASS Gateway Integration Guide
Glossary 132

Index 135

iv
DIGIPASS Gateway Integration Guide
Figures

Figure 1: Online activation workflow via User Self-Management Website (Overview) 20

Figure 2: Online authentication workflow (Overview) 76

Figure 3: Push and login workflow (Overview) 83

Figure 4: Push and sign workflow (Overview) 100

Figure 5: Notification registration workflow (Overview) 111

v
DIGIPASS Gateway Integration Guide
Tables

Table 1: Requests handled by DIGIPASS Gateway service endpoints (v2) 14

Table 2: Activation image parameters 21

Table 3: DSAPPActivate parameters 23

Table 4: DSAPPActivate return values 24

Table 5: DSAPPGenerateActivationData parameters 25

Table 6: DSAPPGenerateActivationData return values 26

Table 7: DSAPPMdlAddDevice parameters 28

Table 8: DSAPPRegister return values 29

Table 9: DSAPPRegister parameters 30

Table 10: DSAPPRegister return values 31

Table 11: DSAPPSRPGenerateActivationData parameters 32

Table 12: DSAPPSRPGenerateEphemeralKey return values 33

Table 13: DSAPPSRPGenerateActivationData parameters 34

Table 14: DSAPPSRPGenerateActivationData return values 35

Table 15: DSAPPSRPGenerateEphemeralKey parameters 37

Table 16: DSAPPSRPGenerateEphemeralKey return values 38

Table 17: DSAPPSRPGenerateEphemeralKey parameters 39

Table 18: DSAPPSRPGenerateEphemeralKey return values 40

Table 19: getServerTime return values 41

Table 20: MdlActivate parameters 43

Table 21: MdlActivate return values 44

vi
DIGIPASS Gateway Integration Guide
Table 22: MdlActivate parameters 45

Table 23: MdlActivate return values 46

Table 24: MdlAddDevice parameters 47

Table 25: MdlAddDevice return values 48

Table 26: MdlAddDevice parameters 49

Table 27: MdlAddDevice return values 50

Table 28: MdlRegister parameters 51

Table 29: MdlRegister return values 52

Table 30: activate parameters 53

Table 31: addDevice parameters 55

Table 32: addDevice return values 56

Table 33: bind parameters 57

Table 34: bind return values 58

Table 35: instanceActivation parameters 59

Table 36: instanceActivation return values 60

Table 37: licenseActivation parameters 61

Table 38: postActivation parameters 63

Table 39: postActivation return values 64

Table 40: register parameters 65

Table 41: registerOffline parameters 67

Table 42: registerOffline return values 68

Table 43: registerOnline parameters 69

Table 44: signature parameters 71

vii
DIGIPASS Gateway Integration Guide
Table 45: signature return values 72

Table 46: synchronize return values 73

Table 47: authUser parameters 77

Table 48: authUser return values 78

Table 49: online parameters 79

Table 50: online return values 80

Table 51: Push notification content parameters 84

Table 52: Login details parameters 84

Table 53: authUser parameters 86

Table 54: authUser return values 87

Table 55: cancelAuthUser parameters 88

Table 56: cancelAuthUser return values 89

Table 57: getPreparedSecureChallenge parameters 90

Table 58: getPreparedSignatureRequest return values 91

Table 59: cancelLogin parameters 92

Table 60: cancelLogin return values 93

Table 61: retrieveLogin parameters 94

Table 62: retrieveLogin return values 95

Table 63: signLogin parameters 96

Table 64: signLogin return values 97

Table 65: Push notification content parameters 101

Table 66: authSignature parameters 103

Table 67: authSignature return values 104

viii
DIGIPASS Gateway Integration Guide
Table 68: cancelAuthSignatureRequest parameters 106

Table 69: cancelAuthSignatureRequest return values 107

Table 70: getPreparedSignatureRequest parameters 108

Table 71: getPreparedSignatureRequest return values 109

Table 72: sendNotification parameters 113

Table 73: sendNotification return values 114

Table 74: sendNotification parameters 115

Table 75: sendNotification return values 116

Table 76: updateNotificationID parameters 117

Table 77: updateNotificationID return values 118

Table 78: updateNotificationID parameters 119

Table 79: updateNotificationID return values 120

Table 80: DIGIPASS Gateway service mapping (DIGIPASS Gateway 4 vs. 5) 130

ix
DIGIPASS Gateway Integration Guide
Introduction
1

Thank you for reading the DIGIPASS Gateway Integration Guide. This document con-
tains information you will need when integrating DIGIPASS Gateway.

This guide provides information about the requests handled by DIGIPASS Gateway. It
assumes that you have thorough knowledge of either Mobile Authenticator Studio or
OneSpan Mobile Security Suite.

1.1 DIGIPASS Gateway documentation suite 11

1.2 About this document 12

1 Introduction
10
DIGIPASS Gateway Integration Guide
1.1 DIGIPASS Gateway documentation suite
The DIGIPASS Gateway product documentation comprises the following documents:

l DIGIPASS Gateway Getting Started Guide. Provides information required to get

started with DIGIPASS Gateway, such as deploying and configuring it.

l DIGIPASS Gateway Integration Guide. Provides information required when integ-

rating DIGIPASS Gateway with Mobile Authenticator Studio or OneSpan Mobile
Security Suite.

1 Introduction
11
DIGIPASS Gateway Integration Guide
1.2 About this document

1.2.1 How to use this document

You can use this document in different ways, depending on your skill and knowledge
level. You can read it from the beginning to the end (highly recommended for novice
users), you can browse through the chapter abstracts and read specifically the
chapters relevant to your needs, or you can search by key words in the index, if you
need to find certain references quickly.

If you need to do the following Refer to

…activate a mobile application integrating OneSpan 3 Provisioning

Mobile Security Suite

…perform an online authentication with a mobile applic- 4 Online authentication

ation integrating OneSpan Mobile Security Suite

…perform a push and login authentication with a mobile 5 Push and login
application integrating OneSpan Mobile Security Suite

…perform data signing transactions using push noti- 6 Push and sign
fications with a mobile application

…register to receive notifications for a mobile application 7 Notification

integrating OneSpan Mobile Security Suite

…send notifications to a Mobile Authenticator Studio 7 Notification

authenticator assigned to a user

1.2.2 Providing feedback

Every effort has been made to ensure the accuracy and usefulness of this guide.
However, as the reader, you are our most important critic and commentator. We
appreciate your judgment and would like you to write us your opinions, suggestions,
critiques, questions, and ideas. Please send your commentary to: doc-
[email protected].

To recognize the particular guide you are referring to, please include the following
information in your subject header: DPGW-IG-5.7.0en-2023-07-09

Please note that product support is not offered through the above email address.

1 Introduction
12
DIGIPASS Gateway Integration Guide
Integrate DIGIPASS Gateway
2

DIGIPASS Gateway exposes a number of services to mobile applications that integ-

rate OneSpan Mobile Security Suite.

2.1 Overview 14

2 Integrate DIGIPASS Gateway

13
DIGIPASS Gateway Integration Guide
2.1 Overview
DIGIPASS Gateway exposes services to mobile applications via a REST API that uses
JSON (see Table 1). By default, the services are exposed via the following URI:

<dpgateway_host>:<dpgateway_port>/<context_path>/rest/v2/<functionality>↲
/<service>

where:

l <dpgateway_host> is the host running DIGIPASS Gateway.

l <dpgateway_port> is the port of the DIGIPASS Gateway service, by default 11080

(TCP).

l <context_path> is the web application context within your web server. If you install
DIGIPASS Gateway using the installation package, it is deployed as the default
web application (ROOT), hence <context_path> is empty. If you deploy the web
application manually to an existing web server, <context_path> must be specified
respectively in the requests.

l <functionality> is the name of the functionality group, e.g. provisioning.

l <service> is the name of the service endpoint.

Clients need to use the POST method to submit service requests, e.g:

POST https://192.0.2.1:11080/rest/v2/provisioning/getServerTime

Table 1: Requests handled by DIGIPASS Gateway service endpoints (v2)

Request Action Functionality

DSAPPActivate Performs a provisioning activation Online activation

operation using DSAPP (see 3.2
DSAPPActivate (service)).

DSAPPMdlAddDevice Registers a new device that supports Online activation

Secure Channel activation (see 3.4
DSAPPMdlAddDevice (service)).

2 Integrate DIGIPASS Gateway

14
DIGIPASS Gateway Integration Guide
Table 1: Requests handled by DIGIPASS Gateway service endpoints (v2) (continued)

Request Action Functionality

DSAPPRegister Performs a provisioning registration Online activation

operation using DSAPP (see 3.5
DSAPPRegister (service)).

DSAPPSRPGenerateActivationData Retrieves Activation Message 1 Online activation

(license) (see 3.6 DSAPPSRPGen-
erateActivationData (service) [v2]).

DSAPPSRPGenerateEphemeralKey Initializes the activation process by Online activation

exchanging public keys (see 3.8
DSAPPSRPGenerateEphemeralKey
(service) [v2]).

getServerTime Retrieves the current server time as Online activation

Unix time (see 3.10 getServerTime
(service)).

MdlActivate Finalizes the activation process (see Online activation

3.11 MdlActivate (service) [v2]).

MdlAddDevice Retrieves Activation Message 2 Online activation

(instance) (see 3.13 MdlAddDevice
(service) [v2]).

MdlRegister Generates Activation Message 2 for a Online activation

specific user (see 3.15 MdlRegister
(service) [v2]).

authUser Performs an online authentication (see Online authen-

4.2 authUser (service)). tication

authUser Completes a pending push and login Push and login

authentication (see 5.2 authUser (ser-
vice) [v2]).

cancelAuthUser Cancels a pending push and login Push and login

request (see 5.3 cancelAuthUser (ser-
vice) [v2]).

getPreparedSecureChallenge Retrieves a prepared authentication Push and login

request (see 5.4 getPre-
paredSecureChallenge (service) [v2]).

authSignature Completes a pending data signing Push and sign

transaction (see 6.2 authSignature
(service)).

2 Integrate DIGIPASS Gateway

15
DIGIPASS Gateway Integration Guide
 Table 1: Requests handled by DIGIPASS Gateway service endpoints (v2) (continued)

Request Action Functionality

cancelAuthSignatureRequest Cancels a pending data signing trans- Push and sign

action (see 6.3 can-
celAuthSignatureRequest (service)).

getPreparedSignatureRequest Retrieves a prepared signature Push and sign

request for transaction data signing
(see 6.4 getPre-
paredSignatureRequest (service)).

sendNotification Sends a push notification message to Notification

a user (see 7.2 sendNotification (ser-
vice) [v2]).

updateNotificationID Registers a mobile application to Notification

receive notifications (see 7.4
updateNotificationID (service) [v2]).

2.1.1 Authentication
To use the DIGIPASS Gateway services, the mobile application must authenticate
against DIGIPASS Gateway by using basic HTTP authentication. For this purpose, two
separate API keys are generated when setting up DIGIPASS Gateway:

l The front-end API key is required for services typically used by mobile applic-
ations, e.g. OneSpan Mobile Authenticator.

l The back-end API key is required for services typically exposed to the solution's
back-end side, e.g. the banking website.

Which API key is specifically required by each command is specified in the API ref-
erence.

The API key must be used as the user name for authentication. The password field is
ignored and can be left empty.

EXAMPLE: Using an API key of 123456, you need to add the following HTTP header
field to your request:

Authorization: Basic MTIzNDU2Og==

2 Integrate DIGIPASS Gateway

16
DIGIPASS Gateway Integration Guide
 Or using curl:

curl -v -H "Content-Type: application/json" --data {} -u 123456:

192.0.2.1:11080/rest/v2/provisioning/getServerTime

For more information about installing DIGIPASS Gateway, refer to the DIGIPASS Gate-
way Getting Started Guide.

CAUTION: The DIGIPASS Gateway API key is sensitive data and should be properly
protected in the source code of the mobile application. We recommend encrypting it
using the OneSpan White-Box Cryptography (WBC) SDK provided as part of the
OneSpan Mobile Security Suite package.

NOTE: You need the front-end API key when registering for a push notification
account on the OneSpan Customer Portal. Note that the OneSpan Customer Portal
refers to the API key as DP Gateway Password.

2.1.2 API versions

DIGIPASS Gateway provides different API versions. The current is API version 2.

NOTE: API version 1 is deprecated and provided for backward-compatibility reasons

and migration purposes only! Use only API version 2 for new implementations.

2 Integrate DIGIPASS Gateway

17
DIGIPASS Gateway Integration Guide
Provisioning
3

Mobile applications must be activated to enable the Digipass security features (e.g.
push and login). The online activation handles secure provisioning of secret keys
from DIGIPASS Gateway to the mobile application.

3.1 Online activation 20

3.2 DSAPPActivate (service) 23

3.3 DSAPPGenerateActivationData (service) 25

3.4 DSAPPMdlAddDevice (service) 28

3.5 DSAPPRegister (service) 30

3.6 DSAPPSRPGenerateActivationData (service) [v2] 32

3.7 DSAPPSRPGenerateActivationData (service) [v1] 34

3.8 DSAPPSRPGenerateEphemeralKey (service) [v2] 37

3.9 DSAPPSRPGenerateEphemeralKey (service) [v1] 39

3.10 getServerTime (service) 41

3.11 MdlActivate (service) [v2] 43

3.12 MdlActivate (service) [v1] 45

3.13 MdlAddDevice (service) [v2] 47

3 Provisioning
18
DIGIPASS Gateway Integration Guide
3.14 MdlAddDevice (service) [v1] 49

3.15 MdlRegister (service) [v2] 51

3.16 activate (service) 53

3.17 addDevice (service) 55

3.18 bind (service) 57

3.19 instanceActivation (service) 59

3.20 licenseActivation (service) 61

3.21 postActivation (service) 63

3.22 register (service) 65

3.23 registerOffline (service) 67

3.24 registerOnline (service) 69

3.25 signature (service) 71

3.26 synchronize (service) 73

3 Provisioning
19
DIGIPASS Gateway Integration Guide
3.1 Online activation
The mobile application must be activated to enable the Digipass security features (e.g.
push and login). The Online activation handles the secure provisioning of secret keys
from DIGIPASS Gateway to the mobile application.

The user must initiate the online activation process via the User Self-Management
Website. This website generates an image that contains the activation credentials (see
Table 2). To complete the online activation, the user must scan the image with the
mobile application. The online activation requires four network connections to
DIGIPASS Gateway (see Figure 1).

Figure 1: Online activation workflow via User Self-Management Website (Overview)

NOTE: Figure 1 provides a high-level overview of the integration of OneSpan Mobile

Security Suite in the mobile application, and does not show all the required calls to

3 Provisioning
20
DIGIPASS Gateway Integration Guide
 the OneSpan SDKs. Furthermore, it does not display the call by DIGIPASS Gateway
and the User Self-Management Website to OneSpan Authentication Server.

For more information, refer to the OneSpan Mobile Security Suite documentation.

CAUTION: When calling the GenerateSRPSessionKey method of the DSAPP SDK, the
registration identifier must be provided as a parameter for the user identity.

3.1.1 Activation image

The activation image contains the credentials required to perform an online activ-
ation. It is encoded as a plain text string with each parameter separated by a semi-
colon.

Table 2: Activation image parameters

Parameter Description

Version Version of the encoding protocol.

Length: 2 digits

Possible values:
l 01. Current encoding.

Message type The type of message contained in the image.

Length: 2 digits

Possible values:
l 01. Activation image.

User identifier The unique identifier used by OneSpan Authentication Server to

identify a user. It must be stored in the persistent memory.

Length: Up to 255 UTF-8 characters.

Domain The unique identifier used by OneSpan Authentication Server to

identify a group of users. It must be stored in the persistent memory.

Length: Up to 255 UTF-8 characters.

3 Provisioning
21
DIGIPASS Gateway Integration Guide
Table 2: Activation image parameters (continued)

Parameter Description

Registration identifier The unique identifier of a user for a given activation process. It will be
used during the entire activation process.

The length, character set, and casing must be configured in the

OneSpan Authentication Server Provisioning scenario.

User password Data shared between the client and the server to secure the activ-
ation process. It will be used during the activation process.

The length, character set, and casing must be configured in the

OneSpan Authentication Server Provisioning scenario.

DIGIPASS Gateway The unique identifier for DIGIPASS Gateway if the mobile application
identifier uses the OneSpan cloud infrastructure to redirect the network con-
nections to a given instance of DIGIPASS Gateway.

This identifier must be ignored if the mobile application does not use
the OneSpan cloud infrastructure, otherwise it must be stored in the
persistent memory.

Length: 10 hexadecimal characters.

EXAMPLE:
"01;01;myUserID;myDomain;myRegistrationIdentifier;myActivationPassword;123456789A"

3 Provisioning
22
DIGIPASS Gateway Integration Guide
3.2 DSAPPActivate (service)

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The DSAPPActivate service performs a provisioning activation operation using Digipass

Software Advanced Provisioning Protocol (DSAPP).

3.2.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/provisioning/DSAPPActivate

3.2.2 Request
Table 3: DSAPPActivate parameters

Parameter name Data type Description

clientInitialVector String Required. The client initial vector used by the

mobile application using the DSAPP SDK.

derivationCode String Required. The derivation code generated by the

mobile application using the Digipass SDK.

encryptedServerNonce String Required. The encrypted server nonce used by

the mobile application using the DSAPP SDK.

registrationIdentifier String Required. The unique identifier of a user for a

given activation process; returned by
DSAPPRegister.

Example

1 {
2 "registrationIdentifier": "e3wfISG9",
3 "encryptedServerNonce": "E7D63951460ACB3EC08C5AF618FB29D1",
4 "clientInitialVector": "45D8319F02E4B42C5EA067A6A0593B20",
5 "derivationCode": "591107863614246"
6 }

3 Provisioning
23
DIGIPASS Gateway Integration Guide
3.2.3 Response
Table 4: DSAPPActivate return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

result A JSON object that contains the user information.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "result":
10 {
11 "userID": "jane.doe",
12 "domain": "myDomain.com",
13 "serialNumber": "VDS1000003"
14 }
15 }

3 Provisioning
24
DIGIPASS Gateway Integration Guide
3.3 DSAPPGenerateActivationData (service)

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The DSAPPGenerateActivationData service generates an encrypted full activation data

(XFAD) for a standard authenticator or Activation Message 1 for a multi-device licens-
ing (MDL) authenticator.

3.3.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/provisioning
/DSAPPGenerateActivationData

3.3.2 Request
Table 5: DSAPPGenerateActivationData parameters

Parameter name Data type Description

registrationIdentifier String Required. The unique identifier of a user for a

given activation process; returned by
DSAPPRegister.

dsAppVersion Integer Required. The version of the communication pro-

tocol to use.

Possible values: 1, 2

The current version is 2.

initialVector String Required. The initial vector used during the

encryption of the license activation message.

publicKey String Required. The encrypted public key and nonce

generated by the mobile application using the
DSAPP SDK.

3 Provisioning
25
DIGIPASS Gateway Integration Guide
 Example

1 {
2 "dsAppVersion": 2,
3 "registrationIdentifier": "123456789A",
4 "publicKey": "D20AFA7756BD4CBDAF495D8CA4805305...",
5 "initialVector": "07D32029F8FA298E0A354927106F753C"
6 }

3.3.3 Response
Table 6: DSAPPGenerateActivationData return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

serverTimeResult A JSON object that contains the current server time as Unix time.
This is the number of seconds that have elapsed since 00:00:00
Thursday, 1 January 1970, Coordinated Universal Time (UTC). Leap
seconds are not counted.

result A JSON object that contains the generated activation data.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "serverTimeResult":
10 {
11 "serverTime": 1547472526
12 },
13 "result":
14 {
15 "userID": "jane.doe",
16 "domain": "mydomain.com",
17 "serverIV": "99565048F29D69AFFB9BBF7C34386505",

3 Provisioning
26
DIGIPASS Gateway Integration Guide
18 "encryptedNonces": "DA3AAE32102BE4FA95AF1B3D25667B11",
19 "encryptedServerPublicKey": "D9C35501B0B6AF4BDE9CDEED0FC59E6A...",
20 "activationMessage": "DEC85FF288C11DC573BC60B78B16056D...",
21 "activationMessageIV": "20E35B72D523BEE6A10FB0BA3F846795",
22 "eventReactivationCounter": "",
23 }
24 }

3 Provisioning
27
DIGIPASS Gateway Integration Guide
3.4 DSAPPMdlAddDevice (service)

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The DSAPPMdlAddDevice service registers a new device that supports Secure Channel
activation.

3.4.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/provisioning
/DSAPPMdlAddDevice

3.4.2 Request
Table 7: DSAPPMdlAddDevice parameters

Parameter name Data type Description

deviceCode String Required. The device code generated by the

DSAPP SDK.

initialVector String Required. The updated initial vector used by the

mobile application using the DSAPP SDK.

nonce String Required. The updated encrypted server nonce

used by the mobile application using the DSAPP
SDK.

registrationIdentifier String Required. The unique identifier of a user for a

given activation process. It is returned by
DSAPPRegister.

description String Optional. The description of the Digipass instance

being activated.

Up to 255 characters. Special characters are

replaced with spaces.

3 Provisioning
28
DIGIPASS Gateway Integration Guide
 Example

1 {
2 "registrationIdentifier": "e3wfISG9",
3 "nonce": "5B983EE185B954A461CEFEECEBBBF214",
4 "initialVector": "43B525454EFA11CE0F5D1EBFAC5D9127",
5 "deviceCode": "6887133123"
6 "description": "myDigipassInstance"
7 }

3.4.3 Response
Table 8: DSAPPRegister return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

result A JSON object that contains the generated registration activation

data.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "result":
10 {
11 "instanceActivationMessage": "011665337766495347390016546230343861..."
12 }
13 }

3 Provisioning
29
DIGIPASS Gateway Integration Guide
3.5 DSAPPRegister (service)

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the back-end API key.

The DSAPPRegister service performs a provisioning registration operation using Digi-

pass Software Advanced Provisioning Protocol (DSAPP).

3.5.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/provisioning/DSAPPRegister

3.5.2 Request
Table 9: DSAPPRegister parameters

Parameter name Data type Description

domain String Optional. The domain of the user.

dsAppVersion Integer Required. The version of the communication pro-

tocol to use.

Possible values: 1, 2

The current version is 2.

staticPassword String Required. The static password of the user.

userID String Required. The user name.

Example

1 {
2 "dsAppVersion": 2,
3 "userID": "jane.doe",
4 "domain": "mydomain.com",
5 "staticPassword": "myPassword"
6 }

3 Provisioning
30
DIGIPASS Gateway Integration Guide
3.5.3 Response
Table 10: DSAPPRegister return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

result A JSON object that contains the generated registration activation

data.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "result":
10 {
11 "registrationIdentifier": "e3wfISG9",
12 "activationPassword": "Tb048aX1",
13 "credentialsMessage": "88D998CD6B8FE3989CB6E342854DEA4C"
14 }
15 }

3 Provisioning
31
DIGIPASS Gateway Integration Guide
3.6 DSAPPSRPGenerateActivationData (service) [v2]

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The DSAPPSRPGenerateActivationData service generates either standard online activation

data or an Activation Message 1 for multi-device licensing (MDL) and encrypt it using
Digipass Software Advanced Provisioning Protocol-Secure Remote Password (DSAPP-
SRP) session keys.

3.6.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/provisioning
/DSAPPSRPGenerateActivationData

3.6.2 Request
Table 11: DSAPPSRPGenerateActivationData parameters

Parameter name Data type Description

registrationIdentifier String Required. The unique identifier of a user for a

given activation process.

clientEvidenceMessage String Required. The client evidence message gen-

erated by the mobile application using the
DSAPP SDK, for validation purposes.

Example

1 {
2 "registrationIdentifier": "myRegistrationID",
3 "clientEvidenceMessage": "C2ADAF66D93539AD7188555ABC45B886..."
4 }

3 Provisioning
32
DIGIPASS Gateway Integration Guide
3.6.3 Response
Table 12: DSAPPSRPGenerateEphemeralKey return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

result A JSON object containing the generated activation data.

l serverEvidenceMessage. Server evidence message generated by
the server, for validation purposes.

l encryptedLicenseActivationMessage. The license activation mes-

sage (i.e. Activation Message 1) encrypted using the DSAPP
SDK.

l encryptedCounter. The initial vector used during the encryption of

the license activation message.

l mac. The message authentication code (MAC), which will be

used to check the integrity of the encrypted license activation
message.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "result":
10 {
11 "serverEvidenceMessage": "F148FED2B888BFBFB4C9D84BB380B1B2...",
12 "encryptedLicenseActivationMessage": "276FE50E49360E0BAC7AE0CE205...",
13 "encryptedCounter": "73BD6BC4C912DAD3B4F1460FF50268D9",
14 "mac": "15765B12A44DFCE58FAC322FD5BFA979..."
15 }
16 }

3 Provisioning
33
DIGIPASS Gateway Integration Guide
3.7 DSAPPSRPGenerateActivationData (service) [v1]

NOTE: This command is deprecated! Use 3.6 DSAPPSRPGenerateActivationData

(service) [v2] instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: Basic HTTP authentication using the front-end API key.

The DSAPPSRPGenerateActivationData service generates either standard online activation

data or an Activation Message 1 for multi-device licensing (MDL) and encrypt it using
Digipass Software Advanced Provisioning Protocol-Secure Remote Password (DSAPP-
SRP) session keys.

3.7.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/activation
/DSAPPSRPGenerateActivationData

3.7.2 Request
Table 13: DSAPPSRPGenerateActivationData parameters

Parameter name Data type Description

registrationID String Required. The unique identifier of a user for a

given activation process.

clientEvidenceMessage String Required. The client evidence message generated

by the mobile application using the DSAPP SDK,
for validation purposes.

Example

1 {
2 "registrationID": "myRegistrationID",

3 Provisioning
34
DIGIPASS Gateway Integration Guide
 3 "clientEvidenceMessage": "BCD6E385FDE54C9D5C1C7523035C12A6..."
4 }

3.7.3 Response
Table 14: DSAPPSRPGenerateActivationData return values

Return value Data type Description

errorCode Integer The return code provided by OneSpan

Authentication Server. 0 is returned in
case of success.

errorMessage String The error message provided by

OneSpan Authentication Server. STAT_
SUCCESS is returned in case of suc-
cess.

serverEvidenceMessage String This is the server evidence message

that is generated by the server for val-
idation purposes.

encryptedLicenseActivationMessage String The license activation message (i.e.

Activation Message 1) encrypted using
the DSAPP SDK.

encryptedCounter String The initial vector used during the

encryption of the license activation
message.

mac String The message authentication code

(MAC), which will be used to check the
integrity of the encrypted license activ-
ation message.

Example

1 {
2 "errorCode": 0,
3 "errorMessage": "STAT_SUCCESS",
4 "serverEvidenceMessage": "E38CCA22F307A15DB94C3639256975C3...",
5 "encryptedLicenseActivationMessage": "DBBD11F7F779D2619DEBFD14F98658...",
6 "encryptedCounter": "0FC645CEF184D753",
7 "mac": "F3142357A58534F8A37C7C8F243CE354..."

3 Provisioning
35
DIGIPASS Gateway Integration Guide
8 }

3 Provisioning
36
DIGIPASS Gateway Integration Guide
3.8 DSAPPSRPGenerateEphemeralKey (service) [v2]

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The DSAPPSRPGenerateEphemeralKey service initializes the activation process by exchan-

ging public keys. It performs a provisioning ephemeral key generation using Digipass
Software Advanced Provisioning Protocol-Secure Remote Password (DSAPP-SRP).

3.8.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/provisioning
/DSAPPSRPGenerateEphemeralKey

3.8.2 Request
Table 15: DSAPPSRPGenerateEphemeralKey parameters

Parameter name Data type Description

registrationIdentifier String Required. The unique identifier of a user for a

given activation process.

clientEphemeralPublicKey String Required. The client ephemeral public key gen-

erated by the mobile application with the
DSAPP SDK.

Example

1 {
2 "registrationIdentifier": "myRegistrationID",
3 "clientEphemeralPublicKey": "0BB2EA6580A127320F3C6341CEF75367..."
4 }

3 Provisioning
37
DIGIPASS Gateway Integration Guide
3.8.3 Response
Table 16: DSAPPSRPGenerateEphemeralKey return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

result A JSON object that contains the ephemeral public key and the salt.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "result":
10 {
11 "serverEphemeralPublicKey": "661CF5095BA2C5C0679B7BCEB516BADE...",
12 "salt": "8F1958E25B9749FDBC28362CEED92C01"
13 }
14 }

3 Provisioning
38
DIGIPASS Gateway Integration Guide
3.9 DSAPPSRPGenerateEphemeralKey (service) [v1]

NOTE: This command is deprecated! Use 3.8 DSAPPSRPGenerateEphemeralKey

(service) [v2] instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: Basic HTTP authentication using the front-end API key.

The DSAPPSRPGenerateEphemeralKey service initializes the activation process by exchan-

ging public keys. It performs a provisioning ephemeral key generation using Digipass
Software Advanced Provisioning Protocol-Secure Remote Password (DSAPP-SRP).

3.9.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/activation
/DSAPPSRPGenerateEphemeralKey

3.9.2 Request
Table 17: DSAPPSRPGenerateEphemeralKey parameters

Parameter name Data type Description

registrationID String Required. The unique identifier of a user for a

given activation process.

clientEphemeralPublicKey String Required. The client ephemeral public key gen-

erated by the mobile application with the
DSAPP SDK.

Example

1 {
2 "registrationID": "myRegistrationID",
3 "clientEphemeralPublicKey": "589C8CC389883455EC0D2B484892974E..."

3 Provisioning
39
DIGIPASS Gateway Integration Guide
 4 }

3.9.3 Response
Table 18: DSAPPSRPGenerateEphemeralKey return values

Return value Data type Description

errorCode Integer The return code provided by OneSpan

Authentication Server. 0 is returned in case of
success.

errorMessage String The error message provided by OneSpan

Authentication Server. STAT_SUCCESS is
returned in case of success.

serverEphemeralPublicKey String The server ephemeral public key generated by

the server.

salt String The random salt value generated by the server.

Example

1 {
2 "errorCode": 0,
3 "errorMessage": "STAT_SUCCESS",
4 "serverEphemeralPublicKey": "C29DE535E89B04A1E17E984B9FF77458...",
5 "salt": "A23C9C3B2B8B734EBEF0EA1895F9E355"
6 }

3 Provisioning
40
DIGIPASS Gateway Integration Guide
3.10 getServerTime (service)

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The getServerTime service retrieves the current server time as Unix time to be used in
activation and re-activation of Mobile Authenticator Studio.

The server time returned used the Unix time format (POSIX time or UNIX Epoch time),
i.e. the number of seconds that have elapsed since 00:00:00 Thursday, 1 January 1970,
Coordinated Universal Time (UTC), not counting leap seconds.

3.10.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/provisioning/getServerTime

3.10.2 Request
The getServerTime service does not accept any parameters.

3.10.3 Response
Table 19: getServerTime return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

result A JSON object that contains the current server time as Unix time.
This is the number of seconds that have elapsed since 00:00:00
Thursday, 1 January 1970, Coordinated Universal Time (UTC). Leap
seconds are not counted.

3 Provisioning
41
DIGIPASS Gateway Integration Guide
Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "result":
10 {
11 "serverTime": 1547556827
12 }
13 }

3 Provisioning
42
DIGIPASS Gateway Integration Guide
3.11 MdlActivate (service) [v2]

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: The service is secured by the back-end and front-end API key.

The MdlActivate service validates the confirmation code generated by the authen-
ticator and finalizes the activation process.

3.11.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/provisioning/MdlActivate

3.11.2 Request
Table 20: MdlActivate parameters

Parameter name Data type Description

registrationIdentifier String Required. The unique identifier of a user for a

given activation process.

signature String Required. The signature generated by the mobile

application using the Digipass SDK. This is
needed for validation purposes.

Example

1 {
2 "registrationIdentifier": "myRegistrationID",
3 "signature": "1234567890123456"
4 }

3 Provisioning
43
DIGIPASS Gateway Integration Guide
3.11.3 Response
Table 21: MdlActivate return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

result A JSON object that contains the user information.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "result":
10 {
11 "userID": "jane.doe",
12 "domain": "myDomain.com",
13 "serialNumber": "VDS1000003"
14 }
15 }

3 Provisioning
44
DIGIPASS Gateway Integration Guide
3.12 MdlActivate (service) [v1]

NOTE: This command is deprecated! Use 3.11 MdlActivate (service) [v2] instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: Basic HTTP authentication using the front-end API key.

The MdlActivate service validates the confirmation code generated by the authen-
ticator and finalizes the activation process.

3.12.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/activation/MdlActivate

3.12.2 Request
Table 22: MdlActivate parameters

Parameter name Data type Description

registrationID String Required. The unique identifier of a user for a

given activation process.

signature String Required. The signature generated by the mobile

application using the Digipass SDK. This is needed
for validation purposes.

Example

1 {
2 "registrationID": "myRegistrationID",
3 "signature": "1234567890123456"
4 }

3 Provisioning
45
DIGIPASS Gateway Integration Guide
3.12.3 Response
Table 23: MdlActivate return values

Return value Data type Description

errorCode Integer The return code provided by OneSpan Authentic-

ation Server. 0 is returned in case of success.

errorMessage String The error message provided by OneSpan

Authentication Server. STAT_SUCCESS is returned
in case of success.

Example

1 {
2 "errorCode": 0,
3 "errorMessage": "STAT_SUCCESS"
4 }

3 Provisioning
46
DIGIPASS Gateway Integration Guide
3.13 MdlAddDevice (service) [v2]

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: The service is secured by the back-end and front-end API key.

The MdlAddDevice service registers a new device that supports Secure Channel activ-
ation. It retrieves Activation Message 2 (instance).

3.13.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/provisioning/MdlAddDevice

3.13.2 Request
Table 24: MdlAddDevice parameters

Parameter name Data type Description

registrationIdentifier String Required. The unique identifier of a user for a

given activation process.

deviceCode String Required. The device code generated by the

mobile application using the Digipass SDK. This is
needed for validation and derivation purposes.

description String Optional. The description of the Digipass instance

being activated.

Up to 255 characters. Special characters are

replaced with spaces.

Example

1 {
2 "registrationIdentifier": "myRegistrationID",
3 "deviceCode": "12345678901234567890123456"
4 "description": "myDigipassInstance"
5 }

3 Provisioning
47
DIGIPASS Gateway Integration Guide
3.13.3 Response
Table 25: MdlAddDevice return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

result A JSON object that contains the instance activation message (i.e.
Activation Message 2).

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "result":
10 {
11 "instanceActivationMessage": "AA82DD554C7A39356FC033203A9F7EB6...",
12 }
13 }

3 Provisioning
48
DIGIPASS Gateway Integration Guide
3.14 MdlAddDevice (service) [v1]

NOTE: This command is deprecated! Use 3.13 MdlAddDevice (service) [v2] instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: Basic HTTP authentication using the front-end API key.

The MdlAddDevice registers a new device that supports Secure Channel activation. It
retrieves Activation Message 2 (instance).

3.14.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/activation/MdlAddDevice

3.14.2 Request
Table 26: MdlAddDevice parameters

Parameter name Data type Description

registrationID String Required. The unique identifier of a user for a

given activation process.

deviceCode String Required. The device code generated by the

mobile application using the Digipass SDK. This is
needed for validation and derivation purposes.

Example

1 {
2 "registrationID": "myRegistrationID",
3 "deviceCode": "12345678901234567890123456"
4 }

3 Provisioning
49
DIGIPASS Gateway Integration Guide
3.14.3 Response
Table 27: MdlAddDevice return values

Return value Data type Description

errorCode Integer The return code provided by OneSpan

Authentication Server. 0 is returned in case of
success.

errorMessage String The error message provided by OneSpan

Authentication Server. STAT_SUCCESS is
returned in case of success.

instanceActivationMessage String The instance activation message (i.e. Activ-

ation Message 2).

Example

1 {
2 "errorCode": 0,
3 "errorMessage": "STAT_SUCCESS",
4 "instanceActivationMessage": "82A53BF7E525012E2488BA51E9E33655..."
5 }

3 Provisioning
50
DIGIPASS Gateway Integration Guide
3.15 MdlRegister (service) [v2]

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the back-end API key.

The MdlRegister service performs a provisioning registration operation by generating

Activation Message 1 for a specific user.

3.15.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/provisioning/MdlRegister

3.15.2 Request
Table 28: MdlRegister parameters

Parameter name Data type Description

domain String Optional. The user domain.

password String Required. The static password of the user.

userID String Required. The user name.

Example

1 {
2 "userID": "jane.doe",
3 "domain": "mydomain.com",
4 "password": "myPassword"
5 }

3 Provisioning
51
DIGIPASS Gateway Integration Guide
3.15.3 Response
Table 29: MdlRegister return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

result A JSON object that contains the generated registration activation

data.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "result":
10 {
11 "registrationIdentifier": "e3wfISG9",
12 "activationMessageImage": "BBED4D1C617F42C8D496B36F0137AE5E..."
13 }
14 }

3 Provisioning
52
DIGIPASS Gateway Integration Guide
3.16 activate (service)

NOTE: This command is deprecated! Use 3.3 DSAPPGenerateActivationData (ser-

vice) instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: None.

The activate service generates an encrypted full activation data (XFAD) for a standard
authenticator or Activation Message 1 for a multi-device licensing (MDL) authenticator
using Digipass Software Advanced Provisioning Protocol (DSAPP) Version 1.

3.16.1 URL

https://<dpgateway_host>:<dpgateway_port>/activate

3.16.2 Request
Parameters to the service are passed via the URI query component.

Table 30: activate parameters

Parameter name Data type Description

RegistrationIdentifier String Required. The unique identifier of a user for a

given activation process. It is returned by
DSAPPRegister.

InitialVector String Required. The initial vector used during the

encryption of the license activation message.

PublicKey String Required. The encrypted public key and nonce

generated by the mobile application using the
DSAPP SDK.

3 Provisioning
53
DIGIPASS Gateway Integration Guide
 Example

POST
https://192.0.2.1:11080/activate?RegistrationIdentifier=123456789A&PublicKey=D20
AFA7756BD4CBDAF495D8CA4805305D20AFA7756BD4CBDAF495D8CA4805305D20AFA7756BD4CBDAF4
95D8CA4805305D20AFA7756BD4CBDAF495D8CA4805305&InitialVector=07D32029F8FA298E0A35
4927106F753C

3.16.3 Response
The service returns an XML response message containing the result.

Example

1 <?xml version="1.0"?>
2 <DP4Mobile retCode="0" serverTime="1547472526">
3 <Activation
4 xfad="DEC85FF288C11DC573BC60B78B16056D..."
5 xerc="DA3AAE32102BE4FA95AF1B3D25667B11"
6 initialVector="20E35B72D523BEE6A10FB0BA3F846795"
7 serverPublicKey="D9C35501B0B6AF4BDE9CDEED0FC59E6A..."
8 nonces="99565048F29D69AFFB9BBF7C34386505"
9 userId="[email protected]" />
10 </DP4Mobile>

3 Provisioning
54
DIGIPASS Gateway Integration Guide
3.17 addDevice (service)

NOTE: This command is deprecated! Use 3.13 MdlAddDevice (service) [v2] instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: None.

The addDevice service registers a new device that supports Secure Channel activation.
It retrieves Activation Message 2 (instance).

3.17.1 URL

https://<dpgateway_host>:<dpgateway_port>/addDevice

3.17.2 Request
Parameters to the service are passed via the URI query component.

Table 31: addDevice parameters

Parameter name Data type Description

registrationID String Required. The unique identifier of a user for a

given activation process.

deviceCode String Required. The device code generated by the

mobile application using the Digipass SDK. This is
needed for validation and derivation purposes.

Example

POST
https://192.0.2.1:11080/addDevice?registrationID=vxcJRl7O&deviceCode=1234567890

3 Provisioning
55
DIGIPASS Gateway Integration Guide
3.17.3 Response
Table 32: addDevice return values

Return value Description

message A JSON value that contains the status message in case of an

error.

returnCode The return code provided by OneSpan Authentication Server. 0

is returned in case of success.

instanceActivationMessage The instance activation message (i.e. Activation Message 2).

Example

1 {
2 "returnCode": 0,
3 "instanceActivationMessage": "AA82DD554C7A39356FC033203A9F7EB6..."
4 }

3 Provisioning
56
DIGIPASS Gateway Integration Guide
3.18 bind (service)

NOTE: This command is deprecated! Use 3.2 DSAPPActivate (service) instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: None.

The bind service performs a provisioning activation operation using Digipass Software
Advanced Provisioning Protocol (DSAPP).

3.18.1 URL

https://<dpgateway_host>:<dpgateway_port>/bind

3.18.2 Request
Parameters to the service are passed via the URI query component.

Table 33: bind parameters

Parameter name Data type Description

DerivationCode String Required. The derivation code generated by the

mobile application using the Digipass SDK.

InitialVector String Required. The client initial vector used by the

mobile application using the DSAPP SDK.

Nonce String Required. The encrypted server nonce used by

the mobile application using the DSAPP SDK.

RegistrationIdentifier String Required. The unique identifier of a user for a

given activation process. This is returned by
DSAPPRegister.

3 Provisioning
57
DIGIPASS Gateway Integration Guide
 Example

POST
https://192.0.2.1:11080/bind?RegistrationIdentifier=e3wfISG9&Nonce=E7D63951460AC
B3EC08C5AF618FB29D1&InitialVector=45D8319F02E4B42C5EA067A6A0593B20&DerivationCod
e=591107863614246

3.18.3 Response
The service returns an XML response message containing the result.

Table 34: bind return values

Return value Description

//DP4Mobile/@message The error message in case of an error.

//DP4Mobile/@retCode The return code of the operation.

Example (Success)

1 <?xml version="1.0"?>
2 <DP4Mobile retCode="0" />

Example (Failure)

1 <?xml version="1.0"?>
2 <DP4Mobile retCode="–1" message="The Registration Identifier could not be found
in the cache." />

3 Provisioning
58
DIGIPASS Gateway Integration Guide
3.19 instanceActivation (service)

NOTE: This command is deprecated! Use 3.4 DSAPPMdlAddDevice (service)

instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: None.

The instanceActivation registers a new device that supports Secure Channel activation.
It retrieves Activation Message 2 (instance).

3.19.1 URL

https://<dpgateway_host>:<dpgateway_port>/instanceActivation

3.19.2 Request
Parameters to the service are passed via the URI query component.

Table 35: instanceActivation parameters

Parameter name Data type Description

DeviceCode String Required. The device code generated by the

mobile application using the Digipass SDK. This is
needed for validation and derivation purposes.

InitialVector String Required. The updated initial vector used by the

mobile application using the DSAPP SDK.

Nonce String Required. The updated encrypted server nonce

used by the mobile application using the DSAPP
SDK.

RegistrationIdentifier String Required. The unique identifier of a user for a

given activation process.

3 Provisioning
59
DIGIPASS Gateway Integration Guide
 Example

POST
https://192.0.2.1:11080/instanceActivation?RegistrationIdentifier=e3wfISG9&Devic
eCode=6887133123&InitialVector=43B525454EFA11CE0F5D1EBFAC5D9127&Nonce=5B983EE185
B954A461CEFEECEBBBF214

3.19.3 Response
The service returns an XML response message containing the result.

Table 36: instanceActivation return values

Return value Data type Description

//DP4Mobile/@retCode Integer The return code of the operation.

//DP4Mobile/@message String The error message in case of an error.

//InstanceActivation/ String The instance activation message (i.e. Activ-

@instanceActivationMessage ation Message 2).

Example

1 <?xml version="1.0"?>
2
3 <DP4Mobile retCode="0">
4 <InstanceActivation
instanceActivationMessage="82A53BF7E525012E2488BA51E9E33655..." />
5 </DP4Mobile>

3 Provisioning
60
DIGIPASS Gateway Integration Guide
3.20 licenseActivation (service)

NOTE: This command is deprecated! Use 3.3 DSAPPGenerateActivationData (ser-

vice) instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: None.

The licenseActivation service generates an encrypted full activation data (XFAD) for a
standard authenticator or Activation Message 1 for a multi-device licensing (MDL)
authenticator using Digipass Software Advanced Provisioning Protocol (DSAPP) Ver-
sion 2.

3.20.1 URL

https://<dpgateway_host>:<dpgateway_port>/licenseActivation

3.20.2 Request
Parameters to the service are passed via the URI query component.

Table 37: licenseActivation parameters

Parameter name Data type Description

RegistrationIdentifier String Required. The unique identifier of a user for a

given activation process. It is returned by
DSAPPRegister.

InitialVector String Required. The initial vector used during the

encryption of the license activation message.

PublicKey String Required. The encrypted public key and nonce

generated by the mobile application using the
DSAPP SDK.

3 Provisioning
61
DIGIPASS Gateway Integration Guide
 Example

POST
https://192.0.2.1:11080/licenseActivation?RegistrationIdentifier=123456789A&Publ
icKey=D20AFA7756BD4CBDAF495D8CA4805305D20AFA7756BD4CBDAF495D8CA4805305D20AFA7756
BD4CBDAF495D8CA4805305D20AFA7756BD4CBDAF495D8CA4805305&InitialVector=07D32029F8F
A298E0A354927106F753C

3.20.3 Response
The service returns an XML response message containing the result.

Example

1 <?xml version="1.0"?>
2 <DP4Mobile retCode="0" serverTime="1547472526">
3 <LicenseActivation
4 encryptedLicenseActivationMessage="DEC85FF288C11DC573BC60B78B16056D..."
5 encryptedNonces="DA3AAE32102BE4FA95AF1B3D25667B11"
6 licenseActivationMessageIV="20E35B72D523BEE6A10FB0BA3F846795"
7 encryptedServerPublicKey="D9C35501B0B6AF4BDE9CDEED0FC59E6A..."
8 generateSessionKeyIV="99565048F29D69AFFB9BBF7C34386505"
9 userId="[email protected]" />
10 </DP4Mobile>

3 Provisioning
62
DIGIPASS Gateway Integration Guide
3.21 postActivation (service)

NOTE: This command is deprecated! Use 3.11 MdlActivate (service) [v2] instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: None.

The postActivation service validates the confirmation code generated by the authen-
ticator and finalizes the activation process.

3.21.1 URL

https://<dpgateway_host>:<dpgateway_port>/postActivation

3.21.2 Request
Parameters to the service are passed via the URI query component.

Table 38: postActivation parameters

Parameter name Data type Description

RegistrationIdentifier String Required. The unique identifier of a user for a

given activation process.

OTP String Required. The signature generated by the mobile

application using the Digipass SDK. This is
needed for validation purposes.

Example

POST
https://192.0.2.1:11080/postActivation?RegistrationIdentifier=cTlAXXq7&OTP=12345
6

3 Provisioning
63
DIGIPASS Gateway Integration Guide
3.21.3 Response
The service returns an XML response message containing the result.

Table 39: postActivation return values

Return value Description

//DP4Mobile/@message The status message.

//DP4Mobile/@retCode The return code of the operation.

Example (Success)

1 <?xml version="1.0"?>
2 <DP4Mobile retCode="0" message="" />

Example (Failure)

1 <?xml version="1.0"?>
2 <DP4Mobile retCode="–1" message="The Registration Identifier could not be found
in the cache." />

3 Provisioning
64
DIGIPASS Gateway Integration Guide
3.22 register (service)

NOTE: This command is deprecated! Use 3.5 DSAPPRegister (service) instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: None.

The register service performs a provisioning registration operation using Digipass Soft-
ware Advanced Provisioning Protocol (DSAPP) Version 1.

3.22.1 URL

https://<dpgateway_host>:<dpgateway_port>/register

3.22.2 Request
Parameters to the service are passed via the URI query component.

Table 40: register parameters

Parameter name Data type Description

StaticPassword String Required. The static password of the user.

UserID String Required. The user name and domain (RFC5322),

i.e. <username>@<domain>.

Example

POST
https://192.0.2.1:11080/[email protected]&StaticPassword=myP
assword

3.22.3 Response
The service returns an XML response message containing the result.

3 Provisioning
65
DIGIPASS Gateway Integration Guide
Example (Success)

1 <?xml version="1.0"?>
2 <DP4Mobile retCode="0"
3 registrationIdentifier="e3wfISG9"
4 activationPassword="Tb048aX1"
5 credentialsMessage="88D998CD6B8FE3989CB6E342854DEA4C" />

Example (Failure)

1 <?xml version="1.0"?>
2 <DP4Mobile retCode="–2" message="The static password was incorrect" />

3 Provisioning
66
DIGIPASS Gateway Integration Guide
3.23 registerOffline (service)

NOTE: This command is deprecated! Use 3.15 MdlRegister (service) [v2] instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: None.

The registerOffline service performs a provisioning registration operation by gen-

erating Activation Message 1 for a specific user.

3.23.1 URL

https://<dpgateway_host>:<dpgateway_port>/registerOffline

3.23.2 Request
Parameters to the service are passed via the URI query component.

Table 41: registerOffline parameters

Parameter name Data type Description

email String Required. The email address of the user.

password String Required. The static password of the user.

Example

POST
https://192.0.2.1:11080/[email protected]&password=myP
assword

3.23.3 Response
The service returns an XML response message containing the result.

3 Provisioning
67
DIGIPASS Gateway Integration Guide
Table 42: registerOffline return values

Return value Description

//DIGIPASSGateway/@crontoImage The generated registration activation data.

//DIGIPASSGateway/@message The status message.

//DIGIPASSGateway/@registrationID The unique identifier of a user for a given activation pro-

cess.

//DIGIPASSGateway/@retCode The return code of the operation.

Example

1 <?xml version="1.0"?>
2 <DIGIPASSGateway retCode="0" message="Success"
3 registrationID="e3wfISG9"
4 crontoImage="BBED4D1C617F42C8D496B36F0137AE5E..." />

3 Provisioning
68
DIGIPASS Gateway Integration Guide
3.24 registerOnline (service)

NOTE: This command is deprecated! Use 3.5 DSAPPRegister (service) instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: None.

The registerOnline service performs a provisioning registration operation using Digi-

pass Software Advanced Provisioning Protocol (DSAPP) Version 2.

3.24.1 URL

https://<dpgateway_host>:<dpgateway_port>/registerOnline

3.24.2 Request
Parameters to the service are passed via the URI query component.

Table 43: registerOnline parameters

Parameter name Data type Description

StaticPassword String Required. The static password of the user.

UserID String Required. The user name and domain (RFC5322),

i.e. <username>@<domain>.

Example

POST
https://192.0.2.1:11080/[email protected]&StaticPasswo
rd=myPassword

3.24.3 Response
The service returns an XML response message containing the result.

3 Provisioning
69
DIGIPASS Gateway Integration Guide
Example (Success)

1 <?xml version="1.0"?>
2 <DP4Mobile retCode="0" registrationIdentifier="e3wfISG9"
3 activationPassword="Tb048aX1"
4 credentialsMessage="88D998CD6B8FE3989CB6E342854DEA4C" />

Example (Failure)

1 <?xml version="1.0"?>
2 <DP4Mobile retCode="–2" message="The static password was incorrect" />

3 Provisioning
70
DIGIPASS Gateway Integration Guide
3.25 signature (service)

NOTE: This command is deprecated! Use 3.11 MdlActivate (service) [v2] instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: None.

The signature service validates the confirmation code generated by the authenticator
and finalizes the activation process.

3.25.1 URL

https://<dpgateway_host>:<dpgateway_port>/signature

3.25.2 Request
Parameters to the service are passed via the URI query component.

Table 44: signature parameters

Parameter name Data type Description

registrationID String Required. The unique identifier of a user for a

given activation process.

signature String Required. The signature generated by the mobile

application using the Digipass SDK. This is needed
for validation purposes.

Example

POST https://192.0.2.1:11080/signature?registrationID=GtNr4OTi&signature=123456

3 Provisioning
71
DIGIPASS Gateway Integration Guide
3.25.3 Response
Table 45: signature return values

Return value Data type Description

returnCode Integer The return code provided by OneSpan Authentic-

ation Server. 0 is returned in case of success.

message String A JSON value that contains the status message in

case of an error.

Example

{
"returnCode": 0
}

3 Provisioning
72
DIGIPASS Gateway Integration Guide
3.26 synchronize (service)

NOTE: This command is deprecated! Use 3.10 getServerTime (service) instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: None.

The getServerTime service retrieves the current server time as Unix time to be used in
activation and re-activation of Mobile Authenticator Studio.

The server time returned used the Unix time format (POSIX time or UNIX Epoch time),
i.e. the number of seconds that have elapsed since 00:00:00 Thursday, 1 January 1970,
Coordinated Universal Time (UTC), not counting leap seconds.

3.26.1 URL

https://<dpgateway_host>:<dpgateway_port>/synchronize

3.26.2 Request
The synchronize service does not accept any parameters.

3.26.3 Response
The service returns an XML response message containing the result.

Table 46: synchronize return values

Return value Description

//DP4Mobile/@serverTime A JSON object that contains the current server time as Unix time.
This is the number of seconds that have elapsed since 00:00:00
Thursday, 1 January 1970, Coordinated Universal Time (UTC). Leap
seconds are not counted.

3 Provisioning
73
DIGIPASS Gateway Integration Guide
Example

1 <?xml version="1.0"?>
2 <DP4Mobile serverTime="1547556827" />

3 Provisioning
74
DIGIPASS Gateway Integration Guide
Online authentication
4

Online authentication can be used when changing a password to validate the pre-
vious password of the user.

4.1 Online authentication 76

4.2 authUser (service) 77

4.3 online (service) 79

4 Online authentication
75
DIGIPASS Gateway Integration Guide
4.1 Online authentication
Online authentication refers to an authentication via direct validation of a one-time
password (OTP) by the authentication server. The mobile application can perform this
online authentication by using DIGIPASS Gateway after a successful user authen-
tication.

Figure 2: Online authentication workflow (Overview)

NOTE: Figure 2 provides a high-level overview of the integration of OneSpan Mobile

Security Suite in the mobile application, and does not show all the required calls to
the OneSpan SDKs. Furthermore, it does not display the call by DIGIPASS Gateway to
OneSpan Authentication Server.

For more information, refer to the OneSpan Mobile Security Suite documentation.

4 Online authentication
76
DIGIPASS Gateway Integration Guide
4.2 authUser (service)

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The authUser service performs an online authentication.

4.2.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/authentication/authUser

4.2.2 Request
Table 47: authUser parameters

Parameter name Data type Description

userID String Required. The unique identifier used by OneSpan

Authentication Server to identify a user.

domain String Optional. The unique identifier used by OneSpan

Authentication Server to identify a group user.

password String Required. The one-time password (OTP) generated

by the authenticator.

Example

1 {
2 "userID": "jane.doe",
3 "domain": "mydomain.com",
4 "password": "123456"
5 }

4 Online authentication
77
DIGIPASS Gateway Integration Guide
4.2.3 Response
Table 48: authUser return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

result A JSON object that contains the resolved user information and the
serial number of the Digipass authenticator that is effectively used to
complete the authentication request.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "result":
10 {
11 "userID": "jane.doe",
12 "domain": "mydomain.com",
13 "orgUnit": "",
14 "serialNo": "VDS1000120-1"
15 }
16 }

4 Online authentication
78
DIGIPASS Gateway Integration Guide
4.3 online (service)

NOTE: This command is deprecated! Use 4.2 authUser (service) instead!

API version: 1

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The online service performs an online authentication.

4.3.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/auth/online

4.3.2 Request
Table 49: online parameters

Parameter name Data type Description

userID String Required. The unique identifier used by OneSpan

Authentication Server to identify a user.

domain String Optional. The unique identifier used by OneSpan

Authentication Server to identify a group user.

otp String Required.The one-time password (OTP) generated

with the Digipass SDK.

Example

1 {
2 "userID": "myUserID",
3 "domain": "myDomain",
4 "otp": "1234567890123456"
5 }

4 Online authentication
79
DIGIPASS Gateway Integration Guide
4.3.3 Response
Table 50: online return values

Return value Data type Description

errorCode Integer The return code provided by OneSpan Authentic-

ation Server. 0 is returned in case of success.

errorMessage String The error message provided by OneSpan

Authentication Server. STAT_SUCCESS is returned
in case of success.

Example

1 {
2 "errorCode": 0,
3 "errorMessage": "STAT_SUCCESS"
4 }

4 Online authentication
80
DIGIPASS Gateway Integration Guide
Push and login
5

Push and login consists of an out-of-band authentication initiated on a website

and validated with a mobile application. The authentication request is transmitted
via a push notification.

5.1 Push and login 82

5.2 authUser (service) [v2] 86

5.3 cancelAuthUser (service) [v2] 88

5.4 getPreparedSecureChallenge (service) [v2] 90

5.5 cancelLogin (service) 92

5.6 retrieveLogin (service) 94

5.7 signLogin (service) 96

5 Push and login

81
DIGIPASS Gateway Integration Guide
5.1 Push and login
Push and login consists of an out-of-band authentication initiated on a website and
validated with a mobile application. The authentication request is transmitted via a
push notification. The user must initiate the push and login process by using the web-
site of an application server communicating with OneSpan Authentication Server. A
push notification will be sent to the mobile application, which must implement the fol-
lowing steps:

1. Retrieve the login details related to the authentication session from DIGIPASS
Gateway.

2. Display the login details to the user for approval.

3. If the user approves the login request:

a. Authenticate the user with a given authentication method (e.g. PIN or fin-
gerprint recognition).

b. Sign the login request and transmit the generated signature to DIGIPASS
Gateway.

4. If the user rejects the login request:

l Transmit the cancellation request to DIGIPASS Gateway.

5. Display a status message in the mobile application.

The application server can now display the result of the authentication request to
the user on the website.

5 Push and login

82
DIGIPASS Gateway Integration Guide
 Figure 3: Push and login workflow (Overview)

NOTE: Figure 3 provides a high-level overview of the integration of OneSpan Mobile

Security Suite in the mobile application, and does not show all required calls to the
OneSpan SDKs.

For more information, refer to the OneSpan Mobile Security Suite documentation.

5.1.1 Push notification message content

The content of the push notification is contained in a Secure Channel message, which
must be decrypted using the Digipass SDK. Once decrypted, the content of the push
notification is encoded as a plain text string with each parameter separated by a semi-
colon (see Table 51).

5 Push and login

83
DIGIPASS Gateway Integration Guide
 Table 51: Push notification content parameters

Parameter Description

Version Version of the encoding protocol.

Length: 2 digits

Possible values:
l 01. Current encoding.

Message type The type of message contained in the encoded string.

Length: 2 digits

Possible values:
l 03. Content is a challenge key for an authentication request.

Challenge key The unique identifier used by OneSpan Authentication Server to identify
a login request. It will be used during the entire login request process.

Length: 10 hexadecimal characters.

EXAMPLE: "01;03;0123456789"

5.1.2 Login request content

The login details are protected in a Secure Channel message which must be decryp-
ted with the Digipass SDK. Once decrypted, the login details are encoded as a plain
text string with each parameter separated by a semicolon (see Table 52).

Table 52: Login details parameters

Parameter Description

Version Version of the encoding protocol.

Length: 2 digits

Possible values:
l 01. Current encoding.

5 Push and login

84
DIGIPASS Gateway Integration Guide
Table 52: Login details parameters (continued)

Parameter Description

Message type The type of message contained in the encoded string.

Length: 2 digits

Possible values:
l 04. Login details.

Service name The variable specified by the application server when calling the authUser
method of OneSpan Authentication Server, triggering the push noti-
fication.

Crypto app index The index of the cryptographic application used to sign the login details.

Lenght: 1 digit

Possible values: 1–8

User identifier The unique identifier used by OneSpan Authentication Server to identify
a user. This must be stored in the persistent memory.

Length: Up to 255 UTF-8 characters.

Domain The unique identifier used by OneSpan Authentication Server to identify

a group of users. This must be stored in the persistent memory.

Length: Up to 255 UTF-8 characters.

EXAMPLE: "01;04;myService;3;myUserID;myDomain"

If the user approves the login request and is successfully authenticated, the login
request must be signed with the Digipass SDK using the Secure Channel message
received from DIGIPASS Gateway that contains the login details.

If the user rejects the login request, the challenge key must be encrypted in a Secure
Channel message with the Digipass SDK.

5 Push and login

85
DIGIPASS Gateway Integration Guide
5.2 authUser (service) [v2]

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The authUser service completes a pending push and login authentication. It resumes
an authentication request that the serving OneSpan Authentication Server instance
previously suspended during a SOAP call (authUser) from the application server.

The authentication request is retrieved by the client using getPreparedSecureChallenge.

The respective authentication request is identified by a challenge key previously
received via push notification (see 5.4 getPreparedSecureChallenge (service) [v2]).

5.2.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/authentication/push /authUser

5.2.2 Request
Table 53: authUser parameters

Parameter name Data type Description

challengeKey String Required. The unique identifier used by OneSpan

Authentication Server to identify a login request.

domain String Optional. The unique identifier used by OneSpan

Authentication Server to identify a group user.

signature String Required. The signature generated with the Digi-

pass SDK using the Secure Channel message con-
taining the login details.

userID String Required. The unique identifier used by OneSpan

Authentication Server to identify a user.

5 Push and login

86
DIGIPASS Gateway Integration Guide
 Example

1 {
2 "userID": "jane.doe",
3 "domain": "mydomain.com",
4 "challengeKey": "0123456789",
5 "signature": "1234567890123456"
6 }

5.2.3 Response
Table 54: authUser return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

result A JSON object that contains the resolved user information and the
serial number of the Digipass authenticator that is effectively used to
complete the authentication request.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "result":
10 {
11 "userID": "jane.doe",
12 "domain": "mydomain.com",
13 "orgUnit": "",
14 "serialNo": "VDS1000120-1"
15 }
16 }

5 Push and login

87
DIGIPASS Gateway Integration Guide
5.3 cancelAuthUser (service) [v2]

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The cancelAuthUser service cancels a pending push and login authentication. The
respective authentication is identified by a challenge key previously received via push
notification.

5.3.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/authentication/push
/cancelAuthUser

5.3.2 Request
Table 55: cancelAuthUser parameters

Parameter name Data type Description

serialNumber String Required. The unique identifier of the Digipass

instance. This is the concatenation of the Digipass
serial number and the Digipass sequence number,
separated by a dash.

challengeKey String Required. The challenge key protected by a Secure

Channel message generated with the Digipass
SDK.

Example

1 {
2 "serialNumber": "VDS1000000-1",
3 "challengeKey": "D2602CE39F8CC50398CD40F41924702C..."
4 }

5 Push and login

88
DIGIPASS Gateway Integration Guide
5.3.3 Response
Table 56: cancelAuthUser return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 }
9 }

5 Push and login

89
DIGIPASS Gateway Integration Guide
5.4 getPreparedSecureChallenge (service) [v2]

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The getPreparedSecureChallenge service retrieves a prepared authentication request. The

respective authentication request is identified by a challenge key previously received
via push notification.

Only one application is allowed to retrieve the authentication request. The challenge
key is consumed by the first application retrieving the secure challenge message, sub-
sequent attempts to retrieve it will fail with status code STAT_NOT_FOUND.

Depending on the user’s choice the mobile application can either complete the
authentication request (see 5.2 authUser (service) [v2]) or cancel it (see 5.3 can-
celAuthUser (service) [v2]).

5.4.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/authentication/push
/getPreparedSecureChallenge

5.4.2 Request
Table 57: getPreparedSecureChallenge parameters

Parameter name Data type Description

serialNumber String Required. The unique identifier of the Digipass

instance. This is the concatenation of the Digipass
serial number and the Digipass sequence number,
separated by a dash.

challengeKey String Required. The unique identifier used by OneSpan

Authentication Server to identify a login request.

5 Push and login

90
DIGIPASS Gateway Integration Guide
 Example

1 {
2 "serialNumber": "VDS1000000-1",
3 "challengeKey": "1234567890",
4 }

5.4.3 Response
Table 58: getPreparedSignatureRequest return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

result A JSON object that contains the actual authentication request as a

Secure Channel message (requestMessage).

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "result":
10 {
11 "requestMessage": "2EAA8300F254C137B35237560CCBFE98..."
12 }
13 }

5 Push and login

91
DIGIPASS Gateway Integration Guide
5.5 cancelLogin (service)

NOTE: This command is deprecated! Use 5.3 cancelAuthUser (service) [v2] instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: Basic HTTP authentication using the front-end API key.

The cancelLogin service cancels a pending push and login authentication. The respect-
ive authentication is identified by a challenge key previously received via push noti-
fication.

5.5.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/push/cancelLogin

5.5.2 Request
Table 59: cancelLogin parameters

Parameter name Data type Description

digipassInstanceID String Required. The unique identifier of the Digipass

instance. This is the concatenation of the Digipass
serial number and the Digipass sequence number,
separated by a dash.

encryptedChallengeKey String Required. The challenge key protected by a

Secure Channel message generated with the Digi-
pass SDK.

Example

1 {
2 "digipassInstanceID": "VDS1000000-1",
3 "encryptedChallengeKey": "254B698F7809C9AEAB10F1DEAC658601..."
4 }

5 Push and login

92
DIGIPASS Gateway Integration Guide
5.5.3 Response
Table 60: cancelLogin return values

Return value Data type Description

errorCode Integer The return code provided by OneSpan Authentic-

ation Server. 0 is returned in case of success.

errorMessage String The error message provided by OneSpan

Authentication Server. STAT_SUCCESS is returned
in case of success.

Example

1 {
2 "errorCode": 0,
3 "errorMessage": "STAT_SUCCESS"
4 }

5 Push and login

93
DIGIPASS Gateway Integration Guide
5.6 retrieveLogin (service)

NOTE: This command is deprecated! Use 5.4 getPreparedSecureChallenge (ser-

vice) [v2] instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: Basic HTTP authentication using the front-end API key.

The retrieveLogin service retrieves a prepared authentication request. The respective

authentication request is identified by a challenge key previously received via push
notification.

5.6.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/push/retrieveLogin

5.6.2 Request
Table 61: retrieveLogin parameters

Parameter name Data type Description

digipassInstanceID String Required. The unique identifier of the Digipass

instance. This is the concatenation of the Digipass
serial number and the Digipass sequence number,
separated by a dash.

challengeKey String Required. The unique identifier used by OneSpan

Authentication Server to identify a login request.

Example

1 {
2 "digipassInstanceID": "VDS1000000-1",
3 "challengeKey": "1234567890"
4 }

5 Push and login

94
DIGIPASS Gateway Integration Guide
5.6.3 Response
Table 62: retrieveLogin return values

Return value Data type Description

errorCode Integer The return code provided by OneSpan Authentic-

ation Server. 0 is returned in case of success.

errorMessage String The error message provided by OneSpan

Authentication Server. STAT_SUCCESS is returned
in case of success.

encryptedLoginDetails String The login details protected by a Secure Channel

message, which must be decrypted with the Digi-
pass SDK.

Example

1 {
2 "errorCode": 0,
3 "errorMessage": "STAT_SUCCESS",
4 "encryptedLoginDetails": "903A1166C89C82F3ED1DB920666E4370..."
5 }

5 Push and login

95
DIGIPASS Gateway Integration Guide
5.7 signLogin (service)

NOTE: This command is deprecated! Use 5.2 authUser (service) [v2] instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: Basic HTTP authentication using the front-end API key.

The signLogin service completes a pending push and login authentication.

5.7.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/push/signLogin

5.7.2 Request
Table 63: signLogin parameters

Parameter name Data type Description

userID String Required. The unique identifier used by OneSpan

Authentication Server to identify a user.

domain String Optional. The unique identifier used by OneSpan

Authentication Server to identify a group user.

challengeKey String Required. The unique identifier used by OneSpan

Authentication Server to identify a login request.

signature String Required. The signature generated with the Digi-

pass SDK using the Secure Channel message con-
taining the login details.

Example

1 {
2 "userID": "myUserID",
3 "domain": "myDomain",

5 Push and login

96
DIGIPASS Gateway Integration Guide
 4 "serialNumber": "VDS1000000-1",
5 "challengeKey": "1234567890",
6 "signature": "1234567890123456"
7 }

5.7.3 Response
Table 64: signLogin return values

Return value Data type Description

errorCode Integer The return code provided by OneSpan Authentic-

ation Server. 0 is returned in case of success.

errorMessage String The error message provided by OneSpan

Authentication Server. STAT_SUCCESS is returned
in case of success.

Example

1 {
2 "errorCode": 0,
3 "errorMessage": "STAT_SUCCESS"
4 }

5 Push and login

97
DIGIPASS Gateway Integration Guide
Push and sign
6

Push and sign allows data signing using a separate and unconnected channel
(out-of-band signing).

6.1 Push and sign 99

6.2 authSignature (service) 103

6.3 cancelAuthSignatureRequest (service) 106

6.4 getPreparedSignatureRequest (service) 108

6 Push and sign

98
DIGIPASS Gateway Integration Guide
6.1 Push and sign
Transaction data signing using push notification (push and sign) allows data signing
using a separate and unconnected channel (out-of-band signing). The data signing
transaction is initiated by a web application and validated by the mobile application.
The signature request information is transmitted via a push notification.

The transaction data signing using push notification workflow overview:

1. The user initiates a data signing transaction in the web application, e.g. a banking
site.

2. The web application sends a respective request to the connected OneSpan

Authentication Server instance via SOAP (authSignatureRequest).

3. The OneSpan Authentication Server instance prepares the signature request

uniquely identified by a request key. The signature request is stored in the sig-
nature cache of OneSpan Authentication Server. The request key is transmitted
to all applicable Digipass authenticator instances via push notifications (see 6.1.1
Push notification message content).

4. The user accepts the push notification received by the mobile application (Digi-
pass authenticator). The mobile application retrieves the actual signature request
via DIGIPASS Gateway (using getPreparedSignatureRequest) and presents it to the
user accordingly (see 6.1.2 Signature request content).

5. The user does one of the following:

l The user confirms the signature request. The mobile application generates a
signature and completes the signature request via DIGIPASS Gateway (using
authSignature). The signature request is successfully processed and removed
from the signature cache.

l The user cancels the signature request. The mobile application cancels the
signature request via DIGIPASS Gateway (using cancelAuthSignatureRequest).
The signature request is removed from the signature cache without being
completed.

6. The mobile application displays a status message.

6 Push and sign

99
DIGIPASS Gateway Integration Guide
 Figure 4: Push and sign workflow (Overview)

NOTE: Figure 4 provides a high-level overview of the integration of OneSpan Mobile

Security Suite in the mobile application, and does not show all required calls to the
OneSpan SDKs. Furthermore, it does not display the call by DIGIPASS Gateway to
OneSpan Authentication Server.

For more information, refer to the OneSpan Mobile Security Suite documentation.

6.1.1 Push notification message content

The content of the push notification is protected in a Secure Channel message, which
must be decrypted with the Digipass SDK. Once decrypted, the content of the push
notification is encoded as a plain text string with each parameter separated by a semi-
colon (see Table 65).

6 Push and sign

100
DIGIPASS Gateway Integration Guide
 Table 65: Push notification content parameters

Parameter Description

Version Version of the encoding protocol.

Length: 2 digits

Possible values:
l 01. Current encoding.

Message type The type of message contained in the encoded string.

Length: 2 digits

Possible values:
l 05. Content is a request key for a signature transaction message v2.

Request key The unique identifier used by OneSpan Authentication Server to identify
a signature request. This key will be used during the entire transaction
data signing process.

Length: 10 hexadecimal characters.

EXAMPLE: "01;05;0123456789"

6.1.2 Signature request content

The signature request retrieved using getPreparedSignatureRequest (identified by the
request key) is contained in a Secure Channel message, which must be decrypted
using the Digipass SDK to obtain the signature request data.

The signature request data and how to handle it depends on the signature data type
used in the authSignatureRequest SOAP command (OneSpan Authentication Server) ini-
tiating the push and sign workflow:

l Separate key/value signature data fields (signatureFields). The signature

request data is binary data generated with the Secure Messaging SDK (using
generateSignatureTransactionMessageBodyV2). It also needs to be parsed as such
using the respective client function of the Secure Messaging SDK Client.

l Binary data signature body (signatureBody). The signature request data is some
hexadecimal raw data and needs to be handled accordingly.

6 Push and sign

101
DIGIPASS Gateway Integration Guide
 If the user approves the signature request, the request must be signed with the Digi-
pass SDK based on the Secure Channel message received from DIGIPASS Gateway
that contains the signature details.

If the user rejects the signature request, the request key must be encrypted in a
Secure Channel message with the Digipass SDK.

6.1.3 Additional references

For more information about handling Secure Channel messages, refer to the Secure
Messaging SDK Client Integration Guide.

For more information about the OneSpan Authentication Server SOAP commands,
refer to the OneSpan Authentication Server SDK SOAP Reference.

6 Push and sign

102
DIGIPASS Gateway Integration Guide
6.2 authSignature (service)

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The authSignature service completes a pending data signing transaction. It resumes a

transaction the serving OneSpan Authentication Server instance previously sus-
pended during a SOAP call (authSignatureRequest) from the respective application
server to OneSpan Authentication Server initiating the signing transaction.

The signature request is retrieved by the client using getPreparedSignatureRequest. The

respective signature request is identified by a request key previously received via push
notification (see 6.4 getPreparedSignatureRequest (service)).

6.2.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/signature/push /authSignature

6.2.2 Request
Table 66: authSignature parameters

Parameter name Data type Description

userID String Required. The unique identifier used by OneSpan

Authentication Server to identify a user.

domain String Optional. The unique identifier used by OneSpan

Authentication Server to identify a user domain.

requestKey String Required. The request key that refers to the sig-
nature request previously generated by OneSpan
Authentication Server and received via push noti-
fication.

signature String Required. The signature created from the secure

channel message, i.e. the actual signature request
retrieved using getPreparedSignatureRequest.

6 Push and sign

103
DIGIPASS Gateway Integration Guide
 NOTE: Parameter names are case-sensitive.

Example

1 {
2 "userID": "jane.doe",
3 "domain": "mydomain.com",
4 "requestKey": "8408980524",
5 "signature": "3833791"
6 }

6.2.3 Response
Table 67: authSignature return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

result A JSON object that contains the resolved user information and the
serial number of the Digipass authenticator that is effectively used to
complete the signature request.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "result":
10 {
11 "userID": "jane.doe",
12 "domain": "mydomain.com",
13 "orgUnit": "",
14 "serialNo": "VDS1000120-1"
15 }
16 }

6 Push and sign

104
DIGIPASS Gateway Integration Guide
 6 Push and sign
105
DIGIPASS Gateway Integration Guide
6.3 cancelAuthSignatureRequest (service)

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The cancelAuthSignatureRequest service cancels a pending data signing transaction. The

respective data signing transaction is identified by a request key previously received
via push notification.

Only the application that originally retrieved the prepared signature request using
getPreparedSignatureRequest is allowed to cancel the signature request. Attempts by
other applications to cancel the request will fail with the STAT_NOSUPPORT status code
(see 6.4 getPreparedSignatureRequest (service)).

6.3.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/signature/push
/cancelAuthSignatureRequest

6.3.2 Request
Table 68: cancelAuthSignatureRequest parameters

Parameter name Data type Description

requestKey String Required. The request key referring to the sig-

nature request previously generated by OneSpan
Authentication Server and received via push noti-
fication.

serialNumber String Required. The Digipass authenticator serial num-

ber, e.g. VDS1000120-1.

NOTE: Parameter names are case-sensitive.

6 Push and sign

106
DIGIPASS Gateway Integration Guide
 Example

1 {
2 "requestKey": "77FA6E11F09FE817A7D5E3CC51DE680F...",
3 "serialNumber": "VDS1000120-1"
4 }

6.3.3 Response
Table 69: cancelAuthSignatureRequest return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 }
9 }

6 Push and sign

107
DIGIPASS Gateway Integration Guide
6.4 getPreparedSignatureRequest (service)

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The getPreparedSignatureRequest service retrieves a prepared signature request for

transaction data signing. The respective signature request is identified by a request
key previously received via push notification.

Only one application is allowed to retrieve the signature request. The request key is
consumed by the first application retrieving the signature transaction message, sub-
sequent attempts to retrieve it will fail with the STAT_NOT_FOUND status code.

Depending on the user’s choice the mobile application can either complete the sig-
nature request (see 6.2 authSignature (service)) or cancel it (see 6.3 can-
celAuthSignatureRequest (service)).

6.4.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/signature/push
/getPreparedSignatureRequest

6.4.2 Request
Table 70: getPreparedSignatureRequest parameters

Parameter name Data type Description

requestKey String Required. The request key referring to the sig-

nature request previously generated by OneSpan
Authentication Server and received via push noti-
fication.

serialNumber String Required. The Digipass authenticator serial num-

ber, e.g. VDS1000120-1.

6 Push and sign

108
DIGIPASS Gateway Integration Guide
 NOTE: Parameter names are case-sensitive.

Example

1 {
2 "requestKey": "8408980524",
3 "serialNumber": "VDS1000120-1"
4 }

6.4.3 Response
Table 71: getPreparedSignatureRequest return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

result A JSON object that contains the actual signature request as a Secure
Channel message (requestMessage).

How to handle the signature request depends on the signature data

type used in the initiating authSignatureRequest SOAP request (see
6.1.2 Signature request content).

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 },
9 "result":
10 {
11 "requestMessage": "00C1C3E40F42B8B36D836BE8A3CC1168…"
12 }
13 }

6 Push and sign

109
DIGIPASS Gateway Integration Guide
Notification
7

DIGIPASS Gateway can send push notifications to specific users. To receive push
notifications mobile applications need to register themselves and obtain a noti-
fication identifier.

7.1 Notification registration 111

7.2 sendNotification (service) [v2] 113

7.3 sendNotification (service) [v1] 115

7.4 updateNotificationID (service) [v2] 117

7.5 updateNotificationID (service) [v1] 119

7 Notification
110
DIGIPASS Gateway Integration Guide
7.1 Notification registration
A registration must be done to enable the notification feature in a mobile application.
When the user starts a mobile application that has previously already been activated
(or just after a successful activation), a background process must be started to per-
form the following steps:

1. Get the OneSpan notification identifier using the Notification SDK.

2. Check whether the OneSpan notification identifier has been updated by com-
paring it with the previous data stored in the persistent memory.

3. If the OneSpan notification identifier has been updated:

a. Encrypt the OneSpan notification identifier using the Digipass SDK.

b. Transmit the encrypted OneSpan notification identifier to the DIGIPASS

Gateway via the dedicated service.

c. Store the OneSpan notification identifier in the persistent memory.

Figure 5: Notification registration workflow (Overview)

NOTE: Figure 5 provides a high-level overview of the integration of OneSpan Mobile

Security Suite in the mobile application, and does not show all required calls to the

7 Notification
111
DIGIPASS Gateway Integration Guide
OneSpan SDKs. Furthermore, it does not display the call by DIGIPASS Gateway to
OneSpan Authentication Server.

For more information, refer to the OneSpan Mobile Security Suite documentation.

7 Notification
112
DIGIPASS Gateway Integration Guide
7.2 sendNotification (service) [v2]

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: The service is secured by the back-end and front-end API key.

The sendNotification service sends a push notification message to a user.

7.2.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/notification/push
/sendNotification

7.2.2 Request
Table 72: sendNotification parameters

Parameter name Data type Description

app_id String Optional. Required if pushing to iOS devices.The

application identifier.

message String Required. The text to be used as content of the

notification message.

pnid String Required. The push notification identifier of the

authenticator to send the notification message to.

subject String Optional. The text to be used as subject of the noti-

fication message.

title String Optional. The text to be used as title of the noti-

fication message.

NOTE: Parameter names are case-sensitive.

7 Notification
113
DIGIPASS Gateway Integration Guide
 Example

1 {
2 "pnid": "01000001010200CC4150413931624841694341666A4854385755586C7751...",
3 "app_id": "com.example.someapp",
4 "subject": "Notification subject",
5 "title": "Notification title",
6 "message": "Notification message"
7 }

7.2.3 Response
Table 73: sendNotification return values

Return value Data type Description

error_message String An error message in case of an error, e.g. when an

invalid request is received.

device_platform String The platform of the device that has actually

received the notification message.

Example

1 {
2 "device_platform": "ANDROID"
3 }

7 Notification
114
DIGIPASS Gateway Integration Guide
7.3 sendNotification (service) [v1]

NOTE: This command is deprecated! Use 7.2 sendNotification (service) [v2]

instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: Basic HTTP authentication using the front-end API key.

The sendNotification service sends a push notification message to a user.

7.3.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/notification/sendNotification

7.3.2 Request
Table 74: sendNotification parameters

Parameter name Data type Description

app_id String Optional. Required if pushing to iOS devices.The

application identifier.

message String Required. The text to be used as content of the

notification message.

pnid String Required. The push notification identifier of the

authenticator to send the notification message to.

subject String Optional. The text to be used as subject of the noti-

fication message.

title String Optional. The text to be used as title of the noti-

fication message.

NOTE: Parameter names are case-sensitive.

7 Notification
115
DIGIPASS Gateway Integration Guide
 Example

1 {
2 "pnid": "01000001010200CC4150413931624841694341666A4854385755586C7751...",
3 "app_id": "com.example.someapp",
4 "subject": "Notification subject",
5 "title": "Notification title",
6 "message": "Notification message"
7 }

7.3.3 Response
Table 75: sendNotification return values

Return value Data type Description

error_message String An error message in case of an error, e.g. when an

invalid request is received.

device_platform String The platform of the device that has actually

received the notification message.

Example

1 {
2 "device_platform": "ANDROID"
3 }

7 Notification
116
DIGIPASS Gateway Integration Guide
7.4 updateNotificationID (service) [v2]

API version: 2

Availability: DIGIPASS Gateway 5.0 and later

Authentication: Basic HTTP authentication using the front-end API key.

The updateNotificationID service updates the push notification identifier (PNID) of a

specific authenticator.

7.4.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/v2/notification/push
/updateNotificationID

7.4.2 Request
Table 76: updateNotificationID parameters

Parameter name Data type Description

digipassInstanceID String Required. The identifier of the authenticator

instance to update.

domain String Required. The domain of the user.

encryptedNotificationID String Required. The notification identifier to set as

encrypted Secure Channel message.

userID String Required. The user name.

NOTE: Parameter names are case-sensitive.

Example

1 {
2 "userID": "jane.doe",
3 "domain": "myDomain.com",
4 "digipassInstanceID": "VDS1000001-1",

7 Notification
117
DIGIPASS Gateway Integration Guide
 5 "encryptedNotificationID": "0901C3E40F42B8112D690D2E8E11105BD156E89D..."
6 }

7.4.3 Response
Table 77: updateNotificationID return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 }
9 }

7 Notification
118
DIGIPASS Gateway Integration Guide
7.5 updateNotificationID (service) [v1]

NOTE: This command is deprecated! Use 7.4 updateNotificationID (service) [v2]

instead!

API version: 1

Availability: DIGIPASS Gateway 4.1 and later

Authentication: Basic HTTP authentication using the front-end API key.

The updateNotificationID service updates the push notification identifier (PNID) of a

specific authenticator.

7.5.1 URL

https://<dpgateway_host>:<dpgateway_port>/rest/notification
/updateNotificationID

7.5.2 Request
Table 78: updateNotificationID parameters

Parameter name Data type Description

digipassInstanceID String Required. The identifier of the authenticator

instance to update.

domain String Required. The domain of the user.

encryptedNotificationID String Required. The notification identifier to set as

encrypted Secure Channel message.

userID String Required. The user name.

NOTE: Parameter names are case-sensitive.

7 Notification
119
DIGIPASS Gateway Integration Guide
 Example

1 {
2 "userID": "jane.doe",
3 "domain": "myDomain.com",
4 "digipassInstanceID": "VDS1000001-1",
5 "encryptedNotificationID": "0901C3E40F42B8112D690D2E8E11105BD156E89D..."
6 }

7.5.3 Response
Table 79: updateNotificationID return values

Return value Description

resultCodes A JSON object that contains the return and status codes of the ser-
vice.

Example

1 {
2 "resultCodes":
3 {
4 "returnCodeEnum": "RET_SUCCESS",
5 "statusCodeEnum": "STAT_SUCCESS",
6 "returnCode": 0,
7 "statusCode": 0
8 }
9 }

7 Notification
120
DIGIPASS Gateway Integration Guide
Security recommendations
8

DIGIPASS Gateway provides endpoints to the outside world (mobile client applic-
ations). It is highly recommended to consider the security guidelines and best prac-
tices in this chapter to ensure secure deployment and usage of DIGIPASS Gateway.

8.1 Configuration of SSL/TLS 122

8.2 Restricting source IP address ranges 124

8 Security recommendations
121
DIGIPASS Gateway Integration Guide
8.1 Configuration of SSL/TLS
You can configure DIGIPASS Gateway to use encrypted communication, either during
or after the initial setup.

There are two communication channels you need to protect:

l Between the DIGIPASS Gateway service and the mobile client applications.

l Between the DIGIPASS Gateway service and OneSpan Authentication Server.

8.1.1 Securing communication between DIGIPASS Gateway and the

mobile client application
If you use the DIGIPASS Gateway installation packages, an Apache Tomcat web server
is automatically installed to deploy the DIGIPASS Gateway web service.

This embedded Apache Tomcat web server is automatically configured to secure con-
nections to the DIGIPASS Gateway web service via TLS v1.2. A TLS certificate and a ran-
dom password are generated for that purpose.

If you manually deploy the DIGIPASS Gateway web application to an existing web or
Java application server, you should configure it to use TLS to encrypt the com-
munication.

8.1.2 Securing communication between DIGIPASS Gateway and

OneSpan Authentication Server
If you use the DIGIPASS Gateway installation packages to install DIGIPASS Gateway on
a machine, where OneSpan Authentication Server is already installed, the DIGIPASS
Gateway setup configures the server connection settings (including the SSL cer-
tificate) automatically to use the local OneSpan Authentication Server deployment.

If you manually deploy the DIGIPASS Gateway web application to an existing web or
Java application server, you should configure it to use TLS. This encrypts the com-
munication to the OneSpan Authentication Server instances via the OneSpan Web
Configuration Tool.

The certification authority (CA) for the certificate of the OneSpan Authentication
Server instance must be added to the trust store of DIGIPASS Gateway.

8 Security recommendations
122
DIGIPASS Gateway Integration Guide
 For more information about protecting SSL certificates and private keys, refer to the
IDENTIKEY Authentication Server Security Best Practices Guide.

8.1.3 Securing communication between DIGIPASS Gateway and

third-party notification services
By default, communication between OneSpan Notification Gateway or DIGIPASS Gate-
way and third-party notification services is protected by encryption. Additionally, push
notification messages sent are secured by encapsulating the actual message content
within a Secure Channel message. This is done automatically, and you do not need
special configuration for this.

For more information about the connection security implemented by Apple Push Noti-
fication service (APNs) and Firebase Cloud Messaging (FCM), see
https://developer.apple.com/library/archive/documentation/NetworkingInternet/Co
nceptual/RemoteNotificationsPG/APNSOverview.html#//apple_
ref/doc/uid/TP40008194-CH8-SW1 and https://firebase.google.com/docs/cloud-
messaging/server#choose, respectively.

8 Security recommendations
123
DIGIPASS Gateway Integration Guide
8.2 Restricting source IP address ranges
In addition to correctly setting up your firewall to control network access, you can
restrict the source IP addresses from which requests are allowed directly in DIGIPASS
Gateway.

By default, all services that are considered to be used by the back-end application are
restricted to be accessed from the local host only. This includes all services requiring
authentication using the back-end API key, as well as API v1 services that don't require
authentication, but were part of the Administration interface in legacy versions of
DIGIPASS Gateway. If OneSpan Authentication Server, DIGIPASS Gateway, and your
back-end application are not installed on the same server, you need to allow the
OneSpan Authentication Server and back-end application server. All other services are
unrestricted. You should restrict those services to specific source IP address ranges.

You can restrict requests by explicitly specifying allowed source IP address ranges
using CIDR blocks via the OneSpan Web Configuration Tool:

admintool type dpgateway endpoint allow "<service>" <cidr_block>

where:

l <service> specifies the DIGIPASS Gateway service endpoint, including the pre-
fixing slash mark ('/'). You can use glob notation specifying a matching pattern to
set the CIDR block for several services at once. In that case you need to set the
value within quotation marks.

l <cidr_block> specifies an IPv4 address range using CIDR notation, e.g. 192.0.2.0/24.
Any request originating from a host within that CIDR block will be allowed. You
can specify multiple CIDR blocks at once as comma-separated list.

For more information, refer to the DIGIPASS Gateway Getting Started Guide, Section
"Configure DIGIPASS Gateway".

8 Security recommendations
124
DIGIPASS Gateway Integration Guide
Migrating previous versions of
DIGIPASS Gateway
9

DIGIPASS Gateway 5 is a major update, which introduces new features while at the
same time changes or removes legacy functionality, thus breaking compatibility with
certain legacy client applications.

Before migrating from a legacy version, i.e. DIGIPASS Gateway 4.1 or earlier, it is vital to
know the changed and missing behavior and features to be able to prepare the envir-
onment, including websites and mobile client applications.

9.1 Changes in DIGIPASS Gateway 5 126

9.2 Migrating to DIGIPASS Gateway 5 services 130

9 Migrating previous versions of DIGIPASS Gateway

125
DIGIPASS Gateway Integration Guide
9.1 Changes in DIGIPASS Gateway 5
DIGIPASS Gateway 5 introduces a couple of breaking changes compared to earlier ver-
sions of DIGIPASS Gateway.

9.1.1 Architectural changes

l Stateless gateway. Previous versions relied on an external PostgreSQL database
to store some state information, such as transactions and transaction data.

This database requirement has been removed. DIGIPASS Gateway no longer

saves any state information whatsoever, but rather relies on the respective
authentication server, e.g. OneSpan Authentication Server.

l DIGIPASS Gateway services. Previous versions consisted of two web services

providing two different interfaces: The so-called Administration interface and the
DIGIPASS interface.

These two interfaces have been consolidated to one.

The Administration interface has been completely removed, since most of the
administrative services have become obsolete, e.g. transaction management for
Mobile Authenticator Studio. The remaining services have been merged with the
DIGIPASS interface. The distinction between administrative and client services
now only exists in context of required authentication.

l API authentication. In previous versions some services were protected using

basic HTTP authentication via one API key.

In DIGIPASS Gateway 5, all services are protected using basic HTTP authen-
tication via one of two API keys:
l The front-end API key is required for services typically used by mobile applic-
ations, e.g. OneSpan Mobile Authenticator.

l The back-end API key is required for services typically exposed to the solu-
tion's back-end side, e.g. the banking website.

9.1.2 Workflow changes

l Out-of-band transaction data signing. This feature was implemented in pre-
vious versions of DIGIPASS Gateway and exposed to Mobile Authenticator Studio.

9 Migrating previous versions of DIGIPASS Gateway

126
DIGIPASS Gateway Integration Guide
 It has been replaced by a new transaction data signing workflow integrating
seamlessly with OneSpan Authentication Server, using push notifications.

l Transaction management. It is no longer possible to manage transactions, such

as listing pending transactions. When a transaction is initiated, the user receives
a push notification. The mobile application retrieves the transaction details and
the user can either accept or reject it right away.

9.1.3 Changes in the API

New or changed services

The following services are either new or updated versions of previous existing ones:

l /rest/v2/authentication/authUser

l /rest/v2/authentication/push/authUser

l /rest/v2/authentication/push/cancelAuthUser

l /rest/v2/authentication/push/getPreparedSecureChallenge

l /rest/v2/notification/push/sendNotification

l /rest/v2/notification/push/updateNotificationID

l /rest/v2/provisioning/DSAPPActivate

l /rest/v2/provisioning/DSAPPGenerateActivationData

l /rest/v2/provisioning/DSAPPMdlAddDevice

l /rest/v2/provisioning/DSAPPRegister

l /rest/v2/provisioning/DSAPPSRPGenerateActivationData

l /rest/v2/provisioning/DSAPPSRPGenerateEphemeralKey

l /rest/v2/provisioning/getServerTime

l /rest/v2/provisioning/MdlActivate

l /rest/v2/provisioning/MdlAddDevice

9 Migrating previous versions of DIGIPASS Gateway

127
DIGIPASS Gateway Integration Guide
 l /rest/v2/provisioning/MdlRegister

l /rest/v2/signature/push/authSignature

l /rest/v2/signature/push/cancelAuthSignatureRequest

l /rest/v2/signature/push/getPreparedSignatureRequest

Deprecated services
Deprecated services are still available in the interface for backward-compatibility reas-
ons and migration purposes only. However, newer versions of the same services or sim-
ilar new services exist that should be used for new implementations.

The following services have been deprecated:

l /activate

l /addDevice

l /bind

l /instanceActivation

l /licenseActivation

l /postActivation

l /register

l /registerOffline

l /registerOnline

l /rest/activation/DSAPPSRPGenerateActivationData

l /rest/activation/DSAPPSRPGenerateEphemeralKey

l /rest/activation/MdlActivate

l /rest/activation/MdlAddDevice

l /rest/auth/online

l /rest/notification/push/sendNotification

9 Migrating previous versions of DIGIPASS Gateway

128
DIGIPASS Gateway Integration Guide
 l /rest/notification/push/updateNotificationID

l /rest/push/cancelLogin

l /rest/push/retrieveLogin

l /rest/push/signLogin

l /signature

l /synchronize

Removed services
The following services have been removed:

l /createSecureChannelTransaction

l /createTransaction

l /deleteNotif

l /deleteTransaction

l /getTransactionStatus

l /listSecureChannelTransactions

l /listTds

l /manageTransaction

l /notify

l /registerNotif

l /rejectTransaction

l /testOffline

l /validateSecureChannelTransaction

l /validateTransaction

9 Migrating previous versions of DIGIPASS Gateway

129
DIGIPASS Gateway Integration Guide
9.2 Migrating to DIGIPASS Gateway 5 services
When migrating from DIGIPASS Gateway 4.1 or earlier you probably need to adapt
your application websites as well as your mobile applications integrating OneSpan
Mobile Security Suite.

If your mobile application uses deprecated services, you should change your applic-
ation to use the respective services in the current API version provided by DIGIPASS
Gateway 5 instead (see Table 80).

Table 80: DIGIPASS Gateway service mapping (DIGIPASS Gateway 4 vs. 5)

DIGIPASS Gateway 4 DIGIPASS Gateway 5

/activate /rest/v2/provisioning↲
/DSAPPGenerateActivationData
/licenseActivation
See 3.3 DSAPPGenerateActivationData
(service).

/addDevice /rest/v2/provisioning/MdlAddDevice

/rest/activation/MdlAddDevice See 3.13 MdlAddDevice (service) [v2]

/bind /rest/v2/provisioning/DSAPPActivate

See 3.2 DSAPPActivate (service).

/instanceActivation /rest/v2/provisioning/DSAPPMdlAddDevice

See 3.4 DSAPPMdlAddDevice (service).

/postActivation /rest/v2/provisioning/MdlActivate

/signature See 3.11 MdlActivate (service) [v2].

/rest/activation/MdlActivate

/register /rest/v2/provisioning/DSAPPRegister

/registerOnline See 3.5 DSAPPRegister (service)

/registerOffline /rest/v2/provisioning/MdlRegister

See 3.15 MdlRegister (service) [v2].

/rest/activation/DSAPPSRPGenerateActivationData /rest/v2/provisioning/↲
/DSAPPSRPGenerateActivationData

See 3.6 DSAPPSRPGen-

erateActivationData (service) [v2].

9 Migrating previous versions of DIGIPASS Gateway

130
DIGIPASS Gateway Integration Guide
Table 80: DIGIPASS Gateway service mapping (DIGIPASS Gateway 4 vs. 5) (continued)

DIGIPASS Gateway 4 DIGIPASS Gateway 5

/rest/activation/DSAPPSRPGenerateEphemeralKey /rest/v2/provisioning↲
/DSAPPSRPGenerateEphemeralKey

See 3.8 DSAPPSRPGen-

erateEphemeralKey (service) [v2].

/rest/auth/online /rest/v2/authentication/authUser

See 4.2 authUser (service).

/rest/notification/push/sendNotification /rest/v2/notification/push/sendNotification

See 7.2 sendNotification (service) [v2].

/rest/notification/push/updateNotificationID /rest/v2/notification/push↲
/updateNotificationID

See 7.4 updateNotificationID (service)

[v2].

/rest/push/cancelLogin /rest/v2/authentication/push/cancelAuthUser

See 5.3 cancelAuthUser (service) [v2].

/rest/push/retrieveLogin /rest/v2/authentication/push↲
/getPreparedSecureChallenge

See 5.4 getPreparedSecureChallenge (ser-

vice) [v2].

/rest/push/signLogin /rest/v2/authentication/push/authUser

See 5.2 authUser (service) [v2].

/synchronize /rest/v2/provisioning/getServerTime

See 3.10 getServerTime (service).

9 Migrating previous versions of DIGIPASS Gateway

131
DIGIPASS Gateway Integration Guide
Glossary

activation customer master key

The process in which the Digipass A triple DES key embedded in the
seeds and configuration data are static vector. This key is unique per
extracted from the activation data. customer.
Once the client activation is
completed, the Digipass instance is Digipass activation
ready to generate Digipass The process of providing the
responses. Digipass serial number, parameter
set, secret, and initial seed value for
activation code future one-time password (OTP) or
The Digipass key encrypted with the e-signature generation. Activation is
customer master key in the static successful when the first Digipass
vector. response is validated on the server.

activation password Digipass key

Up to 64 alphanumeric characters, A 64-bit or 128-bit secret key used
that customers and their end users for OTP or signature generation. It is
share prior to the registration encrypted in the activation code
process. It significantly enhances transferred from the server to the
security. It is sometimes referred to client.
as customer historical secret.
Digipass password
alea Mobile Authenticator Studio is
See nonce. password-protected. The password
protects the application usage, i.e.
customer users need to enter it for password-
The OneSpan customer who protected operations.
licenses and distributes Mobile
Authenticator Studio to end users, encrypted event reactivation
e.g. a bank. counter (XERC)
The event reactivation counter
customer historical secret (CHS) encrypted with the activation
See activation password. password or a session key.

Glossary
132
DIGIPASS Gateway Integration Guide
encrypted full activation data nonce
(XFAD) A random 64–hexadecimal number
The full activation data encrypted generated by the application. It is
with the activation password or a part of the one-time activation
session key. process and ensures that no other
computer can register with the
event reactivation counter (ERC) same data.
Data that must be provided to an
event-based Digipass authenticator one-time password (OTP)
during reactivation. By default, the A password that is valid for only one
event counter is set to 0 during authentication process. An one-time
Digipass activation, to be in sync password can be used only once,
with the event counter in the and each authentication process
Digipass BLOB. When the Digipass requires a new one-time password.
instance is used, the event counter
in the Digipass BLOB is OneSpan Authentication Server
incremented to the value of the last Framework
verified OTP. If the same Digipass An API-based authentication
instance is installed on another platform that serves as a back-end
device, the event counter must not system for Digipass strong
be set to 0 but to the event value authentication and e-signatures.
stored in the Digipass BLOB. The
ERC is generated by OneSpan OneSpan Mobile Authenticator
Authentication Server Framework to Studio
push the event value of the Digipass A mobile application supporting
BLOB to the Digipass client for OneSpan strong authentication.
synchronization.
post-activation
full activation data (FAD) The (optional) process following the
The full activation data includes the client activation.
parameter settings for the Mobile
Authenticator Studio activation, and registration
the encrypted activation data to The process of generating Digipass
finalize the activation process. It activation data on the server side.
includes the static vector, the
serial number
activation code, and the serial
The serial number of Mobile
number suffix.
Authenticator Studio.

Glossary
133
DIGIPASS Gateway Integration Guide
serial number suffix (SNS)
The last seven digits of the serial
number.

server activation
The validation of the first Digipass
response generated after client
activation. The server activation is
part of the post-activation process.

static vector
The Digipass parameter set. It
contains the customer master key
and the parameter set of the
cryptographic application(s). It is
generated by OneSpan Logistics
based on the Mobile Authenticator
Studio parameter sheet.

user
The Mobile Authenticator Studio
end user, e.g. a bank’s customer.

Glossary
134
DIGIPASS Gateway Integration Guide
Index

A suite 11
DIGIPASS Gateway services
activate (v1), service 53 for OneSpan Mobile Security
activation image 21 Suite 14
addDevice (v1), service 55 DSAPPActivate, service 23
authentication DSAPPGenerateActivationData, ser-
authUser (v2) service 77 vice 25
online (v1) service 79 DSAPPMdlAddDevice, service 28
out-of-band 82 DSAPPRegister (v2), service 30
push and login 82 DSAPPSRPGenerateActivationData
authSignature, service 103
(v1), service 34
authUser (v2), service 77, 86
DSAPPSRPGenerateActivationData
(v2), service 32
DSAPPSRPGenerateEphemeralKey
B
(v1), service 39
bind, service 57 DSAPPSRPGenerateEphemeralKey
(v2), service 37

C
calling GenerateSRPSessionKey, Cau-
G
tion notice 21 getPreparedSecureChallenge (v2), ser-
cancelAuthSignatureRequest, vice 90
service 106 getPreparedSignatureRequest, ser-
cancelAuthUser (v2), service 88 vice 108
cancelLogin (v1), service 92 getServerTime, service 41
configuring SSL/TLS 122

H
D
HTTP method 14
DIGIPASS Gateway 5
API changes 127
architectural changes 126 I
workflow changes 126
instanceActivation (v1), service 59
DIGIPASS Gateway documentation

Index
135
DIGIPASS Gateway Integration Guide
L provisioning
activate (v1) service 53
licenseActivation (v1), service 61 addDevice (v1) service 55
bind service 57
DSAPPActivate service 23
M DSAPPGenerateActivationData ser-
MdlActivate (v1), service 45 vice 25
MdlActivate (v2), service 43 DSAPPMdlAddDevice service 28
MdlAddDevice (v1), service 49 DSAPPRegister (v2) service 30
MdlAddDevice (v2), service 47 DSAPPSRPGenerateActivationData
MdlRegister (v2), service 51 (v1) service 34
DSAPPSRPGenerateEphemeralKey
(v1) service 39
N DSAPPSRPGenerateEphemeralKey
(v2) service 37
notification registration 111
getServerTime service 41
notifications
instanceActivation (v1) service 59
sendNotification (v1) service 115
licenseActivation (v1) service 61
sendNotification (v2) service 113
MdlActivate (v1) service 45
updateNotificationID (v2)
MdlActivate (v2) service 43
service 117
MdlAddDevice (v1) service 49
updateNotificationID service 119
MdlAddDevice (v2) service 47
MdlRegister (v2) service 51
postActivation (v1) service 63
O register (v1) service 65
OneSpan Mobile Security Suite 14 registerOffline (v1) service 67
online (v1), service 79 registerOnline (v1) service 69
online activation 20 signature (v1) service 71
activation image 21 synchronize service 73
online authentication 76 push and login 82
authUser (v2) service 77 login request content 84
online (v1) service 79 push notification content 83
out-of-band authentication 82 push and login authentication 82
authUser (v2) service 86
cancelAuthUser (v2) service 88
P cancelLogin (v1) service 92
getPreparedSecureChallenge (v2)
POST, HTTP method 14
service 90
postActivation (v1), service 63
retrieveLogin (v1) service 94
protecting the DIGIPASS Gateway API
signLogin (v1) service 96
key, Caution notice 17
push and sign 99
push notification content 100

Index
136
DIGIPASS Gateway Integration Guide
 signature request content 101

R
register (v1), service 65
registerOffline (v1), service 67
registerOnline (v1), service 69
retrieveLogin (v1), service 94

S
Secure Channel 83-85, 101-102
sendNotification (v1), service 115
sendNotification (v2), service 113
signature (v1), service 71
signLogin (v1), service 96
synchronize, service 73

T
transaction data signing 99
authSignature service 103
cancelAuthSignatureRequest ser-
vice 106
getPreparedSignatureRequest ser-
vice 108
out-of-band signing 99
using push notifications 99

U
updateNotificationID (v2), service 117
updateNotificationID, service 119

Index
137
DIGIPASS Gateway Integration Guide