/
iOS Device
com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_link3' is unknown.

iOS Device

Feb 08, 2017

Let's take a look at the tasks that Tom, the EMM administrator of MobX, has to do from downloading WSO2 EMM to registering the iOS device of Kim, the device owner.

Before you begin

  1. WSO2 EMM supports devices on iOS 7, 8, 9, and 10.

  2. Install Oracle Java SE Development Kit (JDK) version 1.7.* or 1.8.* and set the JAVA_HOME environment variable. For more information on setting up JAVA_HOME on your OS, see Installing the Product.

  3. Download WSO2 EMM.

  4. Start WSO2 EMM by navigating to the <EMM_HOME>/bin directory using the command-line and executing wso2server.bat --run (for Windows) or wso2server.sh (for Linux).
    Example: Starting WSO2 EMM on a Linux OS.

    cd <EMM_HOME>/bin ./wso2server.sh

    The server starts, and the command line displays the management console URL, which ends in /carbon/. Note the host and port in this URL, which you will use in the next step to access the EMM console.

  5. In your browser, access the EMM Console by navigating to https://<EMM_HOST>:<EMM_PORT>/emm and log in using admin as the username and password.

  6. Obtain a signed Certificate Signing Request (CSR) file in the .plst  format using any approach listed below:

    • Get your own certificate signed by Apple 

      You can use this method, if you were not successful in the WSO2 CSR evaluation process or if you wish to get your certificate directly signed by Apple. When following this approach, initially, register your organization with the Apple Developer Enterprise Program. Thereafter, follow the steps mentioned in MDM Vendor CSR Signing Overview. 

    • Make a request to WSO2, who is a registered EMM vendor with Apple, and get your certificate signed 
      When following this approach, carry out the steps mentioned below. After submitting the CSR file, a WSO2 Account Manager will contact you in due course to evaluate your request. 

    1. Create a CSR file (e.g., customer.csr) from the EMM server using a private key.

      openssl genrsa -des3 -out customerPrivateKey.pem 2048 openssl req -new -key customerPrivateKey.pem -out customer.csr

    2. Enter the requested information when prompted. This information is incorporated into the CSR with your organization’s official details. For example,

      Given below are the required fields:

    3. To get a signed CSR file in .plist format, submit the CSR file to WSO2 via the WSO2 site.

    4. Note that WSO2 account managers evaluate the CSR files and send you an email with the following information within 3 to 4 working days.

      • The signed CSR file in the .plst format

      • Agent source code

      • P2 repository, which contains the feature list

Configuring WSO2 EMM

Tom needs to configure the following to allow users to register and monitor their devices with WSO2 EMM:

Configuring the email client

Configure the email client to send out registration confirmation emails to users through WSO2 EMM:

In EMM, the user registration confirmation emails are disabled by default, and the admin needs to provide the required configuration details to enable it.

  1. Create an email account (e.g., tom-mobx@gmail.com) to send out emails to users who register with WSO2 EMM.

  2. Open the <EMM_HOME>/repository/conf/axis2/axis2.xml file, uncomment the mailto transportSender section, and configure the EMM email account.
    Before the configuration:

    <!-- Uncomment and configure the SMTP server information check com.sun.mail.smtp package documentation for descriptions of properties <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender"> <parameter name="mail.smtp.host">smtp.gmail.com</parameter> <parameter name="mail.smtp.port">587</parameter> <parameter name="mail.smtp.starttls.enable">true</parameter> <parameter name="mail.smtp.auth">true</parameter> <parameter name="mail.smtp.user">synapse.demo.0</parameter> <parameter name="mail.smtp.password">mailpassword</parameter> <parameter name="mail.smtp.from">synapse.demo.0@gmail.com</parameter> </transportSender> -->

    Example, after the configuration:

    <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender"> <parameter name="mail.smtp.host">smtp.gmail.com</parameter> <parameter name="mail.smtp.port">587</parameter> <parameter name="mail.smtp.starttls.enable">true</parameter> <parameter name="mail.smtp.auth">true</parameter> <parameter name="mail.smtp.user">tom-mobx</parameter> <parameter name="mail.smtp.password">$mobx1234</parameter> <parameter name="mail.smtp.from">tom-mobx@gmail.com</parameter> </transportSender>

