The SOAP provisioning interface provides administrative commands for authenticator provisioning. Most operations are exposed via the provisioningExecute command as subcommands (see Table: provisioningExecute commands (SOAP provisioning)). Some operations (in most cases, operations introduced in more recent product versions) execute one distinct command (see Table: SOAP provisioning commands).
SOAP provisioning commands are not available in the OAS Authentication SDK!
Table: SOAP provisioning commands | Command | Description |
|---|
| dsappSRPActivate | This command activates an authenticator after successful provisioning on OneSpan Authentication Server using Digipass Software Advanced Provisioning Protocol-Secure Remote Password (DSAPP-SRP). It validates the OTP of the newly generated software authenticator or binds it to the mobile device (see dsappSRPActivate (Command)). |
| dsappSRPGenerateActivationData | Generates activation data for either a standard online activation or multi-device licensingActivation Message 1 and encrypts this message by using DSAPP-SRP session keys (see dsappSRPGenerateActivationData (Command)). |
| dsappSRPGenerateEphemeralKey | Exchanges keys for a provisioning registration operation on OneSpan Authentication Server using DSAPP-SRP (see dsappSRPGenerateEphemeralKey (Command) ). |
| dsappSRPRegister | Performs a provisioning registration operation on OneSpan Authentication Server using DSAPP-SRP (see dsappSRPRegister (Command)). |
| getAppUpgradeInfo | Upgrades the mobile authenticator application to a new version to support push notifications (see getAppUpgradeInfo (Command)). |
| provisioningExecute | Generic execute command to wrap (basic) provisioning operations (see Table: provisioningExecute commands (SOAP provisioning)). |
| updateDevicePNID | Updates the device's DIGIPASS Push Notification Identifier (PNID) associated with a specific device (see updateDevicePNID (Command)). |
Table: provisioningExecute commands (SOAP provisioning) | Command | Description |
|---|
| PROVISIONCMD_ACTIVATE | Performs a provisioning activation operation on OneSpan Authentication Server (see PROVISIONCMD_ACTIVATE). |
| PROVISIONCMD_ASSIGN | Performs a provisioning assignment operation on OneSpan Authentication Server (see PROVISIONCMD_ASSIGN). |
| PROVISIONCMD_DSAPPACTIVATE | Performs a provisioning activation operation on OneSpan Authentication Server using DSAPP (see PROVISIONCMD_DSAPPACTIVATE). |
| PROVISIONCMD_DSAPPGENERATEACTIVATIONDATA | Generates activation data for Mobile Authenticator Studio on OneSpan Authentication Server (see PROVISIONCMD_DSAPPGENERATEACTIVATIONDATA). |
| PROVISIONCMD_DSAPPREGISTER | Performs a provisioning registration operation on OneSpan Authentication Server using DSAPP (see PROVISIONCMD_DSAPPREGISTER). |
| PROVISIONCMD_MDL_ACTIVATE | Validates the confirmation code generated by an authenticator when processing Activation Message 2 (see PROVISIONCMD_MDL_ACTIVATE). Supports Response-Only OTP validation and Secure Channel signature validation of the confirmation code. Applies to authenticators compliant with multi-device licensing (MDL). |
| PROVISIONCMD_MDL_ADD_DEVICE | Registers a new device that supports two-step activation (see PROVISIONCMD_MDL_ADD_DEVICE). Applies to authenticators compliant with multi-device licensing (MDL). |
| PROVISIONCMD_MDL_REGISTER | Generates Activation Message 1 for a specified end-user on OneSpan Authentication Server (see PROVISIONCMD_MDL_REGISTER). In a two-step activation scenario, this constitutes the first activation step. Applies to authenticators compliant with multi-device licensing (MDL). |
| PROVISIONCMD_REGISTER | Performs a provisioning registration operation on OneSpan Authentication Server (see PROVISIONCMD_REGISTER). |
| PROVISIONCMD_SERVER_TIME | Retrieves the server time to use in activation and re-activation of Mobile Authenticator Studio. The PROVISIONCMD_SERVER_TIME command supports only the PROVFLD_SERVER_TIME (output) attribute. |
The following field attributes are available for the operations of this command:
Table: SOAP provisioning field attributes | Attribute name | Data type | Description |
|---|
| clientEphemeralPublicKey | String | The client ephemeral public key is required to generate the server ephemeral public key, and is generated during protocol initialization. Hexadecimal string |
| PROVFLD_ACTIVATION_CODE | String | Activation information for the assigned authenticator. Depending on the value of PROVFLD_ACTIVATION_TYPE, the returned code is an online activation code or offline activation data. The online activation code is returned in encrypted full activation data (XFAD) format. The activation code can be encrypted, either with the user's static password (if the policy does not require local or back-end authentication) or with a custom encryption password (specified by PROVFLD_CUSTOM_ENCRYPT_PWD). If neither is specified, the activation code will not be encrypted. |
| PROVFLD_ACTIVATION_CODE_IV | String | The initial vector for PROVFLD_ACTIVATION_CODE if DSAPPv2 is used. |
| PROVFLD_ACTIVATION_MESSAGE | String | The generated activation message. Applies to authenticators compliant with multi-device licensing (MDL). |
| PROVFLD_ACTIVATION_MESSAGE_IV | String | The generated activation message in multi-device activation mode if DSAPPv2 is used. |
| PROVFLD_ACTIVATION_PASSWORD | String | Shared data for DSAPP, i.e. either activation password or authorization code. |
| PROVFLD_ACTIVATION_TYPE | Unsigned Integer | This attribute determines if the register operations (PROVISIONCMD_REGISTER, PROVISIONCMD_MDL_REGISTER) should generate online or offline activation data. Possible values: - 0. Generate online activation data.
- 1. Generate offline activation data.
- If any other integer value is specified, the activation data is derived from the initial configuration in the DPX.
Default value: - 0 for PROVISIONCMD_REGISTER
- DPX configuration for PROVISIONCMD_MDL_REGISTER
|
| PROVFLD_ALEA | String | A pseudo-randomly generated encryption diversifier. Up to 512 characters. Shared data plus alea must not exceed 512 characters. |
| PROVFLD_AUXILIARY_MESSAGE | String | Returned if registration is not successful. |
| PROVFLD_CESPR | String | Deprecated. The change encrypted static password request generated by the Digipass 110 applet. |
| PROVFLD_CHALLENGE | String | The challenge that was presented to the user to generate the password to verify. |
| PROVFLD_CLIENT_HASH | String | Deprecated. The PC hash generated by the DIGIPASS for Web application. |
| PROVFLD_CLIENT_IV | String | The client initial vector. |
| PROVFLD_COMPONENT_TYPE | String | The SOAP client application identifier. |
| PROVFLD_CONFIRM_NEW_STATIC_PASSWORD | String | The confirmation of the new static password to be set. |
| PROVFLD_CUSTOM_ENCRYPT_PWD | String | This is a custom encryption password that can be used to encrypt the activation code (PROVFLD_ACTIVATION_CODE). |
| PROVFLD_DELIVERY_METHOD | String | Specifies and triggers the message delivery via Message Delivery Component (MDC). If this attribute is omitted, notifications will not be sent via MDC. Possible values: |
| PROVFLD_DERIVATION_CODE | String | Contains a derivation code. Must be used when the value for the PROVFLD_REQUEST_TYPE attribute is set to 0. |
| PROVFLD_DESCRIPTION | String | A description of the authenticator instance, as added during multi-device activation. Up to 255 characters. Special characters are replaced with spaces. |
| PROVFLD_DESTINATION | String | The delivery destination, e.g. the destination email address. If this attribute is present, PROVFLD_DELIVERY_METHOD must be present as well. If the PROVFLD_DELIVERY_METHOD attribute is specified but PROVFLD_DESTINATION is omitted, the user account email address will be used. |
| PROVFLD_DEVICE_CODE | String | The code generated by an authenticator when processing the first activation message. Applies to authenticators compliant with multi-device licensing (MDL). |
| PROVFLD_DEVICE_ID | String | The identifier that refers to a specific authenticator. Applies to authenticators compliant with multi-device licensing (MDL). |
| PROVFLD_DEVICE_TYPE | String | The device type for which a new authenticator instance is created. Applies to authenticators compliant with multi-device licensing (MDL). Possible values: - 0. Hardware device
- 1. Unknown software platform
- 3. iOS
- 5. Jailbroken iOS
- 7. Android
- 9. Rooted Android
- 11. Windows Phone
- 13. BlackBerry Native
- 15. MIDP2 Platform or BlackBerry Java
- 17. Windows
- 19. Linux
- 21. Mac
- 23. RFU
|
| PROVFLD_DOMAIN | String | As output, the user's resolved domain will be specified. Up to 255 characters. |
| PROVFLD_DP_RESPONSE | String | Contains a Response-Only OTP. Must be used if the value for the PROVFLD_REQUEST_TYPE attribute is 1. |
| PROVFLD_DSAPP_VERSION | Unsigned Integer | Specifies the DSAPP protocol version number to be used. If this attribute is omitted, the default value is version 1. |
| PROVFLD_ENCRYPTED_CLIENT_PUBLIC_KEY_NONCE | String | The encrypted concatenation of the client public key and the client nonce. Exactly 136 (128+8) characters. |
| PROVFLD_ENCRYPTED_NONCES | String | The concatenation of the server and client nonces encrypted with the chsKey. |
| PROVFLD_ENCRYPTED_SERVER_NONCE | String | The encrypted server nonce received from the client. |
| PROVFLD_ENCRYPTED_SERVER_PUBLIC_KEY | String | The server public key encrypted with chsKey. |
| PROVFLD_EVENT_REACTIVATION_COUNTER | String | Output for the provisioningRegister command. |
| PROVFLD_EVENT_REACTIVATION_COUNTER_IV | String | Output for the provisioningRegister command in standard activation mode if DSAPPv2 is used. |
| PROVFLD_NEW_STATIC_PASSWORD | String | The new static password to be set. |
| PROVFLD_ORGANIZATIONAL_UNIT | String | Indicates the user's resolved organizational unit. Up to 255 characters. |
| PROVFLD_REGISTRATIONID | String | |
| PROVFLD_REQUEST_TYPE | Unsigned Integer | Defines if the authenticator is activated with an OTP (PROVFLD_DP_RESPONSE) or a derivation code with device-binding (PROVFLD_DERIVATION_CODE). If this attribute is omitted, the authenticator is activated with an OTP. |
| PROVFLD_SERVER_IV | String | The server initial vector. |
| PROVFLD_SERIAL_NO | String | The serial number of the authenticator for which the activation code has been generated. When used as an input parameter for PROVISIONCMD_MDL_REGISTER, the serial number needs to be already assigned to the user. Otherwise, activation message generation will fail. Exactly 10 characters. |
| PROVFLD_SERVER_NONCE | String | |
| PROVFLD_SERVER_TIME | Integer | The current system Unix time (POSIX time or UNIX Epoch time), i.e. the number of seconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), not counting leap seconds. Output attribute of the PROVISIONCMD_SERVER_TIME command. |
| PROVFLD_SIGNATURE | String | The signature generated by the authenticator when processing Activation Message 2. |
| PROVFLD_STATIC_PASSWORD | String | The current static password of the user. |
| PROVFLD_STATUS_MESSAGE | String | Returned if registration is not successful. |
| PROVFLD_USERID | String | The user ID as provided by the calling application (no specific format is required). As output, the resolved user ID will be specified. Up to 255 characters. |
| PROVFLD_WEB_PUBLIC_KEY | String | A diversifier value to prevent man-in-the-middle (MITM) attacks. If this parameter is NULL, diversification will not be applied. |
| serverEphemeralPublicKey | String | The server ephemeral public key is used to generate the OneSpan secure remote password (SRP) session key. Hexadecimal string |
PROVISIONCMD_REGISTER
The following attributes can be specified in the attributeSet input parameter of this command:
Table: PROVISIONCMD_REGISTER (Supported input attributes) | Attribute name | Optionality |
|---|
| PROVFLD_ACTIVATION_TYPE | Optional |
| PROVFLD_ALEA | Optional |
| PROVFLD_CLIENT_HASH | Optional |
| PROVFLD_COMPONENT_TYPE | Mandatory |
| PROVFLD_CUSTOM_ENCRYPT_PWD | Optional |
| PROVFLD_DELIVERY_METHOD | Optional |
| PROVFLD_DESTINATION | Optional |
| PROVFLD_DOMAIN | Optional |
| PROVFLD_DP_RESPONSE | Optional |
| PROVFLD_STATIC_PASSWORD | Optional |
| PROVFLD_USERID | Mandatory |
The following attributes will be specified in the results output parameter of this command:
Table: PROVISIONCMD_REGISTER (Supported output attributes) | Attribute name | Returned? |
|---|
| PROVFLD_ACTIVATION_CODE | Always |
| PROVFLD_AUXILIARY_MESSAGE | Always (in error case) |
| PROVFLD_DOMAIN | Always |
| PROVFLD_EVENT_REACTIVATION_COUNTER | If defined
|
| PROVFLD_ORGANIZATIONAL_UNIT | Always
|
| PROVFLD_SERIAL_NO | Always |
| PROVFLD_STATUS_MESSAGE | Always (in error case)
|
| PROVFLD_USERID | Always |
PROVISIONCMD_ACTIVATE
Once the one-time password (OTP) has been successfully validated, this command ends the authenticator grace period.
The following attributes can be specified in the attributeSet input parameter of this command:
Table: PROVISIONCMD_ACTIVATE (Supported input attributes) | Attribute name | Optionality |
|---|
| PROVFLD_CESPR | Optional |
| PROVFLD_CHALLENGE | Optional |
| PROVFLD_COMPONENT_TYPE | Mandatory |
| PROVFLD_CONFIRM_NEW_STATIC_PASSWORD | Optional |
| PROVFLD_DERIVATION_CODE | Optional |
| PROVFLD_DOMAIN | Optional |
| PROVFLD_DP_RESPONSE | Optional |
| PROVFLD_NEW_STATIC_PASSWORD | Optional |
| PROVFLD_REQUEST_TYPE | Optional |
| PROVFLD_STATIC_PASSWORD | Optional |
| PROVFLD_USERID | Mandatory |
| PROVFLD_WEB_PUBLIC_KEY | Optional |
The following attributes will be specified in the results output parameter of this command:
Table: PROVISIONCMD_ACTIVATE (Supported output attributes) | Attribute name | Returned? |
|---|
| PROVFLD_AUXILIARY_MESSAGE | Always (in error case) |
| PROVFLD_DOMAIN | Always |
| PROVFLD_ORGANIZATIONAL_UNIT | Always |
| PROVFLD_SERIAL_NO | Always |
| PROVFLD_STATUS_MESSAGE | Always (in error case) |
| PROVFLD_USERID | Always |
PROVISIONCMD_ASSIGN
The following attributes can be specified in the attributeSet input parameter of this command:
Table: PROVISIONCMD_ASSIGN (Supported input attributes) | Attribute name | Optionality |
|---|
| PROVFLD_CESPR | Mandatory |
| PROVFLD_CHALLENGE | Mandatory |
| PROVFLD_COMPONENT_TYPE | Mandatory |
| PROVFLD_DOMAIN | Optional |
| PROVFLD_SERIAL_NO | Mandatory |
| PROVFLD_STATIC_PASSWORD | Mandatory |
| PROVFLD_USERID | Mandatory |
| PROVFLD_WEB_PUBLIC_KEY | Optional |
The following attributes will be specified in the results output parameter of this command:
Table: PROVISIONCMD_ASSIGN (Supported output attributes) | Attribute name | Returned? |
|---|
| PROVFLD_AUXILIARY_MESSAGE | Always (in error case) |
| PROVFLD_STATUS_MESSAGE | Always (in error case) |
PROVISIONCMD_DSAPPREGISTER
The following attributes can be specified in the attributeSet input parameter of this command:
Table: PROVISIONCMD_DSAPPREGISTER (Supported input attributes) | Attribute name | Optionality |
|---|
| PROVFLD_CLIENT_HASH | Optional |
| PROVFLD_COMPONENT_TYPE | Mandatory |
| PROVFLD_DOMAIN | Optional |
| PROVFLD_DSAPP_VERSION | Optional |
| PROVFLD_SERIAL_NO | Optional |
| PROVFLD_STATIC_PASSWORD | Mandatory |
| PROVFLD_USERID | Mandatory |
The following attributes will be specified in the results output parameter of this command:
Table: PROVISIONCMD_DSAPPREGISTER (Supported output attributes) | Attribute name | Returned? |
|---|
| PROVFLD_ACTIVATION_PASSWORD | Always (in success case) |
| PROVFLD_AUXILIARY_MESSAGE | Always (in error case) |
| PROVFLD_REGISTRATIONID | Always (in success case) |
| PROVFLD_SERIAL_NO | Always (in success case) |
| PROVFLD_STATUS_MESSAGE | Always (in error case) |
PROVISIONCMD_DSAPPACTIVATE
Once the one-time password (OTP) has been successfully validated, this command ends the authenticator grace period.
The following attributes can be specified in the attributeSet input parameter of this command:
Table: PROVISIONCMD_DSAPPACTIVATE (Supported input attributes) | Attribute name | Optionality |
|---|
| PROVFLD_CLIENT_IV | Mandatory |
| PROVFLD_COMPONENT_TYPE | Mandatory |
| PROVFLD_DERIVATION_CODE | Optional |
| PROVFLD_DP_RESPONSE | Optional |
| PROVFLD_ENCRYPTED_SERVER_NONCE | Mandatory |
| PROVFLD_REGISTRATIONID | Mandatory |
| PROVFLD_REQUEST_TYPE | Optional |
| PROVFLD_SERIAL_NO | Optional |
The following attributes will be specified in the results output parameter of this command:
Table: PROVISIONCMD_DSAPPACTIVATE (Supported output attributes) | Attribute name | Returned? |
|---|
| PROVFLD_AUXILIARY_MESSAGE | Always (in error case) |
| PROVFLD_DOMAIN | Always |
| PROVFLD_SERIAL_NO | Always (in error case) |
| PROVFLD_STATUS_MESSAGE | Always (in error case) |
| PROVFLD_USERID | Always |
PROVISIONCMD_DSAPPGENERATEACTIVATIONDATA
The following attributes can be specified in the attributeSet input parameter of this command:
Table: PROVISIONCMD_DSAPPGENERATEACTIVATIONDATA (Supported input attributes) | Attribute name | Optionality |
|---|
| PROVFLD_CLIENT_IV | Mandatory |
| PROVFLD_COMPONENT_TYPE | Mandatory |
| PROVFLD_DSAPP_VERSION | Optional |
| PROVFLD_ENCRYPTED_CLIENT_PUBLIC_KEY_NONCE | Mandatory |
| PROVFLD_REGISTRATIONID | Mandatory |
The following attributes will be specified in the results output parameter of this command:
Table: PROVISIONCMD_DSAPPGENERATEACTIVATIONDATA (Supported output attributes) | Attribute name | Returned? |
|---|
| PROVFLD_ACTIVATION_CODE | If defined |
| PROVFLD_ACTIVATION_CODE_IV | If defined |
| PROVFLD_ACTIVATION_MESSAGE | If defined |
| PROVFLD_ACTIVATION_MESSAGE_IV | If defined |
| PROVFLD_AUXILIARY_MESSAGE | Always (in error case) |
| PROVFLD_DOMAIN | Always |
| PROVFLD_ENCRYPTED_NONCES | Always |
| PROVFLD_ENCRYPTED_SERVER_PUBLIC_KEY | Always |
| PROVFLD_EVENT_REACTIVATION_COUNTER | If defined |
| PROVFLD_EVENT_REACTIVATION_COUNTER_IV | If defined |
| PROVFLD_SERIAL_NO | Always |
| PROVFLD_SERVER_IV | Always |
| PROVFLD_STATUS_MESSAGE | Always (in error case) |
| PROVFLD_USERID | Always |
PROVISIONCMD_MDL_REGISTER
Generates Activation Message 1 for a specified end-user on OneSpan Authentication Server. In a two-step activation scenario, this constitutes the first activation step.
Applies to authenticators compliant with multi-device licensing (MDL).
Parameters
The following attributes can be specified in the attributeSet input parameter of this command:
Table: PROVISIONCMD_MDL_REGISTER (Supported input attributes) | Attribute name | Input |
|---|
| PROVFLD_ACTIVATION_TYPE | Optional |
| PROVFLD_COMPONENT_TYPE | Mandatory |
| PROVFLD_DOMAIN | Optional |
| PROVFLD_SERIAL_NO | Optional |
| PROVFLD_STATIC_PASSWORD | Mandatory |
| PROVFLD_USERID | Mandatory |
The following attributes will be specified in the results output parameter of this command:
Table: PROVISIONCMD_MDL_REGISTER (Supported output attributes) | Attribute name | Returned? |
|---|
| PROVFLD_ACTIVATION_MESSAGE | Always |
| PROVFLD_AUXILIARY_MESSAGE | Always (in error case) |
| PROVFLD_DOMAIN | Always |
| PROVFLD_ORGANIZATIONAL_UNIT | Optional |
| PROVFLD_REGISTRATIONID | Always |
| PROVFLD_SERIAL_NO | Always |
| PROVFLD_STATUS_MESSAGE | Always (in error case) |
| PROVFLD_USERID | Always |
PROVISIONCMD_MDL_ADD_DEVICE
The following attributes can be specified in the attributeSet input parameter of this command:
Table: PROVISIONCMD_MDL_ADD_DEVICE (Supported input attributes) | Attribute name | Optionality | Remarks |
|---|
| PROVFLD_CLIENT_IV | Optional | Mandatory if PROVISIONCMD_DSAPPGENERATEACTIVATIONDATA was used to generate Activation Message 1. |
| PROVFLD_COMPONENT_TYPE | Mandatory | |
| PROVFLD_DESCRIPTION | Optional | |
| PROVFLD_DEVICE_CODE | Mandatory | |
| PROVFLD_ENCRYPTED_SERVER_NONCE | Optional | Mandatory if PROVISIONCMD_DSAPPGENERATEACTIVATIONDATA was used to generate Activation Message 1. |
| PROVFLD_REGISTRATIONID | Mandatory | |
The following attributes will be specified in the results output parameter of this command:
Table: PROVISIONCMD_MDL_ADD_DEVICE (Supported output attributes) | Attribute name | Returned? |
|---|
| PROVFLD_ACTIVATION_MESSAGE | Always |
| PROVFLD_AUXILIARY_MESSAGE | Always (in error case) |
| PROVFLD_DEVICE_ID | Always |
| PROVFLD_DEVICE_TYPE | Always |
| PROVFLD_REGISTRATIONID | Always |
| PROVFLD_SERIAL_NO | Always |
| PROVFLD_STATUS_MESSAGE | Always (in error case) |
PROVISIONCMD_MDL_ACTIVATE
Once the one-time password (OTP) has been successfully validated, this command ends the authenticator grace period.
The following attributes can be specified in the attributeSet input parameter of this command:
Table: PROVISIONCMD_MDL_ACTIVATE (Supported input attributes) | Attribute name | Optionality |
|---|
| PROVFLD_COMPONENT_TYPE | Mandatory |
| PROVFLD_REGISTRATIONID | Mandatory |
| PROVFLD_SIGNATURE | Mandatory |
The following attributes will be specified in the results output parameter of this command:
Table: PROVISIONCMD_MDL_ACTIVATE (Supported output attributes) | Attribute name | Returned? | Remarks |
|---|
| PROVFLD_DOMAIN | Optional | Returned if PROVISIONCMD_MDL_ACTIVATE command is successful. |
| PROVFLD_REGISTRATIONID | Mandatory | |
| PROVFLD_SERIAL_NO | Optional | Returned if PROVISIONCMD_MDL_ACTIVATE command is successful. |
| PROVFLD_USERID | Optional | Returned if PROVISIONCMD_MDL_ACTIVATE command is successful. |