Product Documentation

Android for Work

Android for Work (Android enterprise) is a secure workspace available on Android devices running Android 5.0 and later. The workspace isolates business accounts, apps, and data from personal accounts, apps, and data. In XenMobile, you manage your bring your own device (BYOD) and company-owned Android devices by having users create a separate work profile on their devices. By combining hardware encryption and the policies that you deploy, you securely separate the corporate and personal areas on a device. You can remotely manage or wipe all corporate policies, apps, and data without affecting the personal area of the user. For more information about supported Android devices, see the Google Android Enterprise website.

You use Google Play to add, buy, and approve apps for deployment to the Android for Work workspace on a device. You can use Google Play to deploy your private Android apps, in addition to public and third-party apps. When you add a paid public app store app to XenMobile for Android for Work, you can review the Bulk Purchase licensing status. That status is the total number of licenses available, the number now in use, and the email address of each user consuming the licenses. For details about adding an app to XenMobile, see Add a public app store app.

Note:

In XenMobile Service and our documentation, we reference Android for Work. The latest terminology is Android enterprise. For details, see the Android documentation.

Set up Android for Work

XenMobile provides a simple way to set up Android for Work for your organization. Using XenMobile Management Tools, you bind XenMobile as your enterprise mobility management provider through Google Play and create an enterprise for Android for Work.

Note:

G Suite customers, see Legacy Android for Work for G Suite customers, which includes a table of related policy information.

You’ll need:

  • Your Citrix account credentials to sign in to XenMobile Tools
  • Your corporate Google ID credentials to sign in to Google Play
  1. In the XenMobile console, click the gear icon in the upper-right corner. The Settings page appears.

  2. On the Settings page, click Android for Work.

    Image of Settings page for Android for Work

  3. On the Android for Work page in XenMobile Settings, click Go to XenMobile Tools.

    Image of Go to XenMobile Tools link

  4. Sign in to your Citrix account if prompted.
  5. In the Android for Work page in XenMobile Tools Management, click Go to Google Play.

    Image of Go to Google Play option

  6. In Google Play, register Citrix as your organization enterprise mobility management:

    • Enter your organization name.
    • Ensure that Citrix is shown as your enterprise mobility management.
    • Accept the terms and then click Confirm.

    Image of Google Play registration page

    • In the page that appears, click Complete Registration.

    That step creates a file for you to download and then upload to XenMobile.

  7. In the Android for Work page in XenMobile Tools Management, click Download.
  8. Create a password for file encryption. Make a note about the password for reference when you upload the file and need to enter the password.

    Image of password prompt

  9. Click Go back to XenMobile.
  10. In Android for Work page in XenMobile Settings, click Upload file.

    Image of upload file option

  11. Browse to the file you downloaded and then enter the password you created. Click Upload.

    Image of Upload option

  12. An enterprise ID is added for Android for Work. To enable Android of Work, slide Enable Android for Work to Yes.

    Image of enable Android for Work option

Publish XenMobile Apps for Android for Work

In order to publish XenMobile Apps for Android Enterprise, follow the steps below.

  1. In your managed Google Play Store account, publish the apps you want your users to have. You can manage your Google Play account at https://play.google.com/work.
  2. In your XenMobile console, publish the same apps as the following:
    1. Select public store apps and choose Android for Work. For more information on publishing public store apps, see Add a public app store app.
    2. Publish the apps as MDX apps, so that they receive MDX policies. For more information on publishing MDX apps, see Add an MDX app.

Unenroll an Android for Work enterprise

You can unenroll an Android for Work enterprise using the XenMobile Server console and XenMobile Tools.

When you perform this task, the XenMobile Server opens a popup window for XenMobile Tools. Before you begin, ensure that the XenMobile Server has permission to open popup windows in the browser you are using. Some browsers, such as Google Chrome, require you to disable popup blocking and add the address of the XenMobile site to the popup block whitelist.

Warning:

