admintool

Syntax

admintool command [parameter]… [‑‑help] [‑‑quiet]

Command-line options

Table: admintool command-line options
Command Parameters Description
autoadd

name (required)

url (required)

connection_limit

connection_timeout

Performs a server add command. In addition, if an SSL certificate is available for the specified server, it adds it to the trust store. If admintool autoadd can connect to the specified server but cannot retrieve and add the SSL certificate to its trust store, it will not create the server entry.

You may optionally specify the number of concurrent connections allowed (connection_limit) and a connection timeout (connection_timeout). connection_limit is required if connection_timeout is specified.

connection_limit and connection_timeout are only supported by Administration Web Interface and DIGIPASS Gateway.

Can be used with the type command.
server list  

List the configured OneSpan Authentication Server records.

Can be used with the type command.
server add

name (required)

url (required)

connection_timeout

connection_limit

Add a new OneSpan Authentication Server record to the server list displayed in the Administration Web Interface Login page . The parameters name and url are mandatory.

You may optionally specify the number of concurrent connections allowed (connection_limit) and a connection timeout (connection_timeout). connection_limit is required if connection_timeout is specified.

connection_limit and connection_timeout are only supported by Administration Web Interface and DIGIPASS Gateway.

Can be used with the type command.
server delete name (required)

Remove an existing OneSpan Authentication Server record from the server list.

Can be used with the type command.

server default

name (required)

Set the specified OneSpan Authentication Server record as the default server.

Setting a default server is only supported by Administration Web Interface.

Can be used with the type command.
server localaddress

name (required)

local_address (required)

Specify a local IP address to specify when connecting to the provided server name.

Binding to a specific local IP address is only supported by Administration Web Interface.

Can be used with the type command.
type website (required)

Optional. Specify which product or website to configure with the (executive) command (Default: webadmin).

Possible values:

  • dpgateway
  • selfmgmt
  • votp
  • webadmin

If website is set to dpgateway, selfmgmt, or votp, the name parameter of the executive command can only be either primary or backup. If website is set to webadmin, the name parameter can be freely chosen.
certificate list keystore   List all client certificates in the keystore, including their IDs.
certificate list truststore   List all server certificates in the trust store, including their IDs.
certificate add

certificate_file (required)

private_key_file

keystore_password

Server certificate: add the specified certificate to the trust store.

Client certificate: add the specified certificate and associated PEM private key file to the keystore.

The client certificate must use base64 encoding, and its PEM private key file must be unencrypted, in PKCS#8 format, and use DER encoding. Private key will be encoded during the execution of the command.
certificate delete certificate_id (required)

Delete the specified certificate.

The certificate ID is displayed in the output from a certificate list command.
certificate delete keystore   Delete all client certificates from the keystore.
certificate delete truststore   Delete all server certificates from the trust store.
component list

 

Lists the configured client component to be used for a specific type.

Setting the client component is only supported for DIGIPASS Gateway.

Can be used with the type command.
component set

component_type (required)

component_name (required)

Set the client component to be used for a specific type.

Possible values for component_type:

  • authentication
  • authentication.secure_channel
  • provisioning.dp4mobile
  • provisioning.mdl
  • signature
  • signature.secure_channel

Setting the client component is only supported for DIGIPASS Gateway.

Can be used with the type command.
component unset component_type (required)

Unset the specified client component for a specific type.

Possible values for component_type:

  • authentication
  • authentication.secure_channel
  • provisioning.dp4mobile
  • provisioning.mdl
  • signature
  • signature.secure_channel

Unsetting the client component is only supported for DIGIPASS Gateway.

Can be used with the type command.
push‑notification android‑fcm account_file (required)

Set up the notification web service for DIGIPASS Gateway for Android devices using the Firebase Cloud Messaging (FCM) API.

account_file is the Firebase service account key file (JSON format).

Setting up notification web services is only supported for DIGIPASS Gateway.

