Customization schema for single-device licensing legacy

Prev Next

When Mobile Authenticator Studio is integrated in multi-device licensing (MDL) legacy mode, the following schema can be used to customize the mobile app. For sample code to create your customization file, see Example: JSON customization single-device licensing legacy integration.

Type: object

config Required

root > config

Type: object

No Additional Properties

appName Required

root > config > appName

Type: string

Description

Display name of the application.

Constraints

The app name can contain any character with a maximum string length of 30 characters for an Android and iOS application name.

Must match regular expression: ^.{1,30}$

staticVector Required

root > config > staticVector

Type: string

Description

Initial static vector.

Constraints

No maximum string length. Must be hexadecimal characters.

Must match regular expression: ^[0-9A-Fa-f]+$

ios

root > config > ios

Type: object

No Additional Properties

buildNumber Required

root > config > ios > buildNumber

Type: string

Description

Number of the app build.

Constraints

Build version must only contain numeric characters (0-9).

Must match regular expression: ^[0-9]+$.

Example:

"1000"

appVersion Required

root > config > ios > appVersion

Type: string

Description

Version of the app.

Constraints

The required format is three, period-separated, integers. The string can only contain numeric characters (0-9) and periods.

Must match regular expression: ^(([0-9]+\.){1,2})?[0-9]+$

Example:

"1.0.0"

android

root > config > android

Type: object

No Additional Properties

packageName Required

root > config > android > packageName

Type: string

Description

Name of the Android app package.

Constraints

Technically,  the package name can be anything, but we highly recommend using a reverse domain name format (see example below). The name may contain uppercase or lowercase letters ('A' through 'Z'), numbers, and underscores ('_'). However, individual package name parts must only start with letters.

Must match regular expression: ^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)+[A-Za-z0-9_]$

Example:

"com.onespan.appname"

buildNumber Required

root > config > android > buildNumber

Type: string

Description

Number of the app build.

Constraints

Build version must only contain numeric characters (0-9).

Must match regular expression: ^[0-9]+$.

Example:

"1000"

appVersion Required

root > config > android > appVersion

Type: string

Description

Version of the app.

Constraints

The required format is three, period-separated, integers. The string can only contain numeric characters (0-9) and periods.

Must match regular expression: ^(([0-9]+\.){1,2})?[0-9]+$

Example:

"1.0.0"

features

root > config > features

Type: object

No Additional Properties

protection

root > config > features > protection

Type: boolean Default: false

Description

Defines whether the app should be protected with a PIN code.

deleteInstance

root > config > features > deleteInstance

Type: boolean Default: false

Description

Defines whether the feature to delete an instance should be enabled.

renameInstance

root > config > features > renameInstance

Type: boolean Default: false

Description

Defines whether the feature to rename an instance should be enabled.

multiInstance

root > config > features > multiInstance

Type: boolean Default: false

Description

Defines whether the multi-instance feature should be enabled.

changeLanguage

root > config > features > changeLanguage

Type: boolean Default: false

Description

Defines whether the feature to change the language from the Settings menu of the app should be enabled.

helpUrl

root > config > features > helpUrl

Type: string

Description

The URL to display a help page.

Constraints

No constraints. Can only be used with https.

Must match regular expression: ^(http|https)://.+$

oneTimePassword

root > config > features > oneTimePassword

Type: object

No Additional Properties

identifier

root > config > features > oneTimePassword > identifier

Type: string

Description

Identifier of the action used for auto-launching the app.

Constraints

Must be unique.

Must match regular expression: ^.*$

cryptoAppIndex Required

root > config > features > oneTimePassword > cryptoAppIndex

Type: string

Description

The crypto-app index used to generate the one-time password (OTP).

Constraints

Must be an integer from 1 to 8.

Must match regular expression: ^[0-8]$

autoLaunch

root > config > features > autoLaunch

Type: object

No Additional Properties

android

root > config > features > autoLaunch > android

Type: object

No Additional Properties

scheme Required