After an enterprise is unenrolled, Android for Work apps on devices already enrolled through it are reset to their default states. Google no longer manages the devices. Re-enrolling them in an Android for Work enterprise may not restore previous functionality unless you perform further configuration.

After the Android for Work enterprise is unenrolled:

  • Devices and users enrolled through the enterprise have the Android for Work apps reset to their default state. Android for Work App Permissions and Android for Work App Restrictions policies previously applied no longer effect operations.
  • XenMobile manages devices enrolled through the enterprise. From the perspective of Google, those devices are unmanaged. You can’t add new Android for Work apps. You can’t apply Android for Work App Permissions or Android for Work App Restrictions policies. You can apply other policies, such as Scheduling, Password, and Restrictions, to these devices.
  • If you attempt to enroll devices in Android for Work, they are enrolled as Android devices, not Android for Work devices.

To unenroll an Android for Work enterprise:

  1. In the XenMobile console, click the gear icon in the upper-right corner. The Settings page appears.

  2. On the Settings page, click Android for Work.

  3. Click Remove Enterprise.

    Image of the Remove Enterprise option

  4. Specify a password. You’ll need the password for the next step to complete the unenrollment. Then click Unenroll.

    Image of the Unenroll option

  5. When the XenMobile Tools page opens, enter the password you created in the previous step.

    Image of the password field

  6. Click Unenroll.

    Image of the Unenroll option

Enroll Android for Work devices

If your device enrollment process requires users to enter a username or user ID: The format accepted depends on whether XenMobile is configured to search for users by User Principal Name (UPN) or SAM account name.

If the XenMobile is configured to search for users by UPN, users must enter a UPN in the format:

  • username@domain

If the XenMobile is configured to search for users by SAM, users must enter a SAM in one of these formats:

  • username@domain
  • domain\username

To determine which type of user name that XenMobile uses:

  1. In the XenMobile console, click the gear icon in the upper-right corner. The Settings page appears.
  2. Click LDAP to view the configuration of the LDAP connection.
  3. Near the bottom of the page, view the User search by field:

    • If it is set to userPrincipalName, XenMobile is set for UPN.
    • If it is set to sAMAccountName, XenMobile is set for SAM.

Provision work-managed device mode in Android for Work

Work-managed device mode for Android for Work is available for corporate-owned devices only. XenMobile supports these methods of enrollment in work-managed device mode:

  • afw#xenmobile: With this enrollment method, the user enters the characters “afw#xenmobile” when setting up the device. This token identifies the device as managed by XenMobile and downloads Secure Hub.
  • QR code: QR code provisioning is an easy way to provision a distributed fleet of devices that do not support NFC, such as tablets. The QR code enrollment method can be used on fleet devices that have been reset to their factory settings. The QR code enrollment method sets up and configures work-managed device mode by scanning a QR code from the setup wizard.
  • Near field communication (NFC) bump: The NFC bump enrollment method can be used on fleet devices that have been reset to their factory settings. An NFC bump transfers data through between two devices using near-field communication. Bluetooth, Wi-Fi, and other communication modes are disabled on a factory-reset device. NFC is the only communication protocol that the device can use in this state.

afw#xenmobile

The enrollment method is used after powering on a new or factory reset devices for initial setup. Users enter “afw#xenmobile” when prompted to enter a Google account. This action downloads and installs Secure Hub. Users then follow the Secure Hub set-up prompts to complete the enrollment.

In this enrollment method is recommended for most customers because the latest version of Secure Hub is downloaded from the Google Play store. Unlike with other enrollment methods, you do not provide Secure Hub for download from the XenMobile server.

Prerequisites:

  • Supported on all Android devices running Android 5.0 and above.

QR code

To enroll a device in device mode using a QR code, you generate a QR code by creating a JSON and converting the JSON to a QR code. Device cameras scan the QR code to enroll the device.

Prerequisites:

  • Supported on all Android devices running Android 7.0 and above.

Create a QR code from a JSON

