Version 3.26 (August 2024)
New features and enhancements
New policy setting to avoid initial authenticator time synchronization
When an authenticator is used for the first time, OneSpan Authentication Server calculates the initial deviation between the authenticator time and the server time. A new policy setting (POLICYFLD_AVOID_INITIAL_SYNC) has been added to skip the initial time shift initialization on the server side. This can be useful, because the time shift is usually handled by the mobile app, so it can be omitted on the server side.
The policyExecute and policyQuery commands have been updated accordingly to handle the new policy setting.
Returned list of assigned authenticators is now sorted by default
When you execute a user command (userExecute, userQuery) that returns the list of assigned authenticators (USERFLD_ASSIGNED_DIGIPASS), the returned list is now alphabetically sorted in ascending order by default. In previous versions, the list was returned in arbitrary order as retrieved by the database query.
DSAPP/DSAPP-SRP registration now allows to specify serial number
When you perform a provisioning registration operation using DSAPP or DSAPP-SRP, you can now specify the serial number of the authenticator to use:
- provisioningExecute:PROVISIONCMD_DSAPPREGISTER accepts PROVFLD_SERIAL_NO as optional input attribute (via attributeSet).
- dsappSRPRegister accepts serialNumber as new optional input parameter.
This allows you to register additional authenticator instances if an authenticator is already activated and assigned to the respective user. In previous versions, you would receive a RET_DENIED error and a STAT_TOO_MANY_DIGIPASS status code in such cases.
Surrounding whitespaces trimmed from input parameters
When you create a new user account, domain, or organizational unit any trailing or leading whitespaces are removed from the respective ID fields. This affects the following commands and attributes:
- domainExecute:DOMAINCMD_CREATE ⇒ DOMAINFLD_DOMAIN
- orgunitExecute:ORGUNITCMD_CREATE ⇒ ORGUNITFLD_ORGANIZATIONAL_UNIT
- userExecute:USERCMD_CREATE ⇒ USERFLD_USERID, USERFLD_USERNAME
- userExecute:USERCMD_MOVE ⇒ USERFLD_NEW_USERID
Surrounding whitespaces are not removed when these attributes are used with other commands, such as queries, to avoid issues with existing user, domain, or organizational unit records.
It is generally not a good practice to use whitespace characters in user names, user IDs, domain names, or organizational unit names.
Improved exception handling in SOAP wrappers
By default, the SOAP handlers ignore underlying exceptions, and always return a generic "Service is not available" error message. You can now configure the SOAP wrappers, so that underlying exceptions are re-thrown (as IdentikeyConnectionException) and can be properly handled by the application.
For the Java wrappers, this behavior can be configured with the ConfigurationBean.setRethrowOnConnectionError() method.
For the .NET wrappers, this behavior can be configured via the RethrowOnConnectionError setting in the application configuration file (app.config).
Jakarta EE support
The SDK now fully supports the Jakarta EE platform. The package includes project files and artifacts for the SOAP client and the SOAP wrapper that are compliant with Jakarta EE 9 and provide Java 11 target compatibility.
Fixes and other updates
Issues OAS-21802, OAS-21529: Missing or incorrect input/output attributes (Documentation)
Description: The OneSpan Authentication Server SDK SOAP Reference does not list all attributes supported by the digipassExecute:DIGIPASSCMD_ASSIGN and offlinedataExecute:OFFLINEDATACMD_DELETE commands. Moreover, some of the listed attributes are incorrect.
Affects: OneSpan Authentication Server SDK 3.21–3.25
Status: The documentation has been updated.
Issue OAS-21228: authUser does not return used authenticator instance
Description: Authentication and signature validation commands return the serial number of the used authenticator (CREDFLD_SERIAL_NO). In case of MDL, this field contains the authenticator instance number, e.g. VDS1000120-1. This was not the case for the authUser command.
Affects: OneSpan Authentication Server SDK 3.21–3.25
Status: This issue has been fixed. The authUser command now correctly returns the authenticator (instance) serial number as CREDFLD_SERIAL_NO. Note that this attribute is not returned if a static password was used for the authentication.
Issue OAS-19748: Response indicates success despite database error
Description: When a SOAP operation fails due to a database or ODBC connection issue, it correctly returns an error code (RET_FAILURE) whereas the status code indicates success (STAT_SUCCESS). Furthermore, the error stack in the SOAP response includes database/ODBC-specific error messages that can expose critical information to potential attackers.
Affects: OneSpan Authentication Server SDK 3.21–3.25
Status: This issue has been fixed. All SOAP operations now correctly return STAT_COMMS in case of database connection issues and don't include low-level database error messages in the SOAP response anymore.
Issue OAS-9099 (Support case CS0061534): Signature validation uses incorrect authenticator application and succeeds
Description: In some environments where more than one signature authenticator application is used, the authSignature command may use an incorrect authenticator application to process the request and still create a valid signature.
Consider a scenario where two signature authenticator applications exist on an authenticator, SG1 that accepts exactly one data field and SG2 that accepts two data fields. Now assume that a user attempts a transaction signature validation for a business application that requires two data fields, but mistakenly selects the authenticator application that is accepting only one data field. The signature validation can still be successful, because it uses SG1 to successfully process the request (ignoring the second data field).
Affects: OneSpan Authentication Server SDK 3.21–3.25
Status: This issue has been fixed.
- The data field handling in the authSignature command was improved, any authenticator application that cannot process as many data fields as required by the request will be ignored.
- The attribute handling in the authUser command was changed to ignore Response-Only authenticator applications if the CREDFLD_CHALLENGE attribute is specified.
Issues OAS-6841 (Support case CS0048717): isSessionAlive() does not clear session (SOAP wrapper)
Description: The AdministrationBean.isSessionAlive() method (Java) and the AdministrationHandler.isSessionAlive() method (.NET), respectively, do not clear the session from the session storage when the session has already expired on the server. This causes unnecessary additional server calls to verify the session status.
Affects: OneSpan Authentication Server SDK 3.21–3.25
Status: This issue has been fixed.
Deprecated components and features
PDF documentation (Deprecated)
You can view the user documentation of most OneSpan products online already at https://community.onespan.com/documentation, and we plan to shift exclusively to online documentation.
This means that PDF documentation will be completely removed in future major releases of OneSpan Authentication Server SDK (currently planned for 3.27).
Known issues
Issue 44570: New client components for multi-device licensing (MDL) not automatically created (OneSpan Authentication Server Configuration Wizard)
Description: When running the Configuration Wizard and registering the SDK as part of an advanced installation, the client components for the new multi-device licensing (MDL) functionalities are not created automatically.
Affects: OneSpan Authentication Server SDK 3.7–3.26
Status: Before using the sample websites, the client components for MDL must be created manually.
Issue 38548: Incorrect casing for domain attribute results in decryption error
Description: When using SOAP API commands to manipulate an authenticator record (moving, updating, etc.) the domain name is considered case-sensitive. If the domain name provided uses a different casing than the name of the actual Active Directory (AD) domain, the operation fails. This is indicated by a "Fail to decrypt data with the supplied key" error message in the audit log.
Affects: SOAP API on OneSpan Authentication Server 3.6–3.26 with AD data store
Status: No fix available. Ensure that you use correct casing for the domain name.
Version 3.25 (January 2024)
New features and enhancements
Custom authenticator application selection for Secure Channel operations
You can now select a specific authenticator application to use when you initiate an authentication or signature validation process using Secure Channel.
The SOAP communication interface now supports the following attributes to select a specific authenticator application:
- CREDFLD_CRYPTO_APP_INDEX. The index of the authenticator application to use when you initiate an authentication process with the getSecureChallenge command.
- CREDFLD_CRYPTO_APP_NAME. The name of the authenticator application to use when you initiate an authentication process with the getSecureChallenge command.
- SIGNFLD_CRYPTO_APP_INDEX. The index of the authenticator application to use when you initiate a signature validation with the genRequest command.
- SIGNFLD_CRYPTO_APP_NAME. The name of the authenticator application to use when you initiate a signature validation with the genRequest command.
If you do not specify a particular authenticator application, the first applicable authenticator application that is allowed by the effective policy will be used (current default behavior).
Version 3.24 (July 2023)
Fixes and other updates
Issue OAS-14297 (Support case CS0098211): Missing description of PROVFLD_CUSTOM_ENCRYPT_PWD (Documentation)
Description: The OneSpan Authentication Server SDK SOAP Reference lists PROVFLD_CUSTOM_ENCRYPT_PWD as provisioning field attribute, but does not provide a description. Moreover, its relation to PROVFLD_ACTIVATION_CODE is not mentioned.
Affects: 3.12–3.23
Status: The documentation has been updated.
Version 3.23 (July 2022)
New features and enhancements
Improved deletion of users with assigned items
The USERCMD_DELETE command allows you to delete user accounts. In previous versions, the command failed if the target user account had items assigned that cannot be deleted, e.g. reports, recurring tasks, or pending operations (maker or checker role).
To delete such user accounts, you can now specify a successor user that will take ownership of those items. The successor must be an administrative user account in the same domain as the user to be deleted.
The USERCMD_DELETE command now accepts two new optional parameters to specify the successor account:
- USERFLD_SUCCESSOR_DOMAIN
- USERFLD_SUCCESSOR_USERID
Automatic execution option for pending operations
It is now possible for maker administrators to specify an auto-execute flag when scheduling a pending operation that requires maker–checker authorization. If set to true, the pending operation is automatically executed on the maker administrator's behalf upon approval by the checker administrator. In that case, the maker administrator does not need to execute it explicitly by calling the respective command a second time.
All commands that support maker–checker authorization now accept an optional parameter, i.e. *_AUTO_EXECUTE:
- DIGIPASSCMD_ASSIGN
- DIGIPASSCMD_UNASSIGN
- USERCMD_CREATE
- USERCMD_DELETE
The administrative commands to view and query pending operations (queryPendingOperation and viewPendingOperation) also support a new parameter to retrieve auto-execute information (POFLD_AUTO_EXECUTE).
Generic authentication status codes (Support case CS0087535)
OneSpan provides a new policy setting (POLICYFLD_USE_GENERIC_AUTH_STATUS_CODES) that specifies whether certain status codes and messages should be mapped to generic status information in server responses, to prevent user account disclosure in authentication and provisioning scenarios. The real status code and message will still be visible in the audit and trace messages.
If enabled, the following status codes will be mapped to 1000 (STAT_INVCREDENTIALS) even if more specific status information is available:
- 1007
- 1009
- 1010
- 1011
- 1012
- 1023
- 1025
- 1033
- 1045
By default, the new policy setting is disabled for parentless policies.
Supported platforms and other third-party products
Software libraries
OneSpan Authentication Server SDK now includes the following (updated) third-party libraries:
- Apache Log4j Core 2.17.1
Fixes and other updates
Issue OAS-10388: New output attribute for queryPendingOperation and viewPendingOperation
Description: The queryPendingOperation and viewPendingOperation commands now support a new output attribute POFLD_TO_SERIAL_NO. The new attribute is returned as upper bound of a serial number range between POFLD_SERIAL_NO and POFLD_TO_SERIAL_NO of possibly affected authenticators of a pending operation.
Issue OAS-12270 (Support case CS0085940): Wrong parameter in cancelAuthSignatureRequest example (Documentation)
Description: In the OneSpan Authentication Server SDK SOAP Reference, the cancelAuthSignatureRequest example contains an incorrect parameter (requestKey). The correct parameter is requestKeyMessage.
Affects: OneSpan Authentication Server SDK 3.17–3.22
Status: The documentation has been updated.
Issue OAS-11626 (Support case CS0082219): Incomplete description of PROVFLD_SERIAL_NO (Documentation)
Description: When PROVFLD_SERIAL_NO is used as an input attribute for PROVISIONCMD_MDL_REGISTER, the serial number needs to be already assigned to the user. Otherwise, activation message generation will fail.
This information is missing and should be added to the OneSpan Authentication Server SDK SOAP Reference.
Status: The documentation has been updated.
Issue OAS-11218 (Support case CS0079957): No information about VACMAN Controller error codes (Documentation)
Description: The OneSpan Authentication Server SDKProgrammer's Guide does not provide information about the VACMAN Controller error codes. The document should refer users to the list in the OneSpan Authentication ServerAdministrator Reference.
Status: The documentation has been updated.
Issue OAS-10217: Additional input attributes for queryPendingOperation
Description: The queryPendingOperation command now supports POFLD_CONTEXT and POFLD_SERIAL_NO as input attributes. Both attributes can contain asterisk wildcards.
Issue OAS‑8234: USERCMD_COPY_PERMISSION allows to copy from non-administrative user accounts
Description: The userExecute:USERCMD_COPY_PERMISSION command copies administrative privileges from one user account to another. If the target user account has privileges assigned that the source user account does not have, then the target user account will lose those privileges. If you select a non-administrative user account to copy the privileges from by mistake, the target user account will lose all privileges.
Affects: OneSpan Authentication Server SDK3.12–3.22
Status: The command behavior has been changed. If you now specify a user account that does not have any administrative privileges assigned, the command will return an error.
Version 3.22 (October 2021)
New features and enhancements
Authenticator/host synchronization
A new syncTokenAndHost command has been added to the SOAP authentication interface that allows users to synchronize the device time or event counter of their authenticators with the authentication server.
This is useful for scenarios where an authenticator has not been used for a long period of time or the authenticator clock has drifted too far. The synchronization supports time- and event-based authenticator applications.
Authenticator type limit policy
As of 3.22, OneSpan Authentication Server allows you to restrict the maximum number of assigned authenticators allowed per user for specific authenticator types.
The authenticator type limit is a string value (1024 characters) containing a list of comma-separated key/value pairs of authenticator type/limit and can be managed via a new user attribute, i.e. POLICYFLD_DP_TYPE_LIMIT.
The following commands of the SOAP administration interface have been extended to directly manage the authenticator type limit:
- POLICYCMD_CREATE
- POLICYCMD_GET_EFFECTIVE_POLICY
- POLICYCMD_UPDATE
- POLICYCMD_VIEW
- policyQuery
New command to remove finished tasks
A new deleteFinishedTasks command has been added to the SOAP administration interface to remove old finished tasks. This allows you to clean up the task list and remove completed tasks regularly to maintain clarity and avoid performance issues with the task management.
The command takes the age in days of the finished tasks to be deleted as parameter. All finished tasks with an end date (completion) older or equal than this value will be deleted. The command schedules a server task itself that processes the server task table. If required, the cleanup task can be configured to recur on a daily or monthly basis.
Fixes and other updates
Issue OAS-10951 (Support case CS0079133): Body field in table is formatted as table header (Documentation)
Description: In the OneSpan Authentication Server SDK SOAP Reference, the USERFLD_DOMAIN entry is incorrectly formatted as header line of the "USERCMD_ENABLE input parameters" table.
Affects: OneSpan Authentication Server SDK 3.21
Status: The documentation has been updated.
Issue OAS-9297 (Support case CS0064510): Assign authenticator fails with certain serial number range parameters
Description: When you attempt to assign an authenticator with the DIGIPASSCMD_ASSIGN command, you can specify a range of serial numbers to automatically pick an authenticator from that range (DIGIPASSFLD_SERNO, DIGIPASSFLD_TO_SERNO). However, the serial number range is incorrectly evaluated if any of the range parameters specify either a serial number that contains alphabetic character prefixes, e.g. VDS0000001, or a number larger than 2147483648. In either case, the first authenticator found in the database is used for assignment, regardless of its serial number.
Affects: OneSpan Authentication Server SDK 3.12–3.21
Status: This issue has been fixed.
Version 3.21 (January 2021)
New features and enhancements
Administrator level management
OneSpan Authentication Server 3.21 introduces administrator levels. These are optional values that can be used to create an administrative account hierarchy that controls which other administrator accounts a particular administrator account can view, edit, and update (as long as they are within the administrative scope). Administrators cannot modify, delete, or even view administrator accounts that have an administrator level higher than their own.
The administrator level is an integer value in the range of 0–255 and can be managed via a new user attribute, i.e. USERFLD_ADMIN_LEVEL.
The following commands of the SOAP administration interface have been extended to directly manage the administrator level:
- USERCMD_CREATE
- USERCMD_VIEW
- USERCMD_UPDATE
Digipass import file upload via SOAP
You can now upload and process Digipass import files via SOAP directly without using Data Migration Tool. A DIGIPASS import file is a comma-separated text file (.csv) that contains authenticator records. They are used, for instance, to import authenticator data from an existing VACMAN Controller environment to OneSpan Authentication Server.
The SOAP communication interface now provides four new commands to handle Digipass import files:
- dpCSVFileImport. Processes authenticator data previously uploaded from a DIGIPASS import file (via a server task).
- dpCSVFileImportStatus. Returns the current status of a server task that is importing authenticator data from a DIGIPASS import file.
- dpCSVFileImportStop. Stops a server task that is importing authenticator data from a DIGIPASS import file.
- dpCSVFileUploadMTOM. Uploads a DIGIPASS import file using MTOM encoding.
Search for administrative user accounts
You can now filter search results to include or exclude user accounts with administrative privileges when searching for users. Note that you cannot filter for a particular administrative privilege, but only limit the search results to user accounts that have either any administrative privilege assigned or none.
To do so, you can now use the USERFLD_ADMIN_PRIVILEGES attribute as a zero-value input parameter for the userQuery command and set the attributeOptions accordingly, e.g.:
- <adm:userQuery …>
- …
- <attributeSet>
- <attributes>
- <attributeOptions>
- <negative>true</negative>
- <null>true</null>
- </attributeOptions>
- <value xsi:type="xsd:base64Binary">0</value>
- <attributeID>USERFLD_ADMIN_PRIVILEGES</attributeID>
- </attributes>
- </attributeSet>
- …
- </adm:userQuery>