Configure DIGIPASS Gateway

You can use the OneSpan Web Configuration Tool to configure DIGIPASS Gateway.

To complete the initial configuration of DIGIPASS Gateway, you usually need to configure:

• OneSpan Authentication Server connection and SSL certificate settings (see Configure OneSpan Authentication Server instances and server certificates).
• DIGIPASS Gateway client components used by OneSpan Authentication Server (see Configure OneSpan Authentication Server client components).
• API keys used for HTTP authentication when connecting to DIGIPASS Gateway (see Configure DIGIPASS Gateway API keys).
• Notification web service settings for DIGIPASS Gateway (see Configure push notification web services).
• Optionally, the IP address ranges of clients allowed to send requests to DIGIPASS Gateway (see Configure allowed source IP address ranges).

When changing configuration settings you need to restart your web or Java application server for the configuration changes to become effective!

If you 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 certificate) and client components automatically to use the local OneSpan Authentication Server deployment.

If you want to configure a DIGIPASS Gateway web service that you have manually deployed to an existing web or Java application server, you need to use the OneSpan Web Configuration Tool shipped with the web application file and invoke it as follows:

java -Dcom.onespan.dpgateway.config.file=properties_file -jar admintool.jar ...

Configure OneSpan Authentication Server instances and server certificates

When deploying DIGIPASS Gateway manually to an existing web or Java application server, you should use the OneSpan Web Configuration Tool Java executable (admintool.jar). Use this to configure the OneSpan Authentication Server instances only, and use the Java Key and Certificate Management Tool (keytool) to configure the respective certificates.

To configure a OneSpan Authentication Server instance and automatically retrieve and add the respective server certificates to the trust store use the following command:

admintool type dpgateway autoadd name url connection_limit connection_timeout

where:

• name is the display name of the OneSpan Authentication Server entry. Valid values are primary and backup to set a primary and backup server instance, respectively. You need to set at least a primary server instance.
• url is the IP address (or FQDN) and SOAP port of the OneSpan Authentication Server instance, including the protocol string.
• connection_limit is optional and currently not used by DIGIPASS Gateway. However, connection_limit is required if connection_timeout is specified.

• connection_timeout is optional and specifies the timeout to establish a connection to the server instance. If no connection to the primary server can be established and a backup server instance is configured, DIGIPASS Gateway uses the backup server, and vice versa.

  If DIGIPASS Gateway falls back to the backup server, DIGIPASS Gateway keeps using the backup server until it becomes unreachable. To force DIGIPASS Gateway to use the primary server again, you need to restart DIGIPASS Gateway.

  You can use system monitoring to automatically receive notifications as soon as DIGIPASS Gateway starts using the backup server instance. To do so, create a system monitoring filter on the backup server instance, which filters for Success audit messages with the following field conditions:

  • Client Location equals "dpgateway_location"
  • Input Details includes "{Component Type : DIGIPASS Gateway}"

  For more information about system monitoring, refer to the OneSpan Authentication Server Administrator Guide, section "Monitoring".

 

Set the primary server using https at address 192.0.2.1 and port 8888 and automatically add the respective SSL certificate for the specified server to the trust store, if available:

admintool type dpgateway autoadd primary https://192.0.2.1:8888

To avoid high-availability issues with push–notification-based authentication via OneSpan Mobile Authenticator, DIGIPASS Gateway must use the same primary and backup OneSpan Authentication Server instances that are configured for the application server(s) initiating the Push Notification authentication requests for OneSpan Mobile Authenticator.

To add a OneSpan Authentication Server instance only without adding any server certificates to the trust store, use admintool server add (see Configure OneSpan Authentication Server instances).

To add a server certificate for an existing OneSpan Authentication Server instance, use admintool certificate add (see Configure server certificates for OneSpan Authentication Server instances).

Configure OneSpan Authentication Server instances

To configure a OneSpan Authentication Server instance use the following command:

