Push Authentication

Using the push notification mechanisms offered by Apple and Google, a device can receive requests to authenticate.

When the session exploiter (such as a webservice) knows the identity of the user who should authenticate, VeridiumID can create a session immediately. A session opportunity (QR code) is not needed. The exploiter can trigger an APNS or FCM push notification from the VeridiumID server to the expected authenticator (typically a phone) to complete an authentication session.

Server authentication request

The exploiter, usually through the 3rd party server, makes an AuthenticationRequest call (see Appendix VeridiumID API) to the Veridium server using the provisioned client certificate. Information necessary for the creation of the session includes:

memberExternalId (string): Enteprise integration external identifier (for example, ADv2MultiStepEnrollment)
profileExternalId (string): Enterprise user profile external identifier (for this example it is the user login name)

CODE


curl -X POST \
  https://[domain:port]/websec/rest/enterprise/AuthenticationRequest \
  -H 'content-type: application/vnd.veridiumid.authenticationrequest-v1+json' \
  -d '{ "memberExternalId":"ADv2MultiStepEnrollment","profileExternalId":"user123","context":{"userAgentName":"Chrome","userAgentVersion":"1.0","osName":"Linux","osVersion":"11.0","serviceIdentifier":"Geofencing","location":{"countryName":"UK","city":"London"}}}'

The Veridium Server detects which devices are able to complete the session (devices that have the profile enrolled) and sends them a push notification.

Session status changes can be queried by calling GetSessionStatus/GetSessionStatusAsync (see Appendix VeridiumID API). For example, a website that wants to refresh the login page when the session status is changed, must make periodic calls for GetSessionStatus or open a long polling connection with GetSessionStatusAsync and make appropiate logic based on the returned session status.

Mobile authentication

When the mobile application receives the push notification it needs to forward it to the SDK for handling.

CODE

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {    
    ...
    func application(_ application:, didReceiveRemoteNotification notification:, fetchCompletionHandler completionHandler:) {
        print("Did receive push: \(String(describing: notification["actionName"]))")
        VIDMobileSDK.shared().handlePush(notification)
    }
    ...
}

class MainViewController: UIViewController {
    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        
        // ...
        
        VIDMobileSDK.shared().pushDelegate = self
        VIDMobileSDK.shared().authenticationDelegate = self
        
        // ...
    }
}

extension MainViewController: VIDPushDelegate {
    func pushesPending() {
        VIDMobileSDK.shared().consumePendingPushes()
    }
}

class AuthenticationHandler : VIDAuthenticationDelegate {
    // MARK: VIDAuthenticationDelegate
    func didStartAuthentication() { }

    func didFinishAuthentication(response: VIDAuthResponse, profile: VIDProfile?) { }
    
    func didFinishAuthenticationServerChallenge(signedResponse: VIDAuthResponse, profile: VIDProfile?) { }

    func didCancelAuthentication(profile: VIDProfile?) { }
    
    func didCancelAuthenticationServerChallenge(signedResponse: VIDAuthResponse, profile: VIDProfile?) { }
    
    func didFailAuthentication(error: VIDError, profile: VIDProfile?) {
        if error.requiresBiometryRevalidation() && profile != nil {
            VIDMobileSDK.shared().reenrollBiometricAuthenticators(for: profile!)
        }
        else {
            let nsError = error as NSError
            print(nsError.localizedReason)
        }
     }
    
    func didFailAuthenticationServerChallenge(signedResponse: VIDAuthResponse, error: VIDError, profile: VIDProfile?) { }

}

CODE

// Call this when a push notification is received
    ...
    VeridiumIdPendingIntent pendingIntent = VeridiumMobileSDK.getInstance().processNotification(notification);
    if(pendingIntent.hasPendingIntent())
        pendingIntent.launchPendingIntent(this, RC_AUTH);
    ...

    // Handle result
    protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
        if (resultCode == RESULT_CANCELED)
            return;
        if (requestCode == RC_AUTH) {
            VeridiumIdErrorResponse errorResponse = data.getParcelableExtra(VeridiumMobileSDK.VERIDIUMID_KEY_ERROR_EXTRA);
            if (errorResponse != null) {
                // ToDo Handle authentication error response according to your needs
            } else {
                VeridiumIdAuthenticationResponse response = data.getParcelableExtra(VeridiumMobileSDK.VERIDIUMID_KEY_RESPONSE_EXTRA);
                //ToDo Handle authentication result according to your needs
            }
        }
    }

After the mobile device completes biometric assertion, it returns the results to the veridiumID server which updates the session status accordingly.