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
| Request | Action | Functionality |
|---|---|---|
| DSAPPActivate | Performs a provisioning activation operation using DSAPP (see DSAPPActivate (service)). | Online activation |
| DSAPPMdlAddDevice | Registers a new device that supports Secure Channel activation (see DSAPPMdlAddDevice (service)). | Online activation |
| DSAPPRegister | Performs a provisioning registration operation using DSAPP (see DSAPPRegister (service)). | Online activation |
| DSAPPSRPGenerateActivationData | Retrieves Activation Message 1 (license) (see DSAPPSRPGenerateActivationData (service) [v2]). | Online activation |
| DSAPPSRPGenerateEphemeralKey | Initializes the activation process by exchanging public keys (see DSAPPSRPGenerateEphemeralKey (service) [v2]). | Online activation |
| getServerTime | Retrieves the current server time as Unix time (see getServerTime (service)). | Online activation |
| MdlActivate | Finalizes the activation process (see MdlActivate (service) [v2]). | Online activation |
| MdlAddDevice | Retrieves Activation Message 2 (instance) (see MdlAddDevice (service) [v2]). | Online activation |
| MdlRegister | Generates Activation Message 2 for a specific user (see MdlRegister (service) [v2]). | Online activation |
| authUser | Performs an online authentication (see authUser (service)). | Online authentication |
| authUser | Completes a pending push and login authentication (see authUser (service) [v2]). | Push and login |
| cancelAuthUser | Cancels a pending push and login request (see cancelAuthUser (service) [v2]). | Push and login |
| getPreparedSecureChallenge | Retrieves a prepared authentication request (see getPreparedSecureChallenge (service) [v2]). | Push and login |
| authSignature | Completes a pending data signing transaction (see authSignature (service)). | Push and sign |
| cancelAuthSignatureRequest | Cancels a pending data signing transaction (see cancelAuthSignatureRequest (service)). | Push and sign |
| getPreparedSignatureRequest | Retrieves a prepared signature request for transaction data signing (see getPreparedSignatureRequest (service)). | Push and sign |
| sendNotification | Sends a push notification message to a user (see sendNotification (service) [v2]). | Notification |
| updateNotificationID | Registers a mobile application to receive notifications (see updateNotificationID (service) [v2]). | Notification |
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.