admintool type dpgateway server add name url connection_limit connection_timeout

where:

• name is the display name of the OneSpan Authentication Server entry. Valid values are primary and backup to set a primary and backup server instance, respectively. You need to set at least a primary server instance.
• url is the IP address (or FQDN) and SOAP port of the OneSpan Authentication Server instance, including the protocol string.
• connection_limit is optional and currently not used by DIGIPASS Gateway. However, connection_limit is required if connection_timeout is specified.

• connection_timeout is optional and specifies the timeout to establish a connection to the server instance. If no connection to the primary server can be established and a backup server instance is configured, DIGIPASS Gateway uses the backup server, and vice versa.

  If DIGIPASS Gateway falls back to the backup server, DIGIPASS Gateway keeps using the backup server until it becomes unreachable. To force DIGIPASS Gateway to use the primary server again, you need to restart DIGIPASS Gateway.

 

Set the primary server using https at address 192.0.2.1 and port 8888:

admintool type dpgateway server add primary https://192.0.2.1:8888

To avoid high-availability issues with push–notification-based authentication via OneSpan Mobile Authenticator, DIGIPASS Gateway must use the same primary and backup OneSpan Authentication Server instances that are configured for the application server(s) initiating the Push Notification authentication requests for OneSpan Mobile Authenticator.

To add a server certificate for an existing OneSpan Authentication Server instance, use admintool certificate add (see Configure server certificates for OneSpan Authentication Server instances).

To add a OneSpan Authentication Server instance and automatically retrieve and add the respective server certificate to the trust store in one step, use admintool autoadd (see Configure OneSpan Authentication Server instances and server certificates).

Configure server certificates for OneSpan Authentication Server instances

The certification authority (CA) for the certificate of the OneSpan Authentication Server instance must be added to the trust store of DIGIPASS Gateway. In the case of a self-signed certificate, this will be the self-signed certificate itself.

When deploying DIGIPASS Gateway manually to an existing web or Java application server, you should use the OneSpan Web Configuration Tool Java executable (admintool.jar). Use this to configure the OneSpan Authentication Server instances only, and use the Java Key and Certificate Management Tool (keytool) to configure the respective certificates.

To add the SSL certificate for SOAP connections to the OneSpan Authentication Server instance to the trust store use the following command:

admintool type dpgateway certificate add certificate_file

where:

• certificate_file is the path to the OneSpan Authentication Server SSL certificate used by the SOAP communicator.

  By default, the self-signed certificates created when installing OneSpan Authentication Server are located in:

  • /etc/vasco/ias (Linux)
  • %PROGRAMFILES%\VASCO\IDENTIKEY Authentication Server\bin (Windows)

  The CA certificate used for the DIGIPASS Gateway trust store should be the SOAP communicator SSL certification authority, i.e. ikey_soap_serverca.pem.

 

Add the ikey_soap_serverca.pem CA certificate to the default trust store:

./admintool type dpgateway certificate add /etc/vasco/ias/ikey_soap_serverca.pem (Linux)

admintool type dpgateway certificate add "%PROGRAMFILES%\VASCO\IDENTIKEY Authentication Server\bin\ikey_soap_serverca.pem" (Windows)

Ensure that the connection URL to the server is specified to use https if you add a certificate.

To add a OneSpan Authentication Server instance only without adding any server certificates to the trust store, use admintool server add (see Configure OneSpan Authentication Server instances).

To add a OneSpan Authentication Server instance and automatically retrieve and add the respective server certificate to the trust store in one step, use admintool autoadd (see Configure OneSpan Authentication Server instances and server certificates).

Configure OneSpan Authentication Server client components

OneSpan Authentication Server requires a client component record to be created for each DIGIPASS Gateway client installed at different locations (IP address).

To specify the client component DIGIPASS Gateway should use when connecting to OneSpan Authentication Server use the following command:

admintool type dpgateway component set component_type component_name

