Kiosk

Kiosk mode allows users to register on front office mobile device and then authenticate everywhere. The mobile device is referred as “shared device”.

Kiosk mode requires server side biometry matching, since after enrollment, users can authenticate in any other office using registered devices.

Enabling Kiosk Mode for iOS

Prerequisites

In order to benefit from the kiosk mode functionalities, the container app should add the VeridiumKioskOrchestrator.xcframework and VeridiumCore.xcframework to its dependencies.

In addition to VeridiumKioskOrchestrator.xcframework and VeridiumCore.xcframework, the container app should also include dependencies for the biometric libraries it would like to use. For example, if 4F biometric library is used, the following dependencies should be added:

Veridium4FUI.xcframework
Veridium4FBiometrics.xcframework

The VeridiumKioskOrchestrator.xcframework targets the iOS version 11 and above, since it relies on some Secure Enclave functionalities that are stabilized with iOS 11.

SDK Initialization

The kiosk mode functionalities are provided by the VIDKioskSDK class. In order to use the functionalities, the container app should create a VIDKioskSDK instance and initialize it with appropriate configuration. The following steps show how it is done:

Create a VIDEnvironment instance:

CODE

let environment: VIDEnvironment = VIDEnvironment(baseURL: "<base URL>",
                                                 name: "<environment name>", 
                                                 externalId: "<external id in UUID format>", 
                                                 memberExternalId: "<external id of the integration>")

Create a VIDKioskSDK instance using the environment object:

CODE

let kioskSDK: VIDKioskSDK = VIDKioskSDK.getInstance(environment: environment)

Configure VIDKioskSDK instance with a VIDKioskSDKConfiguration instance with proxy device registration protocol implementation (see Device registration for details) and biometric methods to be used for enrollment:

CODE

let config = VIDKioskSDKConfiguration(deviceDataSource: <VIDDeviceRegisterDataSourceProtocol implementation>,
                                      bioLibConfigurations: <Array of VIDBioLibConfiguration implementations>)
kioskSDK.initialize(with: config)

The VIDBioLibConfiguration implementations are used for providing registration and configuration of biometric libraries. The VIDKioskSDKConfiguration should be initialized with at least one VIDBioLibConfiguration implementation, otherwise the SDK initialization result with an error.

An example VIDBioLibConguration implementation for the 4F library is as follows:

CODE

class FourFBiolibConfiguration: VIDBioLibConfiguration {
    var biometricLibraryType: VIDBiometricLibrary {
        VIDBiometricLibrary.FOURF
    }
    
    func setupBiometricLibrary(with license: String, using veridiumSDK: VeridiumSDK) -> VeridiumLicenseStatus {
        return veridiumSDK.setupLib4F(withLicense: license)
    }
    
    func registerBiometricEnrollerAndAuthenticator(using veridiumSDK: VeridiumSDK) {
        veridiumSDK.register4FUIAuthenticator()
        veridiumSDK.register4FUIEnroller()
    }
    
    func configureBiometricLibrary(using veridiumSDK: VeridiumSDK) {
        let authenticatorConfig = VeridiumFourFCaptureConfig.init(forAuthWithHand: .forceRightHandEnroll, andLiveness: true)
        authenticatorConfig.do_debug = false
        authenticatorConfig.configureTimeoutEnabled(true, withTimeoutCanRestart: true, andTimoutSeconds: 30, andAllowedRetries: .infinite)
        veridiumSDK.configureFourFAuthenticator(authenticatorConfig)
        
        let enrollerConfig = VeridiumFourFCaptureConfig.init(forEnrollWithHand: .forceRightHandEnroll, andLiveness: true)
        enrollerConfig.do_debug = false
        enrollerConfig.configureTimeoutEnabled(true, withTimeoutCanRestart: true, andTimoutSeconds: 30, andAllowedRetries: .infinite)
        veridiumSDK.configureFourFEnroler(enrollerConfig)
    }
}

After the initialize call, the VIDKioskSDK instance becomes ready for device registration, user enrollment and authentication.

The VIDKioskSDK instance can be kept as a member field in AppDelegate of the container app, in order to use its public methods throughout different view controllers.

Device Registration

To perform device registration, the registerDevice API method of the VIDKioskSDK instance should be called as follows:

CODE

kioskSDK.registerDevice { result, error in
    if let error = error {
        // Handle error
        return
    }
    // Perform actions after a successful registration 
}

To establish device registration through proxy API call, the container app should also implement VIDDeviceRegisterDataSourceProtocol and provide it through the VIDKioskSDK's initialize call.

The protocol is defined as follows:

CODE

@objc public protocol VIDDeviceRegisterDataSourceProtocol {
    
    /// `RegisterDeviceCallback` is the type used for providing result of device registration.
    ///   - registrationResult: Dictionary containing parameters after a successful registration. Can be `nil` if registration fails.
    ///   - registrationError:  Error returned if device registration fails. `nil` for successful registration
    typealias RegisterDeviceCallback = (_ registrationResult: NSDictionary?, _ registrationError: Error?) -> ()
    