Create a JSON with the following fields.

These fields are required:

Key: android.app.extra.PROVISIONING_DEVICE_ADMIN_COMPONENT_NAME

Value: com.zenprise/com.zenprise.configuration.AdminFunction

Key: android.app.extra.PROVISIONING_DEVICE_ADMIN_SIGNATURE_CHECKSUM

Value: qn7oZUtheu3JBAinzZRrrjCQv6LOO6Ll1OjcxT3-yKM

Key: android.app.extra.PROVISIONING_DEVICE_ADMIN_PACKAGE_DOWNLOAD_LOCATION

Value: https://path/to/securehub.apk

Note:

If Secure Hub is uploaded onto Citrix XenMobile server as an enterprise app, it can be downloaded from https://<fqdn>:4443/*instanceName*/worxhome.apk. The path to the Secure Hub APK must be accessible over the Wi-Fi connection that the device connects to during provisioning.

These fields are optional:

  • android.app.extra.PROVISIONING_LOCALE: Enter language and country codes.

    The language codes are two-letter lowercase ISO language codes (such as en) as defined by ISO 639-1. The country codes are two-letter uppercase ISO country codes (such as US) as defined by ISO 3166-1. For example, enter en_US for English as spoken in the United States.

  • android.app.extra.PROVISIONING_TIME_ZONE: The time zone in which the device is running.

    Enter an Olson name of the form area/location. For example, America/Los_Angeles for Pacific time. If you don’t enter one, the time zone is automatically populated.

  • android.app.extra.PROVISIONING_LOCAL_TIME: Time in milliseconds since the Epoch.

    The Unix epoch (or Unix time, POSIX time, or Unix timestamp) is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT). The time doesn’t include leap seconds (in ISO 8601: 1970-01-01T00:00:00Z).

  • android.app.extra.PROVISIONING_SKIP_ENCRYPTION: Set to true to skip encryption during profile creation. Set to false to force encryption during profile creation.

A typical JSON looks like the following:

Image of a typical JSON

Validate the JSON that is created using any JSON validation tool, such as https://jsonlint.com. Convert that JSON string to a QR code using any online QR code generator, such as http://goqr.me.

This QR code gets scanned by a factory-reset device to enroll the device in work-managed device mode.

To enroll the device

To enroll a device in work-managed device mode, the device must be in factory reset state.

  1. Tap the screen six times on the welcome screen to launch the QR code enrollment flow.
  2. When prompted, connect to Wi-Fi. The download location for Secure Hub in the QR code (encoded in the JSON) is accessible over this Wi-Fi network.

    Once the device successfully connects to Wi-Fi, it downloads a QR code reader from Google and launches the camera.

  3. Point the camera to the QR code to scan the code.

    Android downloads Secure Hub from the download location in the QR code, validate the signing certificate signature, install Secure Hub and sets it as device owner.

For more information, see this Google guide for Android EMM developers: https://developers.google.com/android/work/prov-devices#qr_code_method.

NFC bump

To enroll a device in device mode using NFC bumps requires two devices: One that is reset to its factory settings and one running the XenMobile Provisioning Tool.

Prerequisites:

  • Supported on all Android devices running Android 5.0, Android 5.1, Android 6.0 and above.
  • A XenMobile Server version 10.4 that is enabled for Android for Work.
  • A factory-reset device, provisioned for Android for Work in work-managed device mode. You can find steps to complete this prerequisite later in this article.
  • Another device with NFC capability, running the configured Provisioning Tool. The Provisioning Tool is available in Secure Hub 10.4 or on the Citrix downloads page.

Each device can have only one Android for Work profile, managed by an enterprise mobility management (EMM) app. In XenMobile, Secure Hub is the EMM app. Only one profile is allowed on each device. Attempting to add a second EMM app removes the first EMM app.

You can start work-managed device mode on new devices or on devices restored to factory settings. You manage the entire device by using XenMobile.