where:

• component_type is the client component type to configure, i.e. one of the following:

  • authentication
  • authentication.secure_channel
  • provisioning.dp4mobile
  • provisioning.mdl
  • signature
  • signature.secure_channel
• component_name is the client component to use as created in OneSpan Authentication Server (see Create a client component in OneSpan Authentication Server). By default, the value for all client components is set to DIGIPASS Gateway.

 

Specify the client component used for push and login activation to be DIGIPASS Gateway:

admintool type dpgateway component set authentication.secure_channel "DIGIPASS Gateway"

Configure push notification web services

This step is not required for OneSpan Mobile Authenticator.

You can set up the corresponding credentials for the notification web service for DIGIPASS Gateway according to the used mobile platform and generic notification settings.

Android notification settings

To authorize your application to access the Firebase Cloud Messaging (FCM) services, you need to generate a private key file for your Firebase service account.

To set up the notification service for Android devices

1. In the Android developer console, enable Cloud Messaging for Android.

2. Generate a Firebase service account key file:

   1. In the Firebase console, switch to the Project settings > Service accounts tab.
   2. Click Generate new private key and confirm.
   3. Download the private key as JSON file.

3. On the DIGIPASS Gateway server, specify the Firebase service account key using the following command:

   admintool type dpgateway push‑notification android‑fcm account_file

   where:

   • account_file is the path and file name of the Firebase service account key file (JSON).

Google Cloud Messaging (GCM) APIs that use a server key string to authorize messaging are deprecated and will be removed in June 2024! If your project still uses such APIs (configured using push-notification android-legacy), you need to migrate at the earliest opportunity.

iOS notification settings

To configure the usage of the development environment for initial development (Apple Sandbox) use the following command:

admintool type dpgateway push‑notification ios‑sandbox use_sandbox

where:

• use_sandbox specifies whether to use the development environment (Apple Sandbox), i.e. true or false (default).

Setting up the credentials for Apple Push Notification service (APNs) depends on the used provider connection trust scheme:

• To set up token-based authentication for APNs use the following command:

  admintool type dpgateway push‑notification ios‑p8‑set key_file key_id team_id

  where:

  • key_file is the path and file name of the PKCS #8 key file downloaded from the Apple developer console. It is used to authenticate to the Apple services.
  • key_id is the key identifier of the PKCS #8 key.
  • team_id is the team identifier of your Apple developer account used to create the PKCS #8 key.

• To set up certificate-based authentication for APNs use the following command:

  admintool type dpgateway push‑notification ios‑p12‑set certificate_file certificate_password

  where:

  • certificate_file is the path and file name of the PKCS #12 certificate file. It is used to authenticate to the Apple services.
  • certificate_password is the password used to protect the PKCS #12 certificate.

If you configure both, the certificate-based authentication scheme takes precedence!

To clear the configured credentials use one of the following commands:

admintool type dpgateway push‑notification ios‑p8‑unset

admintool type dpgateway push‑notification ios‑p12‑unset

General notification settings

To specify the general notification service configuration values use the following command:

admintool type dpgateway push‑notification settings threads connection‑timeout terminate‑timeout

where:

• threads is the maximum number of notification threads, by default 20.
• connection_timeout is the connection timeout in milliseconds, by default 20000.
• terminate_timeout is the terminate timeout in milliseconds, by default 60000.

 

admintool type dpgateway push‑notification settings 30 40000 80000

Proxy server settings

By default, DIGIPASS Gateway connects directly to the cloud-based notification services (Apple APNs, Google FCM) via OneSpan cloud infrastructure to send push notification messages.

You can configure a proxy server to relay requests to notification services. DIGIPASS Gateway currently supports two types of proxies:

• HTTP
• SOCKS5

To configure a proxy server for push notifications use the following command:

admintool type dpgateway push‑notification proxy‑set url [username] [password]

where:

