...
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 AOneAppSecurity
class. SecureClient
class.
Version 1.1.0+
Code Block |
---|
// Get the class instance and start provisioning AOneAppSecurityvar secureClient = SecureClient.getInstance(this.contextactivity, AOneAppSecurityCbk(this.activity)) ... secureClient.provision(settings) |
Version 1.1.3+
Code Block |
---|
// Get the class instance and start provisioning var secureClient = SecureClient.getInstance(AOneAppSecurityCbk()) ... secureClient.authenticate(activity) secureClient.provision(settings) secureClient.clientInitialize() secureClient.clientStart() |
Note |
---|
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 AOneAppSecurity
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 IAOneAppSecurityCbk
IAppSecurityCbk
interface. The rest of its content is implementation dependent. Find below an basic implementation example:
...
domain: Secure Backend IP address or hostname
port
osType (should be set to “Anroid”“Android”)
hardwareDescription
terminalId: terminal ID received when registering the device in the database
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:
Code Block |
---|
// Provisioning parameters val settings = """ |{ |"domain":"mydev.domainatheos.nameca", |"port":8090443, |"osType":"Android", |"hardwareDescription":"AmadisOneClient", |"terminalId":"123456789111111111111", |"clientId":2"<client_id>", |"secret":"<client_secret>", |"ownCertPass":"amadis", |"checkSrvCert":"iSSuer.Cn = Alexandre Munsch | subJect/St ~ Quebec ", |"certDir": "${getSecureClientDir()}", |"safetynetKey":"DbIHpPvGbfnj6j8gh6mG7FtB8eAgO1yM8V0DnDPT<safetynet_key>" |}""".trimMargin() |
The “checkSrvCert” element cannot be empty and should contain valid information for both the issuer
and the subject
fields.
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…).
Warning |
---|
Calling the provisioning method on an already provisioned device will not only fail but also clean the provisioning settings from the system. |
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 it is cleaner to programmatically remove the existing data (called stores) and then start provisioning again.
To delete the existing store, the following code can be used:
...
a call to the clearProvision()
function must be made beforehand.
Warning |
---|
Calling the provisioning method on an already provisioned device will fail. |