Data transferred through the NFC bump

Provisioning a factory-reset device requires you to send the following data through an NFC bump to initialize Android for Work:

  • Package name of the EMM provider app that acts as device owner (in this case, Secure Hub).
  • Intranet/Internet location from which the device can download the EMM provider app.
  • SHA1 hash of EMM provider app to verify if the download is successful.
  • Wi-Fi connection details so that a factory-reset device can connect and download the EMM provider app. Note: Android now does not support 802.1x Wi-Fi for this step.
  • Time zone for the device (optional).
  • Geographic location for the device (optional).

When the two devices are bumped, the data from the Provisioning Tool is sent to the factory-reset device. That data is then used to download Secure Hub with administrator settings. If you don’t enter time zone and location values, Android automatically configures the values on the new device.

Configuring the XenMobile Provisioning Tool

Before doing an NFC bump, you must configure the Provisioning Tool. This configuration is then transferred to the factory-reset device during the NFC bump.

Image of the Provisioning Tool configuration

You can type data into the required fields or populate them via text file. The steps in the next procedure describe how to configure the text file and contain descriptions for each field. The app doesn’t save information after you type it, so you might want to create a text file to keep the information for future use.

To configure the Provisioning Tool by using a text file

Name the file nfcprovisioning.txt and place the file in the /sdcard/ folder on the SD card of the device. The app can then read the text file and populate the values.

The text file must contain the following data:

android.app.extra.PROVISIONING_DEVICE_ADMIN_PACKAGE_DOWNLOAD_LOCATION=<download_location>

This line is the intranet/internet location of the EMM provider app. After the factory-reset device connects to Wi-Fi following the NFC bump, the device must have access to this location for downloading. The URL is a regular URL, with no special formatting required.

android.app.extra.PROVISIONING_DEVICE_ADMIN_PACKAGE_CHECKSUM=<SHA1 hash>

This line is the checksum of the EMM provider app. This checksum is used to verify that the download is successful. Steps to obtain the checksum are discussed later in this article.

android.app.extra.PROVISIONING_WIFI_SSID=<wifi ssid>

This line is the connected Wi-Fi SSID of the device on which the Provisioning Tool is running.

android.app.extra.PROVISIONING_WIFI_SECURITY_TYPE=<wifi security type>

Supported values are WEP and WPA2. If the Wi-Fi is unprotected, this field must be empty.

android.app.extra.PROVISIONING_WIFI_PASSWORD=<wifi password>

If the Wi-Fi is unprotected, this field must be empty.

android.app.extra.PROVISIONING_LOCALE=<locale>

Enter language and country codes. The language codes are two-letter lowercase ISO language codes (such as en) as defined by ISO 639-1. The country codes are two-letter uppercase ISO country codes (such as US) as defined by ISO 3166-1. For example, type en_US for English as spoken in the United States. If you don’t type any codes, the country and language are automatically populated.

android.app.extra.PROVISIONING_TIME_ZONE=<timezone>

The time zone in which the device is running. Type an Olson name of the form area/location. For example, America/Los_Angeles for Pacific time. If you don’t enter a name, the time zone is automatically populated.

android.app.extra.PROVISIONING_DEVICE_ADMIN_PACKAGE_NAME=<package name>

This data isn’t required, because the value is hardcoded into the app as Secure Hub. It’s mentioned here only for the sake of completion.

If there is a Wi-Fi protected by using WPA2, a completed nfcprovisioning.txt file might look like the following:

android.app.extra.PROVISIONING_DEVICE_ADMIN_PACKAGE_DOWNLOAD_LOCATION=http://www.somepublicurlhere.com/path/to/securehub.apk

android.app.extra.PROVISIONING_DEVICE_ADMIN_PACKAGE_CHECKSUM=ga50TwdCmfdJ72LGRFkke4CrbAk\u003d

android.app.extra.PROVISIONING_WIFI_SSID=Protected_WiFi_Name

