MDX Developer’s Guide

Citrix Citrix Endpoint Management is an enterprise solution that lets you manage mobile devices, apps, and data. The basic premise of Citrix 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 Citrix 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 Citrix 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 Citrix Endpoint Management policies. For example, if a Citrix 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 Citrix 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 current release of MDX App SDK for iOS includes these enhancements.

Support for iOS 9. The MDX App SDK 10.2 supports iOS 9.


Secure Hub 10.0.x and apps wrapped with MDX Toolkit 10.0.x will not run on iOS 9. Developers must re-wrap ISV apps with MDX Toolkit 10.2. Users must install the upgraded apps before upgrading their devices to iOS 9. If users try to open on iOS 9 any apps that were wrapped with MDX Toolkit 10.0.x, they will not be able to upgrade those apps and must reinstall a version of those apps wrapped with MDX Toolkit 10.2.

As a result of changes in iOS 9, MDX file-based encryption is incompatible with iOS9 for data downloaded to an iOS 9 device from a wrapped app. Database and keychain encryption remain fully functional. MDX Toolkit 10.2 provides an alternative mechanism to encrypt app data stored on the device file system. You can choose from the following options to protect data:

  • Use iOS File Data Protection to encrypt data.

Apple requires a device passcode to encrypt all app data on the device using iOS File Data Protection. To support this iOS protection, MDX Toolkit 10.2 includes a new policy, Device passcode, which you can use to enforce a PIN or passcode on an iOS 9 device. By default, this policy is On. The policy applies on a per-app basis and can be used whether you run Citrix Endpoint Management in MDM or MAM mode.

  • In addition to requiring a PIN or passcode, you can also specify a minimum iOS data protection class that is used for the app data stored on the file system.

Policies and iOS 9:

  • The user entropy feature, which is enabled through the Encrypt secrets using Passcode key, is not affected by iOS 9. MDX encryption for data stored in databases, the keychain, and the secure vault on the device are not affected.
  • On iOS 9 devices, the Enable encryption policy now enables database and keychain encryption only. For older iOS devices, the Enable encryption policy continues to also enable MDX file encryption.
  • For additional protection on devices with a device passcode enabled, the MDX App SDK also includes a higher level of iOS encryption for files that those apps store on the device. iOS file encryption has several data protection levels. The new Minimum data protection class policy lets you specify a protection class that is used for the app data unless a higher protection level is already specified in the app. The policy values are:

Complete unless open – If a file is open when a device locks, the file continues to be available to the app. This value corresponds to NSFileProtectionCompleteUnlessOpen. Default value.

Complete: When a device locks, files become unavailable. This value corresponds to NSFileProtectionComplete.

Until first lock: When a device restarts, until the user unlocks the device for the first time, files are locked and can’t be read. This value corresponds to NSFileProtectionCompleteUntilFirstUserAuthentication.

None – Files have no special protections and can be read from or written to at any time. This value corresponds to NSFileProtectionNone.

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

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.

Fixed issues. See Fixed Issues in MDX Toolkit.

MAM Capabilities

The enterprise functionality added by Citrix Endpoint Management is controlled through policies that administrators update on a per-app basis from the Citrix Endpoint Management console. Citrix 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, Citrix Endpoint Management can require users to enter corporate credentials or a PIN. This credential challenge can be repeated on a periodic basis.
  • App updates. Citrix 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.
  • Data encryption. For iOS 9 devices, Citrix Endpoint Management uses MDX file encryption for database and keychain files and, for locally stored data, uses Apple file encryption for locally stored data. For locally stored data on iOS 9 you can also use the Minimum data protection class policy to specify a protection class that is used for the app data unless a higher protection level is already specified for the app.
  • Network restrictions and VPN. A Citrix 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 NetScaler Gateway device hosted by the enterprise.
  • Communication restrictions between apps. A Citrix 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. Citrix Endpoint Management policies can disable various device capabilities for an app. Examples include the camera, microphone, and location sensor.

Citrix Endpoint Management Components

The following Citrix Endpoint Management components provide MAM functionality.

  • Citrix Endpoint Management server

    This enterprise or cloud resident server hosts Citrix Endpoint Management Store, the internal app store. Administrators upload mobile apps to Citrix 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 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 developer’s 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 Citrix Endpoint Management backend directly. Those apps always require the presence of Citrix MDX and authorization from a Citrix Endpoint Management Store to run. With Intune, however, those apps can be deployed and managed without Secure Hub or the Citrix Endpoint Management Store being present.

You use the Citrix 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 a Citrix 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.

Image of diagram of differences between General and Premium apps

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 MDX App Gallery, 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.

Diagram of MDX Toolkit inputs and output for ISV app wrapping

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 Citrix Endpoint Management server through the .mdx file added to Citrix 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 Citrix Endpoint Management.

About the Citrix Ready Program

Citrix evaluates and certifies ISV apps through the Citrix Ready program. The evaluation largely involves Citrix Endpoint Management integration testing. The certification ensures that the apps are compatible with the Citrix 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 MDX App Gallery or distribute the bundle directly to your Citrix Endpoint Management customers.

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 Citrix Endpoint Management Store and then subscribes to Citrix Endpoint Management 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 MDX App SDK

The following articles describe how to integrate the MDX App SDK into Android and iOS apps, use the APIs, publish apps, customize policies, and ensure the highest compatibility between your apps and Citrix Endpoint Management.