OneSpan Cloud Authentication November Release – 26.R4

Prev Next

Deprecated or removed components and services

Removed: orchestration-commands endpoint

The POST /orchestration-commands endpoint has now been removed as previously announced. For information about error handling with the Trusted Device microservice and the POST /orchestration-commands-v2 endpoint, see Orchestration Error Handling with Trusted Device microservice and for instructions how to migrate to this microservice, see Migrate to the Trusted Device microservice.

New features and enhancements—supported use cases

Stricter user data validation

As previously announced, user data are now stricter validated. For calls to create and/or update users, a new validation mechanism has been introduced for the USERFLD_EMAIL and USERFLD_MOBILE fields in the Authentication component, and the emailAddress and mobilePhoneNumber input fields will be validated in the same way as the input fields of other OneSpan Cloud Authentication endpoints. Before, calls were either failing and returning HTTP 500 (Internal Server Error), or accepting invalid inputs and returning HTTP 200 (OK), which then lead to issues in subsequent calls.

Now, when the user’s email address or phone number is invalid, strict validation is enforced, and the following applies whenever you create or update user accounts:

  • Email addresses:

    Email addresses will only be accepted if they are well formed and do not contain special characters. The address must only consist of digits, characters from the Latin (extended with accents), Cyrillic, and Arabic alphabets, and typical email punctuation.

  • Phone numbers:

    Numbers are validated against E.164 and other common formats with human-readable formatting.

If the format of the user’s email address and/or phone number is invalid, the Authentication component will now be returning 400 HTTP bad request error messages instead of HTTP 500 errors.

This affects the following endpoints:

Existing user information fields are kept as is and are only revalidated when you attempt to update them.

User login with Digipass for passkey enrollment

OneSpan Cloud Authentication now provides the possibility to combine Digipass authentication (mobile authenticator as well as hardware device) with FIDO authentication provided by DigipassONE Authenticate to allow using passwordless FIDO2 credentials called passkeys. Every passkey is strong and designed with no shared secrets. A passkey provides faster, easier, and more secure sign-in for websites and apps. There are two types of passkeys: device-bound passkeys and synced passkeys. Traditional FIDO2 credentials (device-bound passkey) only work on a single device. A synced passkey can work across all of a user's devices.

The POST /users/{userID@domain}/login endpoint has been extended with the new optional field returnproofOfAuthentication. This indicates whether a proof of authentication should be generated and included in the response. The accepted values are true or false (default). When the parameter is true and authentication completes successfully, the output contains a new field, proofOfAuthentication. This is a JSON Web Token (JWT) issued upon successful authentication. And, also upon successful authentication, the proofOfAuthentication parameter is also included in the output of the GET /sessions {requestID} endpoint.

This also requires upgrading of the Orchestration SDK to the latest supported version which is version 5.13.2 which includes support for issuing a JWT!

For more information, see Integration of User Login with Digipass for Passkey Enrollment.

Evidence trail of processed transaction validation request

OneSpan Cloud Authentication now supports generating a Proof of Transaction Validation JSON Web Token (JWT) for transaction data signing operations performed with Digipass authenticators. For Secure Channel messaging operations, this feature allows you to retrieve an evidence trail to help meet non-repudiation requirements by cryptographically linking a validated transaction to the user, session, the authenticator used, and the time of signature validation.

The POST /users/{userID@domain}/transactions/validate endpoint has been extended. A new optional boolean input field, returnProofOfTransactionValidation, has been added to request the generation of a Proof of Transaction Validation JWT which is then returned in the response body. OneSpan Cloud Authentication generates the JWT signature with a private-public ES256 key pair for verification. The public key is identified via the key ID that is saved in a file with this ID as filename. The key ID is contained in the returned JWT header.

  • Retrieve the public key. To retrieve a JSON object containing the key ID and its PEM-encoded public key via its key ID, call the following new endpoint:

    GET /pubkeys/{keyID}

    The responses for this endpoint include the following:

    • 200: Public key retrieved successfully.

    • 400: The input is invalid.

    • 404: Public key not found.

    • 500: Internal error, sub service failure, server crash.

Our Support Team can provide you the location of the public keys used by OneSpan Cloud Authentication. For more information, see also Evidence trail.

Orchestration options extended

The Orchestration SDK has replaced the legacy Fingerprint and Face options for authentication and transaction validation with Biometric as the unified type. The OneSpan Cloud Authentication REST API entry points have been adapted accordingly.

The following endpoints now accept Biometric as input value:

For backwards compatibility reasons, the API maps incoming Fingerprint and Face values internally to Biometric.

Reliable indicator for failing authentication requests

OneSpan Cloud Authentication now provides a reliable indicator why an authentication request fails when biometric or PIN validation is performed locally on the device. Authentication failures that occur during local PIN or biometric validation on the mobile are now passed on to the server instead of being tracked as an incorrect one-time password. In addition, OneSpan Cloud Authentication now also tracks which authentication method is being used (PIN or biometric).