root > config > features > autoLaunch > android > scheme

Type: string

Description

Set the auto-launch scheme to launch the application via another app or a web browser.

Constraints

Alphanumeric string.

Must match regular expression: ^[A-Za-z0-9]+$

ios

root > config > features > autoLaunch > ios

Type: object

No Additional Properties

scheme Required

root > config > features > autoLaunch > ios > scheme

Type: string

Description

Set the auto-launch scheme to launch the application via another app or a web browser.

Constraints

Alphanumeric string.

Must match regular expression: ^[A-Za-z0-9]+$

app2app

root > config > features > autoLaunch > app2app

Type: object

No Additional Properties

android

root > config > features > autoLaunch > app2app > android

Type: object

No Additional Properties

whiteListURLs Required

root > config > features > autoLaunch > app2app > android > whiteListURLs

Type: array of string Default: []

Description

Contains one or more URL elements that indicate which URLs can be used for the app-to-app Secure Channel.                                                          

Constraints

No constraints.

No Additional Items

ios

root >config > features > autoLaunch > app2app > ios

Type: object

No Additional Properties

whiteListURLs Required

root >config > features > autoLaunch > app2app > ios > whiteListURLs

Type: array of string Default: []

Description

Contains one or more URL elements that indicate which URLs can be used for the app-to-app Secure Channel.

Constraints

No constraints.

No Additional Items

identityPinning

root > config > features > identityPinning

Type: object

No Additional Properties

domain Required

root > config > features > identityPinning > domain

Type: string

Description

The domain used for server communication.

Constraints

No constraints. Can only be used with https.

Must match regular expression: ^.*$

keys Required

root > config > features > identityPinning > keys

Type: array

Description

Public keys. Format: SPKI-SHA256-BASE64.

Constraints

The SPKI-SHA256-BASE64 value is calculated from a public key certificate.

Must contain a minimum of 1 item.

No Additional Items

theme Required

root > theme

theme

Type: object

No Additional Properties

primaryColor Required

root > theme > primaryColor

primaryColor

Type: object

Description

The main color of the app.

Constraints

Is followed by a 6-symbol code containing up to three 2-symbol hexadecimal elements. Each of the 2-symbol elements expresses a hexadecimal color value from 0 to 255.

Must match regular expression: ^#[0-9A-Fa-f]{6}$.

Example:

"#11AA11"

assets Required

root > assets

Type: object

No Additional Properties

splashScreenBackgroundColor Required

root > assets > splashScreenBackgroundColor

splashScreenBackgroundColor

Type: string

Description

Background color of the splash screen.

Constraints

Is followed by a 6-symbol code containing up to three 2-symbol hexadecimal elements. Each of the 2-symbol elements expresses a hexadecimal color value from 0 to 255.

Must match regular expression: ^#[0-9A-Fa-f]{6}$.

Example:

"#11AA11"

server Required

root > server

Type: object

No Additional Properties

type Required

root > server  > type

Type: constant

Description

Legacy server configuration. Needed only if a server with XML API is used (to maintain backwards compatibility). It should contain all the online actions supported by the application. All actions should contain url + method + parameters.

Constraints

Specific value: "legacy"

config Required

root > server > config

Type: object

No Additional Properties

domain

root > server > config > domain

Type: string

Description

Default domain name used when no domain name is provided with the user identifier during offline activation.

Constraints

No constraints.

challengeResponse

root > server > config > challengeResponse

Type: object

No Additional Properties

type Required

root > server > config > challengeResponse > type

Type: enum (of string)

Description

Type of Challenge/Response.

Required property, must be one of:
  • scan

  • manual

signatureCryptoAppIndex Required

root > server > config > challengeResponse > signatureCryptoAppIndex

Type: string

Description

Index of the cryptographic application used to sign the transaction.

Constraints

Must be an integer from 1 to 8.

Must match regular expression: ^[0-8]$

identifier

root > server > config > challengeResponse > identifier

Type: string

Description

Identifier of the action used for auto-launching the app.

