Purpose
Zebra offers an extended device management API with ruggedized Android devices like the Motorola TC70. Using this API offers the possibility to enable the device to setup the device quickly and run applications securely.
- Manage personal certificates to proof device or user identity
- Manage root certificates to setup trust to networks and applications
- Manage the wireless interface to configure networks
- Manage other communication interfaces
- Manage the installation, update and configuration of applications
- Manage barcode scanner configuration
- Manage device settings like clock, language or the touch configuration
- Sending intents or broadcast messages to the Android API
- […] many more […]
The following document outlines the steps enabling Afaria to access the Zebra device management API.
Architecture
The central element of the architecture is an Android application that listens to a broadcast receiver the Afaria client sends commands to. This commands will enforce the execution of the Mobility Extension device management API.
- The foundation of the device management API is the Mx (Mobility Extensions) layer.
- To enable the accessibility for the connector application the Motorola EMDK Android Application has to be installed on the device. (The EMDK is installed in future releases of the Zebra device firmware)
- The MDM Toolkit Connector App uses a broadcast receiver to listen to intents sent by the Afaria Client.
- The Afaria App will enforce the MDM Toolkit Connector to apply a configuration that is stored in an XML file on the file system
- The Afaria App enforces the MDM Toolkit Connector to request a certificate via static link library.
- The client file system holds XML, Application, and certificate files for the MDM Toolkit Connector App and stores the MDM Toolkit Connector App log for the Afaria Client.
- The Afaria App receives Session Script commands “Execute Program: am <broadcast […]>” to enforce the MXM Toolkit Connector app applying the configuration and it manages the XML, Application and Certificate files on the client file system.
- The Afaria Package Server component receives the certificate request of the static link library and forwards it to the certificate authority.
- The Afaria Session Manager component holds the script files that send XML, Application and certificate files from the server file system to the client file system and receives log files from the client file system.
Building the MDM Toolkit Connector Application
The following section will outline the implementation of the MDM Toolkit Connector application and present the technical background.
History
In the past Motorola started building the Mobility Extension API to support the device configuration and a basic device management. The device listens to XML files sent to a specific folder and signed by a certificate provided during deployment process. The next step was implementing the EMDK. An Android Firmware Update provided by Zebra encapsulate the XML signing and configuration applying process and provides the possibility to include configuration files into applications that can trigger the configuration. Currently Zebra starts to ship the MDM Toolkit to enable MDM vendor to integrate the configuration API into device management software.
Overview
- A overview on the functionality accessible to customers of the EMDK can be found here: https://developer.motorolasolutions.com/docs/DOC-2167 The call, that sends the configuration request to the device can be used for the MDM Toolkit, too.
- How to develop “Hello EMDK” can be found here: https://developer.motorolasolutions.com/docs/DOC-2184
- Information about using a broadcast receiver can be found here: http://developer.android.com/reference/android/content/BroadcastReceiver.html
- Information about using the Afaria Static Link Library for Android can be found here: Afaria 7 Client App Integration Static Link Library for Android Devices - SAP Mobility - SCN Wiki
- Sending large APK files to devices: Afaria Session Manger Android Application Download
The implementation
The application design is quite simple. A broadcast receiver listens to commands send by the Afaria Client. According to the send command the application will
- Either: Consume a XML file in the working folder and apply the configuration. If extra files are required, it has to be in the working folder
- Or: Manage a device certificate that will be stored in the device key store. Depending on parameters it will happen:
- Nothing. If a valid certificate is installed and it will not expire in X days
- A new certificate is requested with the Afaria Static Link Library and it will replace to old certificate
Logging
Every action will be stored in a log file in the working folder. If the XML was processed correctly by the Device Management Framework, the framework call will return exact the same XML. Errors in the configuration will be shown in the returned XML. These results and other program calls are stored in the log file in the working folder.
Calling the MDM Toolkit Connector Application in Afaria
The exact call depends on the implementation of the broadcast receiver.
Our Implementation listens to <App-Identifier>.<COMMAND-NAME> <extras>.
Lessons Learned
- Android devices show a different behaviour depending on their operating system. Calling the activity manager (am) from the Afaria application requires a right to do this. "broadcast -a com.sap.mit.APPLY_MDMTOOLKIT_CONFIG_FILE --es filename <%ConfigFileName> --user 0" In Android 4.4.2 the user context needs to be set.
- Calling the activity manager is always asynchronous. The only possibility to wait for feedback is the usage of the script "Wait for file to exist" with a file that never exist.
- If we would connect the devices to the session script that executes the broadcast without any checks, the MDM API would be connected every time. A controlling mechanism is required. We decided to use a change tracking mechanism.
- We defined a variable that is set, if an XML file is sent to the device. Only if this variable is set during a session, the configuration will be applied. If a configuration must be updated, the administrator needs to update the XML files on the Afaria Server. Only in this case the session will send a file to the device.
- Our use case was managing only one personal certificate on the device. We built the certificate managing logic in the application. We keep the certificate metadata in the app trigger a check by broadcast. The app decides, if it calls the static link library and the MDM API to install a new certificate.
- We received the log file from the client during sessions and store them in a folder.
- The connector application logs, if actions are successful or not and it translates the log file that is returned by the Mx API.
- The Mx API returns an identical XML, if the configuration is applied successfully. It is enough to extract the header.
- The Mx API modifies the XML, if the configuration is only applied partially. Errors can be extracted.
Example XML
| XML | Comment |
|---|---|
<wap-provisioningdoc> <characteristic type="Clock" version="4.2" > <parm name="AutoTime" value="true"/> <characteristic type="AutoTimeDetails"> <parm name="NTPServer" value="ch.pool.ntp.org"/> <parm name="SyncInterval" value="00:30:00"/> </characteristic> </characteristic> <characteristic type="WirelessMgr" version="4.3" > <parm name="Bluetooth" value="2"/> <parm name="BluetoothState" value="2"/> <parm name="NFCState" value="2"/> <parm name="GPSState" value="2"/> <parm name="WWANState" value="1"/> </characteristic> <characteristic type="AppMgr" version="4.2" > <parm name="Action" value="Install"/> <parm name="APK" value="/storage/sdcard1/AfariaMDMToolkitConnector/Fiori.apk"/> </characteristic> <characteristic type="CertMgr" version="4.2" > <parm name="CertAction" value="1"/> <characteristic type="cert-details"> <parm name="CertAlias" value="Company Root CA"/> <parm name="CertType" value="5"/> <parm name="CertMethod" value="2"/> <parm name="CertFileCA" value="/storage/sdcard1/AfariaMDMToolkitConnector/CompanyRootCA.pem"/> <parm name="CertAdjustClock" value="false"/> </characteristic> </characteristic> <characteristic type="TouchMgr" version="0.3" > <parm name="TouchAction" value="Stylus and Finger"/> </characteristic> </wap-provisioningdoc> | The configuration file is a wap-provisioningdoc that can consist of multiple characteristics This characteristic modifies the clock on the device This characteristic modifies the wireless components on the device This characteristic installs the Fiori app on the device, if the file is stored in the file system. This characteristic installs the root certificate on the device. This characteristic changes the touch method on the device |
- SAP Managed Tags:
