MDX developer guide

Citrix Endpoint Management is an enterprise solution that lets you manage mobile devices, apps, and data. The basic premise of Endpoint Management mobile app management (MAM) is that it injects enterprise functionality into preexisting apps, which are then hosted on a company’s private app store, the Apple App Store, or the Google Play Store.

To add Endpoint Management enterprise functionality to mobile apps, you wrap them with the MDX Toolkit. The MDX Toolkit is an app container technology that enhances the mobile device experience and prepares apps for secure deployment with Endpoint Management by adding MDX capabilities. The MDX capabilities include policies and settings, signed security certificates, and mobile app management code.

The MDX Toolkit includes the MDX App SDK, which delivers a complete set of MDX capabilities to your mobile apps through the Citrix MDX app container technology. APIs enable you to:

• Perform actions in wrapped apps based on Endpoint Management policies. For example, if an Endpoint Management policy prevents cut and copy in a MDX app, you can prevent text selection in your app. Your app can communicate and share policies with other MDX-enabled apps.
• Detect activities within your MDX-enabled apps. For example, you can check whether an app is wrapped or managed.
• Add custom functionality, such as security and policy enforcement.

• Develop mobile apps that will run either inside or outside a Citrix environment.

  In addition to being centrally configurable with MDX policies when used with Endpoint Management, apps that use the MDX App SDK can operate standalone outside of Citrix environments.

What’s new in the MDX App SDK 10.2

The 10.2 release of MDX App SDK for iOS includes these enhancements and updates.

The Minimum data protection class policy is hidden. To make the policy visible in Citrix Endpoint Management, open the policy_metadata.xml file for the app (in Applications/Citrix/MDXToolkit/data) and, in the MinimumDataProtectionClass section, change the value of PolicyHidden to false. After you wrap your app, the policy appears when you add the app to Citrix Endpoint Management.

App wrapping integration with Xcode build process. Developers can now wrap and publish an iOS app as part of the Xcode build process. For details, see Integrating the SDK into your App Library.

Support for shared vault in Android apps. The MDX App SDK now includes the Android API for the MDX shared vault feature, enabling you to share managed content between apps. For example, the shared vault enables the sharing of certificates and private keys through an enrolled app so that apps can obtain a certificate from the secure vault instead of from Secure Hub. For details, see XenMobile API for Android.

Note:

Developers, be sure to test wrapped apps that perform background processing, such as content refreshes on a locked device or background syncs.

MAM capabilities

The enterprise functionality added by Endpoint Management is controlled through policies that administrators update on a per-app basis from the Endpoint Management console. Endpoint Management pushes policies to mobile devices on the schedule determined by administrators. Policies manage features, such as the following:

• Authentication. When opening a managed app, Endpoint Management can require users to enter corporate credentials or a PIN. This credential challenge can be repeated on a periodic basis.
• App updates. Endpoint Management notifies users when updates to managed apps are available. The administrator can make updates mandatory within a certain time period. If a user doesn’t accept an update, the old version of the app will not execute after the time period elapses.
• Remote locking and wiping. An administrator can temporarily lock or permanently wipe apps on a per-app or per-device basis.
• Network restrictions and VPN. An Endpoint Management policy controls network access: Access can be either blocked, routed through a full VPN, or routed through a proxy VPN. VPN routing is through a Citrix Gateway device hosted by the enterprise.
• Communication restrictions between apps. An Endpoint Management policy determines whether document sharing between apps is blocked or permitted only between managed apps. Thus, the “Open In” pop-up in your app can omit unmanaged apps.
• Feature containment. An Endpoint Management policies can disable various device capabilities for an app. Examples include the camera, microphone, and location sensor.

Endpoint Management components

The following Endpoint Management components provide MAM functionality.

• Citrix Endpoint Management server

  This enterprise or cloud resident server hosts the Citrix Endpoint Management Store, the internal app store. Administrators upload mobile apps to Endpoint Management and then configure app and device policies.

• Secure Hub

  Enterprise users install Secure Hub for Android or iOS on their mobile device and then configure the app with a device enrollment URL and credentials. When Secure Hub opens, users select enterprise apps from the Citrix Endpoint Management Store. After the apps download and install on the device, Secure Hub serves as a hub for managing these apps, performing tasks, such as user authentication and updates of centrally administered policies.

• MDX

  MDX is the source of the MAM functionality. The MDX Toolkit adds MDX code to your mobile app. Other than wrapping apps, you don’t directly work with the MDX code.

• MDX Toolkit and MDX App SDK

  The MDX Toolkit adds enterprise functionality to existing mobile apps, a process called app wrapping. The MDX App SDK lets developers and system integrators MDX-enable their mobile apps. Application wrapping performs three main tasks. First, it injects Citrix code into your app that implements the app management capabilities. The output of that task is a new app file. Second, app wrapping signs the new app file with a security certificate. Finally, app wrapping creates an MDX file, which contains policy information and other settings. In some situations, the signed app file is also directly contained in the MDX file.

This developers guide focuses on app wrapping for ISVs.

Unmanaged and managed modes for ISV Apps

The MDX App SDK offers dual-mode app behavior, enabling you to deploy apps that can run with or without the MDX infrastructure. Apps that are run independently of Secure Hub are referred to as unmanaged apps. When those apps meet certain conditions, they transition to managed apps and run under the control of Secure Hub.

The dual-mode behavior is in contrast with the MDX Apps deployed from the Endpoint Management backend directly. Those apps always require the presence of Citrix MDX and authorization from an Endpoint Management Store to run. With Intune, however, those apps can be deployed and managed without Secure Hub or the Endpoint Management Store being present.