Enabling WSO2 API Manager communication

Configure the following fields, which are under the <APIKeyValidator> tag in the <EMM_HOME>/repository/conf/api-manager.xml file.

  1. Configure the <serverURL> field by replacing ${carbon.local.ip} with the hostname or public IP. For example:

    <ServerURL>https://10.10.10.253:${mgt.transport.https.port}${carbon.context}/services/</ServerURL>

  2. Configure the <RevokeAPIURL> field by replacing ${carbon.local.ip} with the hostname or the public IP. For example:

    <RevokeAPIURL>https://10.10.10.253:${https.nio.port}/revoke</RevokeAPIURL>

  3. Restart the WSO2 EMM server. 

Specifying the WSO2 EMM server

WSO2 EMM uses a web agent to enroll devices. Tom follows the steps below to configure the agent and the device management app to communicate with the correct WSO2 EMM server:

Tip by Tom

If you are directly editing the JSON files, be sure to use straight double quotes (") instead of curly double quotes (”), or you will run into errors.

  • Correct: "

  • Wrong: ”

  1. Open the <EMM_HOME>/repository/deployment/server/jaggeryapps/ emm-web-agent/app/conf/config.json file and give the entire server address in the host attribute that is under generalConfig. This file configures the web agent to handle device enrollments. For example:

    "generalConfig" : { "host" : "http://10.10.10.253:9763", "companyName" : "WSO2 Enterprise Mobility Manager", "browserTitle" : "WSO2 EMM", "copyrightText" : "\u00A9 %date-year%, WSO2 Inc. (http://www.wso2.org) All Rights Reserved." }

  2. Open the <EMM_HOME>/repository/deployment/server/jaggeryapps/emm/app/conf/config.json  file and give the entire server address in the host attribute that is under generalConfig. This file configures WSO2 EMM to manage devices. For example:

    "generalConfig" : { "host" : "10.10.10.253:9443", "companyName" : "WSO2 Carbon Device Manager", "browserTitle" : "WSO2 Device Manager", "copyrightPrefix" : "\u00A9 %date-year%, ", "copyrightOwner" : "WSO2 Inc.", "copyrightOwnersSite" : "http://www.wso2.org", "copyrightSuffix" : " All Rights Reserved." }Please note that because you did not install the WSO2 EMM iOS agent while registering the device

Configuring iOS support in EMM

Now that we have configured EMM, we are ready to set up iOS support as described in the following sections.

For the sake of simplicity in this quick start guide, we are not setting up the WSO2 EMM iOS agent on users' devices, and therefore we will not walk through performing iOS client configurations. Note that the 'device ringing', 'sending messages', and 'getting the device location' operations require the WSO2 EMM iOS agent, so those operations are not available in this scenario.

For more information on configuring WSO2 EMM for iOS, including iOS client configurations, see the iOS configurations guide.

Installing the iOS features

After obtaining a signed CSR, the P2 repository, and the other files via email, Tom proceeds to install the specific features in the P2 repository that are required to enable iOS.

  1. Go to the WSO2 EMM Management Console at https://<EMM_HOST>:<EMM_PORT>/carbon and log in using admin/admin as the credentials.

  2. Click Features on the Configure tab.

  3. Click Add Repository on the Repository Management tab to add the repository to the server.

  4. Fill out the form and click Add. If the Local option is selected for location, unzip the p2-repo.zip file that you received via email when obtaining the CSR file and give the path to that directory.

  5. Click the Available Features tab, select the respective repository, and click Find Features. If the Group features by category option is selected by default, deselect it before checking for the available features. 

  6. Select the EMM - iOS Device Management feature and click Install.

  7. Click Next, accept the license agreement, and click Next to install the features.

  8. Once the features are successfully installed, you will be prompted to restart now or later. 

  9. Enter the IP or the domain name for the following parameters in the <EMM_HOME>/repository/conf/ios-config .xml  file.

    • iOSEnrollURL

    • iOSProfileURL

    • iOSCheckinURL

    • iOSServerURL TokenURL

    For example:

    <?xml version="1.0" encoding="ISO-8859-1"?> <iOSEMMConfigurations> <!-- iOS MDM endpoint urls --> <iOSEnrollURL>https://10.10.10.193:9443/ios-enrollment/scep</iOSEnrollURL> <iOSProfileURL>https://10.10.10.193:9443/ios-enrollment/profile</iOSProfileURL> <iOSCheckinURL>https://10.10.10.193:9443/ios-enrollment/checkin</iOSCheckinURL> <iOSServerURL>https://10.10.10.193:9443/ios-enrollment/server</iOSServerURL> </iOSEMMConfigurations 

  10. Open <EMM_HOME>/repository/conf/cdm-config.xml and uncomment the APNSBasedPushNotificationProvider that is under PushNotificationProviders. For example:

    <PushNotificationProviders> <Provider>org.wso2.carbon.device.mgt.extensions.push.notification.provider.gcm.GCMBasedPushNotificationProvider</Provider> <Provider>org.wso2.carbon.device.mgt.mobile.impl.ios.apns.APNSBasedPushNotificationProvider</Provider> <!--<Provider>org.wso2.carbon.device.mgt.extensions.push.notification.provider.mqtt.MQTTBasedPushNotificationProvider</Provider>--> <!--<Provider>org.wso2.carbon.device.mgt.extensions.push.notification.provider.xmpp.XMPPBasedPushNotificationProvider</Provider>--> </PushNotificationProviders>

  11. Go back to the EMM Management Console and click Restart Now.

Tom has now installed the features required to enable iOS. Next, Tom proceeds to configure WSO2 EMM for iOS.

Configuring WSO2 EMM for iOS

Configuring WSO2 EMM for iOS in a production environment involves many steps. To make the testing process easy, Tom has written a script that automates most of the steps. Let's take a look at how it works and configure the server settings.

  1. Download the ios-configurations.zip  file and unzip it to the <EMM_PRODUCT_HOME> directory.

  2. Run the script you just downloaded to configure the iOS server settings in WSO2 EMM.

    cd <EMM_PRODUCT_HOME>/ios-configurator ./ios.sh

  3. Enter the requested information when prompted. Be sure to provide the same information you gave when generating the CSR file. For example:

Next, Tom generates an MDM Apple Push Notification Service (APNS) certificate. 

Generating an MDM APNS certificate

Except for a few operations (ring, message and get location) that are performed by the WSO2 EMM agent, all the other device operations, and policies are applied on an iOS device via it's operating system. Therefore, for the WSO2 EMM server to communicate with the operating system of the device, you need to generate the MDM APNS certificate.

The MDM APNS certificate will be referred to as the MDM certificate in the EMM Console.

  1. Go to https://appleid.apple.com/account#!&page=create and get an Apple ID, if you do not have one already. 

  2. Go to the Apple Push Certificate Portal at https://identity.apple.com/pushcert/ and log in with your customer account details. You do not need an enterprise account for this. Your Apple ID is sufficient.

  3. Click Create Certificate and agree to the terms and conditions.

  4. Upload the encoded .plist file you received via email from WSO2 earlier in this guide.

  5. Download the generated MDM signing certificate, which is a certificate for third-party servers provided by Apple, and rename it to MDM_Certificate.pem.

  6. Get the USERID (TOPIC ID) from the MDM signing certificate (MDM_Certificate.pem), as it will be used later in the configuration. 
    You can decode the MDM signing certificate to obtain the USERID by executing the following command:

    openssl x509 -in MDM_Certificate.pem -text -noout

  7. Remove the password/pass phrase from your private key file (e.g.,customerPrivateKey.pem).

    openssl rsa -in customerPrivateKey.pem -out customerKey.pem

  8. Merge the customer key file that was derived in the latter step with the MDM signing certificate to generate the MDM Apple Push Notification Service (APNS) Certificate. In this example, Tom merges the customerKey.pem file with the MDM_Certificate.pem file to generate the MDM_APNSCert.pem file.

    cat MDM_Certificate.pem customerKey.pem > MDM_APNSCert.pem

  9. Open the APNS Certificate (MDM_APNSCert.pem) and add a line break between the content of the two files. For example, if your content looks as "-----END CERTIFICATE----------BEGIN RSA PRIVATE KEY-----", add a line break after 5 dashes so that the content looks as follows:

    -----END CERTIFICATE----- -----BEGIN RSA PRIVATE KEY-----

  10. Convert the MDM_APNSCert.pem file to MDM_APNSCert.pfx file. You need a password for this, which you will need again when configuring the iOS platform configurations.

    openssl pkcs12 -export -out MDM_APNSCert.pfx -inkey customerPrivateKey.pem -in MDM_APNSCert.pem

Configuring the iOS platform

Multiple tenants can use WSO2 EMM while maintaining tenant-based isolation. The iOS platform configurations page enables tenants to customize the iOS settings based on their own requirements.

Tom proceeds to configure the iOS platform configurations by adding the generated MDM APNS certificate.

  1. Log in to the EMM Console at https://<EMM_HOST>:<EMM_PORT>/emm  using admin as the username and password if you haven't previously logged in.

  2. Click Menu > CONFIGURATION MANAGEMENT > PLATFORM CONFIGURATIONS > iOS Configurations and fill in the form.

    • MDM Certificate Password: Give the same password you gave when converting the MDM_APNS certificate from the pem to the pfx format. 

    • MDM Certificate Topic ID: Give the topic ID of the certificate.

Configuring WSO2 EMM to install iOS applications

The download URL for WSO2 EMM is configured for HTTP by default. Although you can install Android mobile applications using this default configuration, to install iOS applications, you need to configure it for HTTPS as it's required for the iOS MDM protocol behavior.

Follow the steps given below to configure WSO2 EMM to install iOS mobile applications:

  1. Open the <EMM_HOME>/repository/conf/app-manager.xml file.

  2. Add %https% as the value for the AppDownloadURLHost property.

    <Config name="AppDownloadURLHost">%https%</Config>

Creating users and a sample policy

Follow the steps given below to create two users, Kim and Tom, and a configured passcode policy. This will make it easy for you to try out the EMM quick start guide.

  1. Download the WSO2 EMM sample pack.

  2. Copy the file to a preferred location, navigate to the file via the command prompt, and run the script.

    cd <EMM_QSG_SAMPLE-PACK> ./emm-qsg.sh

  3. Enter your email address when prompted. 

    Example:

    Enter your email address and press enter : kim@wso2.com

Check out the WSO2 EMM dashboard by signing in to the WSO2 EMM console using tom as the username and tomemm as the password: https://<EMM_HOST>:<EMM_PORT>/emm
You will then see the new emm-user role, three new policies, and the two new users that were added using this script.

Updating the passcode policy

As a security measure, the MobX management has asked Tom to update the passcode policy for all iOS devices so that a device user can only enter the wrong password five times. If a user fails to enter the correct password in the fifth attempt, the device will not be accessible for 15 minutes. This can be regulated in WSO2 EMM by updating the passcode policy that was already in place. Tom follows the steps given below to update the policy:

  1. Log out of the EMM console and log in using the following credentials:
    Enter tom as the username and tomemm as the password.

  2. Click LOG IN.

  3. In the EMM console click View under POLICIES.

  4. Click the edit logo that is on the passcode policy for iOS devices.

  5. Update the passcode profile that is already in place by defining the maximum fail attempts as 5, and click CONTINUE.

  6. The passcode policy that was created for this scenario has the following groups assigned. You can optionally update the groups. 

    1. Tom had selected the default ownership type ANY for set device ownership type.
      The set device ownership type defines if the policy needs to be applied on BYOD, COPE or both these device types. The ownership types are listed below: 

    2. Tom had selected the set user role/s option and then selected the emm-user role from the item list.

    3. Tom had selected Enforce as the action that needs to be carried out when a device has not complied with a policy.  

  7. Click CONTINUE.
    Optionally, you can update the name and the description of the policy.

  8. It is mandatory that the policy is assigned to Kim's mobile device, so Tom clicks SAVE & PUBLISH to make the policy active immediately.

If you SAVE the configured profile, it will be in the inactive state and will not be applied to any devices.

If you SAVE & PUBLISH the configured profile of policies, it will be in the active state. The active policies will be enforced on new devices that enroll with EMM based on the policy enforcement criteria. If you want to push this policy to the existing devices and want this policy to be applied to the devices, click APPLY CHANGES TO DEVICES.

Publishing applications

Tom needs to publish the WSO2Con application that was created when running the emm-qsg script.

  1. Navigate to the App Publisher using the following URL: https://<EMM_HOST>:<EMM_PORT>/publisher

  2. Enter the username as tom and password as tomemm. 

  3. Click Submit for Review for the WSO2Con application.

  4. Click Approve > Publish.
    The WSO2Con application is now available in the app store for device owners like Kim to install on their devices.

To learn more about the mobile application life cycle, see Mobile Application Lifecycle Management.

Monitoring devices

Tom can monitor the devices registered with WSO2 EMM via the device statistics dashboard. 

  1. Click the menu icon, and then click DEVICE STATISTICS to access the device statistics dashboard.

  2. The device statistics dashboard is facilitated via the WSO2 Dashboard Server. Therefore, since you have not enabled SSO in this guide for WSO2 EMM, you will need to log into the dashboard using tom as the username and tomemm as the password.
    Currently, you will not see any data populated in the dashboard as there are no enrolled devices and no non-compliant or unmonitored devices in the system. 

For more information, see Monitoring Devices via the Device Statistics Dashboard.

Inviting Kim to register the device with WSO2 EMM

Tom follows the steps given below to invite Kim to register her device with WSO2 EMM:

Tip by Tom

Before you start let's check if the following permissions are given to Kim by navigation to USER MANAGEMENT > ROLES and by clicking edit permissions on the emm-user. You need to give these permissions so Kim can see the device that is going to be enrolled with WSO2 EMM and carry out operations on it.

  1. On the dashboard, click View under USERS.

  2. Click SELECT on the top right corner to select the users you wish to invite.

  3. Select the user Kim User.

  4. Click Invite Selected.

Registering the iOS device

WSO2 EMM supports devices on iOS 7, 8, 9, and 10.

Tip by Tom

Before you begin to enroll the device, make sure that the WSO2 EMM server and the device are on the same network.

Kim receives the email and accesses the email via her iOS device. To download the EMM agent, Kim clicks on the link sent in the email and then follows the steps given below:

When the pages appear, the web browser will typically display an "insecure connection" message, which requires your confirmation before you can continue. 

Follow the instructions below to register an iOS device:

  1. The Safari browser will display the EMM iOS Enrollment screen. iOS devices need the root certificate to be downloaded to trust the server certificate. Tap Install EMM Certificate.

  2. The Install Profile screen appears. Tap Install. 

  3. Tap the Skip Agent Installer link at the bottom of the screen.

  4. On the EMM Registration screen, enter your details:

    • Username - Enter kim as the username.

    • Password - Enter kimemm as the password. 

    • Domain - You don't need to enter the domain details for this scenario.

  5. Tap Log In. 

  6. After reading the End User License Agreement (EULA), tap I accept the terms. 

  7. Tap Install when prompted to install the WSO2 Profile Service. 

  8. A warning message appears to indicate that by installing the profile the EMM will remotely manage the iOS device. Tap Install.

  9. Tap Trust to confirm that you are aware of the device being remotely managed by installing the profile.

  10. After the profile is installed, click Done.

  11. Upon the successful registration, the following confirmation appears.

Since you are not installing the WSO2 EMM iOS agent in this guide, you will get a Cannot Open Page warning message after the enrollment is complete.

Trying out iOS device operations

Kim can now navigate to the Device management page, view information specific to her device, and carry out operations on the device. She follows the steps given below:

  1. Access the EMM Management Console using kim as username and kimemm as the password.

  2. Click the menu icon.

  3. Click DEVICE MANAGEMENT.

  4. Click view on the registered device.

  5. Kim tries out the various operations on her device via the WSO2 EMM Management Console.

Tip by Tom

To know if a policy is applied on your device, see Verifying Policies Applied on an iOS Device. 

Installing an application on the iOS device

MobX wants Tom to ensure that the employees can only download mobile applications made available via the MobX app store. For this, Tom creates and publishes the WSO2Con application to the MobX app store.

Let's take a look at how Kim installs this application on the device.

com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.