iOS Device

Let's take a look at the tasks that Chris, the IoT Server administrator of MobX, has to do from downloading WSO2 IoT Server to registering the iOS device of Alex, the device owner.

Configuring WSO2 IoT Server

Chris needs to configure the following to allow users to register and monitor their devices with WSO2 IoT Server:

• Configuring WSO2 IoT Server with the IP
• Enabling WSO2 API Manager communication
• Configuring WSO2 IoT Server to install iOS applications

Configuring WSO2 IoT Server with the IP or hostname

WSO2 IoT Server is configured via localhost as the product has SSO enabled by default. When configuring WSO2 IoT Server with iOS you need to make it IP or hostname based instead of localhost. Let's take a look at the steps you need to follow to configure WSO2 IoT Server with the IP or hostname:

1. Open the <IoT_HOME>/core/repository/conf/carbon.xml file 

   1. If you configuring WSO2 IoT Server with the IP, comment out the <HostName> and <MgtHostName> attributes.

      <!--<HostName>localhost</HostName>-->
      <!--<MgtHostName>localhost</MgtHostName>-->

   2. If you are configuring WSO2 IoT Server with the hostname, define the hostname as the value for the <HostName> and <MgtHostName> attributes.

      <HostName>{ENTER_THE_HOSTNAME}</HostName>
      <MgtHostName>{ENTER_THE_HOSTNAME}</MgtHostName>

2. Open the <IoT_HOME>/core/repository/conf/app-manager.xml  file, and configure the <IdentityProviderUrl> attribute that is under <SSOConfiguration> by replacing localhost with the IoT Server IP.

   <!-- URL of the IDP use for SSO -->
   <IdentityProviderUrl>https://<IoT_SERVER_IP/HOSTNAME>:${mgt.transport.https.port}/samlsso</IdentityProviderUrl>

3. Open the <IoT_HOME>/core/repository/conf/identity/sso-idp-config.xml file, and find and replace localhost with the <IoT_SERVER_IP/HOSTNAME>.
4. Open the <IoT_HOME>/ core/repository/deployment/server/jaggeryapps/devicemgt/app/conf/app-conf.json file, and configure the following attributes:

   • identityProviderUrl: Replace %iot.keymanager.host%:%iot.keymanager.https.port% with the IoT Server IP and host, which is 9443.

     "identityProviderUrl" : "https://<IoT_SERVER_IP/HOSTNAME>:9443/samlsso",

   • acs: Replace %iot.keymanager.host%:%iot.keymanager.https.port% with the IoT Server IP and host, which is 9443.

     "acs": "https://<IoT_SERVER_IP/HOSTNAME>:9443/devicemgt/uuf/sso/acs",

5. Open the <IoT_HOME>/core/repository/deployment/server/jaggeryapps/api-store/site/conf/site.json  file, and configure the identityProviderUrl attribute by replacing localhost with the IoT Server IP.

   "identityProviderURL" : "https://<IoT_SERVER_IP>:9443/samlsso",

6. Open the <IoT_HOME>/core/repository/deployment/server/jaggeryapps/portal/configs/designer.json file and configure the acs property with the server IP and port, so that you can access the device monitoring console.

   "acs": "https:<IoT_SERVER_IP/HOSTNAME>:9443/portal/acs",

7. If you are using hostname instead of the IP, open the <IOTS_HOME>/core/repository/deployment/server/jaggeryapps/devicemgt/app/conf/config.json file and configure the host property.

   "host" : "<ENTER_THE_HOSTNAME>"

Enabling WSO2 API Manager communication

Configure the following fields, which are in the <IoT_HOME>/core/repository/conf/api-manager.xml file.

1. Configure the <serverURL> field that is under the <APIKeyValidator> tag 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. If you started the WSO2 IoT Server's core profile previously, the APIs published will connect to localhost. Therefore, you need to configure the <EnabledUpdateApi> property as true in the <IoT_HOME>/core/repository/conf/etc/webapp-publisher-config.xml file to update the APIs with the Server IP.

   <!-- If it is true, the APIs of this instance will be updated when the webapps are redeployed -->
   <EnabledUpdateApi>true</EnabledUpdateApi>

Configuring WSO2 IoT Server to install iOS applications

The download URL for WSO2 IoT Server 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 IoT Server to install iOS mobile applications:

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

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

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

   Tip: To test WSO2 IoT Server App management features on Android devices, please use one of the following options:

   • Change the value of the AppDownloadURLHost property back to HTTP 
   • Continue using HTTPS to install applications on Android devices by Generating a BKS File for Android.

Chris has now done the configurations needed to allow users to register and monitor their devices with WSO2 IoT Server. Chris then proceeds to configure iOS support in IoT Server.

Configuring iOS support in IoT Server

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

• Installing the iOS features
• Configuring WSO2 IoT Server for iOS
• Generating an MDM APNS certificate
• Configuring the iOS platform

Installing the iOS features

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