Constraints

Must be unique.

Must match regular expression: ^.*$

activation Required

root > server > config > activation

Type: object

No Additional Properties

type Required

root > server > config > activation > type

Type: constant

Description

Type of activation.

Specific value: "sdl"

identifier

root > server > config > activation > identifier

Type: string

Description

Identifier of the action used for auto-launching the app.

Constraints

Must be unique.

Must match regular expression: ^.*$

modes Required

root > server > config > activation > modes

Type: array of enum (of string)

Description

Activation mode. Can be scanning on image or manually entering activation data.

Must contain a minimum of 1 item. All items must be unique.

All items must be unique.

No Additional Items

Each item of this array must be:


root > server > config > activation > modes > modes items

Type: enum (of string)

Required property, must be one of:

  • image

  • manual


postActivationCryptoAppIndex Required

root > server > config > activation > postActivationCryptoAppIndex

Type: string

Description

The crypto-app index used to generate the post-activation signature.

Constraints

Must be an integer from 1 to 8.

Must match regular expression: ^[0-8]$

useSerialNumber

root > server > config > activation > useSerialNumber

Type: boolean Default: true

Description

Indicates whether a serial number (e.g. FDM1280189) must be entered by the end user during the activation process instead of entering a serial number suffix (i.e. 1280189).

useERC

root > server > config > activation > useERC

useERC

Type: boolean Default: false

Description

Display an input field for the event reactivation counter (ERC) in the SDL offline activation process.

binding

root > server > config > activation > binding

Type: boolean Default: true

Description

Indicates whether the device binding feature is enabled (SDL only). The generated response will be a one-time password (OTP) (false) or a derivation code (true).

transactionDataSigning

root > server > config > transactionDataSigning

Type: object

Description

Transaction data signing (TDS) action.

No Additional Properties

authenticationCryptoAppIndex Required

root > server > config > transactionDataSigning > authenticationCryptoAppIndex

Type: string

Description

Index of the cryptographic application used for authentication that is needed to download the pending transaction list.

Constraints

Must be an integer from 1 to 8.

Must match regular expression: ^[0-8]$

signatureCryptoAppIndex

root > server > config > transactionDataSigning > signatureCryptoAppIndex

Type: string

Description

Index of the cryptographic application used to sign the transaction.

Constraints

Must be an integer from 1 to 8.

Must match regular expression: ^[0-8]$

identifier Required

root > server > config > transactionDataSigning > identifier

Type: string

Description

Identifier of the action.

Constraints

Must be unique.

Must match regular expression:^.*$

config Required

root > server > config > transactionDataSigning > config

Type: object

No Additional Properties

transactionList Required

root > server > config > transactionDataSigning > config > transactionList

Type: object

No Additional Properties

url Required

root > server > config > transactionDataSigning > config > transactionList > url

Type: string

Description

URL linked to the action.

Constraints

No constraints. Can only be used with https.

Must match regular expression: ^(http|https)://.+$

method Required

root > server > config > transactionDataSigning > config > transactionList > method

Type: string

Description

HTTP method linked to the action.

Constraints

POST or GET.

Must match regular expression: ^(POST|GET)$

parameters Required

root > server > config > transactionDataSigning > config > transactionList > parameters

Type: array of object Default: []

Description

The payload parameters, with keys and values.

Constraints

The values might be masks. Can be an empty array.

No Additional Items

Each item of this array must be:


root > server > config > transactionDataSigning > config > transactionList > parameters > items

Type: object

No Additional Properties

key Required

root > server > config > transactionDataSigning > config > transactionList > parameters > items > key

Type: string

Must match regular expression: ^.*$

value Required

root > server > config > transactionDataSigning > config > transactionList > parameters > items > value

Type: string

Must match regular expression: ^.*$


Example:

[
    {
        "key": "key1",
        "value": "value1"
    },
    {
        "key": "key2",
        "value": "%_SerialNumber_%"
    }
]

transactionValidation Required