You use the Endpoint Management APIs to specify the type of dual-mode behavior needed when integrating an app with MDX. You can either develop two versions of app, one that is unmanaged and one that is managed, or a single app for both independent use and for inclusion in MDX. The MDX framework enforces the default behaviors associated with unmanaged and managed apps.

How an app transitions from unmanaged to managed depends on whether the app is wrapped as a General app or a Premium app:

• General app: A General app is hosted on the Apple App Store or the Google Play Store. Users who don’t have Secure Hub can download and run the app normally in an unmanaged mode, just like any generic app store app. If an unmanaged user later installs Secure Hub, the ISV app transitions to managed mode if these conditions are met.

  • The user signs on to a Citrix Endpoint Management enterprise store at least once.

  • The user is in an Endpoint Management delivery group to which the app is deployed.

  • MDX subscribes the user.

  • When prompted, the user confirms that their enterprise can manage the app.

    If a user opts out of enterprise app management, they can continue to run the app for personal use.

• Premium app: A Premium app is an app targeted to enterprise users. Citrix MDX Apps are examples of Premium apps. Although Premium apps typically run in managed mode, the embedded MDX framework allows Premium apps to run in unmanaged mode with a default set of MDX policies that you set through default policy files. Thus, you can effectively control the app behavior and use MDX capabilities even if the user is not associated with an enterprise account.

  If an unmanaged user later installs Secure Hub, the app silently transitions to managed mode if the following conditions are met.

  • The user is in a Citrix Endpoint Management delivery group to which the app is deployed.
  • The user signs on to Secure Hub if required.
  • MDX subscribes the user.

Note

An app cannot transition from managed mode back to unmanaged mode.

The following diagram summarizes the differences between General and Premium apps, based on whether they are managed or unmanaged.

ISV app wrapping

This section provides general information about app wrapping for ISVs. App wrapping performed by enterprise administrators is discussed in About the MDX Toolkit.

When you wrap ISV apps, the MDX Toolkit creates two files: an .mdx file and the app file (.ipa, .app, or .apk). The MDX Toolkit lets you embed the app store URL into the .mdx file, which you then deliver directly to your customers or upload to the Citrix Ready Marketplace, as described in the next section. You deliver the app file through app stores, by hosting it yourself, or by distributing it to your customers.

As shown in the following diagram, the MDX Toolkit combines app files (.ipa, .app, or .apk) with Citrix components and your keystore or signing certificate to produce an .mdx file and the modified app file.

The items added by ISV app wrapping include:

• An information file containing data needed by the MDX SDK framework when the framework binds with Secure Hub. The corresponding binding information is passed to Secure Hub from the Endpoint Management server through the .mdx file added to Endpoint Management. The data includes items, such as an app ID used for self-identification and a package ID used for app update checks.
• A FIPS fingerprint on the OpenSSL FIPS Crypto Object Module embedded in the app integrated with MDX App SDK.
• For iOS only: A new URL scheme that is added to the app file and is also passed to Secure Hub through the .mdx file an administrator adds to Endpoint Management.

About the Citrix Ready Program

Citrix evaluates and certifies ISV apps through the Citrix Ready program. The evaluation largely involves Endpoint Management integration testing. The certification ensures that the apps are compatible with the Endpoint Management infrastructure, thus giving enterprises confidence in your apps.

As part of the Citrix Ready program, you can publish your certified ISV app binaries directly in the Apple App Store or the Google Play Store. That means you don’t need to distribute binaries to enterprises, giving you more control over app updates. In addition, your apps are signed with your ISV certificate. You can also choose to distribute your certified apps directly to enterprises or to host them yourself.

You can also choose how to distribute the .mdx bundle for an ISV app: Either publish the bundle to the Citrix Ready Marketplace or distribute the bundle directly to your Citrix Endpoint Management customers.

For details, see Citrix Ready.

MDX app user experience

The way users interact with an app that is integrated with the MDX App SDK depends on how they install and start the app.

User starts with Secure Hub

1. The user opens Secure Hub and the Apple App Store or Google Play Store.
2. The user signs on to the Endpoint Management Store and then subscribes to the store.
3. The user downloads and installs the app from a public store.
4. Secure Hub prompts the user to sign on, if needed.
5. If the app was previously unmanaged, it silently transitions to managed.

User starts with the Apple App Store or Google Play Store

If Secure Hub is present on device already, users have the following experience for General and Premium apps.

General app

1. The user starts the app.

2. If the app detects an installation of Secure Hub and the app is entitled, the app prompts the user to confirm the transition to managed mode.

3. If the user opts to have their enterprise manage the app, Secure Hub prompts the user to sign on if needed.

4. After MDX subscribes the app to the user, the app transitions to managed mode.

   If Secure Hub isn’t on the device or the app isn’t entitled, the app runs in unmanaged mode, just like a regular public store app.

Premium app

1. The user starts the app.
2. If the app detects an installation of Secure Hub and the app is entitled, the app silently transitions to managed mode. If Secure Hub credentials are required, the app notifies the user about the transition to managed mode and prompts the user to sign on.

Known issues for the MDX App SDK

• Wrapping doesn’t work for Android apps unless they include icons.
• Some app frameworks have compatibility issues with Citrix Endpoint Management. For details, see Mobile App Development Frameworks Support (for Android) and Third Party Library Support (for iOS).
• For other issues, see Known issues.