1. Go to the WSO2 IoT Server Management Console at https://<IoT_HOST>:9443/carbon and log in using admin as the username and password.

   1. The <IoT_PORT> is set to 9443 for HTTPS and 9763 for HTTP by default. As you access the IoT Server Management Console over HTTPS, use 9443 in the URL.

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

       Click here for more information.

      The IoT Server Management Console is based on the HTTPS protocol, which is a combination of HTTP and SSL protocols. This protocol is generally used to encrypt traffic from the client to server for security reasons. The certificate that it works with is used for encryption only and does not prove the server identity. Therefore, when you try to access the Management Console, you usually get a warning saying that the connection is untrusted. To continue working with this certificate, accept the certificate before accessing the site. If you are using the Mozilla Firefox browser, you have to accept the certificate only at the first time. After that, the certificate gets stored in the browser database and marked as trusted. However, with other browsers, the insecure connection warning might be displayed every time you access the server.

      This scenario is suitable for testing purposes, or for running the program on the company's internal networks. If you want to make the Management Console available to external users, you must obtain a certificate signed by a well-known certificate authority, which verifies that the server actually has the name it is accessed by and that the server belongs to the given organization.

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 IoT Server - 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. 

   Don't click restart now until you have completed step 9 and 10.

9. Open <IoT_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>

10. Open the <IoT_HOME>/core/repository/conf/iot-api-config.xml file and replace localhost with your IP or hostname.
    For example: 

    <ServerConfiguration>
        <!-- IoT server host name, this is referred from APIM gateway to call to IoT server for certificate validation-->
        <Hostname>https://10.10.10.37:9443/</Hostname>
        <!--End point to verify the certificate-->
        <VerificationEndpoint>https://10.10.10.37:9443/api/certificate-mgt/v1.0/admin/certificates/verify/</VerificationEndpoint>
        <!--Admin username/password - this is to use for oauth token generation-->
        <Username>admin</Username>
        <Password>admin</Password>
        <!--Dynamic client registration endpoint-->
        <DynamicClientRegistrationEndpoint>https://10.10.10.37:9443/dynamic-client-web/register</DynamicClientRegistrationEndpoint>
        <!--Oauth token endpoint-->
        <OauthTokenEndpoint>https://10.10.10.37:9443/oauth2/token</OauthTokenEndpoint>
        <APIS>
            <ContextPath>/services</ContextPath>
        </APIS>
    </ServerConfiguration>

11. Open the product's startup script based on your OS (i.e., wso2server.sh for Linux/Solaris and wso2server.bat for Windows), which is in the <IoT_HOME>/core/bin directory and add the IP addresses or hostname of the respective servers as shown below: 

    -Diot.core.host="10.10.10.253" \
    -Diot.keymanager.host="10.10.10.253" \
    -Diot.gateway.host="10.10.10.253" \

12. Navigate to the <IoT_HOME>/core/repository/deployment/server/synapse-configs/default/api directory and replace localhost with your <SERVER_IP> for the files listed below:

    • admin--IOS-Enrollment-Profile.xml

    • admin--IOS-Enrollment-Scep.xml

    • admin--IOS-Enrollment.xml

13. Go back to the WSO2 IoT Server management console and click Restart Now.

    Important

    • Sign out of the device management and the WSO2 IoT Server console before restarting the server. 

    • If you clicked Restart Now previously, you need to restart the WSO2 IoT Server core profile again. Else you will run into errors.

Chris has now installed the features required to enable iOS. Next, Chris proceeds to configure WSO2 IoT Server for iOS.

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

Configuring WSO2 IoT Server for iOS

Configuring WSO2 IoT Server for iOS in a production environment involves many steps. To make the testing process easy, Chris 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 <IoT_HOME>/core directory.

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

   cd <IoT_HOME>/core/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, Chris installs the iOS features. 

Generating an MDM APNS certificate

Except for a few operations (ring, message and get location) that are performed by the WSO2 IoT Server agent, all the other device operations, and policies are applied on an iOS device via it's operating system. Therefore, for the WSO2 IoT Server 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 IoT Server 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.

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, Chris merges the customerKey.pem file with the MDM_Certificate.pem file to generate the MDM_APNSCert.pem file.

   Tip: Before you merge the customerKey.pem file and the MDM_Certificate.pem file, make sure both files are in the same directory.

   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 IoT Server while maintaining tenant-based isolation. The iOS platform configurations page enables tenants to customize the iOS settings based on their own requirements.

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

1. Restart the WSO2 IoT Server core profile and log in to the IoT Server Console at https://<IoT_HOST>:9443/devicemgt using admin as the username and password.

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 tothe pfx format. 
   • MDM Certificate Topic ID: Give the topic ID of the certificate.

   Use the generated MDM-APNS certificate for both the MDM certificate and the APNS certificate.

   In this tutorial, you are not installing the WSO2 IoT Server's iOS agent on the device. Therefore, you don't need to generate the APNS certificate. The APNS certificate is used to trigger operations, such as ring, notification, and iOS. If you want to trigger these operations, you need to generate the APNS certificate and upload it.

   

   Tip: To learn more about each platform setting, hover your mouse pointer over thehelp tip.