android.app.extra.PROVISIONING_WIFI_SECURITY_TYPE=WPA2

android.app.extra.PROVISIONING_WIFI_PASSWORD=wifiPasswordHere

android.app.extra.PROVISIONING_LOCALE=en_US

android.app.extra.PROVISIONING_TIME_ZONE=America/Los_Angeles

If there is an unprotected Wi-Fi, a completed nfcprovisioning.txt file might look like the following:

android.app.extra.PROVISIONING_DEVICE_ADMIN_PACKAGE_DOWNLOAD_LOCATION=http://www.somepublicurlhere.com/path/to/securehub.apk

android.app.extra.PROVISIONING_DEVICE_ADMIN_PACKAGE_CHECKSUM=ga50TwdCmfdJ72LGRFkke4CrbAk\u003d

android.app.extra.PROVISIONING_WIFI_SSID=Unprotected_WiFi_Name

android.app.extra.PROVISIONING_LOCALE=en_US

android.app.extra.PROVISIONING_TIME_ZONE=America/Los_Angeles

To get the Secure Hub checksum

To get the checksum of any app, add the app as an enterprise app.

  1. In the XenMobile console, go to Configure > Apps and then click Add.

    The Add Apps window appears.

  2. Click Enterprise.

    The App information page displays.

    Image of the App Information page

  3. Select the following configuration and then click Next.

    The Android for Work Enterprise App page appears.

    Image of the Android For Work Enterprise App

  4. Provide the path to the .apk and then click Next to upload the file.

    Once the upload is complete, the details of the uploaded package appear.

    Image of the file upload page

  5. Click Next to open page to download the JSON file, which you then use to upload to Google Play. For Secure Hub, uploading to Google Play is not required, but you need the JSON file to read the SHA1 value from it.

    Image of the download JSON file page

    A typical JSON file looks like the following:

    Image of a typical JSON file

  6. Copy the file_sha1_base64 value and use it in the Hash field in the Provisioning Tool.

    Note: The hash must be URL safe.

    • Convert any + symbols to -
    • Convert any / symbols to _
    • Replace the trailing \u003d with =

    If you store the hash in the nfcprovisioning.txt file on the SD card of the device, the app does the safety conversion. However, if you opt to type the hash manually, it’s your responsibility to ensure its URL safety.

Libraries used

The Provisioning Tool uses the following libraries in its source code:

  • v7 appcompat library, Design support library, and v7 Palette library by Google under Apache license 2.0

    For information, see Support Library Features Guide.

  • Butter Knife by Jake Wharton under Apache license 2.0

Provision work profile mode in Android for Work

Work profile mode for Android for Work is available for devices on which you securely separate the corporate and personal areas on a device. For example, work profile mode is available for BYOD devices. The enrollment experience for work profile mode is similar to Android enrollment in XenMobile. Users download Secure Hub from Google Play and enroll their devices.

By default, the USB Debugging and Unknown Sources settings are disabled on a device when it is enrolled in Android for Work in work profile mode.

Tip:

When enrolling devices in Android for Work in work profile mode, always go to Google Play. From there, enable Secure Hub to appear in the user’s personal profile.

Support for COSU Android for Work devices

XenMobile supports the management of corporate owned single use (COSU) Android for Work devices. COSU devices fulfill a single use case, such as digital signage, ticket printing, or inventory management. Administrators restrict these devices to one app or small set of apps. Administrators also prevent users from enabling other apps or performing other actions on the device.

To provision COSU devices:

  • Add a role-based access control (RBAC) role that allows XenMobile administrators to enroll COSU devices to your XenMobile deployment. The role is new in this release of XenMobile Server. Assign this role to users whom you want to enroll COSU devices.
  • Add an enrollment profile for XenMobile administrators that you allow to enroll COSU devices to your XenMobile deployment.
  • Whitelist the app or apps you want the COSU device to access.
  • Optionally, set the whitelisted app to allow lock task mode. When an app is in lock task mode, the app is pinned to the device screen when the user opens it. No Home button appears and the Back button is disabled. The user exits the app using an action programmed into the app, such as signing out.
  • Provision each device using xfw#mobile, NFC bump, or QR code method, when the device is first powered on after factory reset. See afw#xenmobile, NFC bump, or QR code.

