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 Onegini 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 enrollForPushMobileAuthWithDeviceToken:completion:
method
of the ONGUserClient
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. Onegini SDK represents them by ONGPendingMobileAuthRequest
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 ONGMobileAuthRequest
class.
From the ONGPendingMobileAuthRequest
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 Onegini 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 Onegini SDK.
Push notification received from APNS is represented by an NSDictionary
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 Onegini SDK. It can be done
by calling the pendingMobileAuthRequestFromUserInfo:
method. This method will try to parse the NSDictionary
to ONGPendingMobileAuthRequest
. If a push notification is intended for the SDK the
method will return ONGPendingMobileAuthRequest
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 ONGPendingMobileAuthRequest
it is handled by calling the handlePendingPushMobileAuthRequest:delegate:
on the
ONGUserClient
shared instance. Since notifications may require authentication, the SDK needs a delegate (ONGMobileAuthRequestDelegate
) 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 ONGMobileAuthRequestDelegate
implementation. Hence, the application
must contain a class that implements the methods specified below.
Mobile authentication requests are represented by ONGMobileAuthRequest
class. Objects of this class are passed to
every ONGMobileAuthRequestDelegate
method. From those obejcts you can get following information about currently
processes mobile authentication request:
userProfile
- instance ofONGUserProfile
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 ONGCustomInfo
object is passed
under the ONGCustomAuthInfoKey
in the userInfo of error object within the ONGPinChallenge
.
Completion
Once the mobile authentication request has been handled there are two callbacks on the ONGMobileAuthRequestDelegate
that might be called: userClient:didHandleMobileAuthenticationRequest: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 -[id<ONGBiometricChallengeSender>
cancelChallenge:]
methods.
In case of failure during authentication with Custom Authenticator returned error might include ONGCustomInfo
object under
the ONGCustomAuthInfoKey
in the userInfo.