Creating users and a sample policy

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

1. Download the WSO2 IoT Server sample pack .

2. Create a directory named samples in the <IoT_HOME>/core directory and copy the downloaded file to it.

3.  Navigate to the samples directory and run the command given below to copy the required content to the quick start guide setup.

   Stop the core profile before running the commands given below.

   cd <IoT_HOME>/core/samples/mobile-qsg
   sh copy-files.sh

4. Restart the core profile.

   cd <IoT_HOME>/core/bin
   ./wso2server.sh

5. Run the script you just downloaded to configure the iOS server settings in WSO2 IoT Server.

   cd <IoT_PRODUCT_HOME>/core/samples/mobile-qsg
   sh mobile-qsg.sh

Updating the passcode policy

As a security measure, the MobX management has asked Chris 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 IoT Server by updating the passcode policy that was already in place. Chris follows the steps given below to update the policy:

1. Log out of the IoT Server console and log in using the following credentials:
   Enter chris as the username and chrisadmin as the password.

2. Click LOG IN.
3. In the IoT Server 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.

   A profile in the context of IoT Server refers to a collection of policies.

   If you want to know more about each policy setting, hover your mouse pointer over the help tip.

   

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

   1. Chris had selected the set user role/s option and then selected the iotMobileuser role from the item list.

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

      The following actions are referred to as non-compliance rules and determine how policies are monitored.

      Non-compliance rules	Description
      Enforce	Forcefully enforce the policies on the assigned groups.
      Warning	If the assigned groups do not adhere to the given policies, a warning message will be sent.
      Monitor	If the assigned groups do not adhere to the given policies, the server is notified of the violation without notifying the user, and the administrator can take the necessary actions.

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 Alex's mobile device, so Chris clicks SAVE & PUBLISH to make the policy active immediately.

Publishing applications

Chris needs to publish the WSO2Con application that was created when running the mobile-qsg script.

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

2. Enter the username as chris and password as chrisadmin. 

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 Alex to install on their devices.

Monitoring devices

Chris can monitor the devices registered with WSO2 IoT Server 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 IoT Server, you will need to log into the dashboard using chris as the username and chris@IoTS 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. 

Registering the iOS device

Follow the instructions below to register an iOS device:

1. Sign in to the WSO2 IoT Server device management console using alex as the username and alexuser as the password.

2. Click Enroll New Device.
3. Click iOS to enroll your device with WSO2 IoTS.
4. Enroll the device.
   1. Click Enroll Device.

   2. Scan the QR code and the Safari browser will display the IoT Server iOS enrollment screen.
      After scanning the QR code you will be directed to a web page. When this page appears, the web browser will typically display an "insecure connection" message, which requires your confirmation before you can continue. 

5. Tap Install IoT Server Certificate. The iOS devices need the root certificate to be downloaded to trust the server certificate. 
   

6. The Install Profile screen appears. Tap Install. 
   

   Tip by Chris

   If you are using iOS 10 with a self-signed certificate, do the following to mark it as a trusted certificate. This is required in iOS 10 because there is a change in how self-signed CA certificates are trusted by iOS devices from iOS 10 onwards.

   1. Open the Certificate Trust Settings found in Settings>General>About.

   2. Enable full trust for the certificate related to WSO2 IoT Server.

7. Tap the Skip Agent Installer link at the bottom of the screen.
   
8. On the IoT Server Registration screen, enter your details:
   
   • Username - Enter alex as the username.
   • Password - Enter alexuser as the password. 
   • Domain - You don't need to enter the domain details for this scenario.

   By default WSO2 IoT Server only supports the "bring your own device" (BYOD) registration process for the iOS platform.

9. Tap Log In. 

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

    

11. Tap Install when prompted to install the carbon.super Profile Service. 
    

12. A warning message appears to indicate that by installing the profile the IoT Server will remotely manage the iOS device. Tap Install.

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

    

14. After the profile is installed, click Done.

    

15. Upon the successful registration, the DEVICE ADDED confirmation appears.

Trying out iOS device operations

Alex 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 IoT Server Management Console using alex as username and alexuser as the password.
2. Click the icon.
3. Click DEVICE MANAGEMENT.
4. Click on the registered device.
   

5. Alex tries out the various operations on her device via the WSO2 IoT Server Management Console.

   NOTE: Because we didn't install the WSO2 IoT Server iOS agent while registering the device, the ring device, send notifications, and get device location operations do not function. For more information on installing the agent in the registration process, you can follow the steps in the iOS tutorial.

   For more information on the available features, Try out the iOS operations.

   

Installing an application on the iOS device

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

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

1. Navigate to the App Store using the following URL:  https://<IoT_HOST>:9443/store 
2. Sign in using alex and alex@IoTS as the username and password.
3. Click the WSO2Con mobile application, and click Install. 
4. Select Instant install, and click Yes.
   
5. Click on your device in the pop-up menu to install and subscribe to the application.
6. A success message will be shown when you have successfully subscribed to the application.
7. Tap install on your device to finish installing the application.