System requirements

  • Support for enrolling Android COSU devices begins with Android 6.0.
  • Device must be new or factory reset.

Add the COSU role

The RBAC role for enrolling COSU devices enables XenMobile to silently provision and activate a managed Google Play account on the device. Unlike managed Google Play user accounts, these device accounts identify a device that is not tied to a user.

You assign this RBAC role to XenMobile administrators to enable them to enroll COSU devices.

To add the RBAC role for enrolling COSU devices:

  1. In the XenMobile console, click the gear icon in the upper-right corner of the console. The Settings page appears.

  2. Click Role-Based Access Control. The Role-Based Access Control page appears, which displays the four default user roles, plus any roles you have previously added.

  3. Click Add. The Add Role page appears.

  4. Enter the following information.

    • RBAC name: Enter COSU or other descriptive name for the role. You cannot change the name of a role.
    • RBAC template: Choose the ADMIN template.
    • Authorized access: Select Admin console access and COSU devices enroller.
    • Console features: Select Devices.
    • Apply permissions: Select the groups to which you want to apply the COSU role. If you click To specific user groups, a list of groups appears from which you can select one or more groups.
  5. Click Next. The Assignment page appears.

  6. Enter the following information to assign the role to user groups.

    • Select domain: In the list, click a domain.
    • Include user groups: Click Search to see a list of all available groups. Or, type a full or partial group name to limit the list to only groups with that name.
    • In the list that appears, select the user groups to which you want to assign the role. When you select a user group, the group appears in the Selected user groups list.
  7. Click Save.

Add a COSU enrollment profile

When your XenMobile deployment includes COSU devices, a single XenMobile administrator or small group of administrators enroll many COSU devices. To ensure that these administrators can enroll all the devices required, create an enrollment profile for them with unlimited devices allowed per user. Assign this profile to a delivery group containing the administrators who enroll COSU devices. That way, even if the default Global profile has a limited number of devices allowed per user, administrators can enroll an unlimited number of devices. Those administrators must be in the COSU enrollment profile.

  1. Go to Configure > Enrollment Profiles. The default Global profile appears.

  2. To add an enrollment profile, click Add. In the Enrollment Info page, type a name for the enrollment profile. Ensure that number of devices that members with this profile can enroll is set to unlimited.

    Image of Enrollment Profiles configuration screen

  3. Click Next. The Delivery Group Assignment screen appears.

  4. Choose the delivery group or delivery groups containing the administrators who enroll COSU devices. Then click Save.

    The Enrollment Profile page appears with the profile you added.

    Image of Enrollment Profiles configuration screen

Whitelist apps and set lock task mode

The Kiosk device policy let you whitelist apps and set lock task mode. By default, Secure Hub and Google Play services are whitelisted.

To add the Kiosk policy:

  1. In the XenMobile console, click Configure > Device Policies. The Device Policies page appears.

  2. Click Add. The Add a New Policy dialog box appears.

  3. Expand More and then, under Security, click Kiosk. The Kiosk Policy page appears.

  4. Under Platforms, select Android for Work.

  5. In the Policy Information pane, type the Policy Name and an optional Description.

  6. Click Next and then click Add.

  7. To whitelist an app and allow or deny lock task mode for that app:

    Select the app you want to whitelist from the list.

    Choose Allow to set the app to be pinned to the device screen when the user starts the app. Choose Deny to set the app not to be pinned. Default is Allow.

    Image of Device Policies configuration screen

  8. Click Save.

  9. To whitelist another app and allow or deny lock task mode for that app, click Add.

  10. Configure deployment rules and choose delivery groups. For more information, see Device policies.