• url is the IP address (or FQDN) and port of the proxy server, including the protocol string.
• username and password are the credentials for authentication if required by the proxy server.

Since Java 8 Update 111, proxies requiring Basic authentication will no longer work, since this authentication scheme is disabled by default. If required, Basic authentication can be reactivated by adding the following parameter when starting the Java web application:

‑Djdk.http.auth.tunneling.disabledSchemes="" ...

This is the default behaviour of the Java Runtime Environment (JRE) running the Apache Tomcat web server deployed by the DIGIPASS Gateway installation packages.

 

• Specify an HTTP proxy server without authentication:

  admintool type dpgateway push‑notification proxy‑set http://192.0.2.10:8080

• Specify a SOCKS5 proxy server with credentials used for authentication:

  admintool type dpgateway push‑notification proxy‑set socks5://192.0.2.10:1080 administrator myPassword

To clear the configured proxy server use the following command:

admintool type dpgateway push‑notification proxy‑unset

Configure DIGIPASS Gateway API keys

The API keys are sensitive data and will be used for HTTP authentication when connecting to 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.

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.

To generate and set a DIGIPASS Gateway API key automatically, use the following command:

admintool type dpgateway interface generate

where:

• interface specifies the interface to generate an API key for. Valid values are api‑key‑frontend and api‑key‑backend to set the API key for the front-end or back-end services, respectively.

The generated DIGIPASS Gateway API key is written to the console.

To specify a specific DIGIPASS Gateway API key use the following command:

admintool type dpgateway interface set api_key

 

• Set the front-end API key to MGgUMrg45P9Y:

  admintool type dpgateway api-key-frontend set MGgUMrg45P9Y

For more information, refer to the Push Notification Solution Guide in the OneSpan Authentication Server documentation package.

Configure allowed source IP address ranges

You can restrict the allowed source IP addresses to each specific DIGIPASS Gateway service by explicitly allowing specific CIDR blocks. Requests from hosts that are not explicitly allowed, are denied.

By default, all services that require authentication with the back-end API key are also restricted to the local host. 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 allow requests from any source IP address.

To allow a specific IP address range use the following command:

admintool type dpgateway endpoint allow "service" cidr_block

where:

• service specifies the DIGIPASS Gateway service endpoint, including the prefixing slash mark ('/'). You can use asterisks ('*') anywhere as wildcard characters specifying a matching pattern to set the CIDR block for several services at once. In this case you need to set the value within quotation marks.
• cidr_block specifies an IP 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.

You can use the command more than once to allow additional CIDR blocks.

 

• Allow any host within the IPv4 range 192.0.2.0 to 192.0.2.255 to use any service in the /rest/v2/provisioning group:

  admintool type dpgateway endpoint allow "/rest/v2/provisioning/*" 192.0.2.0/24

• Allow any host within the IPv6 range 2001:db8: to 2001:db8::ffff:ffff to use any service in the /rest/v2/signature group:

  admintool type dpgateway endpoint allow "/rest/v2/signature/*" 2001:db8::/96

• Allow any request from the local host:

  admintool type dpgateway endpoint allow "*" 127.0.0.1/32

To remove specific CIDR blocks previously allowed, use the following command:

admintool type dpgateway endpoint disallow "service" cidr_block

To remove all CIDR blocks previously allowed, use the following command:

admintool type dpgateway endpoint disallow‑all "service"

To list the currently allowed IP address ranges, use the following command:

admintool type dpgateway endpoint show‑rules "service"

 

• Show the allowed IP ranges for any service in the /rest/v2 group, i.e. for all API v2 services:

  admintool type dpgateway endpoint show‑rules "/rest/v2/*"

• Show the allowed IP ranges for the MdlActivate service of any version:

  admintool type dpgateway endpoint show‑rules "*MdlActivate*"

• Show the allowed IP ranges for all services:

  admintool type dpgateway endpoint show‑rules "*"