The GET /sessions/{requestID} endpoint has been extended with the following fields:

  • failureReason

    Specifies why validation failed.

    Supported value: orchestrationAuthenticationFailure

  • orchestrationAuthenticationType

    Specifies the authentication method used.

    Supported values:

    • NoPIN

    • PIN

    • Biometric

This enhancement also supports a regulatory compliance requirement for 3D Secure 2.

Modernized SMS delivery infrastructure

The SMS delivery infrastructure used for SMS-based user login and event validation has been migrated to a modernized, more secure platform with the following improvements:

  • Regional SMS gateway deployments reduce latency and improve delivery performance

  • Improved SMS delivery status tracking, providing greater visibility into message delivery outcomes, including detailed error information when message delivery fails

  • Better connection handling

  • Tighter integration with OneSpan Cloud Authentication

  • Improved error handling

  • Better supportability

With the extended endpoint, you can now check the exact delivery status of an SMS message and any provider-reported errors directly through the API. Previously, this information had to be retrieved with the help of our Support Team but this enhancement now enables self-service troubleshooting and SMS delivery diagnostics.

The GET /sessions/{requestID} endpoint has been extended with a new smsEvents field to obtain a list of SMS delivery events associated with the request. The new field contains the following values:

  • destinationPhoneNumber: destination of the SMS message

  • providerMessageId: ID assigned to the message by the SMS provider

  • status: current delivery status of the message

  • timestamp: time and date of the most recent update

Existing integrations continue to work as before, full backward compatibility with current SMS delivery APIs has been maintained.

Fixes and other changes

Issue OAS-24606: Import from unsorted Digipass import file can cause issue

Description: Importing authenticator records from a Digipass import file (CSV) can cause issues if the file contains authenticator instances that are linked to authenticator licenses which are defined later in the file.

Status: The CSV import logic was enhanced to first process all authenticator licenses before importing any authenticator instances.

Issue OAS-25737: Security library upgrade

Description: The Open SSL library has been upgraded to provide security updates and to improve compatibility for cryptographic operations and secure communications.

Issue OAS-31809: Effective lock duration for user auto-unlock attempts calculated incorrectly

Description: When user auto-unlock was enabled, the effective lock duration was calculated incorrectly. For example, with the lock duration multiplier set to 200, the lock duration should double after each unsuccessful authentication. Instead, it increased only by the minimum lock duration each time.

Status: This issue has been fixed.

Issues OAS-32375, OAS-32374 (Support case CS0208142): Advanced DPX upload does not accept 64 character key components

Description: In OneSpan Cloud Authentication version 26.R1, support for 256-bit DPX transport keys was added. However, advanced transport keys consisting of multiple key components were still limited to 32 characters per key component.

Status: This issue has been fixed. The Web Administration service of the Authentication component now also accepts up to 64 characters for each key component of an advanced transport key. In addition, key components are now automatically formatted into groups of four characters to simplify data entry, consistent with the handling of basic transport keys.

Issue OAS-35470: Improved handling of report cancellation

Description: In the Web Administration service of the Authentication component, canceling a long-running report that listed Digipass authenticators did not stop the underlying process, resulting in continuous database load.

Status: The handling of long-running Digipass list reports has been improved. Now, the report is being stopped from processing more reliably when cancelled.

Fixed vulnerabilities

As part of our continuous security and maintenance efforts, this release contains updates to third-party components and dependencies. If a vulnerability is identified that materially impacts customers, we will communicate the details directly to affected customers and/or publish relevant guidance in our Knowledge Base.

Known issues

Issue OAS-15853: Incorrect error message when transaction amount fields are provided as data type number

Description: The POST /users/{userID@domain}/transactions/validate endpoint returns an incorrect error message if the transaction amount field is provided from the number data type, and if the transaction amount is large. In this case, the endpoint should return the error message Invalid value type, because the transaction amount field was provided as a number and not as a string. Instead, it returns the incorrect error message Amount: Value must follow -^-?[0-9]{1,20}(\\.[0-9]{1,3})?$,.

Solution: The transaction amount fields in the request body of the transactions/validate endpoint need to be provided as a string. Ensure that the value in the JSON request body is wrapped in double quotes.

Orchestration SDK—supported versions

OneSpan Cloud Authentication supports the following versions of the Orchestration SDK Client:

  • 5.13.3

  • 5.13.2

  • 5.13.0

  • 5.12.0

  • 5.11.0

  • 5.10.0

  • 5.9.0

  • 5.8.1

  • 5.8.0

  • 5.7.0

  • 5.6.4

  • 5.6.3

  • 5.6.0

  • 5.5.1

  • 5.4.2