This documentation is for WSO2 Enterprise Mobility Manager 2.2.0. View documentation for the latest release.
efefAndroid Deviceeefe - Enterprise Mobility Manager 2.2.0 - WSO2 Documentation
Skip to end of metadata
Go to start of metadata

Let's take a look at the tasks that Tom (the EMM administrator) and Kim (the device owner) have to do, from downloading WSO2 EMM to registering the Android device.

Before you begin

  1. EMM supports devices on Android version 4.2.x to 7.0 (Android Jelly Beans to Nougat).
  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 prompt and executing wso2server.bat --run (for Windows) or (for Linux.)
    Example: Starting WSO2 EMM on a Linux OS.

    cd <EMM_HOME>/bin
  5. Access the WSO2 EMM console by navigating to  https://<EMM_HOST>:<EMM_PORT>/emm.

Let's get started!

Configuring WSO2 EMM

The MobX system administrator needs to do the following configurations to allow users like Kiim to register their devices with WSO2 EMM and to allow EMM administrators like Tom to monitor the devices.

Configuring the email client

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

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

  1. Create an email account to send out emails to users that register with WSO2 EMM (e.g., [email protected]).

    If you are using a Google mail account, note that Google has restricted third-party apps and less secure apps from sending emails by default. Therefore, you need to configure your account to disable this restriction, as WSO2 EMM acts as a third-party application when sending emails to confirm user registrations or inviting existing users to register devices with WSO2 EMM.

     Click here for more information.

    Follow the steps given below to enable your Google mail account to provide access to third-party applications.

    1. Navigate to
    2. Click Signing in to Google on the left menu and make sure that the 2-step Verification is disabled or off.
    3. Click Connected apps and sites on the left menu and enable Allow less secure apps.
  2. Open the <EMM_HOME>/repository/conf/axis2/axis2.xml file, uncomment the mailto transportSender section, and configure the EMM email account.

    <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender">
       <parameter name=""></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">[email protected]</parameter>

    For mail.smtp.frommail.smtp.user, and mail.smtp.password, use the email address, username, and password (respectively) from the mail account you set up.


    <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender">
       <parameter name=""></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">[email protected]</parameter>

Specifying the WSO2 EMM server

WSO2 EMM uses a web agent to enroll devices. Tom follows the steps given below to configure the agent and the device management app to communicate with the 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 config.json file that is in the <EMM_HOME>/repository/deployment/server/jaggeryapps/emm-web-agent/app/conf directory. This file configures the web agent to handle device enrollments.
    Configure the host attribute that is under generalConfig by providing the entire server address. 


    "generalConfig" : {
            "host" : "",
            "companyName" : "WSO2 Enterprise Mobility Manager",
            "browserTitle" : "WSO2 EMM",
            "copyrightText" : "\u00A9 %date-year%, WSO2 Inc. ( All Rights Reserved."
  2. Open the config.json file that is in the <EMM_HOME>/repository/deployment/server/jaggeryapps/emm/app/conf directory. This file configures WSO2 EMM to manage devices.
    Configure the host attribute that is under generalConfig by providing the entire server address.


    "generalConfig" : {
            "host" : "",
            "companyName" : "WSO2 Carbon Device Manager",
            "browserTitle" : "WSO2 Device Manager",
            "copyrightPrefix" : "\u00A9 %date-year%, ",
            "copyrightOwner" : "WSO2 Inc.",
            "copyrightOwnersSite" : "",
            "copyrightSuffix" : " All Rights Reserved."

    Optionally, you can configure the Android platform. Otherwise, you can just use the default settings to try out the examples in this quick start guide.

  3. Start WSO2 EMM.
    If you started WSO2 EMM previously, stop it using CRTL+C and restart WSO2 EMM.


Creating users and a sample policy

Follow the steps given below to create the two users Kim and Tom, and a configured passcode policy. This is done so that it will be 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.

  3. Enter your email address when prompted. 


    For this example, we will register the device owner Kim with your email address so that you will be notified via email on how to register your device with WSO2 EMM.


    Enter your email address and press enter : [email protected]

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, 3 new policies, and 2 new users that were added using these scripts.

Updating the passcode policy

As a security measure, the MobX management has requested Tom to update the passcode policy for all Android devices so that a device user can only enter the wrong password four times. If a user fails to enter the correct password in the fourth 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. Access the WSO2 EMM console by navigating to https://<EMM_HOST>:<EMM_PORT>/emm .

    Tip by Tom

    1. By default, <EMM_PORT> has been set to 9443 for HTTPS and 9763 for HTTP. Since we access the EMM console over HTTPS, use 9443 in the URL.
    2. When the pages appear, the web browser will typically display an "insecure connection" message, which requires your confirmation before you can continue.

       Click here for more information.

      The EMM consoles are based on the HTTPS protocol, which is a combination of HTTP and SSL protocols. This protocol is generally used to encrypt the traffic from the client to server for security reasons. The certificate it works with is used for encryption only and does not prove the server identity, so when you try to access these consoles, a warning of untrusted connection is usually displayed. To continue working with this certificate, you must "accept" the certificate before access to the site is permitted. If you are using the Mozilla Firefox browser, this usually occurs only on the first access to the server, after which the certificate is 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 consoles available to external users, your organization should 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 this server belongs to the given organization.

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

    2. Click LOG IN

    The EMM console dashboard appears, giving you easy access to the devices, users, and policies in your organization. 

  2. Click View under POLICIES.
  3. Click the edit logo that is on the passcode policy for Android devices.
  4. Update the passcode profile that is already in place by defining the maximum fail attempts as 4, and click CONTINUE.

    1. A profile in the context of EMM refers to a collection of policies.
    2. If you want to know more about each policy setting, hover your mouse pointer over the help tip.

  5. 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 the set device ownership type.

      BYODBring Your Own Device
      COPECorporate-Owned, Personally Enabled
      AnyThe configured profile of policies will be assigned to both the BYOD and COPE device ownership types
    2. Tom has selected the set user role/s option and then selected the emm-user role from the item list.
    3. Tom has 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.

      EnforceForcefully enforce the policies on the assigned groups

      If the assigned groups do not adhere to the given policies, a warning message will be sent


      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

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

  7. Click SAVE to save the configured profile or click SAVE & PUBLISH to save and publish the configured profile as an active policy to the database. 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 App Catalog 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

    In this scenario, we haven't enabled SSO authentication. Therefore, you need to enter the username and password to log in, else you will automatically be logged in.

    For more information, see Enabling SSO for WSO2 EMM.

  3. Click Submit for Review for the Catalog application.

  4. Click Approve > Publish.

The App Catalog application is now available in the app store for device owners like Kim to install on their device.

Monitoring devices

Tom can monitor the devices registered with WSO2 EMM via the device monitoring console. Follow the steps given below to sign in to the device monitoring console:

  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.  

Inviting users to register the device with WSO2 EMM

Tom follows the steps given below to invite Kim to register the 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 want to invite.

  3. Click Kim User to select the user.
  4. Click Invite Selected.
  5. Click Yes to confirm that you want to send the invite mail, and then click ok.

Registering the Android device

EMM supports devices on Android version 4.2.x to 7.0 (Android Jelly Beans to Nougat).

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 the Android device. To download the EMM agent Kim clicks on the link sent in the email, and then follows the steps given below:

Tip by Tom

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

  1. Kim taps Download EMM Agent on this screen.

  2. Open the downloaded file, and tap INSTALL.
  3. Tap OPEN, once the WSO2 Android Agent is successfully installed.
  4. Tap Skip and go to Enrollment, which will direct you to install the device with WSO2 EMM in the default manner.

    Tip by Tom

    In WSO2 EMM, data containerization is implemented using the Managed Profile feature. For more information on how to set up Work-Profile, see End-user Registering an Android Device via the Managed Profile

  5. Enter the server IP and the port as your server address in the text box provided.

    Example: Register the device via HTTP: 

  6. Tap Yes to continue.
  7. Enter your details and tap Register. A confirmation message will appear..
    • Username - Enter kim as the username.
    • Password - Enter kimemm as the password.
    • Domain - In this example Kim leaves the Domain empty, as it is only required if the server is hosted with multi-tenant support. 
    • Ownership type - Selects the BYOD ownership option. 
  8. Tap Yes to continue.
  9. Read the policy agreement, and tap Agree to accept the agreement. 
  10. Tap ALLOW to allow the WSO2 Android agent to make and manage phone calls and to access photos, media, files, and the device location.

    You will get this message only if your device is on Android OS Marshmallow (6.0) or above.


  11. Kim sets a PIN code with a minimum of four digits and clicks Set PIN Code. The PIN code is used to secure your personal data. Therefore, the EMM server will not be able to carry out critical operations on your personal data without using this PIN. 
    Example: If Tom needs to enterprise-wipe Kim's device or remove data from the device, Tom cannot directly wipe it without the PIN code. 

    You will be prompted to provide a PIN code only if your device is a BYOD device.

  12. Confirm the PIN and click OK to continue.
  13. Tap ACTIVATE to enable the EMM device administrator on your device. A confirmation message will appear after enabling the device admin.

    Kim's device is now successfully registered with WSO2 EMM. Kim can click Unregister to unregister this device.

Trying out Android device operations

Kim can now navigate to the Device management page, view information specific to the device, and carry out operations on the device as explained below:

  1. Access the EMM console using the username and the password that was sent via email.
  2. Click View under DEVICES.
  3. Click on the registered device.

    Kim tries out the various device operations via the WSO2 EMM console.

    1. Kim misplaces the mobile device, so Kim clicks Ring to ring the device and find out if the device is lying around the workspace.

    2. Kim then remembers that the phone was unlocked, so Kim uses the Device Lock operation to lock the device so that the content in the device will be safe.

    3. Using the Location operations Kim finds out that device is in Tom's office. Kim calls Tom and asks Tom to call back from the device.

    4. To make sure Tom can call using the device, Kim unlocks the device using the Device Unlock operation.

    For more information on the available features, see Feature Categorization for Supported Device Types.

Installing an application on the Android 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 app catalog application to the MobX app store.

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

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

  2. Log in using kim and kimemm as the username and password.

  3. Click the Catalog 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.
    A success message will be shown when you have successfully subscribed to the application.
  • No labels