App Shielding configuration

If you would like to use this feature, enable the Updatable Configuration option on the OneSpan Mobile Portal.

Client configuration

With this option, you can specify whether the app will use the Automatic Configuration feature.

When you enable this option, the portal displays additional configuration fields:

  • Request timeout (seconds): Specify the duration in seconds before the client device stops connecting to the server and sends a request timeout error.

  • Config Identifier: Identify for which application the configuration update is intended. If this option is set in the App Shielding configuration, only updatable configurations with the same value are considered valid. This means, a configuration update file must contain the identical config identifier as the original configuration for the app, and must be created with the exact same version of App Shielding.

    If not specified or set to an empty string, the config identifier is set to the package ID of the app, which means that any configuration update for the app must be created with the same input app. However, using the config identifier option allows for multiple apps to use a common source for the updatable configuration file.

  • Certificate type: Use this field to upload your server certificate in the .pem file format.

  • URL: Specify the URL of the web page where the configuration can be downloaded. The server must be running with a config.dat file accessible in the destination path.

    It is possible to use substitution variables encoded in the URL, consistent with the substitution variables launching Exit URL. For more information, see URL variable substitution.

  • Client Certificate: Upload a TLS client certificate. This must be exported as a base64 string from a pkcs12 file.

    The base64 string can be extracted from the pkcs12 file using this command:

    base64 client_cert.p12 > client_cert.b64
  • Password: Password used to generate the pkcs12 client certificate file.

URL variable substitution

It is possible to use substitution variables that are encoded in the URL and which are consistent with the substitution variables for launching Exit URL. This allows the web server to be optionally scripted to answer as required, depending on the available variables. The following substitution variables are available:

URL substitution variables
Placeholder Substitution
%MANUFACTURER% The device manufacturer.
%MODEL% The device model name.
%ANDROID% The Android API level of the device (example: 28).
%IOS% The iOS version..
%VERSION% The Shield version (example: 2.8.5).
%PKGID% The application package or bundle ID. (example: com.example.myapp)
%PKGVERSION% The application package version string.
%CREATED% The configuration time stamp/version.

The %PKGID%, %PKGVERSION%, %CREATED%, and %VERSION% variables are substituted at the time of configuration encoding, while App Shielding substitutes all other variables during runtime.

For more information about launching Exit URLs, see Exit URL Launching.

Using these variables allows you to target configuration updates for specific devices, OS versions, or apps. For example:

https://config-update.example.com/%PKGID%/%VERSION%/new_config.dat

You can also use the variables in a query string to, for instance, gather data on the types of devices that are being used for the given app. For example:

https://configupdate.example.com/new_config.dat?dev=%MANUFACTURER%&mod=%MODEL%&pkg=%PKGID%

Server configuration

For App Shielding to be able to connect to an HTTPS server, the corresponding httpsServer element must be added under the httpsOptions element of your App Shielding configuration. For example:

<httpsOptions>
  <httpsServer>
    <URL  v="https://config-update.example.com" />
    <serverCertificateVerificationPolicy v="pinServerCertificate" />
    <allowedServerCertificate>
      cErtInBaSE64=
    </allowedServerCertificate>
  </httpsServer>
</httpsOptions>

The following options inside the httpsServer element are supported:

Server configuration options
Option Requirements
URL Required.
serverCertificateVerificationPolicy Required and must be either pinServerCertificate or verifyUsingRootCACertificate.
allowedServerCertificate Required if using pinServerCertificate.
allowedRootCACertificate Required if using verifyUsingRootCACertificate.
clientCertificatePKCS12 Optional.
clientCertificatePKCS12Password Optional.