Custom device provisioning
This tutorial explains how to enable and configure custom device provisioning.
Custom device provisioning is an extension of auto device provisioning.
With custom device provisioning, you can validate:
- Certificate Signing Requests during an initial provisioning flow.
- Certificates at every application start.
Prerequisite: Make sure that you understand the topics discussed in Device Provisioning Concepts because this tutorial is fully based on those concepts.
This tutorial covers the following topics:
- Understanding custom device provisioning
- Configuring the authenticationConfig.xml file
- Implementing server-side components
- Implementing client-side components
- Sample application
Understanding custom device provisioning
First application start
Authenticity check is a proprietary IBM MobileFirst Platform Foundation technology, which makes sure that the application is the authentic one and was not modified by anyone.
The main difference between auto and custom provisioning consists in two functions that are provided for custom provisioning:
- Custom validation of CSR during the provisioning process
- Custom validation of certificate during each application start
Subsequent application starts
By default, MobileFirst Server uses its internal keystore to issue a certificate.
You can make the server use your own keystore by adjusting 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.
Configuring the authenticationConfig.xml file
- Add a realm that is named
- Use the auto provisioning authenticator
- Add a
The value of this parameter points to an adapter function that performs CSR validation.
- Add a
- Use the auto provisioning login module
- Add a
The value of this parameter points to an adapter function that performs certificate validation.
- Create a
- Add a mandatory
- Add a mandatory
Implementing server-side components
- Create an adapter that is named
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. After 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 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 the server.
Note: 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 property is a custom property that you add to CSR on the client side.
You can use adapter functionality, such as access to http web services, to validate CSR information. For simplicity, the
activationCode is checked against a predefined hardcoded string.
- If CSR validation is successful, the
validateCSRfunction returns a
clientDN. In addition, it is possible to specify custom attributes to be saved in certificate. After the
isSuccessful:true, the server generates a certificate and returns it to the application.
Note: The function can be modified with more custom data.
- If CSR validation fails, the function must return
isSuccessful:falseand supply an error message.
You can perform certificate validations according to your custom rules here. You can use adapter functionality, such as access to http web services, to validate the certificate. If the certificate is valid, the function must return
isSuccessful:false return value means that the application cannot operate and the only thing that can be done is to reinstall the application so that it can be provisioned again.
Implementing client-side components
Create an application and add an iPhone, iPad, or Android environment to it.
- Add the security test that you created in the Security tests section to protect the created environment.
- If required, configure your application for an application authenticity test as described in Application Authenticity Protection.
AppBody element holds application content.
ProvBody element holds device provisioning-related content.
AppBody element has a button for connection to the server.
- Add a listener to the
- Use the
WL.Client.connect()API to connect to MobileFirst Server.
- Add a
CustomDeviceProvisioningRealmChallengeHandler.jsfile and reference it in the main HTML file.
For a challenge handler for device provisioning, implement the following methods:
handler.createCustomCsr (challenge)– This method is responsible for returning custom properties that are added to CSR. Here you add a custom
activationCodeproperty, which is used in the adapter
validateCSRfunction. 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 the
validateCertificateadapter function that you implemented in the validateCertificate section.
handler.handleFailure()– This method is invoked when certificate validation fails and the
- Create a device provisioning challenge handler by using the
WL.Client.createProvisioningChallengeHandler()API. Specify a realm name as parameter.
- When MobileFirst Server triggers device provisioning, the
createCustomCsrfunction 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 the required custom properties are collected, invoke the
Adding custom properties to CSR is optional. If you do not want to add custom properties, supply an empty JSON object as a parameter.
processSuccessfunction is called each time the certificate successfully passes validation. You can use it for UI manipulations.
handleFailurefunction 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 the server.
Click to download the Studio project.