root > server > config > transactionDataSigning > config > transactionValidation

Type: object

No Additional Properties

url Required

root > server > config > transactionDataSigning > config > transactionValidation > url

Type: string

Description

URL linked to the action.

Constraints

No constraints. Can only be used with https.

Must match regular expression: ^(http|https)://.+$

method Required

root > server > config > transactionDataSigning > config > transactionValidation > method

Type: string

Description

HTTP method linked to the action.

Constraints

POST or GET.

Must match regular expression: ^(POST|GET)$

parameters Required

root > server > config > transactionDataSigning > config > transactionValidation > parameters

Type: array of object Default: []

Description

The payload parameters, with keys and values.

Constraints

The values might be masks. Can be an empty array.

No Additional Items

Each item of this array must be:


root > server > config > transactionDataSigning > config > transactionValidation > parameters > items

Type: object

No Additional Properties

key Required

root > server > config > transactionDataSigning > config > transactionValidation > parameters > items > key

Type: string

Must match regular expression: ^.*$

value Required

root > server > config > transactionDataSigning > config > transactionValidation > parameters > items > value

Type: string

Must match regular expression: ^.*$


Example:

[
    {
        "key": "key1",
        "value": "value1"
    },
    {
        "key": "key2",
        "value": "%_SerialNumber_%"
    }
]

transactionRejection Required

root > server > config > transactionDataSigning > config > transactionRejection

Type: object

No Additional Properties

url Required

root > server > config > transactionDataSigning > config > transactionRejection > url

Type: string

Description

URL linked to the action.

Constraints

No constraints. Can only be used with https.

Must match regular expression: ^(http|https)://.+$

method Required

root > server > config > transactionDataSigning > config > transactionRejection > method

Type: string

Description

HTTP method linked to the action.

Constraints

POST or GET.

Must match regular expression: ^(POST|GET)$

parameters Required

root > server > config > transactionDataSigning > config > transactionRejection > parameters

Type: array of object Default: []

Description

The payload parameters, with keys and values.

Constraints

The values might be masks. Can be an empty array.

No Additional Items

Each item of this array must be:


root > server > config > transactionDataSigning > config > transactionRejection > parameters > items

Type: object

No Additional Properties

key Required

root > server > config > transactionDataSigning > config > transactionRejection > parameters > items > key

Type: string

Must match regular expression: ^.*$

value Required

root > server > config > transactionDataSigning > config > transactionRejection > parameters > items > value

Type: string

Must match regular expression: ^.*$


Example:

[
    {
        "key": "key1",
        "value": "value1"
    },
    {
        "key": "key2",
        "value": "%_SerialNumber_%"
    }
]

responseValidation

root > server > config > responseValidation

Description

Response validation action.

No Additional Properties

All of

root > server > config > responseValidation > All of > Requirement 1

Type: object

Conditional Subschema

If the conditions in the if section are met, the conditions in the then section should also be met. Otherwise, the conditions in the then section must not be present.

if

root > server > config > responseValidation > All of > Requirement 1 > if

Type: object

type

root > server > config > responseValidation > All of > Requirement 1 > if > type

Type: enum (of string)

Required property, must be one of:
  • scanOnline

  • manualOnline

then

root > server > config > responseValidation > All of > Requirement 1 > if > then

Type: object

config

root > server > config > responseValidation > All of > Requirement 1 > if > then > config                        

Type: object

Required properties:

validationEndpoint

root > server > config > responseValidation > All of > Requirement 2

Type: object

Conditional Subschema

If the conditions in the if section are met, the conditions in the then section should also be met. Otherwise, the conditions in the then section must not be present.

if

root > server > config > responseValidation > All of > Requirement 2 > if

Type: object

type

root > server > config > responseValidation > All of > Requirement 2 > if > type

Type: enum (of string)

Required property, must be one of:
  • manualOnline

  • manualOffline

then

root > server > config > responseValidation > All of > Requirement 1 > if > then

Type: object

config

