Mobile authentication with push
Two factor authentication can be implemented using APNs push notifications. It's a very secure and user friendly way of authentication. You can use this feature to allow users to confirm their transactions. Confirmation can be done using simple Accept button, PIN, Biometric or a Custom Authenticator. All transaction information is encrypted and no sensitive information is sent through APNs.
Configuration
Before mobile authentication with push can be used, you should configure:
- Remote Notification Support in your app - you can configure it by following Apple push notification documentation
- Token Server - please follow Mobile authentication configuration guide
When your app and token server are configured for push notifications you should be able to enroll for mobile authentication with push and handle push requests using the SDK.
Enrollment
Push mobile authentication enrollment requires regular mobile authentication enrollment to be done first. Only after it is completed, you can enroll for the push.
Enrollment for the mobile authentication with push can be described as follows:
The first step is to obtain the deviceToken
from APNs. Please follow the Apple remote notification
guide for instructions on how to obtain it.
The next step is to enroll with the device token using the enrollPushMobileAuth(with:completion:)
method
of the UserClient
instance:
The result of the enrollment and, in case an error occurred, an error will be passed to the completion block.
Receiving requests
Once the user is enrolled he is able to receive push notifications. The SDK represents them by PendingMobileAuthRequest
class. Those requests
do not contain any sensitive information, since those might be sent through the unsecure channels like APNS. However, pending mobile authentication requests
contain an identifier which is later used to fetch full mobile authentication request information which is represented by objects of a MobileAuthRequest
class.
From the PendingMobileAuthRequest
object you can get following information:
transactionId
- a unique identifier for each Mobile Authentication request.userProfile
- user profile for which mobile authentication request was sent.date
- the date when the mobile authentication request was sent.timeToLive
- time to live for which mobile authentication request was sent.message
- message specified by the portal when initiating the mobile authentication request.userInfo
- user info received from the APNS.
The SDK supports two ways of obtaining pending mobile authentication requests: APNS and Token Server.
APNS
The process of receiving a push from the APNS can be described as follows. In this flow we call the initiator of the mobile authentication request 'portal':
When application receives a push notifiation from APNS it should be able to differentiate between different push notification messages. The reason why this responsibility is in the app is that one app can only have one push token. This allows the app to support more push messaging features besides mobile authentication provided by the SDK.
Push notification received from APNS is represented by a Dictionary
object which you can obtain from the UNNotificationResponse
object as follows:
In case you are using the old API:
Before handling the push request it is required to verify that the request can be handled by the SDK. It can be done
by calling the pendingMobileAuthRequest(from:)
method. This method will try to parse the Dictionary
to PendingMobileAuthRequest
. If a push notification is intended for the SDK the
method will return PendingMobileAuthRequest
object with transactionId
and userProfile
. Otherwise, it will return nil
.
Example code for parsing push notification received from APNS:
Token Server
When device did not receive sent push notifications you can use this feature to fetch a list containing pending mobile authentication requests. The process of receiving a push from the Token Server can be described as follows. In this flow we call the initiator of the mobile authentication request 'portal':
Fetching pending mobile authentication requests can be performed using the following method:
When the user will not have any pending mobile authentication requests, then the method will return an empty list. The results of this request are sorted by the time sent (descending).
Request handling
Once the push request is received and parsed to PendingMobileAuthRequest
it is handled by calling the handlePendingPushMobileAuthRequest:delegate:
on the
UserClient
shared instance. Since notifications may require authentication, the SDK needs a delegate (MobileAuthRequestDelegate
) to authenticate.
The entire process of handling pending requests can be described as follows.
As you can see from the diagram above, the application has the following responsibilities during the request handling:
-
Responding to authentication challenges
- Displaying a dialog to the end-user when an authentication challenge is received
- Sending the users' response back to the SDK
-
Handling the completion of the mobile authentication request
The Following paragraphs explain those steps and show how the responsibilities mentioned above can be implemented.
Responding to a challenge
After you have passed 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 MobileAuthRequest
class. Objects of this class are passed to
every MobileAuthRequestDelegate
method. From those obejcts you can get following information about currently
processes mobile authentication request:
userProfile
- instance ofUserProfile
for which request has been received.type
- string representing type of the notification which is configured in the Token Server admin panel. The type can be used to distinguish between business functionalities. For example, mobile authentication can be used for logging in or transaction approval.message
- message specified by the portal when initiating the mobile authentication request. This field represents thesecure_message
parameter sent while initiating the mobile authentication request. This message length is not limited.userInfo
- user info received from the APNS. TheuserInfo
can also contain a message. The message specified in theuserInfo
object represents themessage
parameter that was sent while initiating the mobile authentication request. The length of this message is limited to 155 characters due to APNS' message length limitations. The value is set only for push mobile authentications.transactionId
- A unique identifier for each Mobile Authentication request.
When a challenge is received you should display UI containing selected information from ONGMobileAuthRequest
and an
interface which allows user to respond to the received challenge e.g. PIN screen when PIN challenge was received.
The user's response should be send back to the SDK via the challenge sender object or through the confirmation block in
case of confirmation challenge.
Confirmation
PIN
Biometric
Depending on your needs the challenge
may be responded in a various ways: continue with
custom prompt, fallback to pin or even cancel. After you have responded to the challenge
, the SDK presents the TouchID
authentication with the supplied (or default) prompt. Since this method is optional, the SDK will automatically fallback
to PIN authentication if this method is not implemented.
Important: in order to receive biometric challenges you have to register the biometric authenticator first by following the Biometric authenticator topic guide.
Custom
When you receive a Custom Authenticator challenge you can respond to it with optional data, pin fallback or cancellation.
Responding with data will continue authentication process, responding with pin will send pin challenge instead and cancellation
will deny the mobile authentication request.
Authentication with Custom Authenticator might fail with fallback to PIN. In this case CustomInfo
object is passed
under the CustomAuthInfoKey
in the userInfo of error object within the PinChallenge
.
Completion
Once the mobile authentication request has been handled there are two callbacks on the MobileAuthRequestDelegate
that might be called: userClient(_:request:authenticator:info:)
and
userClient(_:didFailToHandleMobileAuthenticationRequest:authenticator:error:)
for success and failure correspondingly. Both methods are
optionals.
For the success callback you may want to refresh your App's data or hide the view:
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's (server-side) deregistration which requires special handling such as
user logout, unwinding the UI to the login page, etc. However, it also may deliver errors that can be ignored such as
the cancellation error which happens, when you cancel the challenge by calling the BiometricChallengeSender.cancel
methods.
In case of failure during authentication with Custom Authenticator returned error might include CustomInfo
object under
the CustomAuthInfoKey
in the userInfo.