    /// Sends request for device registration
    ///   - payload:  Dictionary containing required parameters for device registration request
    ///   - callback: Provides device registration result
    func registerDevice(payload: NSDictionary?, callback: @escaping RegisterDeviceCallback)
    
}

The registerDevice protocol method implementation should perform the API call with the payload dictionary provided by the SDK (request parameters from the container app can be merged with the payload).

The API call result should be provided by calling RegisterDeviceCallback. If the call is resulted with success, the callback should be called with a dictionary containing response parameters. Otherwise, the callback should be called with the error.

The diagram below shows the device registration flow between the VIDKioskSDK and the container app:

User Enrolment

The VIDKioskSDK provides registerAccount public API method to perform enrolment of the users. The method requires VIDRegisterAccountOptions instance as a parameter, in order to provide configuration for the enrollment.

One of the configuration parameters VIDRegisterAccountOptions requires is the loginData. The loginData represents credentials of the user in external system. It can be provided either as a plain json string including user credentials, or a JWT (json web token). The example below shows how the login data parameter is initialized for either format:

CODE

let loginDataAsPlainJson = VIDRegisterAccountLoginData(type: .plainJson, content: "<Credentials data as a Json String>")
let loginDataAsJWT = VIDRegisterAccountLoginData(type: .jwt, content: "<JWT string in standard format>")

Calling the registerAccount method initiates a direct (non-proxy) communication with the VeridiumId server. The result of the enrollment is provided to the container app through an asynchronous closure as method parameter. The code snippet below shows how the registerAccount method is used:

CODE

let loginData = VIDRegisterAccountLoginData(type: .plainJson, content: "<Credentials data>")
let registrationOptions = VIDRegisterAccountOptions(loginData: loginData, 
memberExternalId: "<Integration external identifier>", 
registrationMode: "<Registration mode>")
kioskSDK.registerAccount(options: registrationOptions) { registrationResult, registrationError in
    if let error = registrationError {
        // Handle error
        return
    }
      
    switch registrationResult.state {
    case .ENROLED:
        // Perform actions after successful enrolment
    case .FAILED:
        // Perform actions after failed enrolment
    case .CANCELED:
        // Perform actions after canceled enrolment
    case .CACHED_REQUEST:
        // There is an internet connectivity problem. 
        // Biometric enrolment data are stored on device to be sent later.
        // Use registrationResult.storedBiometricEnrolmentDataId in order to 
        // call registerAccount again with stored enrolment data. 
}

User enrollment in offline mode

If the device is not connected to internet during registerAccount call, the VIDKioskSDK stores the biometric enrollment data to be sent again later in online mode.

The data from each call is first encrypted through Secure Enclave, and stored as separate files in the container app’s sandbox file system. The registerAccount result callback provides a storage id (registrationResult.storedBiometricEnrolmentDataId in the example above).

The container app can use the storage id later in online mode to finalize the enrollment with stored enrollment data, as follows:

CODE

let registrationOptions = VIDRegisterAccountOptions(loginData: "<Credentials data>", 
memberExternalId: "<Integration external identifier>", 
registrationMode: "<Registration mode>", biometricCaptureId: "<the storage id>")
// here, kioskSDK.registerAcount method can be called with VIDRegisterAccountOptions 
// as in the previous example

IMPORTANT

In order to be used in offline mode, the registerAccount method should at least be called once in online mode, in order to get mandatory biometric enrolment methods from the VeridiumId server.

The VIDKioskSDK also provides the removeBiometricEnrolmentData api method to remove stored enrollment data with storage id if account registration is no longer desired. The api method can be called as follows:

CODE

kioskSDK.removeBiometricEnrolmentData(biometricCaptureId: storageId, callback: { (isSuccesful, error) in
    if let error = error {
        // Handle error
        return
    }
    
    if (isSuccesful) {
        // Perform actions after successful removal
    }
})

User Authentication

The VIDKioskSDK provides authenticate public API method to perform authentication of users. The method requires VIDAuthenticationOptions instance as parameter, which includes necessary info for the authentication, like profile external id, member external id, extra values (if available).

Calling the authenticate method initiates a direct (non-proxy) communication with the VeridiumId server. The result of the authentication is provided to the container app through an asynchronous closure as method parameter. The code snippet below shows how the authenticate method is being called:

CODE

let authenticationOptions = VIDAuthenticationOptions(profileExternalId: "<profile id>", memberExternalId: "<member external id>")
kioskSDK.authenticate(options: authenticationOptions) { authenticationResult, authenticationError in
    if let error = authenticationError {
        // Handle error 
        return
    }
    
    switch authenticationResult.state {
    case .AUTHENTICATED:
        // Perform actions after a successful authentication
    case .FAILED:
        // Perform actions after a failed authentication
    case .CANCELED:
        // Perform actions after a canceled authentication
    }  
}

Device Unregistration

The VIDKioskSDK provides removeDevice public API method in order to unregister device. The method can be called as follows:

CODE

kioskSDK.removeDevice(callback: { [weak self] (isRemoved, error) in
    if let error = error {
        // Handle error
        return
    }
    
    if (isRemoved) {
        // Perform actions after a successful removal
    }
})