Can be used with the type command.
push‑notification android‑legacy project_key (required) Deprecated. Use push‑notification android‑fcm instead.
push‑notification ios‑p8‑set

key_file (required)

key_id (required)

team_id (required)

Set up token-based authentication for Apple Push Notification service (APNs) for iOS devices.

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

Setting up notification web services is only supported for DIGIPASS Gateway.

Can be used with the type command.
push‑notification ios‑p8‑unset  

Clear the token-based authentication configuration for Apple Push Notification service (APNs) for iOS devices.

Setting up notification web services is only supported for DIGIPASS Gateway.

Can be used with the type command.
push‑notification ios‑p12‑set

certificate_file (required)

certificate_password (required)

Set up certificate-based authentication for Apple Push Notification service (APNs) for iOS devices.

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

Setting up notification web services is only supported for DIGIPASS Gateway.

Can be used with the type command.
push‑notification ios‑p12‑unset  

Clear the certificate-based authentication configuration for Apple Push Notification service (APNs) for iOS devices.

Setting up notification web services is only supported for DIGIPASS Gateway.

Can be used with the type command.
push‑notification ios‑sandbox use_sandbox (required)

Configure whether to use the development environment (Apple Sandbox) for Apple Push Notification service (APNs) for iOS devices.

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

Setting up notification web services is only supported for DIGIPASS Gateway.

Can be used with the type command.
push‑notification proxy‑set

url (required)

username

password

Configure an HTTP or SOCKS5 proxy server to relay requests to notification services for DIGIPASS Gateway.

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

Setting up a proxy server is only supported for DIGIPASS Gateway.

Can be used with the type command.
push‑notification proxy‑unset  

Remove a configured proxy server for DIGIPASS Gateway.

Setting up a proxy server is only supported for DIGIPASS Gateway.

Can be used with the type command.
push‑notification settings

threads (required)

connection_timeout (required)

terminate_timeout (required)

Set up the general notification web service configuration values for DIGIPASS Gateway.

  • threads is the maximum number of notification threads.
  • connection_timeout is the connection timeout in milliseconds.
  • terminate_timeout is the terminate timeout in milliseconds.

Setting up notification web services is only supported for DIGIPASS Gateway.

Can be used with the type command.
interface generate  

Generate and set a DIGIPASS Gateway API key. The API keys are sensitive data and will be used for HTTP authentication when connecting to DIGIPASS Gateway

Possible values for interface:

  • api-key-backend. Set the API key for the back-end services.
  • api-key-frontend. Set the API key for the front-end services.

Setting an API key is only supported for DIGIPASS Gateway.

Can be used with the type command.
interface list  

Display the API key currently set.

Possible values for interface:

  • api-key-backend. Display the API key for the back-end services.
  • api-key-frontend. Display the API key for the front-end services.

Setting an API key is only supported for DIGIPASS Gateway.

Can be used with the type command.
interface set api_key (required)

Specify a DIGIPASS Gateway API key. The API keys are sensitive data and will be used for HTTP authentication when connecting to DIGIPASS Gateway.

Possible values for interface:

  • api-key-backend. Set the API key for the back-end services.
  • api-key-frontend. Set the API key for the front-end services.

Setting an API key is only supported for DIGIPASS Gateway.

Can be used with the type command.
interface unset  

Clear the DIGIPASS Gateway API key currently set.

Possible values for interface:

  • api-key-backend. Clear the API key for the back-end services.
  • api-key-frontend. Clear the API key for the front-end services.

Setting an API key is only supported for DIGIPASS Gateway.

Can be used with the type command.
endpoint allow

service (required)

cidr_block (required)

