Integration of User Login via Notification

With OneSpan Cloud Authentication, you can implement a two-step authentication process, where users need to perform an additional authentication step. In this additional step, the user must either respond to a Push Notification message (see Integration of Push Notification-based authentication) or enter a one-time password (OTP) received in a challenge SMS or email (see Integration of User Login via Notification—SMS or Email).

Integration of Push Notification-based authentication

OneSpan Cloud Authentication allows you to integrate Push Notification-based authentication in your solution. You can integrate this functionality for the OneSpan Orchestration SDK or for OneSpan Mobile Authenticator Studio.

• In an integration with the OneSpan Orchestration SDK, remote authentication is performed by a trusted device. For more information, see Push Notification-based authentication for the Orchestration SDK.

• In an integration with OneSpan Mobile Authenticator Studio, a new Mobile Authenticator Studio application is enabled on a mobile device to authenticate the user. For more information, see Push Notification-based authentication for OneSpan Mobile Authenticator Studio.

Configuration of Push Notification

To configure Push Notification

1. After configuring your mobile app, you provide the configuration data to OneSpan. This data includes:

   • Android: the API keys and/(or certificates for Firebase Cloud Messaging (FCM)

   • iOS: the certificates and the Bundle ID

   You need to generate all the required certificates and provide them to OneSpan. For information how to generate these certificates, refer to the Apple and Android developer documentation.

2. OneSpan Cloud Authentication uses this data and creates the configuration in the OneSpan Cloud Authentication database. The data is stored under a key referred to as app ID.

3. The app ID must be set as the name of the mobile app (Mobile Application Name) in your Authentication component domain.

4. Send a Push Notification. When sending, OneSpan Cloud Authentication uses the app ID that was configured in the domain to retrieve the necessary configuration data. This data is used to contact Google Firebase Cloud Messaging (Android) and APNs (iOS).

   For Android, the pairing to the ID of the Android application happens exclusively inside the PNS configuration of your Firebase Cloud Messaging account to which you provided the credentials.

   iOS: the Bundle ID must be provided to Apple for each request. If the iOS Bundle ID is missing in the mobile app configuration, the app ID configured in the Authentication component is used as Bundle ID.

   Once the Push Notification is sent to Google FCM/iOS APNs, the notification delivery to the mobile device (the user) is handled by these services, i.e., the notification is not controlled by OneSpan Cloud Authentication.

Push Notification-based authentication for the Orchestration SDK

Remote authentication is performed by a trusted device where the appropriate protection is selected according to the passkey selection. The following protection options are available:

• Device-based

• PIN-based

• Fingerprint-based

Cloud authentication is done via the Login service and the Trusted Device Command service.

To configure Mobile Security Suite Orchestration SDK for OneSpan Cloud Authentication, the existing passkey field must support one of the following values:

• orchestration authentication types: NoPIN, PIN, Fingerprint

The orchestrationDelivery field may support the following values:

• pushNotification: the orchestration command must be delivered to the trusted device through Push Notification

• requestMessage: the orchestration command must be returned as a request message the caller

(Optional) The LoginMessage object. This message will overwrite the default message displayed on the trusted device (e.g. Challenge).

OneSpan Cloud Authentication offers two modes to integrate the user login flow, the synchronous and the asynchronous login mode.

Synchronous login mode

The synchronous login mode is the quickest method to integrate the user login flow. The server-side integration of this mode processes several steps.

Login flow in synchronous mode

Sequence of a login operation in synchronous login mode

1. The user initiates the login operation by providing their credentials and the configured keyword with one of the following values for the Mobile Security Suite Orchestration SDK:

   • PIN

   • NoPIN

   • Fingerprint

2. The Login service creates a secure message that returns a secure orchestration message.

3. To challenge the user, the Login service generates a remote authentication request.
   This notification is temporarily stored in the queue of pending notifications.

4. The login request is sent via notification to the trusted device associated with that user.

5. The state of the notification is checked.

6. The retrieves the authentication challenge that is based on the received push notification.

7. The orchestration command sends a response with an authentication signature to the Login service.

8. The authentication signature is verified and returns the authentication status.

9. The pending notification is updated.

10. If the user performs the notification request successfully and signs the authentication request with the appropriate authentication method, the login request is accepted. User login can fail if the notification has not completed successfully.

Integration of the synchronous login mode

The Login service handles the JSON posts to provide login for the users of your web server application.

For more information about login input and output data, see POST /users/{userID@domain}/login.

To integrate the synchronous login mode, you must specify a timeout value for the login request. The default timeout value is 60 seconds per tenant. To increase the validation period for Push Notification-based authentication within OneSpan Cloud Authentication, this timeout value can be extended.

Contact OneSpan Support to extend the timeout configuration for your tenant(s).

The Trusted Device Command service handles the command response from the mobile device. On the client side (i.e. the mobile application) the Orchestration SDK generates the trusted device response.

For more detailed information about the Orchestration SDK, refer to the Orchestration SDK Integration Guide at Mobile Security Suite > Guides > Integration Guides.

Asynchronous login mode

In the asynchronous login mode, OneSpan Cloud Authentication provides an additional API to check the session status of the user with the Check Session Status service.

Login flow in asynchronous mode

Sequence of a login operation in asynchronous login mode

1. The user initiates the login operation by providing their credentials, the keyword push and one of the following values for the Mobile Security Suite Orchestration SDK:

   • PIN

   • NoPIN

   • Fingerprint

2. The Login service creates a secure message that returns a secure orchestration message.

3. To challenge the user, the Login service generates a remote authentication request.
   This notification is temporarily stored in the queue of pending notifications.

4. The login request is sent via notification to the trusted device associated with that user.

5. The state of the notification is checked.

6. The Orchestration SDK retrieves the authentication challenge that is based on the received push notification.

7. After the service checks the login status of the notification it returns this state to your web server application. Possible states are:

   • Accept

   • Decline

   • Pending

   • Timeout

   • Failed

8. The user ID and request ID are sent to the Login service. After the service checks the request ID status it returns this state to your web server application. Possible states are:

   • Accept

   • Decline

   • Pending

   • Timeout

   • Failed

9. The orchestration command sends a response with an authentication signature to the Login service.

10. The authentication signature is verified, and returns the authentication status.

11. The pending notification is updated.

Integration of the asynchronous login mode

OneSpan Cloud Authentication processes two steps for the asynchronous login mode:

• The OneSpan Cloud Authentication Login service, called with timeout = 0, starts the login process, challenges the user (same process step as in the synchronous login mode), and immediately returns the current state of the session.

• The Check Session Status service returns the current session and notification states of the pending login request immediately, without waiting for the notification process to complete.

To integrate the asynchronous login mode, you must specify a timeout value for the login request. The default timeout value is 60 seconds per tenant. To increase the validation period for Push Notification-based authentication within OneSpan Cloud Authentication, this timeout value can be extended.

Contact OneSpan Support to extend the timeout configuration for your tenant(s).

Find further information in the following documents:

• OneSpan Mobile Security Suite Product Guide

• Orchestration SDK Integration Guide at Mobile Security Suite > Guides > Integration Guides

Push Notification-based authentication for OneSpan Mobile Authenticator Studio

In the push mode, a new OneSpan Mobile Authenticator Studio app is enabled on a mobile device to authenticate the user. The user receives a notification prompt on their mobile device during the authentication process and completes this process by tapping the mobile device.

Sequence of a Push Notification-based authentication operation

1. The user initiates the login operation by providing their credentials, the keyword push and their static password for OneSpan Mobile Authenticator.

2. OneSpan Cloud Authentication verifies the user.

3. The Push Notification service generates a Push Notification message and sends it to the user's mobile device, where the Mobile Authenticator Studio application is installed.

4. The user receives the Push Notification message on their mobile device.

5. The user approves the request to log in.

6. The user's approval is returned to the Push Notification service.

7. The Push Notification service notifies OneSpan Cloud Authentication of the user's approval.

   The user has successfully logged in.

You integrate Push Notification-based authentication with a login request.

To integrate Push Notification-based authentication

• Issue a login request with the POST /users/{userid@domain}/login endpoint.

  • Payload:

    • objectType: “LoginInput”

    • credentials.passKey: "push{password}"

Integration of User Login via Notification—SMS or Email

With OneSpan Cloud Authentication you can implement functionality for your users to log in to your web application through the use of a virtual authenticator via the OneSpan Cloud Authentication platform. A one-time password (OTP) is generated by the authentication component and delivered via SMS or email, depending on the policy set within the OneSpan Cloud Authentication component. OneSpan Cloud Authentication offers two modes to integrate the user login flow: the synchronous and the asynchronous login mode.

User login via notification—process overview

The user attempts to log in to the web server with their credentials. If this first login step is successful, they receive a notification that contains an OTP. Depending on the selected notification mode, the OTP will be delivered to the user as SMS (via the SMS service) to the mobile phone number associated with this user in the user profile or the email address of the user if an email account has been defined for this user.

The user can extract the OTP from the message and continue the login procedure, including the OTP in the request to the TID web server. The TID web service receives the OTP and checks it against the Authentication component. When the OTP validation is successful, the login can be completed.

Integration of user login via notification with SMS

Virtual authenticator OTP via SMS

Sequence of a user login operation via notification with SMS

1. The user initiates the login operation and triggers the client application to send a login request. This request includes the following parameters:

   • authenticator user

   • authenticator domain

   • session identifier

   The user's credentials (static password) must not be included in the request input! Instead of their credentials, the user needs to provide the keyword votp in the passkey field.

2. OneSpan Cloud Authentication responds as follows:

   1. The TID web service requests OneSpan Cloud Authentication to create an OTP and to deliver it via SMS as defined in the user settings.

   2. The web service returns the OTP to the client application.

3. The user collects the OTP received via SMS.

   1. The user attempts to log in with the retrieved OTP.

4. The client application sends the OTP to the web service.

5. The web service validates the OTP with OneSpan Cloud Authentication.

   1. The web service returns to the client application that the authentication has been successful.

   2. The client application checks the status of the login request with the web service.

Integration of user login via notification with email

Virtual authenticator OTP via email

Sequence of a notification user login operation via email

1. The user initiates the login operation and triggers the client application to send login request. This request includes the following parameters:

   • authenticator user

   • authenticator domain

   • session identifier

   The user's credentials (static password) must not be included in the request input! Instead of their credentials, the user needs to provide the keyword votp in the passkey field.

2. OneSpan Cloud Authentication responds as follows:

   1. The TID web service requests OneSpan Cloud Authentication to create an OTP and to deliver via email as defined in the user settings.

   2. The web service returns the OTP to the client application.

3. The user collects the OTP received via email.

   1. The user attempts to log in with the retrieved OTP.

4. The client application sends the OTP to the web service.

5. The web service validates the OTP with OneSpan Cloud Authentication.

   1. The web service returns to the client application that authentication has been successful.

   2. The client application checks the status of the login request with the web service.

Customized delivery method of the virtual one-time password (OTP)

It is also possible to customize how the virtual one-time password (OTP) is delivered to the user. You can for instance use your own gateway or another special, customized communication channel. With this, it is possible to receive the virtual OTP in the request response session. To ensure that the generated virtual OTP is never returned directly to the user, it is stored inside a session that must be queried separately.

Mild security risk

When you use this feature, the virtual OTP is returned in the same session in which it has been requested. Because this forms a mild security risk, be advised to treat the virtual OTP as sensitive data. Make sure the data is transmitted via a different secure channel than the one in which it was requested (e.g. an SMS sent to a different device than the one from which the request was sent).

If you enable this feature this does not deactivate the original delivery method for virtual OTPs! The custom delivery has to be requested in the request payload on a per-request basis.

Prerequisites

• A virtual authenticator (e.g. VIR10) is assigned to the relevant user account.

• The vdpDeliveryMethod field in the user account settings must be set to Default for the custom delivery to work correctly.

Necessary integration steps

You can trigger the customized virtual OTP delivery either with an administrative command or via user authentication.

To integrate the customized delivery method via an administrative command

• To integrate the feature via an administrative command with your back-end system, integrate it into the POST /authenticators/{serialNumber}/applications/{applName}/generate-votp endpoint.
  This endpoint will be triggered when your workflow requires the generation of a virtual OTP at some stage.

• Use the keyword Response in the deliveryMethod field of the GenerateVOTPInput object. The response will be 200 OK, the GenerateVOTPOutput payload will contain the field votp.

To provide the customized delivery method via user authentication

To provide the feature via user authentication, integrate it into the following endpoint:

• POST /users/{userID@domain}/login

Integration into POST /users/{userID@domain}/login

To ensure that the generated virtual OTP is never returned directly to the user, it is stored inside a session that must be queried separately.

The delivery of the virtual OTP is triggered when the keyword votpCustomDelivery is sent via the passKey field of the LoginInput payload. The response is 200 OK, the LoginOutput payload contains the following fields:

• sessionStatus, with the value pending

• requestID, with a generated value, e.g. 47543e06-1c11-49b8-94ed-d9501f7fd3f2

After the delivery has been triggered, the GET /sessions//{requestID} endpoint must be queried. The response will contain the field votpResponse with the generated virtual OTP which you can deliver to your user.

Use of this feature is optional, it is not provided by default. Contact OneSpan Support for activation. Once enabled, the virtual OTP will be delivered with the same method for all tenants that are grouped in the same Authentication component deployment as the one where this feature has been enabled.