root > server > config > responseValidation > All of > Requirement 1 > if > then > config                        

Type: object

Required properties:

dataFields

root > server > config > responseValidation > All of > Requirement 3

Type: object

Conditional Subschema

If the conditions in the if section are met, the conditions in the then section should also be met. Otherwise, the conditions in the then section must not be present.

if

root > server > config > responseValidation > All of > Requirement 3 > if

Type: object

type

root > server > config > responseValidation > All of > Requirement 3 > if > type

Type: enum (of string)

Required property, must be one of:
  • scanOnline

  • scanOffline

then

root > server > config > responseValidation > All of > Requirement 3 > then

Type: object

config

root > server > config > responseValidation > All of > Requirement 3 > then > config

Type: object

dataFields

type Required

root > server > config > responseValidation > type

Type: enum (of string)

Description

Possible values:

  • scanOnline

  • scanOffline for scan and sign

  • manualOnline

  • manualOffline for manual signing

Required property, must be one of:
  • scanOnline

  • scanOffline

  • manualOnline

  • manualOffline

signatureCryptoAppIndex Required

root > server > config > responseValidation > signatureCryptoAppIndex

Type: string

Description

Index of the cryptographic application used to sign the transaction.

Constraints

Must be an integer from 1 to 8.

Must match regular expression: ^[0-8]$

identifier

root > server > config > responseValidation > identifier

Type: string

Description

Identifier of the action used for auto-launching the app.

Constraints

Must be unique.

Must match regular expression: ^.*$

config

root > server > config > responseValidation > config

Type: object

No Additional Properties

dataFields

root > server > config > responseValidation > config > dataFields

Type: array of string Default: []

Description

The list of keys defined in the CSV file containing the names of the data fields for each language.

Constraints

Applies only for manual signing.

No Additional Items

Each item of this array must be:


root > server > config > responseValidation > config > dataFields > dataFields items

Type: string


Example:

[
    "datafield1",
    "datafield2",
    "datafield3"
]

validationEndpoint

root > server > config > responseValidation > config > validationEndpoint

Type: object

Description

The configuration setting to validate the response.

No Additional Properties

url Required

root > server > config > responseValidation > config > validationEndpoint > url

Type: string

Description

URL linked to the action.                                              

Constraints

No constraints. Can only be used with https.

Must match regular expression: ^(http|https)://.+$

method Required

root > server > config > responseValidation > config > validationEndpoint > method

Type: string

Description

HTTP method linked to the action.

Constraints

Must be POST or GET.

Must match regular expression: ^(POST|GET)$

parameters Required

root > server > config > responseValidation > config > validationEndpoint > parameters

Type: array of object Default: []

Description

The payload parameters, with keys and values.

Constraints

The values might be masks. Can be an empty array.

No Additional Items

Each item of this array must be:


root > server > config > responseValidation > config > validationEndpoint > parameters > items

Type: object

No Additional Properties

key Required

root > server > config > responseValidation > config > validationEndpoint > parameters > items > key

Type: string

Must match regular expression: ^.*$

value Required

root > server > config > responseValidation > config > validationEndpoint > parameters > items > value

Type: string

Must match regular expression: ^.*$


Example:

[
    {
        "key": "key1",
        "value": "value1"
    },
    {
        "key": "key2",
        "value": "%_SerialNumber_%"
    }
]

legacy

root > legacy

Type: object

Description

Legacy migration values for migrating data from older versions of Mobile Authenticator Studio to version 5.0 and later.

No Additional Properties

android Required

root > legacy > android

Type: object

No Additional Properties

deviceIdentificationMethod

root > legacy > android > deviceIdentificationMethod

Type: string

Description

The method used to generate the platform fingerprint for the authenticator instance that is being migrated.

deviceIdentificationMigrationEnabled

root > legacy > android > deviceIdentificationMigrationEnabled

Type: boolean Default: false

Description

Flag used to inform Mobile Authenticator Studio which method to use for fingerprint generation. Required for migrations from any version prior to 4.14.3.