Mobile authentication with OTP¶
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 FCM. 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.
In order to use mobile authentication with OTP, you have to set it up in the Token Server. Each user of the app has to perform the mobile authentication enrollment in order to enable the functionality for himself. To learn how to do it please review mobile authentication enrollment section of other topic guide.
It's only required to enroll for mobile authentication to use OTP. To verify if the user was already enrolled, you should use the
UserClient#isUserEnrolledForMobileAuth(UserProfile userProfile) method. If the user was not enrolled, you can perform enrollment by following the
Mobile Authentication Enrollment guide.
The entire OTP mobile authentication process from can be described as follows. In this flow we call the initiator of the mobile authentication request "Portal":
sequenceDiagram autonumber Note over Portal,Token Server: The portal wants to initialise<br/> mobile authentication with OTP Portal ->> Token Server: Mobile authentication request. Token Server ->> Portal: ID of the initialized request<br/> and Base64 encoded OTP. Portal ->> App: Request ID and OTP code. App ->> SDK: Request ID<br/> and OTP code. SDK ->> Token Server: Request for encrypted message. Token Server ->> SDK: Base64 encoded and PGP encrypted<br/> authentication data. SDK ->> SDK: The message is decrypted Note over App,SDK: SDK triggers a request handler so the app<br/> can show a custom dialogue to the end-user. SDK ->> App: Trigger a request handler. App ->> SDK: The authentication result. SDK ->> SDK: Encrypt authentication result. SDK ->> Token Server: The encrypted authentication result. Token Server ->> Portal: The mobile authentication result.
As you can see from the diagram above, the application has the following responsibilities:
- Passing the mobile authentication request received from the initiator to the SDK
- Responding to the confirmation request
- (optionally ) Displaying a dialog to the end-user when his confirmation is required
- Sending the end-user response back to the SDK
- Handling completion of the mobile authentication request
The Following paragraphs explain those steps and shows how these can be implemented.
Setting up the OTP request handler¶
To support mobile authentication with OTP in your app you need to implement the
OneginiMobileAuthOtpRequestHandler interface and set its instance during the
SDK initialization step by calling
setMobileAuthenticationOtpRequestHandler(OneginiMobileAuthOtpRequestHandler handler) method on
Then you need to handle all interface methods in order to show/hide user interface with (for example) buttons allowing to accept or deny request.
Example how to set the OneginiMobileAuthOtpRequestHandler
1 2 3
Example how to implement the OneginiMobileAuthOtpRequestHandler
1 2 3 4 5 6 7 8 9 10 11 12 13 14
You need to implement both the
startAuthentication(final OneginiMobileAuthenticationRequest oneginiMobileAuthenticationRequest, final OneginiAcceptDenyCallback oneginiAcceptDenyCallback)is called when a new mobile authentication request is received. The First parameter is the
OneginiMobileAuthenticationRequestobject which contains the message you can optionally present to the user and the UserProfile object that specifies the profile for which this request is received. The Second parameter is a callback object that you must use when the end-user accepts or denies the request, by calling
finishAuthenticationis called when the required interaction with the request delegate is finished. If you use a dialog or activity to interact with the end-user you can use this method to close the dialog or finish the activity.
Passing the OTP request to the SDK¶
Please keep in mind that to trigger mobile authentication with OTP a user has to be authenticated (logged in to your app). Once that condition is satisfied
and the user is enrolled for mobile authentication you can call the
OneginiClient#UserClient#handleMobileAuthWithOtp(String otpCode, OneginiMobileAuthWithOtpHandler mobileAuthWithOtpHandler) method. The first argument is the
OTP received from your web application (eg. the user scanned a QR code that encodes the OTP). The second argument is the
OneginiMobileAuthWithOtpHandler interface which contains two methods you should react to:
onSuccess() - called when mobile authentication with OTP succeeded,
onError(OneginiMobileAuthWithOtpError error) - called when an error occurred during mobile authentication with OTP. Please check the
OneginiMobileAuthWithOtpError error object to learn about the reason of failure. You can check an error type and message by calling respectively the
getMessage() methods on the error object.
Example how to trigger authentication with OTP
1 2 3 4 5 6 7 8 9 10 11 12 13 14