DIGIPASS Gateway Overview

DIGIPASS Gateway acts as a front-end infrastructure that handles the online communication between OneSpan Authentication Server on one side, and OneSpan Mobile Authenticator, customized solutions of Mobile Authenticator Studio, and mobile applications integrating OneSpan Mobile Security Suite on the other.

It is usually deployed in the demilitarized zone (DMZ) and isolates OneSpan Authentication Server from the (untrusted) mobile applications' networks.

Overview

DIGIPASS Gateway exposes services to mobile applications via a REST API that uses JSON (see Requests handled by DIGIPASS Gateway service endpoints (v2)). By default, the services are exposed via the following URI:

dpgateway_host:dpgateway_port/context_path/rest/v2/functionality/service

where:

• dpgateway_host is the host running DIGIPASS Gateway.

• dpgateway_port is the port of the DIGIPASS Gateway service, by default 11080 (TCP).

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

• functionality is the name of the functionality group, e.g. provisioning.

• 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

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:

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

• 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 reference.

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

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

Authorization: Basic MTIzNDU2Og==

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, see the DIGIPASS Gateway Getting Started Guide.

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.

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.

API versions

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

API version 1 is deprecated and provided for backward-compatibility reasons and migration purposes only! Use only API version 2 for new implementations.