Integration of User Login and Event Validation via Notification
With OneSpan Intelligent Adaptive Authentication you can implement functionality for your users to log in to your web application and request remote strong authentication.
- Device based
- PIN based
- Fingerprint based
Login modes
Intelligent Adaptive Authentication offers two modes to integrate the user login flow, the synchronous and the asynchronous login and event validation 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.
Sequence of a login operation in synchronous login mode
-
The Login service checks the browsing context of the login request. - The risk associated with the user login and event validation is analyzed according to the rules
Rules are used to define sets of criteria to verify if an event (transaction and non-monetary event) matches any fraudulent behavior. If an event matches a previously defined rule, an alert can be raised. set in the Risk Management component The Risk Management component is a highly versatile, reliable, and scalable fraud management system used for monitoring online banking applications and payment processing across multiple channels; it helps to protect against anti-money-laundering (AML), online banking fraud, and to comply with regulations.. - The Login service creates a secure message that returns a secure orchestration message.
- To challenge the user, the Login service generates a remote authentication request.
This notification is temporarily stored in the queue of pending notifications. - The login request is sent via notification to the trusted device associated with that user.
- The state of the notification is checked.
- The Orchestration SDKOrchestration SDK retrieves the authentication challenge that is based on the received push notification.
- The orchestration command sends a response with an authentication signature to the Login service.
- The authentication signature is verified and returns the authentication status.
- The pending notification is updated.
- 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
either because the Risk Management component refuses it, or if the notification has not completed successfully.
Integration of the synchronous login mode
For more information about login input and output data, see POST /users/{[email protected]}/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 Intelligent Adaptive 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, Intelligent Adaptive Authentication provides an additional API to check the session status of the user with the Check Session Status service.
Sequence of a login operation in asynchronous login mode
-
The Login service checks the browsing context of the login request. - The risk associated with the user login and event validation is analyzed according to the rules set in the Risk Management component.
- The Login service creates a secure message that returns a secure orchestration message.
- To challenge the user, the Login service generates a remote authentication request.
This notification is temporarily stored in the queue of pending notifications. - The login request is sent via notification to the trusted device associated with that user.
- The state of the notification is checked.
- The Orchestration SDK retrieves the authentication challenge that is based on the received push notification.
-
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
-
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
- The orchestration command sends a response with an authentication signature to the Login service.
- The authentication signature is verified, and returns the authentication status.
- The pending notification is updated.
Integration of the asynchronous login mode
Intelligent Adaptive Authentication processes two steps for the asynchronous login mode:
- The Intelligent Adaptive 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 Intelligent Adaptive Authentication, this timeout value can be extended.
Contact OneSpan Support to extend the timeout configuration for your tenant(s).
For more information, see Sessions.
Find further information in the following documents:
- OneSpan Mobile Security Suite Product Guide
- Orchestration SDK Integration Guide at Mobile Security Suite > Guides > Integration Guides
Integration of User Login via Notification with SMS, Email, or Voice Call
With Intelligent Adaptive Authentication you can implement functionality for your users to log in to your web application through the use of a virtual authenticator via the Intelligent Adaptive Authentication platform.
User login via notification—process overview
When a user with an assigned virtual authenticator logs in without providing their credentials to the Login service (TID web service), the Risk Management component server answers with a challenge. The value of the returned challenge depends on the selected notification type: 3 for SMS, 8 for email, and 13 for voice call.
This challenge also invokes Intelligent Adaptive Authentication to create 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, the email address of the user if an email account has been defined for this user, or as a voice call to the user if a landline phone number has been defined for this user.
The user is informed about the challenge via the selected notification mode during the first login response. When the user receives the notifcation, they 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 service. 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
-
The user initiates the login operation and triggers the client application to send a login and event validation request. This request includes the following parameters:- authenticator user
- authenticator domain
- CDDC data
- session identifier
The user's credentials (static password) must not be included in the request input!
- The web service triggers a Risk Management component-event request for the login.
-
The Risk Management component responds with an SMS challenge. - The TID web service requests Intelligent Adaptive Authentication to create an OTP and to deliver it via SMS as defined in the user settings.
-
The web service returns the SMS challenge to the client application.
-
The user collects the OTP received via SMS.
- The user attempts to log in with the retrieved OTP.
- The client application sends the OTP to the web service.
-
The web service validates the OTP with Intelligent Adaptive Authentication.
- The web service returns to the client application that the authentication has been successful.
- 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
-
The user initiates the login operation and triggers the client application to send login and event validation request. This request includes the following parameters:- authenticator user
- authenticator domain
- CDDC data
- session identifier
The user's credentials (static password) must not be included in the request input!
- The web service triggers a Risk Management component-event request for the login.
-
The Risk Management component responds with an email challenge. - The TID web service requests Intelligent Adaptive Authentication to create an OTP and to deliver via email as defined in the user settings.
-
The web service returns the email challenge to the client application.
- The user collects the OTP received via email.
- The user attempts to log in with the retrieved OTP.
- The client application sends the OTP to the web service.
- The web service validates the OTP with Intelligent Adaptive Authentication.
- The web service returns to the client application that authentication has been successful.
- The client application checks the status of the login request with the web service.
Integration of user login via notification with voice call
Virtual authenticator OTP via voice call
Sequence of a user login operation via notification with voice call
- The user initiates the login operation and triggers the client application to send login
and event validation request. This request includes the following parameters:- authenticator user
- authenticator domain
- CDDC data
- session identifier
The user's credentials (static password) must not be included in the request input!
- The web service triggers a Risk Management component-event request for the login.
- The Risk Management component responds with a voice challenge.
- The TID web service requests Intelligent Adaptive Authentication to create an OTP and to deliver via voice call as defined in the user settings.
- The web service returns the voice challenge to the client application.
- The user collects the OTP received via voice call.
- The user attempts to log in with the retrieved OTP.
- The client application sends the OTP to the web service.
- The web service validates the OTP with Intelligent Adaptive Authentication.
- The web service returns to the client application that authentication has been successful.
- 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
Integration into POST /users/{[email protected]}/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 upon user request. The decision to use a virtual OTP for authentication happens dynamically while the request is processed, based on the response code of the risk analysis component. Relevant codes are:
- 3: delivery via SMS
- 8: delivery via email
- 13: delivery via voice call
Other response codes do not apply to authentication via virtual OTP. For more information on risk analysis response codes, see Challenges of the Risk Management Component.
Because of the dynamic nature of this behavior, the possibility to customize the delivery of the virtual OTP is not offered by default.
The delivery of the virtual OTP is triggered when the keyword session is sent via the votpDeliveryOverride field of the AdaptiveLoginInput payload (without providing the credentials fields). The response is 200 OK, the LoginOutput payload contains the following fields:
- sessionStatus, with the value pending
- riskResponseCode, with an integer value
- requestID, with a generated value, e.g. 47543e06-1c11-49b8-94ed-d9501f7fd3f2
If the risk response code is 3, 8, or 13:
- the GET /sessions//{requestID} endpoint needs to be queried. The response will contain the field votpResponse with the generated virtual OTP which you can deliver to your user;
- you should check the delivery method indicated by the risk analysis component when you execute the custom delivery of the generated virtual OTP. OneSpan recommends to use the same delivery method as that indicated by the response code of the Risk Management component.
Integration into POST /users/{[email protected]}/events/validate
The integration into this endpoint is the same as that for POST /users/{[email protected]}/login, but with a different payload: AdaptiveEventValidationInput.
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.