Amadis
Secure Client - Provisioning
Foreword
The provisioning is the step that consists in feeding the Secure Client with all the necessary information it needs to connect to the Secure Backend.
The following figure describes the provisioning process:
The provisioning is part of the merchant application onboarding process.
It is assumed that the merchant’s backend administrator has defined the device models, and registered devices and users for each application instance.
The way these parameters are persisted, encoded, and transmitted to the application onboarding process is not known to the SCSDK.
Howto
The secureClient Provisioning and start can be achieved via the singleton instance of the SecureClient
class.
Version 1.1.0+
// Get the class instance and start provisioning
var secureClient = SecureClient.getInstance(activity, AOneAppSecurityCbk(activity))
...
secureClient.provision(settings)
Version 1.1.3+
// Get the class instance and start provisioning
var secureClient = SecureClient.getInstance(AOneAppSecurityCbk())
...
secureClient.authenticate(activity)
secureClient.provision(settings)
secureClient.clientInitialize()
secureClient.clientStart()
As secure client related actions (functions calls) can be time consuming, they should not be performed from android main thread but from another thread to avoid freezing the UI. Only the SecureClient.authenticate() function will ask for device authentication on the activity main thread for security related reasons.
Now there are a few things to consider in this example: the callbacks class AOneAppSecurityCbk
and the provisioning settings.
Callbacks
Some of the SecureClient
class methods are asynchronous. The AOneAppSecurityCbk
class purpose is to provide callback functions for when the asynchronous tasks are complete or terminated for some reason.
The AOneAppSecurityCbk
class must derive the IAppSecurityCbk
interface. The rest of its content is implementation dependent. Find below an basic implementation example:
class AOneAppSecurityCbk() : IAOneAppSecurityCbk {
override fun getApplicationInfo(): String {
Log.v("${this::class.java.simpleName}", "getApplicationInfo")
return "{}"
}
override fun notifyError(error: Int) {
Log.v("${this::class.java.simpleName}", "notifyError - error: " + error)
}
override fun notifyException(e: Exception) {
Log.v("${this::class.java.simpleName}", "notifyException - exception: " + e)
}
override fun notifyExit() {
Log.v("${this::class.java.simpleName}", "notifyExit")
}
override fun notifyRemediation(data: String?) {
Log.v("${this::class.java.simpleName}", "notifyRemediation")
}
override fun pinEnterResult(params: Any?, status: IAOneAppSecurityCbk.PinStatus,
pin: ByteArray?, error: Int) {
Log.v("${this::class.java.simpleName}", "pinEnterResult - params: ${params},
status: ${status}, error: ${error}")
}
override fun syncExecuteResult(params: Any?, error: Int) {
Log.v("${this::class.java.simpleName}", "syncExecuteResult - error: ${error},
params: ${params}")
}
}
Provisioning settings
The provisioning settings are the information the Secure Client will need to connect to the Backend Server. There are to be provided as a JSON string with the following parameter:
domain: Secure Backend IP address or hostname
port
osType (should be set to “Android”)
hardwareDescription
terminalId:
smrdTerminalId
(POI ID) used when creating a the SMDeviceclientId: client ID received when registering the user in the database
secret: client secret received when registering the user in the database
ownCertPass: the owner of the backend certificate
checkServCert: some field to be verified inside the backend certficates
certDir: certificates location inside the phone
safetynetKey: the Google Safetynet access key
Which gives us the following code as example:
Flow
The provisioning step is supposed to happen only once in the application lifetime (unless some parameters need to be changed - for example, a change of user ID or a change of domain name, etc…).
If you want to verify whether provisioning has already been completed, please call the isProvisioned()
function. In case you need to change the provisioning data a call to the clearProvision()
function must be made beforehand.