Mobile authentication with OTP
Introduction
The Onegini Mobile Security Platform offers an ability of mobile authentication with a One Time Password (OTP). Mobile authentication with OTP provides users an easy and secure way for two factor authentication or single factor authentication where no passwords are required. A good use case is for example letting a user login to your web application using his/her mobile device by scanning a QR code displayed within a browser. This essentially allows the user to authenticate using his/her mobile device. It is also not relying on third party services like APNs. All of the communication stays between App, web application and Mobile Security Platform.
An Example implementation could work like this: A web application fetches the OTP from the Token Server and displays it on the login page in the form of a QR code. Then user opens your mobile application and scans the QR code with his camera and is automatically logged in into your website. Of course it's up to you to choose how to implement it, the above scenario is just an example.
Configuration
OTP mobile authentication requires configuration on the Token Server side. Please follow the Mobile authentication configuration guide in order to setup the OTP mobile authentication type.
Enrollment
It's only required to enroll for mobile authentication to use OTP. To verify if the user was already enrolled, you
should use the isMobileAuthEnrolled(for:)
method on the UserClient
. If the user was not enrolled, you can perform
enrollment by following the Mobile authentication enrollment guide.
Request handling
The entire push mobile authentication process from can be described as follows. In this flow we call the initiator of the mobile authentication request 'portal':
As you can see from the diagram above, the application has the following responsibilities:
- Passing mobile authentication request received from initiator to Onegini SDK
-
Responding to the confirmation challenge
- (optionally) Displaying a dialog to the end-user when his confirmation is required
- Sending the end-user response back to the SDK
-
Handling completion
The Following paragraphs explain those steps and shows how these can be implemented.
Passing the OTP request to the SDK
Before handling the request its recommended to verify if the request can be handled by Onegini SDK. It can be done by calling the canHandleOTPMobileAuthRequest(otp:)
method. In case the request can be handled this method returns Bool
.
Once you verified the mobile authentication request you can handle it by calling the handleOTPMobileAuthRequest(otp:delegate:)
method on the UserClient
instance. The request must be the OTP string(encoded in base64) retrieved from the Token Server. This string contains an otp
code and the transaction_id
in JSON format encoded with UTF8.
Please keep in mind that the a user must be authenticated (logged in into your app) before you can trigger handling an OTP mobile authentication request.
If no user is authenticated the SDK will trigger the didFailToHandleMobileAuthRequest
selector on the delegate containing a user not authenticated error.
If all of the requirements are met the SDK will start the mobile authentication request processing and will inform your MobileAuthRequestDelegate
about
the received confirmation challenge.
Responding to a challenge
After you have passed the mobile authentication request to the SDK, the SDK will request the app to let the user either confirm or deny the request.
The SDK will delegate control back to the provided MobileAuthRequestDelegate
implementation. Hence, the application must contain a class that implements
the methods specified below.
Mobile authentication requests are represented by the MobileAuthRequest
class. Objects of this class are passed to every MobileAuthRequestDelegate
method. From those objects you can get the following information about the current mobile authentication request:
userProfile
- instance ofUserProfile
for which the request has been received.type
- string representing the type of notification which is configured in the Token Server admin panel. The type can be used to distinguish between different business functionality. For example, mobile authentication can be used for logging in or transaction approval.message
- message specified by the initiator when initiating the mobile authentication request. This field represents thesecure_message
parameter sent while initiating the mobile authentication request. The message length is not limited.transactionId
- A unique identifier for each Mobile Authentication request.
When a confirmation challenge is received you can display UI containing information from the MobileAuthRequest
and options to confirm or deny the request.
After a response from the user is received you should send it back to the SDK by calling the confirmation block.
Completion
Once the mobile authentication request has been handled there are two callbacks on the MobileAuthRequestDelegate
that might be called:
userClient(_:didHandleRequest:authenticator:info)
and userClient(_:didFailToHandle:authenticator:error:)
for success and failure correspondingly.
Both methods are optional.
For the success callback you may want to refresh your App's data or hide the view that was used to display the mobile authentication request confirmation screen:
For the failure callback, the situation is a bit more complex. It is strongly recommended to implement error handling. The SDK may deliver important errors such as user (server-side) deregistration which requires special handling such as user logout, unwinding the UI to the login page, etc.