Allow the specified service endpoint to accept requests from any host within the specified IP address range.

  • service specifies the DIGIPASS Gateway service endpoint, including the prefixing slash mark ('/'). You can use asterisks ('*') as wildcard characters specifying a matching pattern to configure several services at once; in that case you need to set the value within quotation marks, e.g. "/rest/v2/provisioning/*".
  • cidr_block specifies an IP address range using CIDR notation, e.g. 192.0.2.0/24. You can specify multiple CIDR blocks at once as comma-separated list.

Configuring IP restrictions is only supported for DIGIPASS Gateway.

Can be used with the type command.
endpoint disallow

service (required)

cidr_block (required)

Remove a specific IP address range previously allowed for the specified service endpoint.

  • service specifies the DIGIPASS Gateway service endpoint, including the prefixing slash mark ('/'). You can use asterisks ('*') as wildcard characters specifying a matching pattern to configure several services at once; in that case you need to set the value within quotation marks, e.g. "/rest/v2/provisioning/*".
  • cidr_block specifies an IP address range using CIDR notation, e.g. 192.0.2.0/24. You can specify multiple CIDR blocks at once as comma-separated list.

Configuring IP restrictions is only supported for DIGIPASS Gateway.

Can be used with the type command.
endpoint disallow‑all service (required)

Remove all IP address ranges currently allowed for the specified service endpoint.

  • service specifies the DIGIPASS Gateway service endpoint, including the prefixing slash mark ('/'). You can use asterisks ('*') as wildcard characters specifying a matching pattern to configure several services at once; in that case you need to set the value within quotation marks, e.g. "/rest/v2/provisioning/*".

Configuring IP restrictions is only supported for DIGIPASS Gateway.

Can be used with the type command.
endpoint show‑rules service (required)

Show the currently allowed IP address ranges for the specified service endpoint.

  • service specifies the DIGIPASS Gateway service endpoint, including the prefixing slash mark ('/'). You can use asterisks ('*') as wildcard characters specifying a matching pattern to list several services at once; in that case you need to set the value within quotation marks, e.g. "/rest/v2/provisioning/*".

Configuring IP restrictions is only supported for DIGIPASS Gateway.

Can be used with the type command.

Exit codes

Table: admintool exit codes
Exit code Description
0 The command completed successfully.
–1 The command did not succeed or no command was specified.
–2 The specified parameters are invalid.

Additional information

  • On Windows, the OneSpan Web Configuration Tool is launched using a batch file, i.e. admintool.bat. On Linux, the OneSpan Web Configuration Tool is launched using a shell script, i.e. admintool.

    The script executes a Java executable file (admintool.jar) using an embedded Java Runtime Environment (JRE), which is included when the OneSpan Web Configuration Tool is installed using the setup.

    You need to use the Java executable directly only, if you want to deploy the Administration Web Interface web application manually to an existing web server instead of using the embedded Apache Tomcat installed with either Web Administration Service (advanced installation) or OneSpan User Websites.

    When deploying and configuring Administration Web Interface manually, you should use the OneSpan Web Configuration Tool Java executable (admintool.jar) to configure the OneSpan Authentication Server instances only, and use the Java Key and Certificate Management Tool (keytool) to configure the respective certificates.

  • When you use admintool autoadd with an FQDN in the connection string, only the first IP address will be used even if the domain name is resolved to more than one IP address by the DNS server. The application will display a warning message in that case.

    Effectively, this should not cause an issue, because all OneSpan Authentication Server client products and web applications will use the first IP address as well. OneSpan Authentication Server will respond on network interfaces that are bound to the IP addresses specified in the server license only. Those IP addresses should align with the IP addresses returned by the DNS server.

  • The URL host component that is used to connect to the OneSpan Authentication Server instance (either IP address, host name, or FQDN) must match the common name (CN) or the subject alternative name (SAN) in the TLS/SSL server certificate for SOAP connections. Otherwise, you will receive an error that the certificate does not match the common name of the certificate subject when Administration Web Interface attempts to connect to OneSpan Authentication Server, e.g. if you are trying to connect via the FQDN, but the certificate is issued for the IP address.