Custom device provisioning
In this tutorial, enabling and configuring custom device provisioning will be covered.
Custom device provisioning is an extension of auto device provisioning.
With Custom device provisioning you can validate:
- Certificate Signing Request during initial provisioning flow.
- Certificate during every application start.
It is vital to gain a solid understanding of the topics that are discussed in the Device Provisioning Concepts tutorial because this tutorial is fully based on those concepts.
Understanding custom device provisioning
First Application StartAuthenticity check is a proprietary IBM MobileFirst Platform Foundation technology that makes sure application is the authentic one and was not modified by anyone.
The main difference between auto and custom provisioning is two functions that you can perform custom validation of CSR during the provisioning process and custom validation of certificate during each application start.
Subsequent Application Starts
By default, the MobileFirst Server uses its internal keystore to issue a certificate.
You can tell the server to use your own keystore by adjusting the worklight.properties file.
Note: The wl.ca.keystore.path property value can be either relative to the /server/ folder of the MobileFirst project or absolute to the file system.
Start by adding a realm that is named CustomDeviceProvisioningRealm to the authenticationConfig.xml file.
Use the auto provisioning authenticator className parameter.
Add a validate-csr-function parameter.
The value of this parameter points to an Adapter function that performs CSR validation.
Use the auto provisioning login module className parameter.
Add a validate-certificate-function parameter.
The value of this parameter points to an Adapter function that performs certificate validation.
Create a mobileSecurityTest.
Add a mandatory testAppAuthenticity test.
Add a mandatory testDeviceId test.
Implementing server-side components
Create an adapter that is named ProvisioningAdapter.
- validateCSR (clientDN, csrContent) – this function is invoked only during initial device provisioning. It is used to check whether the device is authorized to be provisioned. Once the device is provisioned, this function is not invoked again.
- validateCertificate (certificate, customAttributes) – this function is invoked every time that the mobile application establishes a new session with the MobileFirst server. It is used to validate that the certificate that the application/device possesses is still valid and that the application/device is allowed to communicate with server.
These functions are called internally by the MobileFirst authentication framework. Therefore, do not declare them in the XML file of the adapter XML file.
csrContent.activationCode is a custom property that you add to CSR on the client side.
Adapter functionality, for example access http web services, can be used to validate CSR information. For simplicity, the activationCode is checked whether it is equal to a predefined hardcoded string.
If CSR validation is successful, the validateCSR function returns a clientDN (note that it can be modified with more custom data). In addition, it is possible to specify custom attributes to be saved in certificate. Once isSuccessful:true is returned from the validateCSR function, the server generates a certificate and return it to the application.
If CSR validation fails, you must return isSuccessful:false and supply an error message.
You can perform certificate validations according to your custom rules here. Adapter functionality, for example access http web services, can be used to validate the certificate. If the certificate is valid, you must return isSuccessful:true.
Returning isSuccessful:false means that application cannot operate and the only thing that can be done is to reinstall the application so it can be provisioned again.
Implementing client-side components
Create an application, add iPhone/iPad/Android environment to it.
Add security test that is created in previous steps to protect created environment.
In case it is required, configure your application for Application Authenticity test as described in the Application Authenticity Protection training module.
The AppBody element holds application content.
The ProvBody element holds device provisioning-related content.
Note the connectToServerButton in AppBody.
Add listener to connectToServerButton.
Use the WL.Client.connect() API to connect to the MobileFirst Server.
Add a CustomDeviceProvisioningRealmChallengeHandler.js file and reference it in the main HTML file.
Device provisioning challenge handler requires following methods to be implemented:
- handler.createCustomCsr (challenge) – This method is responsible for returning custom properties that are added to CSR. Here you add a custom activationCode property, which is used in the adapter’s validateCSR function. This method is asynchronous to allow collecting custom properties via native code or separate flow.
- handler.processSuccess(identity) – This method is invoked when certificate validation is successfully completed by using the validateCertificate adapter function that you implemented earlier.
- handler.handleFailure() – This method is invoked when certificate validation fails (isSuccessful:false is returned from validateCertificate function).
Create device provisioning challenge handler by using the WL.Client.createProvisioningChallengeHandler() API. Specify realm name as parameter.
When the MobileFirst Server triggers device provisioning, the createCustomCsr function is invoked. Use it to manipulate your UI, for example to hide the application screen and show device provisioning-related components.
You can use information that is returned in the authentication challenge, for example, error messages.
When required custom properties are collected, invoke the submitCustomCsr() API. Adding custom properties to CSR is optional. If you do not want to add custom properties, supply empty JSON object as a parameter.
processSuccess function is called each time the certificate successfully passes validation. You can use it for UI manipulations.
handleFailure function is called each time that the certificate fails validation. You can use it for UI manipulations and to notify the user that the application cannot connect to server.
Click to download the Studio project.▲