MDX Toolkit - Product Documentation · PDF file 4 About the MDX Toolkit The MDX Toolkit is an...
147
citrix.com 1 MDX Toolkit http://docs.citrix.com/content/docs/en-us/mdx-toolkit/10.html Jun. 22, 2016 Docs.Citrix.com
Transcript of MDX Toolkit - Product Documentation · PDF file 4 About the MDX Toolkit The MDX Toolkit is an...
citrix.com 1
MDX Toolkit
http://docs.citrix.com/content/docs/en-us/mdx-toolkit/10.htmlJun. 22, 2016
Docs.Citrix.com
citrix.com 2
MDX Toolkit
About the MDX Toolkit
System Requirements
XenMobile Compatibility
Installing the MDX Toolkit
Wrapping iOS Mobile Apps
Deploying iOS Devices Through Apple DEP
Wrapping Worx Apps for iOS 8 or iOS 9
Wrapping Android Mobile Apps
Wrapping WorxMail, WorxWeb, and Worx Home for Windows Phone
MDX Policies at a Glance
XenMobile MDX Policies for Android AppsXenMobile MDX Policies for iOS AppsXenMobile MDX Policies for Windows Phone Apps
MDX Developer's Guide
System RequirementsDeveloping Android AppsBest Practices for Android AppsWorx API for AndroidDeveloping iOS AppsBest Practices for iOS AppsWorx API for iOSPolicy Defaults and Custom PoliciesTroubleshooting
About the MDX Toolkit
System Requirements
XenMobile Compatibility
Installing the MDX Toolkit
Wrapping iOS Mobile Apps
Deploying iOS Devices Through Apple DEP
Wrapping Worx Apps for iOS 8 or iOS 9
Wrapping Android Mobile Apps
Wrapping WorxMail, WorxWeb, and Worx Home for Windows Phone
MDX Policies at a Glance
XenMobile MDX Policies for Android AppsXenMobile MDX Policies for iOS AppsXenMobile MDX Policies for Windows Phone Apps
MDX Developer's Guide
System RequirementsDeveloping Android AppsBest Practices for Android AppsWorx API for AndroidDeveloping iOS AppsBest Practices for iOS AppsWorx API for iOSPolicy Defaults and Custom PoliciesTroubleshooting
citrix.com 3
iOS 9 and XenMobile
In a previous advisory, Citrix notified customers about a problem wherein files written onto an iOS 9 device by XenMobile-managed mobile apps did not use Citrix encryption. A solution to this issue is now available as part of the latest MDX Toolkit 10.2.1. For details, see . Note that when you update apps with the MDX Toolkit 10.2.1, users simply update their apps from the enterprise store. They do not need to uninstall and reinstall the apps.
This solution provides the same level of encryption supported on iOS 8. The XenMobile MDX policies that Citrix created in the MDX Toolkit 10.2 to provide additional security for application files support with iOS 9 are still available but have been turned off by default. It is not necessary to enforce a device passcode on iOS 9 devices to take advantage of Citrix encryption provided with MDX Toolkit 10.2.1.
Citrix recommends that customers update to the latest 10.2.1 version of Worx Home and update version 10.2 of Worx apps and enterprise apps with the MDX Toolkit 10.2.1.
For details on earlier advisory communication, see iOS and XenMobile .
What's New in the MDX Toolkit 10.2.1
Earlier Advisory Communication
citrix.com 4
About the MDX Toolkit
The MDX Toolkit is an app container technology that enhances the mobile device experience and lets you prepare apps for secure deployment with XenMobile by adding the following information to the apps:
The code required to support mobile app management tasks, such as provisioning, custom authentication, per-app revocation, data containment policies, data encryption, and per-app virtual private networkingSigned security certificatesPolicy information and other XenMobile settings
The MDX Toolkit can securely wrap apps created within your organization or third-party mobile apps, such as the Citrix Worx apps.
After you wrap an app, you then use the XenMobile console to add the app to XenMobile. When you add the app, you can change the policy configuration, add app categories, apply workflows, and deploy apps to delivery groups.
To download XenMobile components, see .
Known Issues in the MDX ToolkitFixed Issues in the MDX Toolkit
Planning a XenMobile deployment involves many considerations. For recommendations, common questions, and use cases for your end-to-end XenMobile environment, see the .
To view the entire set of MDX Toolkit documentation earlier than version 10.3.6, download the .
About App WrappingYou can wrap Citrix Worx apps and Android or iOS apps you obtain from app vendors.
Note: Independent Software Vendors (ISVs) can wrap apps they develop and then make them available in an app store or the Citrix Worx App Gallery. For details, see the .
The MDX Toolkit combines app files (.ipa, .app, or .apk) with Citrix components and your keystore or signing certificate to produce a wrapped MDX app.
The MDX Toolkit and Worx App SDK for iOS and AndroidYou can use the MDX Toolkit to wrap Worx apps and compiled, non-public custom apps for Android and iOS, including apps created with PhoneGap.
For enterprise application wrapping, you start with an iOS application (.ipa) or an Android application (.apk). Be sure to acquire third-party applications directly from the application vendor. iOS applications downloaded from the Apple store are encrypted and cannot be wrapped.
Note: The MDX Toolkit for iOS version 10.0.7 and later supports iOS apps developed on the Xamarin platform. Android apps developed with Xamarin are not supported.
The MDX Toolkit and Worx App SDK for iOS and Android includes the following tools:
A Mac OS GUI tool that can wrap both iOS and Android apps.A Mac OS command-line tool that wraps iOS apps.A Java command-line tool that wraps Android apps.Worx App SDK: Third-party app developers can use the Worx App SDK to perform actions in wrapped apps based on XenMobile policies. For example, if a XenMobile policy prevents cut and copy in a Worx app, a developer can prevent text selection in the app. For details, see the . Also, note changes in the wrapping process with the MDX Toolkit version 10.3, as discussed in the What's New section later in this article.
The MDX Toolkit for Windows Phone
http://www.citrix.com/downloads/xenmobile/product-software.html
Known Issues in the MDX ToolkitFixed Issues in the MDX Toolkit
XenMobile Deployment Handbook
MDX Developer's Guide
MDX Developer's Guide
citrix.com 5
The MDX Toolkit for Windows Phone 8.1 and Windows Phone 10 contains a Windows command-line tool that wraps WorxMail and WorxWeb. Although the MDX Toolkit for Windows Phone 8.1 currently does not support wrapping other apps, you use it to re-sign Worx Home, as well as any third-party Windows Phone apps you want to deploy. Windows Phone 8.1 and Windows Phone 10 requires all apps to be signed by the same certificate to enable enrollment of deployed apps.
What's New in the MDX Toolkit 10.3.9Arm64 Support for iOS Enterprise Apps. You can now wrap 64-bit application binaries in addition to 32-bit application binaries for iOS. This is not the case for Android applications. In addition, the MDX Toolkit verifies the binary after it's modified to ensure that it is a valid ELF MachO binary.Block localhost Connections (Android only). The Block localhost Connections policy allows you to stop connections to the loopback address (127.0.0.1).
What's New in the MDX Toolkit 10.3.6Whitelisted WiFi networks. The Whitelisted WiFi networks policy allows you to specify allowed networks. Apps work only when connected to one of the networks on the list. This feature is available in MDM+MAM mode only.ShareFile support for shared devices. ShareFile mobile app version 4.4 now supports shared devices in MDM+MAM mode, allowing multiple users to share a device without re-enrolling. For more information, see
.Icon handling (iOS). App developers can now put icon files in the app bundle root folder, as an alternative to the usual practice of putting them in info.plist. For the toolkit to be able to locate the icon files, their names must be in one the following formats:
icon.pngicon-60x2.pnicon-72.pngicon-76.png
Improved mail sync (iOS). Updates to mail sync and ShareFile integration have made mail sync more reliable.
What's New in the MDX Toolkit 10.3.5Worx Home policy retrieval sign-on behavior. When you set the Maximum offline period MDX policy, with this release of the MDX Toolkit, if Worx Home for iOS has a valid NetScaler Gateway token, the app retrieves new policies for MDX apps from XenMobile without any interruption to users. If Worx Home does not have a valid NetScaler token, users must authenticate through Worx Home in order for app policies to update. The NetScaler token may become invalid due to a NetScaler Gateway session inactivity or a forced session time-out policy. When users sign on to Worx Home again, they can continue running the app.Secure signoff (iOS). When users sign off from Worx Home, the container automatically locks so that all Worx and MDX apps stay secure. To access the apps again, users have to enter their Worx PINs. Remove iOS app extensions. You can remove iOS extensions from the app during the enterprise app wrapping process by selecting the check box Strip extensions (Today, Watch, etc.) from iOS applicationon the screen, as shown in the following figure. Note that iOS apps with Apple Watch Verify App Details extensions are not supported when wrapping apps.
Shared Devices in XenMobile
citrix.com 6
Reverse split tunnel exclusion list. If you don't want certain websites to tunnel through NetScaler Gateway, you can add a comma-separated list of fully qualified domain names (FQDN) or DNS suffixes that connect by using the local area network (LAN) instead. This list applies only to Secure Browse mode when NetScaler Gateway is configured in mode. Default value is empty.Split tunnel reverseInactivity timer behavior. When the inactivity timer is set to 0, inactivity offline authentication is disabled for MDX apps.Mail compose redirection (iOS). You have three choices for how users are allowed to compose mail from an enterprise app:
: If installed on the device, WorxMail automatically opens. If not, native mail does not open. WorxMailInstead, users get a message instructing them to install WorxMail.
: The device's native mail program opens.Native email: Both WorxMail and native mail are blocked.Blocked
Default is . This policy replaces the policy, which is deprecated.WorxMail Block email compose
What's New in the MDX Toolkit 10.3x86 support. With the MDX Toolkit 10.3, MDX enterprise wrapped apps are supported on Android x86-based devices.Shared devices. If you're deploying XenMobile 10.3, you can configure devices to be shared by multiple users. Only WorxMail and WorxWeb are currently supported. For more information, see Shared devices in XenMobile.Self-destruct app lock and wipe client property. This global security policy applies to Android platforms and is an enhancement of the existing app lock and wipe policies. Self-destruct prevents access to Worx Home and managed apps, after a certain number of days of inactivity. After the time limit, apps are no longer usable, and the user device is unenrolled from the XenMobile server. Wiping the data includes clearing the app data for each installed app, including the app cache and user data. The inactivity time is when the server does not receive an authentication request to validate the user over a specific length of time. For example, if you set 30 days for the policy and the user does not use Worx Home or other apps for more than 30 days, the policy takes effect.Android PAC file support. When you add an MDX-wrapped WorxWeb app to XenMobile, you can specify the Proxy Auto-Configuration (PAC) file URL or the proxy server for web browsers to use automatically when fetching a given URL. This functionality is supported in full tunnel mode only; you cannot use Secure Browse when you specify a PAC. When you configure this setting, also make sure the Permit VPN mode switching policy remains as the default value of .OffSingle sign-on (SSO) support in user entropy environments. If users have not used an MDX app on the device for a certain period of time, as defined by the inactivity timer, users are prompted to sign on. They can use either their Worx PIN or Touch ID, if you have enabled Touch ID authentication. This feature is now available in environments that have user entropy turned on, as well as in environments that have user entropy turned off. This capability is available for iOS apps only.
citrix.com 7
Developing ISV apps for iOS with the Worx Framework. MDX Toolkit 10.3 has changed the process that ISV developers need to follow when preparing an app for distribution, after they have built the app using Xcode. Instead of using the graphical MDX tool or the wrap command at the command-line, with MDX Toolkit 10.3, developers can sign, deploy, and debug their app within the Xcode Integrated Development Environment (IDE). Developers now need to run the SDKPrep command of the MDX command-line tool as part of the Xcode build process, eliminating the need to wrap the app outside of Xcode. For details on the step-by-step procedures for ISV wrapping in the MDX Toolkit tool and command-line interface, see
. : Enterprise apps that you build with the Worx Framework in Xcode and then Notewrap by using the enterprise mode of the MDX Toolkit are still supported.
App geofence. This feature allows you to restrict app usage based on the location of the user device. For example, a person travels to Amsterdam. You can allow users to use the app when they are in Amsterdam, but if the person travels to Belgium, the app locks and users cannot interact with the app. When the user returns to Amsterdam, the app unlocks and is available for normal use. There are three settings to enable geofencing:
GPS longitude and latitude also called a .pointThe radius that defines the area in which apps can operate, such as in the Netherlands. If you set the radius to 0, the app does not support geofencing.
If the app supports geofencing and you disable location services, a message appears in which users can either quit the app or can click that goes to the screen on the Android device. If users enable Settings Settings locations services, they can return and continue using the app.
When the radius and location services settings are correct, the app checks for a geofence breach. If the distance between the current location and the center point (as specified in the policy) is greater than the specified radius, the user is blocked from using the app. When this occurs, users receive an option to quit the app. The user must be within the fence to continue using the app.
If the distance between the current location and then the center point is less than the specified radius, the user can continue to use the app.
The app checks the network provider (WiFi, 3G, or 4G) or the GPS Provider to find the location. The device can also use GPS and the cell phone carrier network together, which is also called high accuracy mode and helps in obtaining the location faster.
There is a two-minute time-out to allow for longer times in checking the location:
Center point longitude. Enter the longitude point to specify the area in which the app is allowed to work.
Center point latitude. Enter the latitude point to specify the area in which the app is allowed to work.
Radius. Enter the radius from the center point in which the app is allowed to work. If set to 0, geofencing is not allowed.
Note: To get an accurate location from the device, and to avoid users trying to circumvent geofence by disabling WiFi or the GPS, Citrix recommends setting the policy to .Online session required On
New MDX policies for WorxMail. For a list of new WorxMail policies available in the MDX Toolkit, see . The policies for Windows Phone have not changed since the earlier release. For the complete list of app Mobile Apps
policies, see the articles in this section, .
What's New in the MDX Toolkit 10.2.1
iOS 9 CompatibilityMDX Toolkit 10.2.1 and Worx Mobile Apps 10.2 are now compatible with iOS 9.
Important
Developing iOS Apps
About Worx Mobile Apps
MDX Policies at a Glance
citrix.com 8
Worx Home 10.0.x and apps wrapped with MDX Toolkit 10.0.x will not run on iOS 9. Users must upgrade to apps wrapped with MDX Toolkit 10.2.1 and to Worx Home 10.2.1 before upgrading their devices to iOS 9. If users try to open on iOS 9 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.1.
The XenMobile MDX policies, as described in this article, that were created to provide additional security for application files support with iOS 9 are still available but have been turned by default. It is not necessary to set a device Off passcode to enable iOS Data Protection, nor to enforce a device passcode in the XenMobile console.
The following options help 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.1 includes a new policy, , which you can use to Device passcodeenforce a PIN or passcode on an iOS 9 device. By default, this policy is . The policy applies on a per-app Offbasis and can be used whether you run XenMobile 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.If you do not want to require a PIN or passcode, you can instead restrict the data stored on iOS 9 devices through new policies for WorxMail, WorxNotes, and WorxWeb.
Policies and iOS 9
User entropy featureThe user entropy feature, which is enabled through the key, is not affected by iOS 9. Encrypt secrets using PasscodeMDX encryption for data stored in databases, the keychain, and the secure vault on the device are not affected.
To allow users to use Touch ID when they start an app, enable and set to . After Worx PIN User Entropy falseconfiguring these settings, users do not need to enroll their devices again.
Minimum data protection class policyFor additional protection on devices with a device passcode enabled, you can specify 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. Default value.
Complete – When a device locks, files become unavailable.
citrix.com 9
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.
None – Files have no special protections and can be read from or written to at any time.
The Minimum data protection class policy is hidden. To make the policy visible in XenMobile, open the policy_metadata.xml file for the app (in Applications/Citrix/MDXToolkit/data) and, in the section, change MinimumDataProtectionClassthe value of to . After you wrap your app, the policy appears when you add the app to XenMobile.PolicyHidden false
Data restriction policies
If you do not want to require a device PIN or passcode, new MDX policies for WorxMail, WorxNotes, and WorxWeb enable you to restrict the data stored on iOS 9 devices. The following policies are by default. If you enable a policy, Offafter users update Worx apps to version 10.2, previously downloaded data that doesn’t comply with the policy is removed.
Block file attachments policy: Disables downloading attachments in WorxMail.
Important: If you enable the Block file attachments policy, Worx Home can’t attach logs to support emails sent from Worx Home. Be sure to let your users know that, on iOS 9 devices, they must not use WorxMail to send logs when they report an issue. To change the mail app used to send logs, users select Report an Issue, select the app, tap Settings, and then set Send Report with WorxMail to Off.
Block email as attachment policy: Disables sending from WorxNotes a note as an email with a PDF attachment. When WorxNotes is used with ShareFile, notes are files, not data, and therefore rely entirely on a device passcode for encryption.
citrix.com 10
iOS 9 security restrictions policy: In WorxWeb, disables downloading files and offline pages. The policy also disables cookie caching and HTML 5 local storage. Enabling this policy slows web page loading.
iOS data protection policies (for ASD compliance)
Enterprises who must meet Australian Signals Directorate (ASD) data protection requirements can use the new Enable iOS data protection policies for WorxMail and WorxWeb. By default the policies are . When Enable iOS data Offprotection is for WorxWeb, WorxWeb uses Class A protection level for all files in the sandbox. For details about OnWorxMail data protection, see . A higher protection level specified for the Minimum data protection class policy overrides this policy.
Australian Signals Directorate Data Protection
citrix.com 11
For related information, see and .
App Upgrades
To use Worx Mobile Apps on iOS 9, users must upgrade to Worx Home 10.2 and upgrade to Worx Mobile Apps 10.2 to iOS 9. If users upgrade a device to iOS 9 before upgrading Worx apps and MDX-wrapped before upgrading
enterprise apps to version 10.2, app data might be corrupted when users open an app. In that case, users must reinstall the 10.2.1 version of the app.
When upgrading an app, the first time users open a Worx app (version 10.2) or an app wrapped with MDX Toolkit 10.2.1 on an iOS 9 device that doesn’t have a passcode, Worx prompts them to create a passcode.
After users create a passcode and start a wrapped app, Worx updates the app data to use Apple file encryption. That update can take a few minutes, during which users should not close the app. After the app update completes, Worx prompts users to quit and reopen the app. After that, users must enter their passcode to unlock a device when it starts or resumes after a period of inactivity. For step-by-step details of the update process, see
.Apps for iOS 9
iOS 9, IBM Notes Traveler Server, and SSL
On iOS 9 devices, WorxMail can't connect to the Notes Traveler server if the Traveler server is configured for SSL 3.0 connections. The recommended work-around is to use TLS 1.2 on IBM Notes Traveler Server 9.0. If you must use SSL 3.0 connections, do not upgrade to WorxMail 10.2. For details, see “Configuring IBM Notes Traveler Server for WorxMail― in .
Other New Features in MDX Toolkit 10.2.1
Support for Android M. This release of MDX Toolkit and Worx App SDK support mobile devices running Android M.
Advisory: iOS 9 and XenMobile Configuring iOS Data Protection Policies for iOS 9
How to Update Worx Mobile Apps for iOS 9
Integrating Exchange Server or IBM Notes Traveler Server
citrix.com 12
Touch ID offline authentication on iOS devices. When a wrapped app needs to request offline authentication (for a Worx PIN or AD password), it can now ask for Touch ID instead on supported iOS devices that have the Touch ID feature. This allows your users to sign on using Touch ID.
You can enable this feature in the following authentication scenarios:
Worx PIN + Client certificate configuration
Worx PIN + Cached AD password configuration
Worx PIN + Client certificate configuration and Cached AD password configuration
Worx PIN is off
If Touch ID authentication fails or if a user cancels the Touch ID prompt, wrapped apps fall back to Worx PIN or AD password authentication.
To enable Touch ID authentication, see .
Support for Australian Signals Directorate (ASD) computer security data protection. Enterprises who must meet ASD computer security requirements can use the new Enable iOS data protection policy for WorxMail and WorxWeb. The policies are by default. For details, see and Off
.Policies for iOS AppsConnection security level. The Connection security level policy is now also available for Android.New MDX policies for iOS. For details, see and
.AppsBlock email as attachment (WorxNotes)Block file attachments (WorxMail)Default sync interval (WorxMail)Device passcodeiOS 9 security restrictions (WorxWeb)Enable iOS data protection (WorxMail, WorxWeb)Enable week number (WorxMail)Minimum data protection class
New MDX policies for Android. For details, see and .Worx Mobile Apps
Connection security levelDefault sync intervalDisable cookiesDisable HTML5 local storageEnable week numberRequire device lock. Replaces the Require device PIN or passcode policy and the Require device pattern screen lock policy.
The Require internal network policy and the Internal WiFi networks policy are deprecated for XenMobile 10.
For a description of Worx App SDK enhancements, see .
About Client PropertiesClient properties contain information that is provided directly to Worx Home on users' devices. Client properties are located in the XenMobile console by clicking the cog icon in the upper-right corner and then clicking . Client Properties
About Client Properties
WorxMail XenMobile MDX Policies for iOS Apps
XenMobile MDX Policies for iOS Apps About Worx Mobile Apps
XenMobile MDX Policies for Android Apps About Worx Mobile Apps
What's New in the Worx App SDK
citrix.com 13
1.
2.
Client properties are used to configure settings such as the following:
User password caching
User password caching allows the users' Active Directory password to be cached locally on the mobile device. If you enable user password caching, users are prompted to set a Worx PIN or passcode.
Inactivity timer
The inactivity timer defines the time in minutes that users can leave their device inactive and then can access an app without being prompted for a Worx PIN or passcode. To enable this setting for an MDX app, you must set the App passcode policy to . If the App passcode policy is , users are redirected to Worx Home to perform a full On Offauthentication. When you change this setting, the value takes effect the next time users are prompted to authenticate.
Worx PIN authentication
Worx PIN simplifies the user authentication experience. Worx PIN is used to secure a client certificate or save Active Directory credentials locally on the device. If you configure Worx PIN settings, the user sign on experience is as follows:
When users start Worx Home for the first time, they receive a prompt to enter a PIN, which caches the Active Directory credentials.When users subsequently start a Worx app, they enter the PIN and sign on.
You use client properties to enable Worx PIN authentication, specify the PIN type, and specify PIN strength, length, and change requirements.
Touch ID authentication
Touch ID is an alternative to Worx PIN when wrapped apps, except for Worx Home, need offline authentication, such as when the inactivity timer expires. You can enable this feature in the following authentication scenarios:
Worx PIN + Client certificate configuration
Worx PIN + Cached AD password configuration
Worx PIN + Client certificate configuration and Cached AD password configuration
Worx PIN is off
If Touch ID authentication fails or if a user cancels the Touch ID prompt, wrapped apps fall back to Worx PIN or Active Directory password authentication.
Touch ID authentication requirements:
iOS devices (minimum version 8.1) that support Touch ID and have at least one fingerprint configured.User entropy must be off.
Note: To allow users to use Touch ID when they start an app, enable Worx PIN and set to . After User Entropy falseconfiguring these settings, users do not need to enroll their devices again.
Follow these steps to configure Touch ID authentication:
citrix.com 14
1. In the XenMobile console, go to and then click . Client Properties Add
2. Add the key , set its to , and set the policy name to ENABLE_TOUCH_ID_AUTH Value True Enable Touch ID .Authentication
Known Issues in the MDX ToolkitMDX Toolkit Version 10.3.5
On Android devices, the Self-Destruct policy works for MDX apps only and doesn't apply to Worx Home. [#613302]When an iOS device loses its network connection after the Maximum offline period policy expires for an MDX app, attempts to use the app result in prompts to tap . The prompts continue until the device Authorizeregains a network connection. [#633285]When you make changes to the following keys in the XenMobile console in > Settings Client Properties, existing MDX apps may not allow users to authenticate with their current Active Directory password:
ENABLE_PASSCODE_AUTH: from to false trueENABLE_PASSWORD_CACHING: from to [#637141]false true
iOS apps with Apple Watch extensions are not supported when wrapping apps.
MDX Toolkit Version 10.3
Unusable icons for apps might remain on Android devices even after the MDX container is wiped.[#611647]When users try to open a newly installed MDX app for Android from Worx Home, when the device is managed in MAM mode, an error, such as "App Not Registered," occurs. This issue occurs on these .x86 device types: Lenovo Yoga (4.4.2) and Dell Venue8 3840 (4.4.4) [#612163]
MDX Toolkit Version 10.2
When you create an APN device policy and deploy the policy to an Android device, if you refresh the policy or deploy the device policy again, the APN setting appears multiple times on the device.
[#564593]
In apps using the Worx App SDK, NSURLSession background download puts unencrypted content in the MDX sandbox when configured using the (iOS 8) and backgroundSessionConfigurationWithIdentifier
(iOS 7). The content is encrypted only after the download completes.backgroundSessionConfiguration
[#556634]
On iOS 9 devices, connections that tunnel to the internal network using a full VPN tunnel don't apply intranet app addresses and are based only on the configured DNS suffix.
[#584426]
citrix.com 15
For third-party apps managed by MDX, the iOS data protection level of files isn't reset on first-time use. Users must restart the app to reset the protection level.
[#589323]
If your attempt to wrap apps fail when using the MDX Toolkit Version 10.2.1 and the Android API 23, complete the following steps:
1. Install the MDX Toolkit Version 10.2.1.2. Get the latest framework from any Android M device by using the following command: $ adb pull /system/framework/framework-res.apk <Destination Directory>3. Rename the framework-res.apk to 1.apk4. Replace ~/Library/apktool/mdx/framework/2.0.1/1.apk with the newly extracted 1.apk
[593020]
Attempts to attach a photo to an email fails after an app upgrade occurs and the is Open-in exclusion listnot overwritten or merged. After upgrading the apps, update the policy on XenMobile with the following settings: {action=android.media.action.IMAGE_CAPTURE}{action=android.provider.MediaStore.RECORD_SOUND}{action=android.media.action.VIDEO_CAPTURE}
[#594466]
Fixed Issues in the MDX ToolkitThe following are fixed issues in the current release of the MDX Toolkit. For fixed issues in MDX Toolkit 10.0.x, see
.
If users attempt to use their website to send an APNS notification to a third-party app wrapped using the MDX Toolkit, the notification fails to reach the device. [#640688] Wrapping a custom iOS app using the MDX Toolkit causes the app to crash when users open the app. [#645314] If users use the MDX Toolkit to wrap an app that uses NSURLRequest as part of its API then opens the app in secure browse mode, the app times out after 15 seconds. [#647096]After wrapping a custom app using the MDX Toolkit and opening the app, the app appears to open, but stays on the initial screen before going into the background. [#647981] If the MDX policy for split tunneling is turned ON or Reverse and no intranet applications are enabled, the connection fails. [#651016]
XenMobile MDX Toolkit 10.0.x - Fixed Issues
citrix.com 16
System Requirements
This article provides the system requirements for using the MDX Toolkit 10.3 to wrap mobile apps, as well as requirements specific to app platforms.
Quick links to sections in this article
MDX Toolkit System RequirementsOther Requirements for Wrapping iOS Mobile AppsOther Requirements for Wrapping Android Mobile AppsOther Requirements for Wrapping Worx Apps for Windows Phone
MDX Toolkit System Requirements
MDX Toolkit and Worx App SDK (iOS and Android)Important: The Worx App SDK 10.2 now requires the following additional components: JavaScriptCore.framework and LocalAuthentication.framework.
Java Development Kit (JDK) 1.7 or 1.8.
You can download the JDK 1.8 from on the Oracle . web siteFor installation instructions, see the on the Oracle . Be web sitesure to install the full JDK; set JDK 1.8 as the default.
Mac OS X 10.10 (minimum version for iOS 9 and iOS 8 apps)Mac OS X 10.8 (minimum version for pre-iOS 8 apps)
The installer for the MDX Toolkit and Worx App SDK must run on Mac OS. The installer includes Mac OS tools that wrap both iOS and Android apps, as well as a Java command-line tool that wraps Android apps.
For Worx App SDK: iOS 9 SDK with Xcode 7; generation disabledbitcode
generation is on by default in Xcode 7. You must disable it to use Xcode 7 with the Worx BitcodeApp SDK.
Computers running Windows 10 for Windows 10 mobile devices. You use the command-line tool and Visual Studio 2013 Community Edition with all service packs installed.
MDX Toolkit for Windows Phone 8.1. Windows 8.1 requirements:
Microsoft .NET Framework 4.5.1Microsoft Silverlight 5 runtime and SDKVisual Studio 2013 (Professional or Enterprise version)Windows Phone 8.1 SDK tools
The MDX Toolkit has other requirements specific to the app platforms, as described in the following sections.
Other Requirements for Wrapping iOS Mobile Apps
To obtain access to the app wrapping prerequisites for iOS, you must register for an Apple distribution account. There are three types of iOS developer accounts: Enterprise, Individual, and University. Citrix strongly recommends iOS Developer Enterprise accounts.
iOS Developer Enterprise The only type of Apple Developer account that allows you to accounts:provision, and test unlimited apps to unlimited devices, with or without app wrapping. Be sure to deploy,distribute your Developer Certificate to your developers so they can sign apps.iOS Developer Individual accounts: Limited to 100 registered devices per year and not qualify for app dowrapping and enterprise distribution with XenMobile.iOS Developer University accounts: Limited to 200 registered devices per year and not qualify for app dowrapping and enterprise distribution with XenMobile.
iOS 9 and iOS 8 app wrapping prerequisites:
MDX Toolkit System RequirementsOther Requirements for Wrapping iOS Mobile AppsOther Requirements for Wrapping Android Mobile AppsOther Requirements for Wrapping Worx Apps for Windows Phone
Java SE Development Kit DownloadsJDK 8 and JRE 8 Installation Guide
citrix.com 17
1. 2.
3.
OS X 10.10 (Yosemite; minimum version)Xcode 6 (minimum version for iOS 9 and iOS 8)Xcode command-line tools 2014)(April,
Pre-iOS 8 app wrapping prerequisites:OS X 10.8 (minimum version)Xcode 5.0 (minimum version)Xcode command-line tools 2013)(October,
Important
Be sure to track when the provisioning profiles for your account are due to expire and renew the profiles before they expire. If a profile used to wrap apps expires, you must renew the profile, re-wrap the apps, and then reinstall the apps on user devices. To renew a provisioning profile, log on to your , go to
, and then select .Certificates, Identifiers & Profiles Provisioning Profiles
Download the Xcode command-line tools from the . Mac OS X 10.10 does not install web sitethe tools automatically. To install the tools, follow these steps:
In , click to use the Mac command-line interface. > Applications Utilities TerminalType the following command:
xcode-select --install
Be sure to include two hyphens before the word in the command.install
After the Xcode command-line tools install, run install any prerequisites.Xcodeto
Other Requirements for Wrapping Android Mobile AppsTo wrap Android wraps, you also need a compatible Android software development kid (SDK) and a valid keystore. To download, create, and properly configure the SDK and keystore, follow these instructions:
Android Software Development Kit
The MDX Toolkit is compatible with API Levels 19-24 of the Android SDK.
Note: For wrapping Worx Apps version 10.3.5, the minimum Android SDK required is API Level 23. For information on troubleshooting errors that can occur when wrapping Android apps with MDX Toolkit 10.3.5, see .
1. Go to the Google developer website and download the Android SDK from the SDK . The full Android Studio is not required. You can download the command line tools from the section near the bottom of the page.
Apple Developer account
Xcode Apple Developer
this article
download page
citrix.com 18
2. Install the latest tools, platform-tools, and build-tools. This installation requires using the Android tool in Android SDK > tools to start the SDK Manager:
a. Unzip the SDK file you downloaded.b. Go to the tools folder and then click to run the SDK Manager.Android
3. In the SDK Manager, select the latest versions of the following:
Android SDK ToolsAndroid SDK Platform-toolsAndroid SDK Build-tools
4. Click .Install Packages
5. On the screen, click for all the packages you are installing and then Choose Packages to Install Accept Licenseclick .Install
citrix.com 19
6. To verify that you downloaded the appropriate SDK Tools and APIs, check that the aapt file is in Android SDK > build-tools > 23.0.3.
7. When updating your SDK, you have to delete all aapt files from the platform-tools folder. The aapt file should be in build-tools only.
8. If the zipalign file is missing from build-tools, copy the file from the platform-tools folder to the build-tools folder, and then delete it from platform-tools.
9. Add the location of the newly installed folders to the android_settings.txt file in the MDX Toolkit install folder.
citrix.com 20
10. In Applications > Citrix > MDX Toolkit, open the android_settings.txt file and then add the full path for the following folders:
Android SDKAndroid SDK > toolsAndroid SDK > platform-toolsAndroid SDK > build-tools > [version]
Note: Be sure to remove the Android SDK > apktools path from the android_settings file, as that path is no longer required.
To find the full path of your SDK folder, right-click on the file, select and then on the Info panel, review the Get InfoWhere information.
11. Before editing the android_settings file, make a copy of the file.
a. Go to Applications > Citrix > MDXToolkit > Android_settings.
b. Add the new paths.
c. Save the file outside of the Applications > Citrix > MDX Toolkit folder.
d. Rename the original android_settings file in the Applications > Citrix > MDXToolkit folder; for example, android_settings.old.
e. Copy the new android_settings file with the added paths into the Applications > Citrix > MDX Toolkit folder.
The following example shows the file with the paths added:
citrix.com 21
Valid Keystore
A valid keystore contains digitally signed certificates that you use to sign Android apps. You create a one time keystoreand retain this file for current and future wrapping. If you do not use the same when wrapping new versions of keystoreapps that you've previously deployed, upgrades of those apps won't work. Instead, users need to manually remove older versions before installing new versions.
A can contain multiple private keys. In most cases, though, the has only one key.keystore keystore
For details about certificates, see .
You must sign your apps with a key that meets the following guidelines:
2048-bit keysizeDSA or RSA key algorithm ( )keyalgDo not use MD5.SHA1withDSA or SHA1withRSA signing algorithm ( )sigalg
If you don't want to use the debug keystore, create a keystore. To create a keystore, start and then enter the Terminalcommand:
keytool -genkey -keystore -alias -keyalg RSA -keysize 2048 -validity 10000my-release-key alias_name
Provide the information requested, such as a password for the keystore and your organization's domain name (example: example.com). The key is valid for 25 years.
To sign an app, use this command:
jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore .keystore .apk my-release-key my_applicationalias_name
You can now wrap Android apps. For details, see .
Other Requirements for Wrapping Worx Apps for Windows Phone 8.1 / 10
Windows Phone 10 is currently supported for XenMobile 10 and 10.3.x only. It is not supported for XenMobile 10.1. For XenMobile 9, you must install a patch for apps to work properly. You can download the patch at
.page
Windows Store requirements:An open Microsoft Windows Store Developer Account (Corporate account type). For details, see
.types, locations, and fees
Signing Your Applications
wrap Android apps
XenMobile downloads page
Account types, locations, and fees
citrix.com 22
This account provides a Publisher ID and a Symantec enterprise certificate.
Publisher ID (PHONEPUBLISHERID) from the Windows Store developer account profile. For details, see .
Enterprise from Symantec. The certificate is required to sign Windows mobile apps. For details, certificatesee .Application Enrollment Token (AET). For details, see
.Windows Phone
When you use the MDX Toolkit to re-sign an app, the Toolkit uses the Symantec certificate to generate an Application Enrollment Token (AET) file, which the Toolkit includes the MDX file.in
The AET file is also needed when creating an Enterprise Hub device policy for Windows Phone 8.1. For more information, see .
Managing your profile
Company app distribution for Windows PhoneHow to generate an application enrollment token for
Windows Phone
To add an Enterprise Hub device policy for Windows Phone 8.1
citrix.com 23
XenMobile Compatibility
For a summary of the versions of XenMobile components that you can integrate, including the version of the MDX Toolkit needed to wrap, configure, and distribute Worx Mobile Apps, see .
For more information, see .
XenMobile Compatibility
Supported Device Platforms in XenMobile
citrix.com 24
1. 2. 3. 4.
5.
6.
a. b.
c.
d.
Installing the MDX Toolkit
Follow these procedures to install the MDX Toolkit and Worx App SDK for iOS and Android, and the MDX Toolkit for Windows Phone 8.1.
Installing the MDX Toolkit and Worx App SDK for iOS and Android
Perform the following steps from a computer running Mac OS X. The installer includes the following tools:
Mac OS tools that wrap both iOS and Android apps.A Java command-line tool that wraps Android apps. You can also run this tool on a Windows computer.
Note
It is recommended to remove the previous version of the MDX toolkit before installing the new version. Remember to backup Android_settings.txt before uninstalling the toolkit.
Log on to the page.Expand .Worx Apps and MDX ToolkitLocate the MDX Toolkit version you want to install and click its link to begin the download.Open MDXToolkit.mpkg with the Mac OS Finder tool on Mac OS X 10.9.4 or later and Xcode 5.1 or later. For version requirements, see .
The installation path is Applications/Citrix/MDXToolkit.
If you want to run the Java command-line tool on a Windows computer, copy ManagedApp.jar and ManagedAppUtility.jar to a directory on a Windows computer that meets the Android wrapping prerequisites. For details, see
.System RequirementsTo use the GUI tool to wrap Android apps, you must update path information in the android_settings.txt file that is installed in Applications/Citrix/MDXToolkit. If you do not complete these steps, the GUI tool will indicate that the prerequisites can not be located.Important: When wrapping Android apps, the MDX Toolkit might fail unless the locale of the computer on which you run the MDX Toolkit is English.
Copy android_settings.txt to a folder that you can write to.To edit android_settings.txt, you can use the following command line. Enter your user password when prompted. The file opens in your terminal window.
vim /Applications/Citrix/MDXToolkit/android_settings.txtsudo
Update the file with the path to the JDK and the Android SDK binaries in your environment.
Add the following to the end of the “PATH =― line in your settings.txt file (separated by “:― on Mac/Unix, and “;― on Windows):
PATH = /bin:/usr/bin:/usr/sbin/sbin:/Documents/Android SDK/adt-bundle-mac-x86_64-20130729/sdk:/Documents/Android SDK/adt-bundle-mac-x86_64-20130729/sdk/tools:Documents/Android SDK/adt-bundle-mac-x86_64-20130729/sdk/platform-tools:Documents/Android SDK/apktools
Save the updated file to the same name, android_settings.txt, and then copy the file to Applications/Citrix/MDXToolkit.
You might be prompted to enter a password to copy to that folder.
XenMobile downloads
System Requirements
MDX Toolkit System Requirements
citrix.com 25
1. 2. 3. 4.
The installation package includes a small utility for removing the MDX Toolkit. The utility is installed in the following location on your computer: /Applications/Citrix/CGAppPrepTool/Uninstaller.app/Contents. Double-click the utility to start the uninstaller app and then follow the prompts. When you remove the tool, you receive a message prompting you for your and password.user name
Important: If you use XenMobile 9, you must install a XenMobile Device Manager patch before wrapping Android apps. To download the patch, go to , navigate to Legacy Software > Product Software >
, and then download XenMobile Device Manager 9.0 Patch.Patches
Installing the MDX Toolkit for Windows Phone 8.1
Perform the following steps from a computer running Windows 8.1.
Log on to the page.Expand .Worx Apps and MDX ToolkitLocate the MDX Toolkit version you want to install and click its link to begin the download.Extract the files and then start the installer, CGAppPrepTool.
The installation path is Applications/Citrix/MDXToolkit.
The installation package includes a small utility for removing the MDX Toolkit. The utility is installed in the following location on your computer: /Applications/Citrix/CGAppPrepTool/Uninstaller.app/Contents. Double-click the utility to start the uninstaller app and then follow the prompts. When you remove the tool, you receive a message prompting you for your user name and password.
http://www.citrix.com/downloads/xenmobile
XenMobile downloads
citrix.com 26
Wrapping iOS Mobile Apps
This article describes how XenMobile administrators wrap enterprise apps and how developers wrap ISV apps. To wrap iOS mobile apps, use the MDX Toolkit, which includes a Mac OS graphical interface tool and a Mac OS command-line tool. The Mac OS command-line tool has customization options, can be referenced from scripts that automate the app wrapping process, and lets you some MDX policies.preset
The file type for a wrapped app is .mdx. You upload the .mdx file to the XenMobile console where you configure specific app details and policy settings that the Worx Store enforces. When users sign on, the app appears in the store. Users can then subscribe, download, and install the app on their device.
The following figure provides an overview of the app wrapping steps, from installation of the MDX Toolkit through testing Worx apps. Related topics are listed under the diagram.
For details, see:
MDX Toolkit System RequirementsOther Requirements for Wrapping iOS Mobile AppsXenMobile CompatibilityInstalling the MDX Toolkit
For details, see:
Creating Provisioning ProfilesApp UpgradesPolicies and Worx AppsEnterprise App Wrapping Using the Graphical InterfaceEnterprise iOS App Wrapping Using the Command LineISV iOS App Wrapping Using the Command LineCommand OptionsPresetting MDX Policies for iOS AppsIdentifying iOS App Wrapping ErrorsCollecting System Logs on iOS DevicesTo add an MDX app to XenMobile
MDX Toolkit System RequirementsOther Requirements for Wrapping iOS Mobile AppsXenMobile CompatibilityInstalling the MDX Toolkit
Creating Provisioning ProfilesApp UpgradesPolicies and Worx AppsEnterprise App Wrapping Using the Graphical InterfaceEnterprise iOS App Wrapping Using the Command LineISV iOS App Wrapping Using the Command LineCommand OptionsPresetting MDX Policies for iOS AppsIdentifying iOS App Wrapping ErrorsCollecting System Logs on iOS DevicesTo add an MDX app to XenMobile
citrix.com 27
1.
2.
3.
4.
Important: Make sure that your user devices are updated with a version of Worx Home that is compatible with the version of MDX Toolkit used to wrap apps. Otherwise, users will see an error message about the incompatibility. For details, see
.
Creating Provisioning Profiles
Any app that runs on a physical iOS device (other than apps in the Apple App Store) must be signed with a provisioning profile and a corresponding distribution certificate. There are two kinds of developer programs for distribution: The iOS Developer Program (Ad-Hoc) and the iOS Developer Enterprise Program. To wrap apps, Citrix recommends using the Enterprise program. You can enroll in the program from the .
The Enterprise profile allows you to run an app on unlimited devices. The Ad Hoc profile allows you to run an app on up to about 100 devices.
Apple no longer supports the use of wildcard App IDs for new Enterprise accounts. If your Enterprise account does not support wildcard App IDs, you must create multiple explicit App IDs and provisioning profiles, as follows.
Verify that you have a valid iOS distribution certificate.
Be aware that an existing iOS Developer for Enterprise certificate and provisioning profile might not be compatible with iOS 8 or iOS 9. For details, see .
From the Apple Enterprise Developer portal, create an explicit App ID for each app you plan to wrap with the MDX Toolkit. An example of an acceptable App ID is: com. . .CompanyName ProductName
From the Apple Enterprise Developer portal, go to and create an in-house Provisioning Profiles > Distributionprovisioning profile. Repeat this step for each App ID created in the previous step.
Download all provisioning profiles.
If your Apple Enterprise account supports wildcard App IDs, you can continue to use a wildcard provisioning profile to wrap apps. However, if you will use the Apple Push Notification service (APNs) for notifications when WorxMail is in the background, you must use an explicit provisioning profile and App ID.
Any device on which you want to install the MDX app needs to have the provisioning profile on the device. You can distribute the profile to user devices by using an email attachment. Users can add the profile on their iOS device by clicking the attachment.
For details about provisioning profiles and distribution certificates, see in the Apple App Distribution Guide.
App Upgrades
Important: Before you upgrade apps, be aware how changes to App IDs or the use of a partial wildcard App ID provisioning profile impact app upgrades.
Previously wrapped apps upgrade in place unless the App ID has changed. For example, if you change a bundle ID from com.citrix.mail to com.example.mail, there is no upgrade path. The user must reinstall the app.
A device considers the app as a new app. The new and prior versions of the app can both reside on the device.
If you use a partial provisioning profile, such as com.xxxx, to wrap an app with a bundle ID that includes com.citrix, Citrix recommends that you remove the installed MDX-wrapped apps and install the apps wrapped with the latest MDX Toolkit. As a result of a bundle ID change from com.citrix.mail to com. , users examplewill need to reinstall the app.An in-place upgrade succeeds if an app was wrapped with a full wildcard App ID and the new version of the app has an App ID that matches the installed app.
Policies and Worx Apps
Citrix provides a generic set of default policies that apply to all Worx apps and a set of specific policies for some of the Worx apps. Policy file names are based on the bundle ID. By default, the policy file name for a Worx app is in the form com.citrix. _policy_metadata.xml, where app is a name such as "mail".app
If you have an Apple Enterprise account that does not support wildcard App IDs, you must change the company identifier in the bundle ID when you wrap a Worx app. For example, the bundle ID for WorxMail is com.citrix.mail. You must replace "citrix" in that identifier with your company identifier. If your company identifier is "example", the bundle ID is com.example.mail. When you wrap that app, the policy file name is com.example.mail_policy_metadata.xml.
XenMobile Compatibility
Apple web site
Wrapping Worx Apps for iOS 8 or iOS 9
Maintaining Identifiers, Devices, and Profiles
citrix.com 28
1.
2. 3.
1.
2.
3.
To determine which policy file to apply to an app, the MDX Toolkit looks for files in the following order and uses the first file it finds:
A file name that matches your bundle ID, such as com.example.mail_policy_metadata.xml, as described in the preceding example.A file name that matches the original bundle ID, such as com.citrix.mail_policy_metadata.xml.A file name that matches the generic default policy file, policy_metadata.xml.
You can create your own set of policy defaults for a specific Worx app by modifying the files that match your bundle ID or the original bundle ID.
Enterprise App Wrapping Using the Graphical Interface
The following steps describe the general process for wrapping an enterprise app that you will deploy from XenMobile. The general process for ISV app wrapping is described in .
Important: Both the private key and the certificate must be installed on the Keychain Access of your Mac before using the graphical interface to wrap iOS apps. If the associated distribution certificate does not have the private key installed into Keychain Access, the graphical interface does not pre-populate the list. For details, see "Repairing iOS Distribution CertificateYour Keychain when the Toolkit Can't Find a Distribution Certificate," later in this article.
Before you use the toolkit to wrap apps, be sure to back up the original version of those apps so you can return to them if needed.Start the MDX Toolkit from your iOS Applications folder, select , and then click .For IT administrators Next
Click , select the file, and then click .Browse Next
ISV App Wrapping Using the Graphical Interface
citrix.com 29
3.
4.
5.
6.
7.
The Verify App Details screen shows information obtained from the app.
As needed, change the pre-filled information. Optionally, specify a minimum and maximum OS version and list the device types on which the app is not allowed to run. You can also change the app details after uploading the app to XenMobile.
In the Create Citrix Mobile App screen, click , select the provisioning profile, and select a distribution certificate.Browse
If the iOS Certificate list is empty, you might need to repair the keychain on the machine where you are running the MDX Toolkit. For details, see "Repairing Your Keychain when the Toolkit Can't Find a Distribution Certificate," later in this article.
If you selected a provisioning profile that has an explicit app ID, the tool prompts you to confirm the app ID.
For example, the bundle ID for a Worx app is com.citrix. . The provisioning profile that you use must ProductNameinclude your company identifier instead of "citrix".
After you click , click .Yes Create
If you selected a provisioning profile that has a wildcard app ID, the tool shows a list of available app IDs. If the app ID you want to use isn't listed, choose a different provisioning profile. After you choose an app ID, click .Create
citrix.com 30
7.
8.
The toolkit lets you know when the MDX package is created. To wrap another app, click .Start Over
The toolkit appends _iOS to the end of the filename of a wrapped iOS app.
Enterprise iOS App Wrapping Using the Command Line
Note: Be sure to obtain third-party apps directly from the app vendor. iOS apps downloaded from the Apple store are encrypted and cannot be wrapped.
Before you use the toolkit to wrap apps, be sure to back up the original version of those apps so you can return to them if needed.
The following example shows a basic app wrapping command using default settings. Modify the bold information for your specific system. The trailing backslash signifies the command continues to the next line. Remove these symbols before running the command.
To perform these commands, navigate to the directory on your command /Applications/Citrix/MDXToolkit/line.
A basic iOS wrapping command line is as follows.
./CGAppCLPrepTool \ Wrap \ –Cert \ CERTIFICATE–Profile \ PROFILE-bundleID \ ID
citrix.com 31
–in \ INPUT_FILE–out OUTPUT_FILE
The following is an example of this command-line option.
./CGAppCLPrepTool \ Wrap \ –Cert “iPhone Developer: Joe Admin (12MMA4ASQB)― \ –Profile “team_profile.mobileprovision― \ -bundleID “com.CompanyABC.Sample― \ –in “~/Desktop/SampleApps/Sample.ipa― \ –out “~/Desktop/SampleApps/Sample.mdx―
Examples of options you may add to the preceding command include:
-appName “Wrapped Sample app―
-appDesc “This is my newly wrapped iOS application.―
Both of those options default to the value read from the app, if possible.
For details about the options, see . For inline documentation, use the option.-help
ISV iOS App Wrapping Using the Command Line
Before you use the toolkit to wrap apps, be sure to back up the original version of those apps so you can return to them if needed. To generate wrapped ISV applications for iOS, start with the following basic wrapping command.
./CGAppCLPrepTool \ –Cert \ CERTIFICATE–Profile \ PROFILE–in \ INPUT_FILE–out OUTPUT_FILE
If you have an Apple Enterprise account that does not support wildcard App IDs, also include the option.–bundleID
Add one of the following options for a Premium app, in which some Citrix policies are enforced even for unmanaged users, or a General app, which contains no Citrix policy enforcement for an unmanaged user:
Premium: -sdk “yes― –appMode “1―General: -sdk “yes― –appMode “2―
If you plan to upload the wrapped IPA file to the Apple App Store or a web server and the URL is known at the time of wrapping, also add the following option.
-storeURL “https://itunes.apple.com/us/app/worx-home-by-citrix/id434682528?mt=8―
If you do not know the URL at the time of wrapping, you can modify the .mdx file later with the following command.
./CGAppCLPrepTool \ setinfo \ -in "~/Desktop/ / .mdx" \ SampleApps Sample-out “~/Desktop/ / .mdx" \ -storeURL "https://itunes.apple.com/us/app/w1browser/id579414750?ls=1&mt=8"SampleApps wrapped/Sample
Examples of options you may add to the preceding command include:
-appName “Wrapped Sample app―
-appDesc “This is my newly wrapped iOS application.―
If you customized the policy file, be sure to point to your modified file:
-policyxml /Applications/Citrix/MDXToolkit/data/policy_metadata.xml
For details about the options, see . For inline documentation, use the option.-help
Command Options
Command Options
Command Options
citrix.com 32
commandwrap
Option Description
-Help Displays Help for this command.
-In Required. Path and file name of the app you are wrapping.
-Out Optional. Path and file name for the resulting .mdx file. If this option is omitted, the file has the same path and file name as the input file and has an .mdx extension.
-Cert Required. Name of the certificate to use to sign the app.
-Profile Required. Name of the provisioning profile to use to sign the app.
-bundleID Required for Enterprise accounts that do not support wildcard App IDs. This is your Apple bundle ID. The MDX Toolkit verifies whether the bundle ID and provisioning profile are compatible.
-Upgrade This option is intended for legacy apps and will be deprecated. Used for in-place upgrades when you use a partial wildcard provisioning profile. This option ensures that the new binary is signed with the same entitlement as the prior version. If the entitlements do not match, then attempts by users to install the upgrade from Worx Home will fail.
-AppName Optional. App name, obtained from the app if possible.
-AppDesc Optional. App description, obtained from the app if possible.
-MinPlatform Optional. Minimum supported platform version. Defaults to blank.
-MaxPlatform Optional. Maximum supported platform version. Defaults to blank.
-ExcludedDevices
Optional. List of device types on which the app is not allowed to run. Defaults to blank.
-PolicyXML Optional. Replacement XML policy definition file and path. Defaults to the built-in policy definitions.
Example: -policyxml /Applications/Citrix/MDXToolkit/data/policy_metadata.xml
For details, see "Presetting MDX Policies for iOS Apps," next.
-LogFile Optional. Name of the log file.
-LogWriteLevel Optional. Log level, through .1 4
-LogDisplayLevel Optional. Log level for standard output, through .0 4
commandsign
Option Description
-Help Displays Help for this command.
-In Required. Path and file name of the app you are wrapping.
-Out Optional. Path and file name for the resulting .mdx file. If this option is omitted, the file has the same path and file name as the input file and has an .mdx extension.
-Cert Required. Name of the certificate to use to sign the app.
-Profile Required. Name of the provisioning profile to use to sign the app.
commandsetinfo
Option Description
-Help Displays Help for this command.
-In Required. Path and file name of the app to be modified.
-Out For setinfo, the output path or file name must differ from the original.
-AppDesc Optional. App description. Remains unchanged if not specified.
-MinPlatform Optional. Minimum supported SDK level. Remains unchanged if not specified.
-MaxPlatform Optional. Maximum supported SDK level. Remains unchanged if not specified.
- Optional. List of device types on which the app is not allowed to run. Remains unchanged if not
citrix.com 33
1.
2.
1. 2.
3.
ExcludedDevices specified.
-StoreURL Optional. URL of the app in the app store. Remains unchanged if not specified.
-PolicyXML Optional. Replacement XML policy definition file and path. Defaults to the built-in policy definitions.
Example: -policyxml /Applications/Citrix/MDXToolkit/data/policy_metadata.xml
For details, see "Presetting MDX Policies for iOS Apps," next.
Presetting MDX Policies for iOS Apps
For apps that you wrap with the MDX Toolkit command-line tool, you can preset some MDX policies. You can also configure policies in the XenMobile console when you add the apps.
Update policy values in the policy XML file.
The MDX Toolkit installer creates this policy file: Applications/Citrix/MDXToolkit/data/policy_metadata.xml
Note: Be aware that the policies files for iOS and Android differ. To preset policies for both of those platforms, you must update their respective policy XML files.When you wrap the app with the command line, include -policyxml
./Applications/Citrix/MDXToolkit/data/policy_metadata.xml
Identifying iOS App Wrapping Errors
If you encounter an error when wrapping an iOS app, you can use the MDX Toolkit logs to identify the error. You must have administrator rights to view the MDX Toolkit logs.
When you run the MDX Toolkit, the tool saves a log file to the following location: > > > Applications Citrix MDXToolkit. By default, the tool saves warnings and errors in the log. > Logs Citrix.log
If an error occurs for an iOS app, a command line with arguments appears at the end of the log. You can copy the command line and run it in . To do that, in , click , and use the Mac command-Terminal Applications > Utilities Terminalline interface to evaluate the command. You may need to refer to the app requirements to evaluate the error.
When you use the command-line tool to run the wrapping process, you can specify the log file location, log display level, and log write level in the command line. You can also specify verbose logging level and a different log file in the command line.
Selecting the Correct Provisioning Profile
When you wrap a mobile iOS app, you might receive a warning indicating that the app was wrapped successfully, but may contain errors. Errors can occur if the provisioning profile you chose differs from the provisioning profile the app originally used.
The MDX Toolkit can alert you about certain provisioning profile issues. For example, your app may require one or more of the following functions:
iCloud app that enables the use of iCloud data storage for your iOS appPush notification that uses the Apple push notification service to deliver messages to the iOS deviceSpecial keychain-access-groups entitlement to access the keychain item for another app
The logs show the missing key and value pairs for the app. For each key and value pair, you can decide whether you want to fix the error. If you do not fix the error, the app may not function correctly. Also, depending on the key and value pair, you need to check if you can fix your provisioning profile. Occasionally, you might not be able to fix the provisioning profile and can release the app with the defect.
For details about provisioning profiles, see the Web site.
Repairing Your Keychain when the Toolkit Can't Find a Distribution Certificate
If the MDX Toolkit does not recognize your iOS Distribution Certificate, there might be an issue between your iCloud Keychain and the keychain on the computer running the MDX Toolkit. To repair your local keychain, follow these steps.
On your Mac, in , tap .System Preferences iCloudClear the check box.Keychain
This removes your locally synchronized keychain from iCloud.
Apple Developer
citrix.com 34
3. 4.
5. 6. 7. 8. 9.
10.
1.
2. 3. 4. 5. 6. 7.
1.
2. 3.
Open , which is in the Utilities folder within the Applications folder.Keychain AccessDelete the iOS Developer Certificate used to sign your wrapped apps. This is typically the "iPhone Distribution: Company Name" certificate with an associated private key.From the menu, choose .Keychain Access Keychain First AidIn the Keychain First Aid dialog box, tap and then .Repair StartAfter the repair completes, tap and then .Verify StartIf the repair is successful, import your iOS Distribution Certificate again into the Keychain Access app.Start the MDX Toolkit. The and fields should contain iOS Distribution Provisioning Profile iOS Distribution Certificateyour information.As needed, resync you keychain to iCloud: In , tap and then select the check box.System Preferences iCloud Keychain
Collecting System Logs on iOS Devices
You an collect system logs on iOS devices either by using iPhone Configuration Utility tool or Xcode. You can then email the files to Citrix support for help troubleshoot issues with apps.
To use a Configuration Utility tool to collect system logs on iOS devices
Download and install the Apple Configurator (previously the iPhone Configuration Utility) tool from . You can use the tool on both the iPhone and IPad.Ensure that your device meets the system requirements and supported languages.Run the installer and follow the prompts to complete the wizard.Open the Configurator tool.Under , click your device.DevicesClick and then click to clear existing logs.Console ClearReproduce the issue, click and then attach and email the logs to support.Save Console As
To use Xcode to collect logs on iOS devices
Download Xcode from the Apple store to your Mac OS X computer.
Connect your iOS device to your computer and then open Xcode. Click and then click . Window Organizer
Apple
citrix.com 35
3.
4.
5.
6. 7. 8.
In the window, click . Organizer Devices
Under , click to view the console logs. iPad ConsoleNote: The pane in the Organizer contains information about app failures. You might have to unplug your Device Logsdevice and plug it again to refresh the list.Click to clear existing logs.ClearReproduce the issue.Click to save the log and then email the attachment to support. Save Log As
citrix.com 36
Deploying iOS Devices Through Apple DEP
You must enroll in the Apple Deployment Program to take advantage of the Apple Device Enrollment Program (DEP) for IOS device enrollment and management in XenMobile. For information about signing up for an Apple Deployment Program account, see this from Apple.
Important
The Apple Deployment Program is available for organizations and not individuals. A considerable amount of corporate details and information need to be provided to create an Apple Deployment Program account, which means it could take some time to request and receive approval for accounts.
Enrolling in the Apple Deployment ProgramWhen applying for an Apple Deployment Program account, the best practice is to use an email address that is tied to the organization, such as [email protected].
1. After you enter your organization information, you should receive a temporary password for the new Apple ID through email.
citrix.com 37
2. You then sign in with the Apple ID and complete the security settings for the account.
3. Configure and enable two-step verification, which is required for use with the DEP Portal. During these steps, you add a phone number where you will receive the 4-digit PIN for the two-step verification.
4. Log in to the DEP Portal to complete the account configuration using the two-step verification that you just set up.
citrix.com 38
5. Add your company details and then select from where you purchase devices. For details on purchasing options, see the next section, .
6. Add the Apple Customer Number or the DEP Reseller ID and then verify your enrollment details and wait for Apple to approve your account.
Ordering DEP-enabled devices
citrix.com 39
7. After you receive your logon credentials from Apple, log into the Apple DEP Portal. Then, follow the steps in the next section to connect your account with XenMobile.
Integrating your Apple DEP account with XenMobileFollow the steps in this section to connect your Apple DEP account with your XenMobile server deployment.
1. On the left-hand side of the Apple DEP Portal, click .Device Enrollment Program
2. Click and then on the right-hand side, click . Manage Servers Add MDM Server
citrix.com 40
3. In , enter a name for your XenMobile server and then click . Add MDM Server Next
4. Upload a public key from your XenMobile server. To generate the key from XenMobile, do the following:
a. Log on to the XenMobile console, click the gear icon in the upper-right corner. The page appears.Settings
b. Under , click .More iOS Bulk Enrollment
b. On the page, expand and then click . The iOS Bulk Enrollment DEP Configuration Export Public Keypublic key is downloaded.
citrix.com 41
5. On the Apple DEP Portal, click , select the public key you just downloaded and then click . Choose file Next
6. Click to generate a server token, which is downloaded from the browser, and then click .Your Server Token Done
7. On the XenMobile console page, next to , click iOS Bulk Enrollment Allow Device Enrollment Program (DEP)YES, click and then upload the token file you downloaded in the preceding step. Import Token File
citrix.com 42
Your Apple DEP token information appears in the XenMobile console after you import the token file.
8. Click to verify the Apple DEP connection with XenMobile.Test Connection
9. On the page, complete the additional settings, select the Apple DEP controls and policies you iOS Bulk Enrollmentwant to implement for your Apple DEP devices and then click .Save
The XenMobile server appears in the Apple DEP Portal.
Ordering DEP-enabled devicesYou can order DEP-enabled devices directly from Apple or DEP-enabled authorized resellers or carriers. To order from Apple, you need to provide your Apple Customer ID within the Apple DEP Portal to enable Apple to associate your device purchased with your Apple DEP account.
To order from your reseller or carrier, contact your Apple reseller or carrier to check if they participate in the Apple DEP. Ask for the resellers' Apple DEP ID when purchasing devices. You will need this information to add your Apple DEP
citrix.com 43
reseller to your Apple DEP account. You will receive a DEP customer ID after adding the resellers' Apple DEP ID, when approved. Provide the DEP customer ID to the reseller, who will use the ID to submit information about your device purchases to Apple. For more information, see this .
Managing DEP-enabled devicesFollow these steps to associate devices with your XenMobile server within your Apple DEP account through the DEP Portal.
1. Log on to the Apple DEP Portal.
2. Click , click and then in , select the option for Device Enrollment Program Manage Devices Choose Devices Bywhich you want to upload and define your Apple DEP-enabled devices - , , or Serial Number Order Number Upload
.CSV File
3. Under , to assign your devices to a XenMobile server, click and then in the list, Choose Action Assign to Serverclick the name of your XenMobile server and then click .OK
Your Apple DEP devices are now associated with the selected XenMobile server.
Apple website
citrix.com 44
User experience enrolling an Apple DEP-enabled deviceWhen users enroll an Apple DEP-enabled device, their experience is as follows.
1. Users start their Apple DEP-enabled device.
2. Users the configuration wizard to configure the initial settings on their iOS device.
3. The device automatically starts the XenMobile device enrollment process. Users follow the wizard to enroll the device into the XenMobile server associated with the Apple DEP-enabled device.
The Apple DEP enrollment process starts automatically as part of the initial IOS configuration flow for Apple DEP enabled devices.
4. The Apple DEP configuration that you configured in the XenMobile console is delivered to the Apple DEP-enabled device. Users follow the wizard to configure the device.
citrix.com 45
5. Users may be prompted to sign into iTunes so that Worx Home can be downloaded.
6. Users open Worx Home and enter their credentials. If required by the policy, users may be prompted to create and verify a Worx PIN.
The remainder of the required apps are pushed down to the device.
citrix.com 46
1. 2. 3.
Wrapping Worx Apps for iOS 8 or iOS 9
To wrap Worx apps for iOS 8 or 9, your Apple iOS Developer for Enterprise certificate and provisioning profile must each contain the necessary attribute properties to work properly. The provisioning profile must include a Team Identifier (ID) and the Organizational Unit (OU) field also used in the Apple iOS Developer for Enterprise Certificate.
The procedures in this article help you verify your existing certificate and provisioning profile and, if needed, create the properly formatted Apple iOS Developer for Enterprise certificate and provisioning profile.
After you have completed that setup, wrap the apps as described in . To use the apps, users must install the most recent version of Citrix Worx Home from the Apple iTunes App Store.
Note: The certificate and provisioning profile requirement does not apply to third-party SDK apps, such as apps found in the Worx App Gallery.
Quick links to sections in this article
To generate a new enterprise certificate for iOS 8 or 9To create a new provisioning profile for iOS 8 or 9To validate an existing iOS Developer for Enterprise certificate and provisioning profile for iOS 8 or 9
To generate a new enterprise certificate for iOS 8 or 9
If you have an older certificate and want to see if it's supported, see .certificate and provisioning profile for iOS 8 or 9
Log on to the Apple iOS Provisioning Portal using the agent role.Go to . > > iOS Dev Center Certificates, Identifiers & Profiles CertificatesIn the section, click the tab and then click the Plus Sign (+), as shown in the following figure.Certificates Production
Wrapping iOS Mobile Apps
To generate a new enterprise certificate for iOS 8 or 9To create a new provisioning profile for iOS 8 or 9To validate an existing iOS Developer for Enterprise certificate and provisioning profile for iOS 8 or 9
To validate an existing iOS Developer for Enterprise certificate and provisioning profile for iOS 8 or 9
citrix.com 47
3.
4. 5.
6.
In the section, click the tab and then click the Plus Sign (+).Certificates ProductionSelect the type as , as shown in the following figure.App Store and Ad Hoc
citrix.com 48
6.
7.
8.
Generate a Certificate Signing Request (CSR), as shown in the following figure.
Use the Certificate Assistant wizard available in the Keychain Access application on Mac OS X, as shown in the following figure.Important: Before starting the wizard, select the private key you want to use, or else you will generate a new public/private key pair.
Upload the CSR to the iOS Provisioning Portal, as shown in the following figure.
citrix.com 49
8.
9. 10. 11.
a. b. c.
1. 2.
Download the distribution certificate.Save the certificate on the disk and then open the certificate using Key Chain Access.To export the certificate to a different computer, such as a production computer, export the certificate in .p12 format, as follows:
In , go to the section.Key Chain Access My CertificatesRight-click the downloaded certificate and then click .ExportSave the certificate in .p12 format and then provide a secure password while saving.
To create a new provisioning profile for iOS 8 or 9
Log on to the iOS Provisioning Portal using the Team Agent role.Go to , as shown in the > , > > iOS Dev Center Certificates Identifiers & Profiles Provisioning Profiles Distributionfollowing figure.
citrix.com 50
2.
3. 4.
On the page, click the Plus Sign (+).Create iOS Provisioning ProfileUnder , select and then press , as shown in the following figure.Distribution Ad Hoc Continue
citrix.com 51
4.
5.
6.
Select an appropriate , as shown in the following figure.App IDImportant: Apple no longer supports the use of wildcard App IDs for new Enterprise accounts. If your Enterprise account does not support wildcard App IDs, you must create a multiple explicit App IDs and provisioning profiles. If you will use the Apple Push Notification service (APNs) for notifications when WorxMail is in the background, you must use an explicit provisioning profile and App ID.
citrix.com 52
6.
1.
2.
3. 4. 5.
Select one or more certificates to include in the profile, which are generally the certificate or certificates you created earlier, as shown in the following figure.
To validate an existing iOS Developer for Enterprise certificate and provisioning profile for iOS 8 or 9
The following steps describe how to review the contents of your Apple iOS Developer for Enterprise certificate and provisioning profile to make sure they meet these requirements:
The certificate and provisioning profile must contain the OU and the Team ID attribute properties required by Apple iOS 8 or 9.A valid iOS Developer certificate with a private key must be installed in the Keychain Access utility of the wrapping Mac OS X workstation. An iOS provisioning profile must reference that certificate.Apple no longer supports the use of wildcard App IDs for new Enterprise accounts. If your Enterprise account does not support wildcard App IDs, you must create a multiple explicit App IDs and provisioning profiles. For details, see .
If your current certificate and provisioning profiles do not contain the OU field and Team ID, you must create a new certificate and provisioning profile. See the second procedure in this article for steps. Before adding the new Apple iOS Developer for Enterprise certificate, make sure you remove the old certificate and the old provisioning profile from the Keychain Access utility of the wrapping Mac OS X workstation.
Apple limits customers to two enterprise certificates per account. Therefore, to generate a new certificate, you must revoke an existing certificate. The result is that apps associated with that certificate stop working.
Copy and rename the existing wrapped MDX app extension from .mdx to .zip and then extract the contents to a folder. For example: /User/Username/Documents/MyMDXapp.mdx becomes /User/Username/Documents/MyMDXapp.zip and is extracted to the folder path /User/Username/Documents/MyMDXapp.Rename the iOS app extension from .ipa to .zip and then extract the contents to the default folder, Payload. For example: /User/Username/Documents/MyMDXapp/MyiOSapp.ipa becomes /User/Username/Documents/MyMDXapp/MyiOSapp.zip and is extracted to the folder path /User/Username/Documents/MyMDXapp/Payload.Open the Mac OS X Terminal app.In the Terminal session, change the directory to the Payload folder containing the iOS app contents.Run the codesign utility as follows:
codesign --display --verbose=4 <AppName>.app
Creating Provisioning Profiles
citrix.com 53
5.
6.
7.
codesign --display --verbose=4 <AppName>.app/CitrixDylib.bundle/CitrixDylib
The resulting output for either query should have the line of syntax indicating the presence of the Team ID codesignproperty. For example: MyMacintosh:Payload Username$ codesign -display --verbose=4 MyApp.app The output is:
Executable=/User/Username/Documents/MyMDXapp/Payload/MyiOSapp.app/MyApp Identifier=com.acmecompany.myapp Format=bundle with Mach-O universal (armv7 armv7s) CodeDirectory v=20100 size=39284 flags=0x0(none) hashes=1956+5 location=embedded Hash type=sha1 size=20 CDHash=0ef4056z3789k0w6as2469ac360g000f123a1bc2 Signature size=4296 Authority=iPhone Distribution: ACME Company, Inc. Authority=Apple Worldwide Developer Relations Certification Authority Authority=Apple Root CA Signed Time=Aug 30, 2014, 7:00:00 AM Info.plist entries=34 TeamIdentifier=01234ABCDEF Sealed Resources version=2 rules=4 files=500 Internal requirements count=2 size=1076
Make sure your Apple iOS Developer for Enterprise certificate contains the OU field as shown under in Subject Namethe following figure.
citrix.com 54
Wrapping Android Mobile Apps
This article describes how XenMobile administrators wrap enterprise apps and how developers wrap ISV apps. To wrap Android mobile apps, use the MDX Toolkit, which includes a Mac OS graphical interface tool and a Java command-line tool. The command-line tool has customization options, can be referenced from scripts that automate the app wrapping process, and lets you some MDX policies.preset
The file type for a wrapped app is .mdx. You upload the .mdx file to the XenMobile console where you then configure specific app details and policy settings that the Worx Store enforces. When users sign on, the app appears in the Worx Store. Users can then subscribe, download, and install the app on their device.
The following figure provides an overview of the app wrapping steps, from installation of the MDX Toolkit through testing Worx apps. Related topics are listed under the diagram.
For details, see:
MDX Toolkit System RequirementsOther Requirements for Wrapping Android Mobile AppsXenMobile CompatibilityInstalling the MDX Toolkit
For details, see:
Enterprise Android App Wrapping by Using the Command LineISV Android App Wrapping by Using the Command LineCommand OptionsPresetting MDX Policies for Android AppsIdentifying Android App Wrapping ErrorsCollecting App Logs from the Command LineTo add an MDX app to XenMobile
Important: Make sure that your user devices are updated with a version of Worx Home that is compatible with the version of MDX Toolkit used to wrap apps. Otherwise, users receive an error message about the incompatibility. For details, see
.
If you use XenMobile 9, you must install a XenMobile Device Manager patch before wrapping Android apps. To download the patch, go to , navigate to Legacy Software > Product Software
, and then download XenMobile Device Manager 9.0 Patch.> Patches
ISV App Wrapping Using the Graphical Interface
MDX Toolkit System RequirementsOther Requirements for Wrapping Android Mobile AppsXenMobile CompatibilityInstalling the MDX Toolkit
Enterprise Android App Wrapping by Using the Command LineISV Android App Wrapping by Using the Command LineCommand OptionsPresetting MDX Policies for Android AppsIdentifying Android App Wrapping ErrorsCollecting App Logs from the Command LineTo add an MDX app to XenMobile
XenMobile Compatibility
http://www.citrix.com/downloads/xenmobile
citrix.com 55
1.
2.
3. 4.
5. 6.
The following steps describe the general process for wrapping an ISV app that you will deploy from the Google Play Store. The general process for enterprise app wrapping is described in
.Interface
Before you use the toolkit to wrap apps, be sure to back up the original version of those apps so you can return to them if needed.Start the MDX Toolkit from your iOS Applications folder, select , and then For Independent Software Vendors (ISVs)click .Next
In the Deploy from App Store screen, select your app and click .NextIn the User Settings screen, if you already have the app store URL, enter it. If you don't have the URL, enter a placeholder such as https://play.google.com/store/apps/details?id=com.zenprise. You can update the URL later.
For Premium apps, select . For General apps, select .MDX apps App Store apps
In the Verify App Details screen, update the details as needed.Browse to your and click .keystore Create
Enterprise App Wrapping Using the Graphical Interface
citrix.com 56
6.
7. Save your app.
When the GUI tool finishes wrapping an app, the app file name includes _andr.
Enterprise Android App Wrapping Using the Command Line
You can use enterprise app wrapping to wrap custom (in-house) apps and some third-party apps. You should acquire third-party apps directly from the app vendor. For enterprise app wrapping, begin with an Android application (.apk). Before you use the toolkit to wrap apps, be sure to back up the original version of those apps so you can return to them if needed.
The following example shows a basic app wrapping command using default settings. The app is signed with the provided keystore. A keystore is a file that contains certificates used to sign your Android app. If the keystore contains multiple private keys, you can specify the key alias. You create a keystore once and then use it to sign the apps that you wrap. If you do not use the same keystore to wrap the new version of an app you previously deployed, upgrades of that app will not work and your users will need to manually remove the old version before they can install the new one.
Modify the bold information for your specific system. The trailing backslash signifies that the command continues to the next line. Please remove these symbols before running the command.
Note: Because the directory is restricted, you may need to run the following command in super user /Applications/mode. To do this, add in front of the command. You will be prompted for your computer password when running from sudothis restricted directory.
java -jar /Applications/Citrix/MDXToolkit/ManagedAppUtility.jar \ wrap \ -in ~/Desktop/ / .apk \ SampleApps Sample-out ~/Desktop/ / .mdx \ SampleApps Sample
citrix.com 57
-keystore ~/Desktop/ .keystore \ MyCompany-storepass \ MyKeystorePassword-keyalias \ MyCompanyKeyAlias-keypass MyKeyAliasPassword
The following are examples of options you may add to the preceding command, after modifying the information in bold:
-appName “Wrapped Sample app―-appDesc “This is my newly wrapped Android application.―
In addition, if the release keystore is not available during development, use the following command to create a retail build of a mobile app that is signed with your key:
java -jar /Applications/Citrix/MDXToolkit/ManagedAppUtility.jar \ wrap \ -in ~/Desktop/ / .apk \ SampleApps Sample-out ~/Desktop/ / .mdx \ SampleApps Sample-keystore ~/Desktop/ .keystore \ MyCompany-storepass \ MyKeystorePassword-keyalias \ MyCompanyKeyAlias-keypass \ MyKeyAliasPassword-createCert
For details about the options, see . For inline documentation, use the option.-help
ISV Android App Wrapping Using the Command Line
Before you use the toolkit to wrap apps, be sure to back up the original version of those apps so you can return to them if needed. To generate wrapped ISV applications for Android, start with the following basic wrapping command.
java -jar /Applications/Citrix/MDXToolkit/ManagedAppUtility.jar \ wrap \ -in ~/Desktop/ / .apk \ SampleApps Sample-out ~/Desktop/ / .mdx \ SampleApps Sample-keystore ~/Desktop/ .keystore \ MyCompany-storepass \ MyKeystorePassword-keyalias \ MyCompanyKeyAlias-keypass \ MyKeyAliasPassword-createCert
To wrap an app as an ISV app, you must set the parameter as follows:–apptype
Premium. To wrap an app as a Premium app, in which some Citrix policies are enforced even for unmanaged users, add the following option: -apptype PremiumGeneral. To wrap an app as a General app, which contains no Citrix policy enforcement for an unmanaged user, add the following option: -apptype General
If you need to upload the wrapped .apk file to the Google Play Store or web server and the URL is known when wrapping, add the option. Make sure to also set the parameter.-storeURL apptype
-storeURL “https://play.google.com/store/apps/details?id=com.zenprise―
If you do not know the URL at the time of wrapping, you can modify the .mdx file later with the following command:
java -jar /Applications/Citrix/MDXToolkit/ManagedAppUtility.jar \ setinfo \ -in ~/Desktop/ / .mdx \ SampleApps Sample-out ~/Desktop/ / / .mdx \ SampleApps wrapped Sample-storeURL \ “https://play.google.com/store/apps/details?id=com.zenprise―
If you customized the policy file, be sure to point to your modified file:
-policyxml /Applications/Citrix/MDXToolkit/data/policy_metadata.xml
For details about the options, see . For inline documentation, use the option.-help
Command Options
Command Options
citrix.com 58
Command Options
commandwrap
Option Description
-Help Displays Help for this command.
-In Required. Path and file name of the app you are wrapping.
-Out Optional. Path and file name for the resulting .mdx file. If this option is omitted, the file has the same path and file name as the input file and has an .mdx extension.
-AppType Optional. Defaults to . To generate ISV apps, use either or .MDXOnly General Premium
-KeyStore Path to the keystore file. Required if signing the .apk file.
-StorePass Password for the keystore. Required if signing the .apk file.
-KeyAlias Name of the specific key in the keystore. Required if signing the .apk file.
-KeyPass Password for the specific key. Required if signing the .apk file.
-SigAlg Optional. Algorithm to use when signing.
-AppName Optional. Application name, obtained from the app if possible.
-AppDesc Optional. Application description, obtained from the app if possible.
-MinPlatform Optional. Minimum supported SDK level. Defaults to blank.
-MaxPlatform Optional. Maximum supported SDK level. Defaults to blank.
-ExcludedDevices
Optional. List of device types on which the app is not allowed to run. Defaults to blank.
-PolicyXML Optional. Replacement XML policy definition file and path. Defaults to the built-in policy definitions.
Example: -policyxml /Applications/Citrix/MDXToolkit/data/policy_metadata.xml
For details, see "Presetting MDX Policies for Android Apps," next.
-StoreURL For ISV apps, the URL of the app in the Google App Store. Defaults to blank.
commandsign
Option Description
-Help Displays Help for this command.
-In Required. Path and file name of the app you are wrapping.
-Out Optional. Path and file name for the resulting .mdx file. If this option is omitted, the file has the same path and file name as the input file and has an .mdx extension.
-KeyStore Required. Path to the keystore file.
-StorePass
Required. Password for the keystore.
-KeyAlias Required. Name of the specific key in the keystore.
-KeyPass Required. Password for the specific key.
-SigAlg Optional. Algorithm to use when signing.
commandsetinfo
Option Description
-Help Displays Help for this command.
-In Required. Path and file name of the app to be modified.
-Out For setinfo, the output path or file name must differ from the original.
-AppType Optional. Defaults to . To generate ISV apps, use either or .MDXOnly General Premium
citrix.com 59
1.
2.
1. 2. 3. 4.
-KeyStore Path to the keystore file. Required if signing the .apk file.
-StorePass Password for the keystore. Required if signing the .apk file.
-KeyAlias Name of the specific key in the keystore. Required if signing the .apk file.
-KeyPass Password for the specific key. Required if signing the .apk file.
-SigAlg Optional. Algorithm to use when signing.
-AppName Optional. Application name, obtained from the app if possible.
-AppDesc Optional. Application description, obtained from the app if possible.
-MinPlatform Optional. Minimum supported SDK level. Defaults to blank.
-MaxPlatform Optional. Maximum supported SDK level. Defaults to blank.
-ExcludedDevices
Optional. List of device types on which the app is not allowed to run. Defaults to blank.
-StoreURL For ISV apps, the URL of the app in the Google App Store. Defaults to blank.
-PolicyXML Optional. Replacement XML policy definition file and path. Defaults to the built-in policy definitions.
Example: -policyxml /Applications/Citrix/MDXToolkit/data/policy_metadata.xml
For details, see "Presetting MDX Policies for Android Apps," next.
Presetting MDX Policies for Android Apps
For apps that you wrap with the MDX Toolkit command-line tool, you can preset some MDX policies. You can also configure policies in the XenMobile console when you add the apps.
Update policy values in the policy XML file.
The MDX Toolkit installer creates this policy file: Applications/Citrix/MDXToolkit/data/policy_metadata.xml
Note: Be aware that the policies files for Android and iOS differ. To preset policies for both of those platforms, you must update their respective policy XML files.When you wrap the app with the command line, include -policyxml
./Applications/Citrix/MDXToolkit/data/policy_metadata.xml
Identifying Android App Wrapping Errors
If you encounter an error when wrapping an Android app, you can use the MDX Toolkit logs to identify the error. You must have administrator rights to view the MDX Toolkit logs.
When you run the MDX Toolkit, the tool saves a log file to the following location: Applications/CitrixMDXToolkit/Logs/Citrix.log. By default, the tool saves warnings and errors in the log.
Collecting App Logs from the Command Line
Install the from the Android Developer web site.Enter the following command to clear existing logs. "adb logcat -c"Reproduce the issue.Enter the following command to capture the logs in a file. adb logcat -d > Name_of_Log_File.txt
Android Debug Bridge
citrix.com 60
Wrapping WorxMail, WorxWeb, and Worx Home for Windows Phone
The MDX Toolkit for Windows Phone helps you prepare WorxMail, WorxWeb, and Worx Home for Windows Phone 10 and Windows Phone 8.1 publishing. The toolkit currently does not support wrapping other apps. You can, however, use the toolkit to re-sign third-party Windows Phone apps. Windows Phone 10/8.1 requires all apps to be signed by the same certificate to enable enrollment of deployed apps.
You must use the toolkit to re-sign and wrap Worx Home so that Windows Phone users can access the company application store published by XenMobile. Unlike Worx Home for Android or iOS, which you upload to app stores, you must add Worx Home for Windows Phone to XenMobile. XenMobile then deploys Worx Home to Windows Phone devices after users complete enrollment.
The command-line tool has customization options and can be referenced from scripts that automate the app wrapping process. This article describes how to use the command-line tool.
The file type for a wrapped app is .mdx. You upload the .mdx file to the XenMobile console where you configure specific app details and policy settings that the Worx Store enforces. When users sign on, the app appears in the store. Users can then subscribe, download, and install the app on their device.
The following figure provides an overview of the app wrapping steps, from installation of the MDX Toolkit through testing Worx apps. Related topics are listed under the diagram.
For details, see:
MDX Toolkit System RequirementsOther Requirements for Wrapping Worx Apps for Windows PhoneXenMobile CompatibilityInstalling the MDX Toolkit
For details, see:
Command-Line Options for CGAppPrepTool.exeCommand-Line SamplesIdentifying Windows Phone App Wrapping ErrorsTo add an MDX app to XenMobile
Important: Make sure that user devices are updated with a version of Worx Home that is compatible with the version of MDX Toolkit used to wrap apps. Otherwise, users will see an error message about the incompatibility. For details, see
.Compatibility
Command-Line Options for CGAppPrepTool.exe
MDX Toolkit System RequirementsOther Requirements for Wrapping Worx Apps for Windows PhoneXenMobile CompatibilityInstalling the MDX Toolkit
Command-Line Options for CGAppPrepTool.exeCommand-Line SamplesIdentifying Windows Phone App Wrapping ErrorsTo add an MDX app to XenMobile
XenMobile Compatibility
citrix.com 61
Run the MDX Toolkit for Windows Phone on a Windows 8.1 64-bit operating system. The Toolkit uses the Windows 8.1 SDK for Windows Phone 10.
Important
Before you use the toolkit to wrap apps, be sure to back up the original version of those apps so you can return to them if needed. Also, create a separate folder for the files you want to wrap. Make sure that the folder does not contain other files. The MDX Toolkit for Windows Phone clears the contents of the folder during the wrapping process.
The app package must have an .xap or .appx extension.
IN. Mandatory. Specifies the location of the app being signed.
Syntax: -in:[ ]path to application package
T. Required an app. When you create an MDX package, this command specifies the location of the to wrapMDX Template directory used during packaging. This directory contains a minimum of five application images, one manifest. file, and one policy_metadata. file.xml xml
Syntax: -T:[ ]MDX template directory
OUT. Optional. If you do not specify the command, the command specifies the name and location of T OUToutput for the .xap or .appx package. Alternatively, the value of can also specify the name and location. If INthe command is specified, the command specifies the name and location of the MDX package.T T
Syntax: -out:[ ]path to output
C. Optional. Specifies the name and location of the certificate that is used to sign the app package.Default: [no certificate]Syntax: -C:[ ]path to certificate
PASSWORD. Optional. Specifies the certificate password.Default: [no password]Syntax: -password:[ ]password
RESIGN. Optional. If this parameter is specified, the app package is re-signed.Default: falseSyntax: -resign
VERBOSE. Optional. Specifies whether the tool generates verbose diagnostic messages.Default: falseSyntax: -verbose
XAPSIGNTOOL. Optional. Signs .xap and .appx packages.Default: %ProgramFiles(x86)%\Microsoft SDKs\Windows Phone\v8.1\Tools\XapSignTool\XapSignTool.exe)Syntax: -xapSignTool:[ ]path to xapSignTool.exe
APPXPACKAGETOOL. Optional. Creates .appx packages.Default: %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86\makeappx.exe)Syntax: -appxPackageTool:[ ]path to makeappx.exe
MDMSERVERURL. Required for Worx Home only. Not applicable for other apps. Specifies the URL of the XenMobile server to embed in the manifest of the .xap or .appx package for Worx Home.
Syntax: -mdmServerURL:[url]PHONEPUBLISHERID. Required. Specifies the publisher ID of the wrapped apps (customer publisher ID).
Syntax: -phonePublisherId:[ ]aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
Command-Line Samples
The following samples show how the preceding command-line options may be used.
citrix.com 62
CGAppPrepTool.exe -in:"tests\unsigned\mytest.appx" -out:"tests\output\WorxWeb.mdx" -T:"Templates\WorxWeb" -C:"tests\Mytestcert.pfx" -verbose -resign -password:mypw
Re-signs the package file with the signing certificate (the signing mytest.appx Mytestcert.pfxcertificate has a separate password). The app package is then wrapped into an MDX package named WorxWeb.mdx. The MDX package contains the template files stored in . Templates\WorxWeb Verbosemode is on.
CGAppPrepTool.exe -in:"tests\unsigned\MobileMail_Release_x86.xap" -out:"tests\output\NewWrapped.xap" -C:"tests\NoPwCert.pfx" -resign -phonePublisherId:aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
Re-signs the package file with the signing MobileMail_Release_x86.xap NoPwCert.pfxcertificate (this certificate does not have a password) and stores the .xap package in . NewWrapped.xapThe tool does not create an MDX package because the parameter is not specified. mode -T: Verboseis off.
CGAppPrepTool.exe -in:"tests\unsigned\WorxHome.appx" -out:"tests\output\WorxHome.appx" -T:"Templates\WorxHome" -verbose -C:"tests\Mytestcert.pfx" -mdmServerURL:"https://my.example.net/zdm" -resign
Embeds the URL in the app manifest file of the https://my.example.net WorxHome.appxpackage file, then stores the resulting signed (with ) and wrapped .appx package in Mytestcert.pfx
. The MDX package contains the template files stored in tests\output\WorxHome.appx. Verbose mode is on.Templates\WorxHome
CGAppPrepTool.exe -in:"tests\unsigned\WorxHome.xap" -C:"tests\Mytestcert.pfx" -T:"Templates\WorxHome" -verbose -resign -password:mypw -mdmServerURL:"https://my.example.net/zdm"
Embeds the URL in the app manifest file of the package https://my.example.net mytest.appxfile, then re-signs the package file with the signing certificate, WorxHome.xap Mytestcert.pfxwhich has a separate password. The MDX package contains the template files stored in
. Because the parameter is not specified, the app Templates\WorxHome -out: WorxHome.xappackage is updated in place. mode is on.Verbose
CGAppPrepTool.exe -in:"tests\unsigned\mytest.appx" -out:"tests\output\NewWrapped.appx" -C:"tests\NoPwCert.pfx" -verbose -resign -appxPackageTool:"backcompat\makeappx.exe"
Re-signs the package file with the signing certificate and stores the mytest.appx NoPwCert.pfxresulting .appx package in . This command uses the packing tool at NewWrapped.appx
to repackage the .appx file. It does not create an MDX package because backcompat\makeappx.exethe parameter is not specified. mode is on.-T: Verbose
CGAppPrepTool.exe -in:"tests\unsigned\mytest.appx" -out:"tests\output\WorxWeb.mdx" -T:"Templates\WorxWeb" -C:"tests\Mytestcert.pfx" -verbose -resign -phonePublisherId:aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee -password:mypw -mdmServerURL:"https://my.example.net/zdm"
Embeds the URL in the app manifest file of the package https://my.example.net mytest.appxfile, then re-signs the package file using the signing certificate, mytest.appx Mytestcert.pfxwhich has a separate password. The tool then wraps the app package into an MDX package named
, which contains the template files stored in . Specifies the WorxWeb.mdx Templates\WorxWebpublisher ID of the wrapped app. mode is on.Verbose
Identifying Windows Phone App Wrapping Errors
If you encounter an error when wrapping a Windows Phone app, you can use the MDX Toolkit logs to identify the error. You must have administrator rights to view the MDX Toolkit logs.
When you run the MDX Toolkit, the tool saves a log file to the following location: Applications/Citrix/MDXToolkit/Logs/Citrix.log. By default, the tool saves warnings and errors in the log.
citrix.com 63
MDX Policies at a Glance
The following tables list the MDX app policies for iOS, Android, and Windows Phone. The notes include restrictions and Citrix recommendations.
Note: Worx Home refreshes policies during certain actions. For details, see .
Policy iOS Android Windows Phone 8.1 and 10
Default setting Notes
Authentication
Device passcode
X Off
App passcode X X X On
Online session required
X X X Off
Online session required grace period
X
0
Maximum offline period
X X X 72 hours
Alternate NetScaler Gateway
X X
Empty
Policy iOS Android Windows Phone 8.1 and 10
Default setting Notes
Device Security
Block jailbroken or rooted
X X On
Require device encryption
X Off
Require device lock
X Off On Android M devices, the Device PIN or passcode and Device pattern screen lock options have the same effect: With either of those options, the app is locked if the device does not have a PIN, passcode, or pattern screen lock set.
Require device PIN or passcode X Off
This policy is supported only on Android 4.1 (Jelly Bean). Setting the policy to On prevents an app from running on older versions.
Use secure
Administering Worx Home
citrix.com 64
connection (SSL) X Off
Policy iOS Android Windows Phone 8.1 and 10
Default setting Notes
Network Requirements
Require WiFi X X Off
Policy iOS Android Windows Phone 8.1 and 10
Default setting Notes
Miscellaneous Access
App update grace period (hours)
X X 168 hours (7 days) Citrix recommends using a value other than zero (0). A zero value immediately prevents users, without warning, from using a running app until they download and install the update. This could lead to a situation in which users are forced to exit the app and potentially lose work.
Erase app data on lock
X X Off
Active poll period (minutes)
X X 60 Only set this value lower than the default for high-risk apps, or performance may be affected.
Policy iOS Android Windows Phone 8.1 and 10
Default setting Notes
EncryptionEncryption keys X Offline Access permitted
File encryption version X Current
Private file encryption X Security Group
Private file encryption exclusions
X Empty
Access limits for public files X Empty
Enabling the Public file encyrption policy enforces this policy (changed from the Disable Option to the SecurityGroup or Application option).
citrix.com 65
This policy applies only to existing, unencrypted public files and specifies when to encrypt the files.
Public file encryption X Security Group Public file encryptions exclusions
X Empty
Public file migration X Write (RO/RW)
Encrypting an existing public file makes the file unavailable to other apps that do not have the same encryption key.
Minimum data protection class
X None iOS 9 only.
Enable encryption X On
If you change this policy for an existing app, users must delete and reinstall the app to apply the policy change.
Database encryption exclusions
X Empty
File encryption exclusions
X Empty
Policy iOS Android Windows Phone 8.1 and 10
Default setting Notes
App Interaction
Security Group X Empty If you change this policy for an existing app, users must delete and reinstall the app to apply the policy change.
Cut and copy X X Restricted
Paste X X Unrestricted
Document exchange (Open In)
X X X Restricted
Connection security level
X X TLS
Inbound document exchange (Open In)
X X Unrestricted
Inbound document exchange whitelist
X X Empty
citrix.com 66
Restricted Open In exception list
X X Empty (for Android); Office 365 apps (for iOS)
On Android, this policy was previously named Open In exclusions.
On iOS, this policy is hidden. For details, see
Policies for iOS .Apps
App URL schemes
X All registered app URL schemes are blocked (outbound)
Allowed URLs X Empty list (all URLs are blocked except for ctxmobilebrowser (WorxWeb) and citrixreceiver: +tel; (outbound)
Policy iOS Android Windows Phone 8.1 and 10
Default setting Notes
App Restrictions
Block camera X X X See Notes. Default value for iOS and Android is On. Default value for Windows Phone is Off.
Block Photo Library
X On
Block Gallery X Off
Block localhost Connection
X X X Off
Block mic record X X On
Block dictation X On
Block location services
X X See Notes. Default value is Off for WorxMail, WorxNotes, and Citrix for Salesforce. Default value is On for other apps.
Block SMS compose
X X On
Block screen capture
X On
Block device sensor
X On
Block NFC X On
XenMobile MDX Policies for iOS Apps
citrix.com 67
Block printing X On
Block iCloud X On
Block file backup X On
Block AirPrint X On
Block AirDrop X On
Block file attachments
X Off iOS 9 only. For WorxMail.
Block email as attachment
X Off iOS 9 only. For WorxNotes.
Block Facebook and Twitter APIs
X On
Obscure screen contents
X On
Block 3rd party keyboards
X On iOS 8 and later only.
Block app logs X X X Off
Mail compose redirection
X
Policy iOS Android Windows Phone 8.1 and 10
Default setting Notes
App Network Access
Network access X X See Notes. Default value for WorxWeb and Citrix for Salesforce is Tunneled to the internal network. Default value for WorxMail and WorxNotes is Unrestricted. Default value for other apps is Blocked.
Certificate label X X Empty
Preferred VPN mode
X X Secure browse
Permit VPN mode switching
X X Off
PAC file URL or proxy server
X Empty
App Logs
citrix.com 68
Default log output
X X X file
Default log level X X X 4 (informational messages)
Max log files X X X 2
Max log file size X X X 2 MB
Redirect app logs
X On
Encrypt logs X Off
Whitelist WiFi networks
X X Blank Doesn't affect cellular networks
Policy iOS Android Windows Phone 8.1 and 10 Default Setting NotesApp GeofenceCenter point longitude X X 0 Center point latitude X X 0 Radius X X 0 Set the radius in meters.
Policy iOS Android Windows Phone 8.1 and 10 Default Setting NotesApp InteractionExplicit Logoff Notification X Shared device
Policy iOS Android Windows Phone 8.1 and 10
Default setting Notes
WorxMail App Settings
WorxMail Exchange Server
X X X Empty If you change this policy for an existing app, users must delete and reinstall the app to apply the policy change.
WorxMail user domain
X X X Empty
Background network services
X X X Empty If you configure this policy, set the Network access policy to Tunneled to the internal network, after which this policy takes effect. In addition, use this policy when the Exchange Server resides in your internal network and you want to use NetScaler Gateway to proxy the connection to the internal Exchange Server.
X X X 168 hours (7 days)
citrix.com 69
Background services ticket expiration
Background network service gateway
X X X Empty If you configure this policy, set the network access policy to Tunneled to the internal network, after which this policy will take effect. In addition, use this policy when the Exchange Server resides in your internal network or if you want to use NetScaler Gateway to proxy the connection to the internal Exchange Server. This policy takes effect when you configure the Network access policy.
Export contacts X X X Off
Contact fields to export
X X All
Accept all SSL certificates
X X Off
Control locked screen notifications
X X Allow
Default email notification
X Off
Default sync interval
X X 3 days The Exchange ActiveSync mailbox policy setting Maximum e-mail age filter has priority over this policy. WorxMail displays only the sync interval values that are less than the Maxiumum e-mail age filter.
Max Sync Interval X 1 month (iOS)
All (Android)
Allowed Max Sync Period
X 1 month (iOS)
All (Android)
X X Off
citrix.com 70
Enable week number
Enable download attachments over WiFi
X X Off
Information Rights Management
X X Off
Email classification
X Off
Email classification markings
X See Notes. See Security
for Classificationsthe list of defaults.
Email classification namespace
X Empty
Email classification version
X Empty
Default email classification
X UNOFFICIAL
Enable auto-save of draft emails
X X On
Enable iOS data protection
X Off
Google analytics X X X On
Push notifications
X Off
Push notifications region
X Americas
Push notifications customer ID
X Empty
S/MIME certificate source
X Email
Enable S/MIME during first WorxMail startup
X Off
Policy iOS Android Windows Phone 8.1 and 10
Default setting Notes
WorxNotes App Settings
Email Security Classifications
citrix.com 71
WorxNotes storage options
X X ShareFile and Exchange Server
WorxNotes Exchange Server
X X Empty
WorxNotes user domain
X X Empty
Background network services
X X Empty
Background services ticket expiration
X X 168 hours (7 days)
Background network service gateway
X X Empty
Accept all SSL certificates
X X Off
Google analytics X X On
Information Rights Management
X Off
Policy iOS Android Windows Phone 8.1 and 10
Default setting Notes
WorxTasks App Settings
WorxTasks Exchange Server
X Empty
WorxTasks user domain
X Empty
Background network services
X X Empty
Background services ticket expiration
X X 168 hours (7 days)
Background network service gateway
X X Empty
Accept all SSL certificates
X X Off
Google analytics X X On
Policy iOS Android Default setting Notes
citrix.com 72
Windows Phone 8.1 and 10
WorxWeb App Settings
Allowed or blocked websites
X X X Empty (all URLs are allowed)
Preloaded bookmarks
X X X Empty
Home page URL
X X X Empty (default start page)
Browser user interface
X X All controls visible
Enable web password caching
X X Off
Google analytics
X X On
Disable cookies
X Off
Disable HTML5 local storage
X Off
File protection X Off
Policy iOS Android Windows Phone 8.1 and 10
Default setting Notes
ShareFile Worx Client App Settings
Enable secure viewer
X On
Policy iOS Android Windows Phone 8.1 and 10
Default setting Notes
ShareConnect App Settings
Save password X X On For ShareConnect only.
Google analytics X X On
Related articles
Refer to the following articles for policy descriptions:
XenMobile MDX Policies for Android AppsXenMobile MDX Policies for iOS AppsXenMobile MDX Policies for Android AppsXenMobile MDX Policies for iOS Apps
citrix.com 73
XenMobile MDX Policies for Windows Phone AppsXenMobile MDX Policies for Windows Phone Apps
citrix.com 74
XenMobile MDX Policies for Android Apps
This article describes the MDX policies for Android apps. You can change policy settings directly in the policy XML files or in the XenMobile console when you add an app.
Quick links to sections in this article
AuthenticationDevice SecurityNetwork RequirementsMiscellaneous AccessEncryptionApp InteractionApp RestrictionsApp Network AccessApp LogsApp GeoLocation GeoFencingShareConnect App SettingsWorxMail App SettingsWorxNotes App SettingsWorxTasks App SettingsWorxWeb App Settings
Authentication
App passcodeIf , a PIN or passcode is required to unlock the app when it starts or resumes after a period of inactivity. Default Onvalue is .On
To configure the inactivity timer for all apps, set the INACTIVITY_TIMER value in minutes in on Client Propertiesthe tab. The default inactivity timer value is 60 minutes. To disable the inactivity timer, so that a PIN or Settingspasscode prompt appears only when the app starts, set the value to zero.
Note: If you select for the Encryption keys policy, this policy is automatically enabled.Secure offline
Online session requiredIf , the user must have a connection to the enterprise network and an active session. If , an active session is not On Offrequired. Default value is .Off
Maximum offline period (hours)Defines the maximum period an app can run without reconfirming app entitlement and refreshing policies from XenMobile. Default value is hours (3 days). Minimum period is 1 hour.72
Users are reminded to sign on at 30, 15, and 5 minutes before the period expires. After expiration, the app is locked until users sign on.
Alternate NetScaler GatewayAddress of a specific alternate NetScaler Gateway that should be used for authentication and for micro VPN sessions with this app. This is an optional policy that when used in conjunction with the Online session required policy forces apps to reauthenticate to the specific gateway. Such gateways would typically have different (higher assurance) authentication requirements and traffic management policies. If left empty, the server's default gateway is always used. Default value is empty.
Device Security
Block jailbroken or rootedIf , the app is locked when the device is jailbroken or rooted. If , the app can run even if the device is jailbroken On Offor rooted. Default value is .On
Require device encryptionIf , the app is locked if the device does not have encryption configured. If , the app is allowed to run even if the On Offdevice does not have encryption configured. Default value is Off.Important: This policy is supported only on Android 3.0 (Honeycomb). Setting the policy to prevents an app from Onrunning on older versions.
Require device lock
AuthenticationDevice SecurityNetwork RequirementsMiscellaneous AccessEncryptionApp InteractionApp RestrictionsApp Network AccessApp LogsApp GeoLocation GeoFencingShareConnect App SettingsWorxMail App SettingsWorxNotes App SettingsWorxTasks App SettingsWorxWeb App Settings
citrix.com 75
If , the app is locked if the device does not have a PIN or passcode. If Device PIN or passcode Device pattern , the app is locked if the device does not have a pattern screen lock set. If , the app is allowed to run screen lock Off
even if the device does not have a PIN, passcode, or pattern screen lock set. Default value is Off.Important: requires a minimum version of Android 4.1 (Jellybean). Setting the policy to Device PIN or passcode
prevents an app from running on older versions.Device PIN or passcodeOn Android M devices, the and options have the same effect: Device PIN or passcode Device pattern screen lockWith either of those options, the app is locked if the device does not have a PIN, passcode, or pattern screen lock set.
Network Requirements
Require WiFiIf , the app is locked when the device is not connected to a WiFi network. If , the app can run if the device has On Offan active connection, such as a 4G/3G, LAN, or WiFi connection. Default value is .Off
Miscellaneous Access
App update grace period (hours)Defines the grace period in which an app can be used after the system discovers that an app update is available. Default value is hours (7 days).168Note: Citrix does not recommend using a value of zero because it immediately prevents a running app from being used until the update is downloaded and installed (without any warning to the user). This can force the use to exit the app (potentially losing work) in order to comply with the required update.
Erase app data on lockErases data and resets the app when the app is locked. If , app data is not erased when the app is locked. Default Offvalue is .Off
An app can be locked for any of the following reasons:
Loss of app entitlement for the userApp subscription removedAccount removedWorx Home uninstalledToo many app authentication failuresJailbroken device detected (per policy setting)Device placed in locked state by other administrative action
Active poll period (minutes)When an app starts, the MDX framework polls XenMobile to determine current app and device status. Assuming the server running XenMobile can be reached, the framework returns information about the lock/erase status of the device and the enable/disable status of the app. Whether the server can be reached or not, a subsequent poll is scheduled based on the active poll period interval. After the period expires, a new poll is again attempted. Default value is 60minutes.Important: Only set this value lower for high-risk apps or performance may be affected.
Encryption
Encryption keysEnables secrets used to derive encryption keys to be persisted on the device. Offline access permitted is the only available option. Citrix recommends that you set the Authentication policy to enable a network logon or an offline password challenge in order to protect access to the encrypted content.
File encryption version
Specifies the encryption version for public and private file encryption. Citrix recommends Current to provide the maximum security, especially in the case of a new app deployment. If you select Current, note that users must reinstall any apps that include a previous encryption version, such as Legacy, or else they may lose data.
Default value is Current.
Private file encryptionControls the encryption of private data files in the following locations: /data/data/<appname> and /mnt/sdcard/Android/data/<appname>. If Disabled, private files are not encrypted. If Security Group, private files are encrypted using a key shared by all MDX apps in the same security group. If Application, private files are encrypted using a key unique to this app. Default value is Security Group.
Private file encryption exclusions
citrix.com 76
Contains a comma-separated list of file paths. Each path is a regular expression that represents on or more files that should ne be encrypted. The file paths are relative to the internal and external sandboxes. Default value is empty.
The exclustions only apply to the following folders:
Internal Storage:/data/data/<your_package_name>
SD Card:/storage/emulated/<SD Card Slot>/Android/data/<your_package_name>/storage/emulated/legacy/Android/data<your_package_name.
Examples:
File To exclude Value in private file encryption exclusion/data/data/com.citrix.mail/files/a.txt ^files/a.txtAll text files in /storage/emulated/0/Android/data/com.citrix.mail/files
^files/(.)+.txt$
All files in /data/data/com.citrix.mail/files ^files/
Access limits for public files
Limits access to specific files: No Access, Read Only, or Read Write.
Contains a comma-separated list. Each entry is a regular expression path followed by (NA), (RO), or (RW). The list is processed in order and the first matching path is used to set the access limit. Default value is empty.
This policy is enforced only when (changed from the option to the Public file encryption is enabled Disable or option). This policy is applicable only to existing, unencrypted public files and SecurityGroup Application
specifies when these files are encrypted.
Files to exclude Value in private file encryption exclusionDownloads folder on external storage read only EXT:^Download/(RO)All MP3 files in the Music folder on virtual storage no access VS:^Music/(.)+.mp3$(NA) Public file encryption
Controls the encryption of public files. If , public files are not encrypted. If , Disabled SecurityGroupencrypts public files by using a key shared by all MDX apps in the same security group. If , Applicationencrypts public files by using a key unique to this app.
Default value is .SecurityGroup
Public file encryption exclusionsContains a comma-separated list of file paths. Each path is a regular expression that represents one or more files that should not be encrypted. The file paths are relative to the default external storage and to any device specific external storage.
Public file encryption exclusions include external folder locations only.
Examples:
File to exclude Value in Public File Encryption ExclusionDownloads folder on SD card ^Download/All MP3 files in Music folder ^Music/(.)+.mp3$
Public file migrationThis policy is enforced only when you enable the Public file encryption policy (changed from to Disabled
or ). This policy is applicable only to existing, unencrypted public files and specifies SecurityGroup Applicationwhen these files are encrypted. Default value is .Write (RO/RW)
Options:
Disabled. Does not encrypt existing files.Write (RO/RW). Encrypts the existing files only when they are opened for write-only or read-write access.Any. Encrypts the existing files when they are opened in any mode.
citrix.com 77
Note: New files or existing unencrypted files that are overwritten encrypts the replacement files in every case.Caution: Encrypting an existing public file makes the file unavailable to other apps that do not have the same encryption key.
App Interaction
Security GroupLeave this field blank if you want all mobile apps managed by XenMobile to exchange information with one another. Define a security group name to manage security settings for specific sets of apps (for example, Finance or Human Resources). If you change this policy for an existing app, users must delete and reinstall the app to apply the : Cautionpolicy change.
Cut and CopyBlocks, permits, or restricts Clipboard cut and copy operations for the app. If , the copied Clipboard data is Restrictedplaced in a private Clipboard that is only available to MDX apps. Default value is .Restricted
Options: , , or Unrestricted Blocked Restricted
PasteBlocks, permits, or restricts Clipboard paste operations for the app. If , the pasted Clipboard data is sourced Restrictedfrom a private Clipboard that is only available to MDX apps. Default value is .Unrestricted
Options: , , or Unrestricted Blocked Restricted
Document exchange (Open In)Blocks, permits, or restricts document exchange operations for the app. If , documents can be exchanged Restrictedonly with other MDX apps and the app exceptions specified in the Restricted Open-In exception list policy. If
, you must set the Private file encryption and Public file encryption policies to so that so that Unrestricted Disabledusers can open documents in unwrapped apps.
If the policy blocks the camera, audio, clipboard, or printing, each of these maintain the last shown timestamp. Users receive a message of the status of the option; for example, Camera: disabled.
Default value is .Restricted
Options: , , or Unrestricted Blocked Restricted
Restricted Open-In exception listWhen the Document exchange (Open In) policy is , this list of Android intents is allowed to pass to Restrictedunmanaged apps. A familiarity with Android intents is needed to add filters to the list. A filter can specify action, package, scheme, or any combination of those. Examples:
{action=android.intent.action.MAIN} {package=com.sharefile.mobile} {action=android.intent.action.DIAL scheme=tel}
Caution: Be sure to consider the security implications of this policy. The exception list allows content to travel between unmanaged apps and the secure Worx environment.
Inbound document exchange (Open In)Blocks, restricts, or allows inbound document exchange operations for this app. If , documents can be Restrictedexchanged only with other MDX apps. Default value is .Unrestricted
If or , you can use the Inbound document exchange whitelist policy to specify apps that can Blocked Restrictedsend documents to this app. For information about other policy interactions, see the Block Gallery policy.
Options: , , or Unrestricted Blocked Restricted
Inbound document exchange whitelistWhen the Inbound document exchange policy is set to or , this comma-delimited list of app IDs, Restricted Blockedincluding non-MDX apps, is allowed to send documents to the app.
Connection security levelDetermines the minimum version of TLS/SSL used for connections. If , connections support all TLS protocols. If TLS
, connections support SSL 3.0 and TLS. Default value is .SSLv3 and TLS TLS
App Restrictions
Important
citrix.com 78
Be sure to consider the security implications of policies that block apps from accessing or using phone features. When those policies are , content can travel between unmanaged apps and the secure Worx environment.Off
Block cameraIf , prevents an app from directly using the camera hardware. Default value is .On On
Block GalleryIf , prevents an app from accessing the Gallery on the device. Default value is . This policy works in conjunction On Offwith the policy Inbound document exchange (Open In).
If Inbound document exchange (Open In) is set to , users working in the managed app cannot Restrictedattach images from the Gallery, regardless of whether you set the Block Gallery to or .OFF ONIf Inbound document exchange (Open In) is set to , users working in the managed app will Unrestrictedexperience the following:
Users can attach images if Block Gallery is set to .OFFUsers are blocked from attaching images if Block Gallery is set to .ON
If the Block Gallery policy is On and there is an intent created from an app, such as the action Open_Document (which is the document picker intent), intent types are handled as follows:
image/*: MDX blocks the intent.*/*: The document picker opens, but MDX prevents the user from selecting images or videos.
Block localhost ConnectionsIf , prevents an app from accessing the loopback address (127.0.0.1). Default value is .On Off
Block mic recordIf , prevents an app from directly using the microphone hardware for recording. Default value is .On On
Block location servicesIf , prevents an app from using the location services components (GPS or network). Default value is for On Off WorxMail, WorxNotes, and Citrix for Salesforce. Default value is for other apps.On
Block SMS composeIf , prevents an app from using the SMS compose feature used to send SMS/text messages from the app. Default Onvalue is .On
Block screen captureIf , prevents users from taking screen captures while the app is running. Also, when the user switches apps, Onobscures the app screen. Default value is .On
When using the Android Near Field Communication (NFC) feature, some apps take a screen shot of itself before beaming the content. To enable that feature in a wrapped app, change the Block screen capture policy to .Off
Block device sensorIf , prevents an app from using the device sensors, such as accelerometer, motion sensor, or gyroscope. Default Onvalue is .On
Block NFCIf , prevents an app from using the Near Field Communications (NFC). Default value is .On On
Block app logsIf , prohibits an app from using the Worx App diagnostic logging facility. If , app logs are recorded and may be On Offcollected by using the Worx Home email support feature. Default value is .Off
Block printingIf , prevents an app from printing data. If an app has a Share command, you must set Document Exchange (Open in) Onto or to fully block printing. Default value is .Restricted Blocked On
App Network Access
Network accessPrevents, permits or redirects app network activity. If Unrestricted, no restrictions are placed on network access; apps have unrestricted access to networks to which the device is connected. If Blocked, all network access is blocked. If
citrix.com 79
Tunneled to the internal network, a per-application VPN tunnel back to the internal network is used for all network access and NetScaler split tunnel settings are used.
Default value for WorxWeb and Citrix for Salesforce is Tunneled to the internal network. Default value for WorxMail and WorxNotes is Unrestricted. Default value for other apps is Blocked.
Certificate labelWhen used with the StoreFront certificate integration service, this label identifies the specific certificate required for this app. If no label is provided, a certificate is not made available for use with a public key infrastructure (PKI). Default value is empty (no certificate used).
Preferred VPN modeSets the initial mode for connections that tunnel to the internal network. Full VPN tunnel is recommended for connections that employ client certificates or end-to-end SSL to a resource in the internal network. Secure browse is recommended for connections that require single sign-on (SSO).
Permit VPN mode switchingWhen tunneling to the internal network, this policy permits switching between VPN modes automatically as needed. If On, a network request that fails due to an authentication request that cannot be handled in the preferred VPN mode is retried in the alternate mode. For example, server challenges for client certificates can be accommodated by full tunnel mode, but not when using secure browse mode. Similarly, HTTP authentication challenges are more likely to be serviced with SSO when using secure browse mode. If Off, the mode specified in the Preferred VPN mode policy is the only mode that is used. Default value is Off.
Whitelisted WiFi networksComma-delimited list of allowed networks. App runs only if connected to one of the networks listed. If left blank, all networks are allowed. This doesn't affect connections to cellular networks. Default value is blank.
App Logs
Default log outputDetermines which output mediums are used by Worx app diagnostic logging facilities by default. Possibilities are file, console, or both file,console. Default value is file.
Default log levelControls default verbosity of the Worx App diagnostic logging facility. Higher level numbers include more detailed logging.
0 - Nothing logged - Critical errors1 - Errors2 - Warnings3 - Informational messages4 - Detailed informational messages5 through - Debug levels 1 through 106 15
Default value is level (Informational messages).4
Max log filesLimits the number of log files retained by the Worx App diagnostic logging facility before rolling over. Minimum is . 2Maximum is . Default value is .8 2
Max log file sizeLimits the size in megabytes (MB) of the log files retained by the Worx App diagnostic logging facility before rolling over. Minimum is MB. Maximum is MB. Default value is MB.1 5 2
Redirect app logsIf , intercepts and redirects system or console logs from an app to the Worx App diagnostic facility. If , app use of On Offsystem or console logs is not intercepted. Default value is .On
Encrypt logsIf , Worx encrypts diagnostic logs as it records the logs. If , diagnostic logs remain unencrypted in the app On Offsandbox.
Caution: Depending upon configured log levels, log encryption can have a noticeable impact on app performance and battery life.
Default value is .Off
citrix.com 80
App GeoLocation and GeoFencingThe GeoLocation feature allows you to restrict app usage based on the location of the user device. For example, a person travels to Amsterdam. You can allow users to use the app when they are in Amsterdam, but if the person travels to Belgium, the app locks and users cannot interact with the app. When the user returns to Amsterdam, the app unlocks and is available for normal use.
There are three settings to enable GeoLocation:
Longitude (X coordinate) is the center point of the point or radius geofence in which the app is constrained to operate. When operated outside the configured geofence, the app remains locked. Enter in a signed degrees format (DDD.dddd). For example, "-31.9635." Preface west longitudes with a minus sign.Latitude (Y coordinate) is the center point of the point or radius geofence in which the app is constrained to operate. Enter in a signed degrees format (DDD.dddd). For example, "43.06581." Preface southern latitudes with a minus sign.Radius of the geofence in which the app is constrained to operate. Express the radius in meters. Setting this value to zero disables geofencing.
Note: If you enable , geofencing does not work correctly.Block locations services
Default is 0 (disabled).
If the app supports geofencing and you disable location services, a message appears where users can either quit the app or can click Settings that goes to the Settings screen on the Android device. If users enable locations services, they can return and continue using the app.
When the radius and location services settings are correct, the app checks for a geofence breach. If the distance between the current location and the center point (as specified in the policy) is greater than the specified radius, the user is blocked from using the app. When this occurs, users receive an option to quit the app. The user must be within the fence to continue using the app.
If the distance between the current location and then the center point is less than the specified radius, the user can continue to use the app.
The app checks the network provider (WiFi, 3G, or 4G) or the GPS Provider to find the location. The device can also use GPS and the cell phone carrier network together, which is also called high accuracy mode and helps in obtaining the location faster.
There is a two-minute time-out to allow for longer times in checking the location.
Note: To get an accurate location from the device, and to avoid users trying to circumvent Geofence by disabling WiFi or the GPS, Citrix recommends setting the policy to .Online session required On
ShareConnect App Settings
Save passwordIf , enables users to save their user name and password for their remote computer. Default value is .On On
Google analyticsIf , Citrix collects anonymous data to improve product quality. If , no data is collected. Default value is .On Off On
WorxMail App Settings
WorxMail Exchange Server
The fully qualified domain name (FQDN) for Exchange Server or, for iOS only, IBM Notes Traveler server. Default value is empty. If you provide a domain name in this field, users cannot edit it. If you leave the field empty, users provide their own server information.
Caution: If you change this policy for an existing app, users must delete and reinstall the app to apply the policy change.
WorxMail user domain
The default Active Directory domain name for Exchange or, for iOS only, Notes users. value is empty.Default
Background network services
citrix.com 81
The FQDN and port of service addresses permitted for background network access. This might be an Exchange Server or ActiveSync server, either in your internal network or in another network that WorxMail connects to, such as mail.example.com:443.
If you configure this policy, set the Network access policy to . This policy takes Tunneled to the internal network affectwhen you configure the network access policy. In addition, use this policy when the Exchange Server resides in your internal network and you want to use NetScaler Gateway to proxy the connection to the internal Exchange Server.
Default value is empty, implying that background network services are not available.
Background services ticket expirationThe time period that a background network service ticket remains valid. When WorxMail connects through NetScaler Gateway to an Exchange Server running ActiveSync, XenMobile issues a token that WorxMail uses to connect to the internal Exchange Server. This property setting determines the duration that WorxMail can use the token without requiring a new token for authentication and the connection to the Exchange Server. When the time limit expires, users must log on again to generate a new token. value is hours (7 days).Default 168
Background network service gatewayAlternate gateway address to use for background network services, in the form This is the NetScaler :portfqdn .Gateway FQDN and port number which WorxMail uses to connect to the internal Exchange Server. In the NetScaler Gateway configuration utility, you must configure the Secure Ticket Authority (STA) and bind the policy to the virtual server. For more information about configuring the STA in NetScaler Gateway, see
.Authority on NetScaler Gateway
The Default value is empty, implying that an alternate gateway does not exist. If you configure this policy, set the Network access policy to . This policy takes when you configure the network Tunneled to the internal network affectaccess policy. In addition, use this policy when the Exchange Server resides in your internal network and you want to use NetScaler Gateway to proxy the connection to the internal Exchange Server.
Export contactsImportant: Do not enable this feature if users can access your Exchange Server directly (that is, outside of NetScaler Gateway). Otherwise, contacts are duplicated on the device and in Exchange.If , prevents the one-way synchronization of WorxMail contacts to the device and prevents the sharing of WorxMail Offcontacts (as vCards). value is .Default Off
Contact fields to exportControls contact fields to be exported to the address book. If , all contact fields will be exported. If All Name and Phone, all name and phone related contact field will be exported. If , all name, phone and email Name, Phone and Emailrelated contact fields will be exported. Default value is .All
Accept all SSL certificatesIf , WorxMail accepts all SSL certificates (valid or not) and allows access. If , WorxMail blocks access when a On Offcertificate error occurs and displays a warning. value is .Default Off
Information Rights ManagementIf , WorxMail supports Exchange Information Rights Management (IRM) capabilities. value is .On Default Off
Control locked screen notificationsControls whether mail and calendar notifications appear on a locked device screen. If , all information contained Allowin the notification appears. If , notifications do not appear. If , only the name of the Block Email sender or event titleemail sender or the title of the calendar event appears. If , only the count of mail and meeting invitations Count onlyplus the time of calendar reminders appear. value is .Default Allow
Use secure connection (SSL)
If , WorxMail uses a secure connection. If , WorxMail does not use a secure connection.On Off
Default is .On
Mail Search Limit
Restricts the amount of mail history that is accessible from mobile devices by limiting the number of days included in mail server searches.
To restrict the amount of mail that is synced to a mobile device, configure the policy.Max sync interval
Default value is .Unlimited
Default sync intervalSpecifies the default sync interval for WorxMail. WorxMail users can change the default.
Configuring the Secure Ticket Authority on NetScaler Gateway
citrix.com 82
The Exchange ActiveSync mailbox policy setting has priority over this policy. If you specify Maximum e-mail age filtera Default sync interval that is larger than the , the setting is Maximum e-mail age filter Maximum e-mail age filterused instead. WorxMail displays only the sync interval values that are less than the Active Sync Maximum e-mail age
setting.filter
Default value is .3 days
Allowed Max Sync Period
Limits search on the device to a specified period of time. Search includes local search and server search that you configure by using two separate policies. You must set the policy on the user device and the server for the policy to be effective.
The values are:
3 days1 week2 weeks1 monthAll
Default value is . All
Max sync interval
Controls the amount of mail stored locally on a mobile device by limiting the sync period.
To restrict the time period that a device can search on the mail server, configure the policy.Mail server search limit
The values are:
3 days1 week2 weeks1 monthAll
Default value is .All
Default sync interval
Specifies the default sync interval for WorxMail. WorxMail users can change the default.
The Exchange ActiveSync mailbox policy setting Maximum e-mail age filter has priority over this policy. If you specify a that is larger than the , the r setting is used Default sync interval Maximum e-mail age filter Maximum e-mail age filte
instead. WorxMail displays only the sync interval values that are less than the Active Sync e-mail age filter setting. Maximum
Default value is .3 days
Enable download of attachments over WiFiIf On, the WorxMail Download attachments option is enabled so that users can, by default, download attachments over internal WiFi networks. If Off, the WorxMail Download attachments option is disabled so that, by default, users cannot download attachments over WiFi. value is .Default Off
Enable auto-save of email draftsIf , WorxMail supports automatically saving messages to the Drafts folder. The auto-save occurs every 20 seconds. On
value is .Default On
Google analyticsIf , Citrix collects anonymous data to improve product quality. If , no data is collected. value is .On Off Default On Enable week numberIf , calendar views include the week number. value is .On Default Off
WorxNotes App Settings
WorxNotes storage options
citrix.com 83
Allows you to set storage options for notes that users create when using WorxNotes. If ShareFile and Exchange , the user can choose the storage option for notes. If , notes are stored in ShareFile. If Server ShareFile only Exchange
, notes are stored in Exchange Server. Default value is .only ShareFile and Exchange Server
WorxNotes Exchange ServerFully qualified domain name (FQDN) for Exchange Server. Default value is empty.
Google analyticsIf , Citrix collects anonymous data to improve product quality. If , no data is collected. Default value is .On Off On
WorxNotes user domainDefault Active Directory domain name for Exchange users. Default value is empty.
Background network servicesThe FQDN and port of service addresses permitted for background network access. This might be an Exchange Server or ActiveSync server, either in your internal network or in another network that WorxMail connects to, such as mail.example.com:443.
If you configure this policy, set the Network access policy to . This policy takes affect Tunneled to the internal networkwhen you configure the Network access policy. In addition, use this policy when the Exchange Server resides in your internal network and you want to use NetScaler Gateway to proxy the connection to the internal Exchange Server.
Default value is empty, implying that background network services are not available.
Background services ticket expirationTime period that a background network service ticket should remain valid. After expiration, an enterprise logon is required to renew the ticket. Default value is hours (7 days).168
Background network service gatewayAlternate gateway address to use for background network services in the form . Default value is empty, fqdn:portimplying that there is no alternate gateway.
Accept all SSL certificatesIf , WorxNotes accepts all SSL certificates (valid or not) and allows access. If , WorxNotes blocks access when On Offa certificate error occurs and displays a warning. Default value is .Off
Information Rights ManagementIf , WorxNotes supports Exchange Information Rights Management (IRM) capabilities. Default value is .On Off
WorxTasks App Settings
Background network servicesThe FQDN and port of service addresses permitted for background network access. This might be an Exchange Server or ActiveSync server, either in your internal network or in another network that WorxMail connects to, such as mail.example.com:443.
If you configure this policy, set the Network access policy to . This policy takes affect Tunneled to the internal networkwhen you configure the Network access policy. In addition, use this policy when the Exchange Server resides in your internal network and you want to use NetScaler Gateway to proxy the connection to the internal Exchange Server.
Default value is empty, implying that background network services are not available.
Background services ticket expirationTime period that a background network service ticket should remain valid. After expiration, an enterprise logon is required to renew the ticket. Default value is hours (7 days).168
Google analyticsIf , Citrix collects anonymous data to improve product quality. If , no data is collected. Default value is .On Off On
Background network service gatewayAlternate gateway address to use for background network services in the form . Default value is empty, fqdn:portimplying that there is no alternate gateway.
Accept all SSL certificatesIf , WorxTasks accepts all SSL certificates (valid or not) and allows access. If , WorxTasks blocks access when On Offa certificate error occurs and displays a warning. Default value is .Off
WorxWeb App Settings
Allowed or blocked websites
citrix.com 84
WorxWeb normally does not filter web links. You can use this policy to configure a specific list of allowed or blocked sites. You configure URL patterns to restrict the websites the browser can open, formatted as a comma-separated list. Each pattern in the list is preceded by a Plus Sign (+) or Minus Sign (-). The browser compared a URL against the patterns in the order listed until a match is found. When a match is found, the action taken is dictated by the prefix as follows:
A minus (-) prefix instructs the browser to block the URL. In this case, the URL is treated as if the web server address could not be resolved.A plus (+) prefix allows the URL to be processed normally.If neither + or - is provided with the pattern, + (allow) is assumed.If the URL does not match any pattern in the list, the URL is allowed
To block all other URLs, end the list with a Minus Sign followed by an asterisk (-*). For example:
The policy value +http://*.mycorp.com/*,-http://*,+https://*,+ftp://*,-* permits HTTP URLs within mycorp.com domain, but blocks them elsewhere, permits HTTPS and FTP URLS anywhere, and blocks all other URLs.The policy value +http://*.training.lab/*,+https://*.training.lab/*,-* allows users open any sites in Training.lab domain (intranet) via HTTP or HTTPS, but no public URLs, such as Facebook, Google, Hotmail, and so on, regardless of protocol.
Default value is empty (all URLs allowed).
Preloaded bookmarksDefines a preloaded set of bookmarks for the WorxWeb browser. The policy is a comma-separated list that include folder name, friendly name, and web address. Each triplet should be of the form folder,name,url where folder and name may optionally be enclosed in double quotes (").
For example, the policy values ,"Mycorp, Inc. home page",http://www.mycorp.com, "MyCorp Links",Account logon,https://www.mycorp.com/Accounts "MyCorp Links/Investor Relations","Contact us",http://www.mycorp.com/IR/Contactus.aspx define three bookmarks. The first is a primary link (no folder name) titled "Mycorp, Inc. home page". The second link will be placed in a folder titled "MyCorp Links" and labeled "Account logon". The third will be placed in the "Investor Relations' subfolder of the "MyCorp Links" folder and displayed as "Contact us"."
Default value is empty.
Home page URLDefines the website that WorxWeb loads when started. Default value is empty (default start page).
Browser user interfaceDictates the behavior and visibility of browser user interface controls for WorxWeb. Normally all browsing controls are available. These include forward, backward, address bar, and the refresh/stop controls. You can configure this policy to restrict the use and visibility of some of these controls. Default value is .All controls visible
Options:
All controls visible. All controls are visible and users are not restricted from using them.Read-only address bar. All controls are visible, but users cannot edit the browser address field.Hide address bar. Hides the address bar, but not other controls.Hide all controls. Suppresses the entire toolbar to provide a frameless browsing experience.
Enable web password cachingWhen WorxWeb users enter credentials when accessing or requesting a web resource, this policy determines whether WorxWeb silently caches the password on the device. This policy applies to passwords entered in authentication dialogs and not to passwords entered in web forms.
If , WorxWeb caches all passwords users enter when requesting a web resource. If , WorxWeb does not On Offcache passwords and removes existing cached passwords. Default value is .Off
Google analyticsIf , Citrix collects anonymous data to improve product quality. If , no data is collected. Default value is .On Off On Disable cookiesIf , removes all WorxWeb cookies when a user exits WorxWeb. As a result, each time users start WorxWeb they must re-Onenter information such as website settings and user name. Default value is .Off
citrix.com 85
Disable HTML5 local storageIf , prevents websites from saving data in HTML5 local storage, where file names are stored as plain text and can be Onviewed from desktop apps such as iExplorer. Most websites work with no HTML5 local storage. Default value is .Off
citrix.com 86
XenMobile MDX Policies for iOS Apps
This article describes the MDX policies for iOS apps. You can change policy settings directly in the policy XML files or in the XenMobile console when you add an app.
Quick links to sections in this article
AuthenticationDevice SecurityNetwork RequirementsMiscellaneous AccessEncryptionApp InteractionApp RestrictionsApp Network AccessApp Geolocation and GeofencingApp LogsShareConnect App SettingsWorxMail App SettingsWorxNotes App SettingsWorxTasks App SettingsWorxWeb App SettingsShareFile Worx Client App Settings
Authentication
Device passcode This policy applies to iOS 9 devices only.Note:
If , a PIN or passcode is required to unlock the device when it starts or resumes after a period of inactivity. A device Onpasscode is required to encrypt app data using Apple file encryption. Data for all apps on the device will be encrypted. Default value is .Off
App passcodeIf , a PIN or passcode is required to unlock the app when it starts or resumes after a period of inactivity. Default value Onis .On
To configure the inactivity timer for all apps, set the INACTIVITY_TIMER value in minutes in on the Client Properties tab. The default inactivity timer value is minutes. To disable the inactivity timer, so that a PIN or passcode Settings 15
prompt appears only when the app starts, set the value to zero.
Online session requiredIf , the user must have a connection to the enterprise network and an active session. If , an active session is not On Offrequired. Default value is .Off
Online session required grace period (minutes)Determines how many minutes a user can use the app offline before the Online session required policy prevents the app from further use (until the online session is validated). Default value is (no grace period).0
Maximum offline period (hours)Defines the maximum period an app can run without reconfirming app entitlement and refreshing policies from XenMobile. At expiration, logon to the server may be triggered if needed. Default value is hours (3 days). Minimum 72period is hour.1
Users are reminded to log sign on at 30, 15, and 5 minutes before the period expires. After expiration, the app is locked until users log sign on.
Alternate NetScaler GatewayAddress of a specific alternate NetScaler Gateway that should be used for authentication and for micro VPN sessions with this app. This is an optional policy that when used in conjunction with the Online session required policy forces apps to reauthenticate to the specific gateway. Such gateways would typically have different (higher assurance) authentication requirements and traffic management policies. If left empty, the server's default gateway is always used. Default value is empty.
Device Security
AuthenticationDevice SecurityNetwork RequirementsMiscellaneous AccessEncryptionApp InteractionApp RestrictionsApp Network AccessApp Geolocation and GeofencingApp LogsShareConnect App SettingsWorxMail App SettingsWorxNotes App SettingsWorxTasks App SettingsWorxWeb App SettingsShareFile Worx Client App Settings
citrix.com 87
Block jailbroken or rootedIf , the app is locked when the device is jailbroken or rooted. If , the app can run even if the device is jailbroken On Offor rooted. Default value is .On
Network Requirements
Require WiFiIf , the app is locked when the device is not connected to a WiFi network. If , the app can run if the device has On Offan active connection, such as a 4G/3G, LAN, or WiFi connection. Default value is .Off
Miscellaneous Access
App update grace period (hours)Defines the grace period that an app can continue to be used after the system has discovered that an app update is available. value is hours (7 days).Default 168Note: Using a value of zero is not recommended since a zero value immediately prevents a running app from being used until the update is downloaded and installed (without any warning to the user). This could lead to a situation in which the user running the app is forced to exit the app (potentially losing work) in order to comply with the required update.
Erase app data on lockErases data and resets the app when the app is locked. If , app data is not erased when the app is locked. Off Defaultvalue is .Off
An app can be locked for any of the following reasons:
Loss of app entitlement for the userApp subscription removedAccount removedWorx Home uninstalledToo many app authentication failuresJailbroken device detected (per policy setting)Device placed in locked state by other administrative action
Active poll period (minutes)When an app starts, the MDX framework polls XenMobile to determine current app and device status. Assuming the server running XenMobile can be reached, the framework returns information about the lock/erase status of the device and the enable/disable status of the app. Whether the server can be reached or not, a subsequent poll is scheduled based on the active poll period interval. After the period expires, a new poll is again attempted. Default value is 60minutes.Important: Only set this value lower for high-risk apps or performance may be affected.Minimum data protection class
This policy is only enforced on iOS 9 devices.Note:
Establishes the minimum iOS data protection class to be used for file operations. value is Default Complete
.unless open
If , uses NSFileProtectionComplete; when a device locks, files become unavailable. CompleteIf , uses NSFileProtectionCompleteUnlessOpen or higher; if a file is open Complete unless open
when a device locks, the file continues to be available to the app.
If , uses NSFileProtectionCompleteUntilFirstUserAuthentication or higher; when a Until first unlock
device restarts, until the user unlocks the device for the first time, files are locked and can't be read.If , uses no specific data protection class; files can be read from or written to at any time.None
Developers must be sure to test wrapped apps that perform background processing, such as content Important:
refreshes on a locked device or background syncs.
Encryption
Minimum data protection classNote: This policy is only enforced on iOS 9 devices. This policy is hidden. To make the policy visible in XenMobile, open the policy_metadata.xml file for the app (in Applications/Citrix/MDXToolkit/data) and, in the
section, change the value of to . After you wrap your app, the DocumentExchangeExceptionList PolicyHidden falsepolicy appears when you add the app to XenMobile.
citrix.com 88
Establishes the minimum iOS data protection class to be used for file operations. If Complete, then NSFileProtectionComplete is used; when a device locks, files become unavailable. If Complete unless open, then NSFileProtectionCompleteUnlessOpen or higher is used; if a file is open when a device locks, the file continues to be available to the app. If Until first unlock, then NSFileProtectionCompleteUntilFirstUserAuthentication or higher is used; when a device restarts, until the user unlocks the device for the first time, files are locked and can’t be read. If None, then no specific data protection class is used and files can be read from or written to at any time.
Default value is .Complete unless open
Enable encryption On iOS 9 devices, this policy enables database and keychain encryption only. To enable file encryption for Note:
those devices, set the Device passcode policy to . For older iOS devices, this policy enables file, database, Onand keychain encryption.
If , the data stored on the device is not encrypted. If , the data stored on the device is encrypted. Default Off Onvalue is .On
Caution: If you change this policy after deploying an app, users must reinstall the app.
Database encryption exclusionsLists the databases that are excluded from automatic encryption. To prevent database encryption for a specific database, add an entry to this comma-separated list of regular expressions. If a database path name matches any of the regular expressions, the database is excluded from encryption. The exclusion patterns support Posix 1003.2 Extended Regular Expressions syntax. The pattern matching is case-insensitive.
Examples:
\.db$,\.sqlite$ excludes any database path name that ends with either ".db" or ".sqlite".
\/Database\/unencrypteddb\.db matches database unencrypteddb.db in the Database subfolder.
\/Database\/ matches all databases that contain /Database/ in its path.
Default value is empty.
File encryption exclusionsExclusion list of files that are not automatically encrypted. To prevent encryption for a specific set of files, add an entry to this comma-separated list of regular expressions. If a file path name matches any of the regular expressions, then that file is excluded from encryption. The exclusion patterns support Posix 1003.2 Extended Regular Expressions syntax. The pattern matching is case-insensitive.
Examples:
\.log$,\.dat$ excludes any file path name that ends with either ".log" or ".dat".
\/Documents\/unencrypteddoc\.txt matches the contents of the file unencrypteddoc.txt in the Documents subfolder.
\/Documents\/UnencryptedDocs\/.*\.txt matches ".txt" files under the subpath /Documents/UnencryptedDocs/.
Default value is empty.
Warning
If you use WorxEdit for iOS to encrypt a file and later try to send this out using another application (WorxMail or native iOS Mail), the file will be sent out unencrypted.
App Interaction
Cut and CopyBlocks, permits, or restricts Clipboard cut and copy operations for the app. If , the copied Clipboard data is Restrictedplaced in a private Clipboard that is only available to MDX apps. Default value is .Restricted
Options: , , or Unrestricted Blocked Restricted
citrix.com 89
PasteBlocks, permits, or restricts Clipboard paste operations for the app. If , the pasted Clipboard data is sourced Restrictedfrom a private Clipboard that is only available to MDX apps. Default value is .Unrestricted
Options: , , or Unrestricted Blocked Restricted
Document exchange (Open In)Blocks, permits, or restricts document exchange operations for the app. If , documents can be exchanged Restrictedonly with other MDX apps and the app exceptions specified in the Restricted Open-In exception list policy.
If , set the Enable encryption policy to so that users can open documents in unwrapped apps. If Unrestricted Onthe receiving app is unwrapped or has encryption disabled, Worx decrypts the document.
If the policy blocks the camera, audio, clipboard, or printing, each of these maintain the last shown timestamp. Users receive a message of the status of the option; for example, Camera: disabled.
Default value is .Restricted
Options: , , or Unrestricted Blocked Restricted
Restricted Open-In exception list
When the Document exchange (Open In) policy is , an MDX app can share documents with this Restrictedcomma-delimited list of unmanaged app IDs, even if the Document exchange (Open In) policy is and Restrictedthe Enable encryption policy is . The default exception list allows Office 365 apps:On
com.microsoft.Office.Word,com.microsoft.Office.Excel,com.microsoft.Office.Powerpoint,com.microsoft.onenote,com.microsoft.onenoteiPad,com.microsoft.Office.Outlook
Only Office 365 apps are supported for this policy.
Caution: Be sure to consider the security implications of this policy. The exception list allows content to travel between unmanaged apps and the secure Worx environment. For additional security, this policy does not appear in the XenMobile console. To make the policy visible in XenMobile, open the policy_metadata.xml file for the app (in Applications/Citrix/MDXToolkit/data) and, in the DocumentExchangeExceptionList section, change the value of to . After you wrap your app, the Restricted Open-In exception list policy appears when PolicyHidden falseyou add the app to XenMobile.
Connection security levelDetermines the minimum version of TLS/SSL used for connections. If , connections support all TLS protocols. If TLS
, connections support SSL 3.0 and TLS. Default value is .SSLv3 and TLS TLS
Inbound document exchange (Open In)Blocks, restricts or allows inbound document exchange operations for this app. If , documents can be Restrictedexchanged only with other MDX apps. Default value is .Unrestricted
If or , you can use the Inbound document exchange whitelist policy to specify apps that can send Blocked Restricteddocuments to this app. Options: , , or Unrestricted Blocked Restricted
Explicit logoff notification
If , the app activates explicitly to inform the app of a user logoff. If , the app does not activate during a user Enabled Disabledlogoff. If set to , then the app activates during user logoff only when configuring the device as a shared Shared devices onlydevice. Default is for all apps except WorxMail, where the default is .Disabled Shared Devices
Inbound document exchange whitelistWhen the Inbound document exchange policy is or , this comma-delimited list of app IDs, including Restricted Blockednon-MDX apps, is allowed to send documents to the app.
App URL schemesiOS apps can dispatch URL requests to other apps that have been registered to handle specific schemes (such as "http://"). This facility provides a mechanism for an app to pass requests for help to another app. This policy serves to filter the schemes that are actually passed into this app for handling (that is, inbound URLs). Default value is empty, meaning that all registered app URL schemes are blocked.
The policy should be formatted as a comma-separated list of patterns in which each pattern may be preceded by a plus "+" or minus "-". Inbound URLs are compared against the patterns in the order listed until a match is found. Once matched, the action taken is dictated by the prefix. A minus sign (-) prefix blocks the URL from
citrix.com 90
being passed into this app. A plus sign (+) prefix permits the URL to be passed into the app for handling. If neither "+" or "-" is provided with the pattern, "+" (allow) is assumed. If an inbound URL does not match any pattern in the list, the URL is blocked.
The following table contains examples of App URL schemes:
Scheme App that requires the URL scheme
Purpose
ctxmobilebrowser WorxWeb Permit WorxWeb to handle HTTP: URLs from other apps.
ctxmobilebrowsers WorxWeb Permit WorxWeb to handle HTTPS: URLs from other apps.
ctxmail WorxMail Permit WorxMail to handle mailto: URLs from other apps.
COL-G2M GoToMeeting Permit a wrapped GoToMeeting app to handle meeting requests.
ctxsalesforce Citrix for Salesforce Permit Citrix for Salesforce to handle Salesforce requests.
wbx WebEx Permit a wrapped WebEx app to handle meeting requests.
Allowed URLsiOS apps can dispatch URL requests to other apps that have been registered to handle specific schemes (such as "http://"). This facility provides a mechanism for an app to pass requests for help to another app.
This policy serves to filter the URLs that are passed from this app to other apps for handling (that is, outbound URLs).
The policy should be formatted as a comma-separated list of patterns in which each pattern may be preceded by a plus "+" or minus "-". Outbound URLs are compared against the patterns in the order listed until a match is found. Once matched, the action taken is dictated by the prefix. A minus sign (-) prefix blocks the URL from being passed out to another app. A plus sign (+) prefix permits the URL to be passed out to another app for handling. If neither "+" or "-" is provided with the pattern, "+" (allow) is assumed. A pair of values separated by "=" indicates a substitution where occurrences of the first string are replaced with the second. You can use the regular-expression "^" prefix to search string to anchor it to the beginning of the URL. If an outbound URL does not match any pattern in the list, it will be blocked.
Default:
+maps.apple.com
+itunes.apple.com
^http:=ctxmobilebrowser:
^https:=ctxmobilebrowsers:
^mailto:=ctxmail:
+^citrixreceiver:
+^telprompt:
+^tel:
+^col-g2m-2:
+^col-g2w-2:
+^mapitem:
+^maps:ios_addr
+^sms:
+^facetime:
citrix.com 91
+^facetime-audio:
+^ctxnotes:
+^ctxtasks:
+^itms-apps
By leaving the setting blank, all URLs are blocked, except for the following:
http:=ctxmobilebrowser:https:=ctxmobilebrowsers:+citrixreceiver: +tel:
The following table contains examples of allowed URLs:
^mailto:=ctxmail: All mailto: URLs open in WorxMail.
^http:=ctxmobilebrowser: All HTTP URLs open in WorxWeb.
^https:=ctxmobilebrowsers: All HTTPS URLs open in WorxWeb.
^tel: Allows user to make calls.
-//www.dropbox.com Blocks Dropbox URLs dispatched from managed apps.
+^COL-G2M: Permits managed apps to open the GoToMeeting client app.
-^SMS: Blocks the use of a messaging chat client.
-^wbx: Permits managed apps to open the WebEx client app.
+^ctxsalesforce: Permits Citrix for Salesforce to communicate with your Salesforce server.
App Restrictions
Important
Be sure to consider the security implications of policies that block apps from accessing or using phone features. When those policies are , content can travel between unmanaged apps and the secure Worx environment.Off
Block cameraIf , prevents an app from directly using the camera hardware. Default value is .On On
Block Photo LibraryIf , prevents an app from accessing the Photo Library on the device. Default value is .On On
Block localhost ConnectionsIf , prevents an app from accessing the loopback address (127.0.0.1). Default value is .On Off
Block mic recordIf , prevents an app from directly using the microphone hardware for recording. Default value is .On On
Block dictationIf , prevents an app from directly using dictation services. Default value is .On On
citrix.com 92
Block location servicesIf , prevents an app from using the location services components (GPS or network). Default value is for On OffWorxMail, WorxNotes, and Citrix for Salesforce. Default value is for other apps.On
Block SMS composeIf , prevents an app from using the SMS compose feature used to send SMS/text messages from the app. Default Onvalue is .On
Block iCloudIf , prevents an app from using iCloud for storing and sharing settings and data.On
Note: iCloud data file backup is controlled by the policy.Block file backup
Default value is .On
Block file backupIf , prevents data files from being backed up by iCloud or iTunes. Default value is .On On
Block AirPrintIf , prevents access to printing by using AirPrint features to print data to AirPrint-enabled printers. Default value is .On On
Block AirDropIf , prevents an app from using AirDrop. Default value is .On On
Block email as attachment: This policy is enforced on iOS 9 only.Note
If , disables sending a note as an email with a PDF attachment. Default value is .On Off
Block file attachments: This policy is enforced on iOS 9 only.Note
If , disables downloading attachments in WorxMail. Default value is .On Off
Block Facebook and Twitter APIsIf , prevents an app from using the iOS Facebook and Twitter APIs. Default value is .On On
Obscure screen contentsIf , when users switch apps, the screen is obscured. This policy prevents iOS from recording screen contents and Ondisplaying thumbnails. Default value is .On
Block 3rd party keyboards (iOS 8 and later only)If , prevents an app from using third-party keyboard extensions on iOS 8 and later devices. Default value is .On On
Block app logsIf , prohibits an app from using the Worx App diagnostic logging facility. If , app logs are recorded and may be On Offcollected by using the Worx Home email support feature. Default value is .Off
Mail compose redirectionYou have three choices for how users are allowed to compose mail from an enterprise app:
WorxMail: If installed on the device, WorxMail automatically opens. If not, native mail does not open. Instead, users get a message instructing them to install WorxMail.Native email: The device's native mail program opens.Blocked: Both WorxMail and native mail are blocked.
Default is .WorxMail
App Network Access
Network accessPrevents, permits or redirects app network activity. If Unrestricted, no restrictions are placed on network access; apps have unrestricted access to networks to which the device is connected. If Blocked, all network access is blocked. If Tunneled to the internal network, a per-app VPN tunnel back to the internal network is used for all network access and NetScaler split tunnel settings are used.
citrix.com 93
Default value for WorxWeb and Citrix for Salesforce is Tunneled to the internal network. Default value for WorxMail and WorxNotes is Unrestricted. Default value for other apps is Blocked.
Certificate labelWhen used with the StoreFront certificate integration service, this label identifies the specific certificate required for this app. If no label is provided, a certificate is not made available for use with a public key infrastructure (PKI). Default value is empty (no certificate used).
Preferred VPN modeSets the initial mode for connections that tunnel to the internal network. Full VPN tunnel is recommended for connections that employ client certificates or end-to-end SSL to a resource in the internal network. Secure browse is recommended for connections that require single sign-on (SSO).
Permit VPN mode switchingWhen tunneling to the internal network, this policy permits switching between VPN modes automatically as needed. If On, a network request that fails due to an authentication request that cannot be handled in the preferred VPN mode is retried in the alternate mode. For example, server challenges for client certificates can be accommodated by full tunnel mode, but not when using secure browse mode. Similarly, HTTP authentication challenges are more likely to be serviced with SSO when using secure browse mode. If Off, the mode specified in the Preferred VPN mode policy is the only mode that is used. Default value is Off.
PAC file URL or proxy serverDefines the Proxy Auto-Configuration (PAC) file URL or the proxy server to use. Supported for full tunnel mode only. Specify a PAC file URL in the form http[s]://192.0.2.0/proxy.pac or http[s]://example.com/proxy.pac. For HTTPS, install the root CA on the device if the certificate is self-signed or untrusted. Specify a proxy server in the form myhost.example.com:port or 10.10.0.100:port. Default and non-default ports are accepted. Default value is empty.
Whitelisted WiFi networksComma-delimited list of allowed networks. App runs only if connected to one of the networks listed. If left blank, all networks are allowed. This doesn't affect connections to cellular networks. Default value is blank.
App Logs
Default log outputDetermines which output mediums are used by Worx app diagnostic logging facilities by default. Possibilities are , file
, or both . Default value is .console file,console file
Default log levelControls default verbosity of the Worx app diagnostic logging facility. Higher level numbers include more detailed logging.
0 - Nothing logged1 - Critical errors2 - Errors3 - Warnings4 - Informational messages5 - Detailed informational messages6 through 15 - Debug levels 1 through 10
Default value is level (Informational messages).4
Max log filesLimits the number of log files retained by the Worx app diagnostic logging facility before rolling over. Minimum is 2. Maximum is 8. Default value is .2
Max log file sizeLimits the size in megabytes (MB) of the log files retained by the Worx app diagnostic logging facility before rolling over. Minimum is 1 MB. Maximum is 5 MB. Default value is MB.2
App Geolocation and Geofencing
citrix.com 94
The GeoLocation feature allows you to restrict app usage based on the location of the user device. For example, a person travels to Amsterdam. You can allow users to use the app when they are in Amsterdam, but if the person travels to Belgium, the app locks and users cannot interact with the app. When the user returns to Amsterdam, the app unlocks and is available for normal use.
There are three settings to enable GeoLocation:
Longitude (X coordinate) is the center point of the point or radius geofence in which the app is constrained to operate. When operated outside the configured geofence, the app remains locked. Enter in a signed degrees format (DDD.dddd). For example, "-31.9635." Preface west longitudes with a minus sign.Latitude (Y coordinate) is the center point of the point or radius geofence in which the app is constrained to operate. Enter in a signed degrees format (DDD.dddd). For example, "43.06581." Preface southern latitudes with a minus sign.Radius of the geofence in which the app is constrained to operate. Express the radius in meters. Setting this value to zero disables geofencing.
If you enable , geofencing does not work correctly.Block locations services
Default is 0 (disabled).
If the app supports geofencing and you disable location services, a message appears where users can either quit the app or can click Settings that goes to the Settings screen on the Android device. If users enable locations services, they can return and continue using the app.
When the radius and location services settings are correct, the app checks for a geofence breach. If the distance between the current location and the center point (as specified in the policy) is greater than the specified radius, the user is blocked from using the app. When this occurs, users receive an option to quit the app. The user must be within the fence to continue using the app.
If the distance between the current location and then the center point is less than the specified radius, the user can continue to use the app.
The app checks the network provider (WiFi, 3G, or 4G) or the GPS Provider to find the location. The device can also use GPS and the cell phone carrier network together, which is also called high accuracy mode and helps in obtaining the location faster.
There is a two-minute time-out to allow for longer times in checking the location.
Note: To get an accurate location from the device, and to avoid users trying to circumvent Geofence by disabling WiFi or the GPS, Citrix recommends setting the policy Online session required to .On
ShareConnect App Settings
Save passwordIf , enables users to save their user name and password for their remote computer. Default value is .On On
WorxMail App Settings
WorxMail Exchange Server
The fully qualified domain name (FQDN) for Exchange Server or, for iOS only, IBM Notes Traveler server. Default value is empty. If you provide a domain name in this field, users cannot edit it. If you leave the field empty, users provide their own server information.
Caution: If you change this policy for an existing app, users must delete and reinstall the app to apply the policy change.
WorxMail user domainThe default Active Directory domain name for Exchange or, for iOS only, Notes users. Default value is empty.
Background network servicesThe FQDN and port of service addresses permitted for background network access. This might be an Exchange Server or ActiveSync server, either in your internal network or in another network that WorxMail connects to, such as mail.example.com:443.
If you configure this policy, set the Network access policy to . This policy Tunneled to the internal networktakes affect when you configure the network access policy. In addition, use this policy when the Exchange Server resides in your internal network and you want to use NetScaler Gateway to proxy the connection to the internal Exchange Server.
citrix.com 95
Default value is empty, implying that background network services are not available.
Background services ticket expirationThe time period that a background network service ticket remains valid. When WorxMail connects through NetScaler Gateway to an Exchange Server running ActiveSync, XenMobile issues a token that WorxMail uses to connect to the internal Exchange Server. This property setting determines the duration that WorxMail can use the token without requiring a new token for authentication and the connection to the Exchange Server. When the time limit expires, users must log on again to generate a new token. Defaultvalue is (7 days).168 hours
Background network service gatewayAlternate gateway address to use for background network services, in the form . This is the NetScaler Gateway fqdn:portFQDN and port number which WorxMail uses to connect to the internal Exchange Server. In the NetScaler Gateway configuration utility, you must configure the Secure Ticket Authority (STA) and bind the policy to the virtual server. For more information about configuring the STA in NetScaler Gateway, see
.NetScaler Gateway
Default value is empty, implying that an alternate gateway does not exist.
If you configure this policy, set the Network access policy to . This policy Tunneled to the internal networktakes affect when you configure the Network access policy. In addition, use this policy when the Exchange Server resides in your internal network and you want to use NetScaler Gateway to proxy the connection to the internal Exchange Server.
Export contacts
Important: Do not enable this feature if users can access your Exchange Server directly (that is, outside of NetScaler Gateway). Otherwise, contacts are duplicated on the device and in Exchange.
If , prevents the one-way synchronization of WorxMail contacts to the device and prevents the sharing of WorxMail Offcontacts (as vCards). Default value is .Off
Contact fields to exportControls contact fields to be exported to the address book. If , all contact fields are exported. If , all All Name and Phonename- and phone-related contact fields are exported. If , all name-, phone- and email-related Name, Phone, and Emailcontact fields are exported. Default value is .All
Accept all SSL certificatesIf , WorxMail accepts all SSL certificates (valid or not) and allows access. If , WorxMail blocks access when a On Offcertificate error occurs and displays a warning. Default value is .Off
Control locked screen notificationsControls whether mail and calendar notifications appear on a locked device screen. If , all information contained in Allowthe notification appears. If , notifications do not appear. If , only the name of the email Block Email sender or event titlesender or the title of the calendar event appears. If , only the count of mail and meeting invitations plus the Count onlytime of calendar reminders appear. Default value is .Allow
Default email notification
Currently, users can change email notifications on their device from Off to On. The Default email notification policy allows you to set a global policy for email notifications for your organization.
When the app checks for new policies, the new value is sent to the user device. This occurs when users install the app for the first time or upgrade the app.
If users set this policy locally and the global setting is different, the local setting does not change when users start the app.
Default value is .Off
Default sync intervalSpecifies the default sync interval for WorxMail. WorxMail users can change the default.
The Exchange ActiveSync mailbox policy setting has priority over this policy. If you specify Maximum e-mail age filtera Default sync interval that is larger than the Maxiumum e-mail age filter, the Maximum e-mail age filter setting is used instead. WorxMail displays only the sync interval values that are less than the Active Sync Maxiumum e-mail age filter setting.
Default value is .3 days
Mail Search Limit
Configuring the Secure Ticket Authority on NetScaler Gateway
citrix.com 96
Restricts the amount of mail history that is accessible from mobile devices by limiting the number of days included in mail server searches.
The options are:
90 days180 days1 yearUnlimited
To restrict the amount of mail synchronized to a mobile device, configure the policy.Max sync interval
Default value is .Unlimited
Max sync interval
Controls the amount of mail stored locally on a mobile device by limiting the sync period.
To restrict the time period that a device can search on the mail server, configure the policy .Mail server search limit
The values are:
3 days1 week2 weeks1 monthAll
Default value is 1 month.
Allowed Max Sync Period
Limits search on the device to a specified period of time. Search includes local search and server search that you configure by using two separate policies. You must set the policy on the user device and the server for the policy to be effective.
The values are:
3 days1 week2 weeks1 monthAll
Default value is 1 month.
Enable week numberIf , calendar views include the week number. Default value is .On Off
Enable download of attachments over WiFiIf , the WorxMail Download attachments option is enabled so that users can, by default, download attachments over Oninternal WiFi networks. If , the WorxMail Download attachments option is disabled so that, by default, users cannot Offdownload attachments over WiFi. Default value is .Off
Information Rights ManagementIf , WorxMail supports Exchange Information Rights Management (IRM) capabilities. Default value is .On Off
Email classificationIf , WorxMail supports email classification markings for security (SEC) and dissemination limiting markers (DLM). OnClassification markings appear in email headers as X-Protective-Marking values. Be sure to configure the related email classification policies. Default value is .Off
Email classification markingsSpecifies the classification markings to be made available to end users. The markings list contains value pairs that are separated by semicolons. Each pair includes the list value that appears in WorxMail and the marking value that is the text appended to the email subject and header in WorxMail. For example, in the marking pair UNOFFICIAL,SEC=UNOFFICIAL, the list value is UNOFFICIAL and the marking value is SEC=UNOFFICIAL.
citrix.com 97
Default value is a list of classification markings that you can modify. For the list of default markings, see .Classifications
If the list is empty, WorxMail does not include a list of protective markings.
Email classification namespaceSpecifies the classification namespace that is required in the email header by the classification standard used. For example, the namespace gov.au appears in the header as NS=gov.au. Default value is empty.
Email classification versionSpecifies the classification version that is required in the email header by the classification standard used. For example, the version 2012.3 appears in the header as VER=2012.3. Default value is empty.
Default email classificationSpecifies the protective marking that WorxMail applies to an email if a user does not choose a marking. This value must be in the list for the Email classification markings policy. Default value is .UNOFFICIAL
Enable auto-save of email draftsIf , WorxMail supports automatically saving messages to the Drafts folder. The auto-save occurs every 20 Onseconds. Default value is .On
Enable iOS data protectionThis policy is intended for enterprises which must meet Australian Signals Directorate (ASD) computer security Note:
requirements.
Enables iOS data protection when working with files. If , specifies the file-protection level when creating and opening Onfiles in the app sandbox. Default value is .Off
Google analyticsIf , Citrix collects anonymous data to improve product quality. If , no data is collected. Default value is .On Off On
Push notificationsEnables APNS-based notifications about mailbox activity. If , WorxMail supports push notifications. Default value is On
.Off
Push notifications regionThe region where the APNS host is located for your WorxMail users. Options are , , and Americas EMEA APAC. Default value is .Americas
Push notifications customer IDYour APNS customer ID, used to identify your account to the Citrix notification service. Default value is empty.
S/MIME certificate sourceSpecifies the source of S/MIME certificates. If , you must email user certificates to users, who then open the email Emailin WorxMail and import the attached certificates. If , a supported digital identity provider supplies Shared vaultcertificates to the Worx app shared vault. The integration with the third-party provider requires that you publish a related app to users. See the description for the Enable S/MIME during first WorxMail startup policy (next) for details about the user experience.
Default value is .Email
Enable S/MIME during first WorxMail startupDetermines whether WorxMail enables S/MIME during the first WorxMail startup, if the S/MIME certificate source policy is . If , WorxMail enables S/MIME if there are certificates for the user in the shared vault. If there are no Shared vault Oncertificates in the shared vault, the user is prompted to import the certificates. In both of those scenarios, users must configure certificates from a supported digital identity provider app before creating an account in WorxMail.
If , WorxMail does not enable S/MIME and the user can enable it in the WorxMail settings. Default value is .Off Off
WorxNotes App Settings
WorxNotes storage optionsAllows you to set storage options for notes that users create when using WorxNotes. If ShareFile and Exchange
, the user can choose the storage option for notes. If , notes are stored in ShareFile. If Server ShareFile only Exchange , notes are stored in Exchange Server. Default value is .only ShareFile and Exchange Server
WorxNotes Exchange ServerFully qualified domain name (FQDN) for Exchange Server. Default value is empty.
WorxNotes user domain
Email Security Classifications
citrix.com 98
Default Active Directory domain name for Exchange users. Default value is empty.
Background network servicesThe FQDN and port of service addresses permitted for background network access. This might be an Exchange Server or ActiveSync server, either in your internal network or in another network that WorxMail connects to, such as mail.example.com:443.
If you configure this policy, set the Network access policy to . This policy takes Tunneled to the internal networkaffect when you configure the Network access policy. In addition, use this policy when the Exchange Server resides in your internal network and you want to use NetScaler Gateway to proxy the connection to the internal Exchange Server.
Default value is empty, implying that background network services are not available.
Background services ticket expirationTime period that a background network service ticket should remain valid. After expiration, an enterprise logon is required to renew the ticket. Default value is hours (7 days).168
Background network service gatewayAlternate gateway address to use for background network services in the form . Default value is empty, fqdn:portimplying that there is no alternate gateway.
Accept all SSL certificatesIf , WorxNotes accepts all SSL certificates (valid or not) and allows access. If , WorxNotes blocks access when On Offa certificate error occurs and displays a warning. Default value is .Off
Usage analyticsIf , Citrix collects anonymous data to improve product quality. If , no data is collected. Default value is .On Off On
WorxTasks App Settings
You can configure the following policies for WorxTasks on iOS devices:
WorxTasks Exchange ServerFully qualified domain name (FQDN) for Exchange Server. Default value is empty.
WorxTasks user domainDefault Active Directory domain name for Exchange users. Default value is empty.
Background network servicesComma-separated list of service addresses and ports that are permitted for background network access. Each service should be of the form . Default value is empty, implying background network services are not available.fqdn:port
Background services ticket expirationTime period that a background network service ticket should remain valid. After expiration, an enterprise logon is required to renew the ticket. Default value is hours (7 days).168
Background network service gatewayAlternate gateway address to use for background network services in the form . Default value is empty, fqdn:portimplying that there is no alternate gateway.
Accept all SSL certificatesIf , WorxTasks accepts all SSL certificates (valid or not) and allows access. If , WorxTasks blocks access when On Offa certificate error occurs and displays a warning. Default value is .Off
Google analyticsIf , Citrix collects anonymous data to improve product quality. If , no data is collected. Default value is .On Off On
WorxWeb App Settings
Allowed or blocked websitesWorxWeb normally does not filter web links. You can use this policy to configure a specific list of allowed or blocked sites. You configure URL patterns to restrict the websites the browser can open, formatted as a comma-separated list. Each pattern in the list is preceded by a Plus Sign (+) or Minus Sign (-). The browser compared a URL against the patterns in the order listed until a match is found. When a match is found, the action taken is dictated by the prefix as follows:
A minus (-) prefix instructs the browser to block the URL. In this case, the URL is treated as if the web server address could not be resolved.A plus (+) prefix allows the URL to be processed normally.
citrix.com 99
If neither + or - is provided with the pattern, + (allow) is assumed.If the URL does not match any pattern in the list, the URL is allowed
To block all other URLs, end the list with a Minus Sign followed by an asterisk (-*). For example:
The policy value +http://*.mycorp.com/*,-http://*,+https://*,+ftp://*,-* permits HTTP URLs within mycorp.com domain, but blocks them elsewhere, permits HTTPS and FTP URLS anywhere, and blocks all other URLs.The policy value +http://*.training.lab/*,+https://*.training.lab/*,-* allows users open any sites in Training.lab domain (intranet) via HTTP or HTTPS, but no public URLs, such as Facebook, Google, Hotmail, and so on, regardless of protocol.
Default value is empty (all URLs allowed).
Preloaded bookmarksDefines a preloaded set of bookmarks for the WorxWeb browser. The policy is a comma-separated list that includes folder name, friendly name, and web address. Each triplet should be of the form folder,name,url where folder and name may optionally be enclosed in double quotes (").
For example, the policy values ,"Mycorp, Inc. home page",http://www.mycorp.com, "MyCorp Links",Account logon,https://www.mycorp.com/Accounts "MyCorp Links/Investor Relations","Contact us",http://www.mycorp.com/IR/Contactus.aspx define three bookmarks. The first is a primary link (no folder name) titled "Mycorp, Inc. home page". The second link will be placed in a folder titled "MyCorp Links" and labeled "Account logon". The third will be placed in the "Investor Relations' subfolder of the "MyCorp Links" folder and displayed as "Contact us"."
Default value is empty.
Home page URLDefines the website that WorxWeb loads when started. Default value is empty (default start page).
Browser user interfaceDictates the behavior and visibility of browser user interface controls for WorxWeb. Normally all browsing controls are available. These include forward, backward, address bar, and the refresh/stop controls. You can configure this policy to restrict the use and visibility of some of these controls. Default value is .All controls visible
Options:
All controls visible. All controls are visible and users are not restricted from using them.Read-only address bar. All controls are visible, but users cannot edit the browser address field.Hide address bar. Hides the address bar, but not other controls.Hide all controls. Suppresses the entire toolbar to provide a frameless browsing experience.
Enable web password cachingWhen WorxWeb users enter credentials when accessing or requesting a web resource, this policy determines whether WorxWeb silently caches the password on the device. This policy applies to passwords entered in authentication dialogs and not to passwords entered in web forms.
If , WorxWeb caches all passwords users enter when requesting a web resource. If , WorxWeb does not On Offcache passwords and removes existing cached passwords. Default value is .Off
This policy is enabled only when you also set the Preferred VPN policy to .Full VPN tunnel for this app
Google analyticsIf , Citrix collects anonymous data to improve product quality. If , no data is collected. Default value is On.On Off
Enable iOS data protectionThis policy is intended for enterprises which must meet Australian Signals Directorate (ASD) computer security Note:
requirements. Enables iOS data protection when working with files. If , specifies the file-protection level when creating and opening files Onin the app sandbox. value is .Default Off
iOS 9 security restrictionsThis policy is only enforced on iOS 9.Note:
If , disables downloading files and offline pages. cookie caching and HTML 5 local storage. On Also disbles Defaultvalue is .Off
citrix.com 100
ShareFile Worx Client App Settings
Enable secure viewerIf , the client uses a secure viewer instead of the iOS Quick Look preview feature. The MDX-based secure viewer Onensures that cut, copy, and paste operations occur only between MDX-wrapped apps. If , the secure viewer is not Offused. Default is .On
citrix.com 101
XenMobile MDX Policies for Windows Phone Apps
This article describes the MDX app policies for Windows Phone versions 8.1 and 10. You can change policy settings directly in the policy XML files or in the XenMobile console when you add an app.
Quick links to sections in this article
AuthenticationApp InteractionApp RestrictionsApp LogsWorxMail App SettingsWorxWeb App Settings
Authentication
App passcodeIf , a PIN or passcode is required to unlock the app when it starts or resumes after a period of inactivity. Default Onvalue is .On
To configure the inactivity timer for all apps, set the INACTIVITY_TIMER value in minutes in on Client Propertiesthe tab. The default inactivity timer value is 60 minutes. To disable the inactivity timer, so that a PIN or Settingspasscode prompt appears only when the app starts, set the value to zero.
Note: If you select for the Encryption keys policy, this policy is automatically enabled.Secure offlineOnline session required
If , the user must have a connection to the enterprise network and an active session. If , an active session is not On Offrequired. Default value is .Off
Maximum offline period (hours)Defines the maximum period an app can run without reconfirming app entitlement and refreshing policies from XenMobile. Default value is hours (3 days). Minimum period is 1 hour.72
Users are reminded to sign on at 30, 15, and 5 minutes before the period expires. After expiration, the app is locked until users sign on.
App Interaction
Document exchange (Open In)Blocks, permits, or restricts document exchange operations for this app. If , documents can be exchanged Restrictedonly with other MDX apps. Default value is . Restricted
Options: , , or .Unrestricted Blocked Restricted
App Restrictions
Caution: Be sure to consider the security implications of policies that block apps from accessing or using phone features. When those policies are , content can travel between unmanaged apps and the secure Worx environment.Off
Block app logsIf , an app is prohibited from using the Worx App diagnostic logging facility. If , app logs are recorded and may On Offbe collected using the Worx Home email support feature. Default value is .Off
Block cameraIf , prevents an app from directly using the camera hardware. Default value is .On Off
App Logs
Default log outputDetermines which output mediums Worx App diagnostic logging facilities use by default. Possibilities are , file console, or both . Default value is .file,console file
Default log levelControls default verbosity of the Worx App diagnostic logging facility. Higher level numbers include more detailed logging.
AuthenticationApp InteractionApp RestrictionsApp LogsWorxMail App SettingsWorxWeb App Settings
citrix.com 102
0 - Nothing logged1 - Critical errors2 - Errors3 - Warnings4 - Informational messages5 - Detailed informational messages6 through - Debug levels 1 through 1015
Default value is level (Informational messages).4
Max log filesLimits the number of log files retained by the Worx App diagnostic logging facility before rolling over. Minimum is 2. Maximum is 8. Default value is .2
Max log file sizeLimits the size in megabytes (MB) of the log files retained by the Worx App diagnostic logging facility before rolling over. Minimum is MB. Maximum is MB. Default value is MB.1 5 2
WorxMail App Settings
WorxMail Exchange ServerThe fully qualified domain name (FQDN) for Exchange Server or, for iOS only, IBM Notes Traveler server. Default value is empty. If you provide a domain name in this field, users cannot edit it. If you leave the field empty, users provide their own server information.Caution: If you change this policy for an existing app, users must delete and reinstall the app to apply the policy change.
WorxMail user domainThe default Active Directory domain name for Exchange or, for iOS only, Notes users. Default value is empty.
Background network servicesThe FQDN and port of service addresses permitted for background network access. This might be an Exchange Server or ActiveSync server, either in your internal network or in another network that WorxMail connects to, such as mail.example.com:443.
If you configure this policy, set the Network access policy to . This policy takes affect Tunneled to the internal networkwhen you configure the Network access policy. In addition, use this policy when the Exchange Server resides in your internal network and you want to use NetScaler Gateway to proxy the connection to the internal Exchange Server.
Default value is empty, implying that background network services are not available.
Background services ticket expirationThe time period that a background network service ticket remains valid. When WorxMail connects through NetScaler Gateway to an Exchange Server running ActiveSync, XenMobile issues a token that WorxMail uses to connect to the internal Exchange Server. This property setting determines the duration that WorxMail can use the token without requiring a new token for authentication and the connection to the Exchange Server. When the time limit expires, users must log on again to generate a new token. Default value is hours (7 days).168
Background network service gatewayAlternate gateway address to use for background network services, in the form . This is the NetScaler fqdn:portGateway FQDN and port number which WorxMail uses to connect to the internal Exchange Server. In the NetScaler Gateway configuration utility, you must configure the Secure Ticket Authority (STA) and bind the policy to the virtual server. For more information about configuring the STA in NetScaler Gateway, see
.Authority on NetScaler Gateway
The Default value is empty, implying that an alternate gateway does not exist. If you configure this policy, set the Network access policy to . This policy takes affect when you configure the Network Tunneled to the internal networkaccess policy. In addition, use this policy when the Exchange Server resides in your internal network and you want to use NetScaler Gateway to proxy the connection to the internal Exchange Server.
Export contactsImportant: Do not enable this feature if users can access your Exchange Server directly (that is, outside of NetScaler Gateway). Otherwise, contacts are duplicated on the device and in Exchange.If , prevents the one-way synchronization of WorxMail contacts to the device and prevents the sharing of WorxMail Offcontacts (as vCards). Default value is .Off
Google analyticsIf , Citrix collects anonymous data to improve product quality. If , no data is collected. Default value is .On Off On
WorxWeb App Settings
Configuring the Secure Ticket Authority on NetScaler Gateway
citrix.com 103
Allowed or blocked websitesWorxWeb normally does not filter web links. You can use this policy to configure a specific list of allowed or blocked sites. You configure URL patterns to restrict the websites the browser can open, formatted as a comma-separated list. Each pattern in the list is preceded by a Plus Sign (+) or Minus Sign (-). The browser compared a URL against the patterns in the order listed until a match is found. When a match is found, the action taken is dictated by the prefix as follows:
A minus (-) prefix instructs the browser to block the URL. In this case, the URL is treated as if the web server address could not be resolved.A plus (+) prefix allows the URL to be processed normally.If neither + or - is provided with the pattern, + (allow) is assumed.If the URL does not match any pattern in the list, the URL is allowed
To block all other URLs, end the list with a Minus Sign followed by an asterisk (-*). For example:
The policy value +http://*.mycorp.com/*,-http://*,+https://*,+ftp://*,-* permits HTTP URLs within mycorp.com domain, but blocks them elsewhere, permits HTTPS and FTP URLS anywhere, and blocks all other URLs.The policy value +http://*.training.lab/*,+https://*.training.lab/*,-* allows users open any sites in Training.lab domain (intranet) via HTTP or HTTPS, but no public URLs, such as Facebook, Google, Hotmail, and so on, regardless of protocol.
Default value is empty (all URLs allowed).
Preloaded bookmarksDefines a preloaded set of bookmarks for the WorxWeb browser. The policy is a comma-separated list that include folder name, friendly name, and web address. Each triplet should be of the form folder,name,url where folder and name may optionally be enclosed in double quotes (").
For example, the policy values ,"Mycorp, Inc. home page",http://www.mycorp.com, "MyCorp Links",Account logon,https://www.mycorp.com/Accounts "MyCorp Links/Investor Relations","Contact us",http://www.mycorp.com/IR/Contactus.aspx define three bookmarks. The first is a primary link (no folder name) titled "Mycorp, Inc. home page". The second link will be placed in a folder titled "MyCorp Links" and labeled "Account logon". The third will be placed in the "Investor Relations' subfolder of the "MyCorp Links" folder and displayed as "Contact us"."
Default value is empty.
Home page URLDefines the website that WorxWeb loads when started. Default value is empty (default start page).
citrix.com 104
MDX Developer's Guide
Citrix XenMobile is an enterprise solution that lets you manage mobile devices, apps, and data. The basic premise of XenMobile 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 XenMobile 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 XenMobile by adding Worx capabilities. The Worx capabilities include policies and settings, signed security certificates, and mobile app management code.
The MDX Toolkit includes the Worx App SDK, which delivers a complete set of Worx capabilities to your mobile apps through the Citrix MDX app container technology. APIs enable you to:
Perform actions in wrapped apps based on XenMobile policies. For example, if a XenMobile policy prevents cut and copy in a Worx app, you can prevent text selection in your app. Your app can communicate and share policies with other Worx-enabled apps.Detect activities within your Worx-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 Worx policies when used with XenMobile, apps that use the Worx App SDK can operate standalone outside of Citrix environments.
Quick links to article sections
The rest of this article includes a list of new features in this release, background information about app management, wrapping, and how your implementation choices affect the Worx user experience.
What's New in the Worx App SDK 10.2MAM CapabilitiesXenMobile ComponentsUnmanaged and Managed Modes for ISV AppsISV App WrappingWorx App User ExperienceKnown Issues for Worx App SDK
What's New in the Worx App SDK 10.2
The current release of Worx App SDK for iOS includes these enhancements.
Support for iOS 9. The Worx App SDK 10.2 supports iOS 9.
Important: Worx Home 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 . The policy applies on a per-app Onbasis and can be used whether you run XenMobile 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:
What's New in the Worx App SDK 10.2MAM CapabilitiesXenMobile ComponentsUnmanaged and Managed Modes for ISV AppsISV App WrappingWorx App User ExperienceKnown Issues for Worx App SDK
citrix.com 105
The user entropy feature, which is enabled through the key, is not Encrypt secrets using Passcodeaffected 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 Worx 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 . Default value.NSFileProtectionCompleteUnlessOpen
Complete – When a device locks, files become unavailable. This value corresponds to .NSFileProtectionComplete
Until lockfirst – When a device until the user unlocks the device for the first time, files are locked restarts,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 XenMobile, open the policy_metadata. file for the app (in Applications/Citrix/MDXToolkit/data) and, in the xml
section, change the value of to . After you wrap your app, MinimumDataProtectionClass PolicyHidden falsethe policy appears when you add the app to XenMobile.
For more information about iOS 9 compatibility, see .
App wrapping integration with Xcode process.build Developers can now wrap and publish an iOS app as part of the Xcode build process. For details, see .
Support for shared vault in Android apps. The Worx App SDK now includes the Android API for the Worx 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 Worx Home. For details, see .
Fixed issues. See .
MAM Capabilities
The enterprise functionality added by XenMobile is controlled through policies that administrators update on a per-app basis from the XenMobile console. XenMobile pushes policies to mobile devices on the schedule determined by administrators. Policies manage features, such as the following:
Authentication. When opening a managed app, XenMobile can require users to enter corporate credentials or a PIN. This credential challenge can be repeated on a periodic basis.App updates. XenMobile 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 8 and earlier devices, XenMobile can encrypt all locally stored data (in files or databases) using FIPS-compliant algorithms. For iOS 9 devices, XenMobile 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 XenMobile 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 XenMobile 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.
What's New in MDX Toolkit 10.2
Publishing an iOS App Using Xcode
Worx API for Android
Fixed Issues in MDX Toolkit
citrix.com 106
Feature containment. XenMobile policies can disable various device capabilities for an app. Examples include the camera, microphone, and location sensor.
XenMobile Components
The following XenMobile components provide MAM functionality.
XenMobile serverThis enterprise or cloud resident server hosts Worx Store, the internal app store. Administrators upload mobile apps to XenMobile and then configure app and device policies.
Worx HomeEnterprise users install Worx Home for Android or iOS on their mobile device and then configure the app with a device enrollment URL and credentials. When Worx Home opens, users select enterprise apps from Worx Store. After the apps download and install on the device, Worx Home serves as a hub for managing these apps, performing tasks, such as user authentication and updates of centrally administered policies.
MDXMDX 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 Worx App SDKThe MDX Toolkit adds enterprise functionality to existing mobile apps, a process called . The Worx App app wrappingSDK lets developers and system integrators Worx-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 Worx App SDK offers dual-mode app behavior, enabling you to deploy apps that can run with or without the Worx infrastructure. Apps that are run independently of Worx Home are referred to as apps. When those apps unmanagedmeet certain conditions, they transition to apps and run under the control of Worx Home.managed
The dual-mode behavior is in contrast with the Worx apps deployed from the XenMobile backend directly. Those apps always require the presence of Citrix Worx and authorization from a XenMobile Worx Store to run.
You use the Worx APIs to specify the type of dual-mode behavior needed when integrating an app with Worx. 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 Worx. The Worx 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 Worx Home can download and run the app normally in an unmanaged mode, just like any generic app store app. If an unmanaged user later installs Worx Home, the ISV app transitions to managed mode if these conditions are met.
The user signs on to a XenMobile enterprise store at least once.The user is in a XenMobile delivery group to which the app is deployed.Worx 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 Worx apps are examples of Premium apps. Although Premium apps typically run in managed mode, the embedded Worx framework allows Premium apps to run in unmanaged mode with a default set of Worx policies that you set through default policy files. Thus, you can effectively control the app behavior and use Worx capabilities even if the user is not associated with an enterprise account.
If an unmanaged user later installs Worx Home, the app silently transitions to managed mode if the following conditions are met.
citrix.com 107
The user is in a XenMobile delivery group to which the app is deployed.The user signs on to Worx Home if required.Worx 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 .
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 Worx 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.
The items added by ISV app wrapping include:
An information file containing data needed by the Worx SDK framework when the framework binds with Worx Home. The corresponding binding information is passed to Worx Home from the XenMobile server through the .mdx file added to XenMobile. 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 Worx App SDK.For iOS only: A new URL scheme that is added to the app file and is also passed to Worx Home through the .mdx file an administrator adds to XenMobile.
About the Citrix Ready Program
Citrix evaluates and certifies ISV apps through the Citrix Ready program. The evaluation largely involves XenMobile integration testing. The certification ensures that the apps are compatible with the XenMobile infrastructure, thus giving enterprises confidence in your apps.
About the MDX Toolkit
citrix.com 108
1. 2. 3. 4. 5.
1. 2.
3. 4.
1. 2.
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 Worx App Gallery or distribute the bundle directly to your XenMobile customers.
Worx App User Experience
The way users interact with an app that is integrated with the Worx App SDK depends on how they install and start the app.
User Starts with Worx Home
The user opens Worx Home and the Apple App Store or Google Play Store.The user signs on to Worx Store and then subscribes to Worx Store.The user downloads and installs the app from a public store.Worx Home prompts the user to sign on, if needed.If the app was previously unmanaged, it silently transitions to managed.
User Starts with the Apple App Store or Google Play Store
If Worx Home is present on device already, users have the following experience for General and Premium apps.
General app
The user starts the app.If the app detects an installation of Worx Home and the app is entitled, the app prompts the user to confirm the transition to managed mode.If the user opts to have their enterprise manage the app, Worx Home prompts the user to sign on if needed.After Worx subscribes the app to the user, the app transitions to managed mode.
If Worx Home 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
The user starts the app.If the app detects an installation of Worx Home and the app is entitled, the app silently transitions to managed mode. If Worx Home credentials are required, the app notifies the user about the transition to managed mode and prompts the user to sign on.
Known Issues for Worx App SDK
Wrapping doesn't work for Android apps unless they include icons.Some app frameworks have compatibility issues with XenMobile. For details, see
(for Android) and (for iOS).Frameworks SupportFor other issues, see .
Related Articles
The following articles describe how to integrate the Worx App SDK into Android and iOS apps, use the APIs, publish apps, customize policies, and ensure the highest compatibility between your apps and XenMobile.
System Requirements for the Worx App SDKDeveloping Android Apps to Deploy with XenMobileBest Practices for Android AppsWorx API for AndroidDeveloping iOS Apps to Deploy with XenMobileBest Practices for iOS AppsWorx API for iOSPolicy Defaults and Custom PoliciesTroubleshooting
Mobile App Development Frameworks Support Third Party Library Support
Known Issues in MDX Toolkit
System Requirements for the Worx App SDKDeveloping Android Apps to Deploy with XenMobileBest Practices for Android AppsWorx API for AndroidDeveloping iOS Apps to Deploy with XenMobileBest Practices for iOS AppsWorx API for iOSPolicy Defaults and Custom PoliciesTroubleshooting
citrix.com 109
1. 2.
3.
System Requirements
This article includes the system requirements for the MDX Toolkit 10.3 and the Worx App SDK.
MDX Toolkit and Worx App SDK (iOS and Android)
Java Development Kit (JDK) 1.7 or 1.8.
You can download the JDK 1.8 from on the Oracle . For web siteinstallation instructions, see the on the Oracle . Be sure to web siteinstall the full JDK; set JDK 1.8 as the default.
Mac OS X 10.10 (minimum version for iOS 9 and iOS 8 apps)Mac OS X 10.8 (minimum version for pre-iOS 8 apps)
The installer for the MDX Toolkit and Worx App SDK must run on Mac OS. The installer includes Mac OS tools that wrap both iOS and Android apps, as well as a Java command-line tool that wraps Android apps.
For Worx App SDK: iOS 9 SDK with Xcode 7, with generation disabledbitcode
Bitcode generation is on by default in Xcode 7. You must disable it to use Xcode 7 with the Worx App SDK.
Other Requirements for Wrapping iOS Mobile Apps
To obtain access to the app wrapping prerequisites for iOS, you must register for an Apple distribution account. There are three types of iOS developer accounts: Enterprise, Individual, and University. Citrix strongly recommends iOS Developer Enterprise accounts.
iOS Developer Enterprise accounts: The only type of Apple Developer account that allows you to provision, deploy, and test unlimited apps to unlimited devices, with or without app wrapping. Be sure to distribute your Developer Certificate to your developers so they can sign apps.iOS Developer Individual accounts: Limited to 100 registered devices per year and do not qualify for app wrapping and enterprise distribution with XenMobile.iOS Developer University accounts: Limited to 200 registered devices per year and do not qualify for app wrapping and enterprise distribution with XenMobile.
iOS 9 and iOS 8 app wrapping prerequisites:OS X 10.10 (Yosemite; minimum version)Xcode 7 (minimum version)Xcode command-line tools (April, 2013)
Pre-iOS 8 app wrapping prerequisites:OS X 10.8 (minimum version)Xcode 5.0 (minimum version)Xcode command-line tools (October, 2013)
Note: Download the Xcode command-line tools from the web site. Mac OS X 10.10 does not install the tools automatically. To install the tools, follow these steps:
In , click to use the Mac command-line interface. > Applications Utilities TerminalType the following command:
xcode-select --install
Be sure to include two hyphens before the word in the command.install
After the Xcode command-line tools install, run Xcodeto install any pre-requisites.
Other Requirements for Wrapping Android Mobile Apps
Android Software Development Kit (SDK), API Level 19 (minimum supported version)Download the Android SDK from the SDK on the Google developer website.Install the latest Android SDK Tools, Android SDK Platform-tools, and Android SDK Build-tools.
Java SE Development Kit DownloadsJDK 8 and JRE 8 Installation Guide
Xcode Apple Developer
download page
citrix.com 110
For details, see on the Google developer website.
Add the location of the newly installed folders to the PATH variable in your environment.Valid keystore (containing digitally signed certificates used to sign your Android apps)
You create a keystore one time and retain this file for current and future wrapping. If you do not use the same keystore when wrapping the new version of an app you previously deployed, upgrades of that app won't work. Instead, users need to manually remove the older version before installing the new version.
A keystore can contain multiple private keys; in most cases, the keystore will only have one key.
For details about certificates, see on the Android Developers website.
You must sign your apps with a key that meets the following guidelines:
1024-bit keysizeDSA key algorithm (keyalg)SHA1with DSA signing algorithm (sigalg)
Installing the Android SDK
Signing Your Applications
citrix.com 111
1. a. b. c. d.
1. 2.
Developing Android Apps
You can use the Worx API in your mobile apps to Worx-enable the apps. This article describes how to integrate the Worx App SDK into your app library and the steps required to test, certify, and publish your apps.
Quick links to sections in this article
How to Use The Worx App SDKIntegrating the SDK into Your App by Using Android Studio and GradlePublishing an Android App
How to Use The Worx App SDK
Here are some examples of how you might use the APIs.
Place restrictions on appsYou can control whether your app allows access to certain features or actions based on whether API calls indicate that the app is managed or wrapped. For example, if an app is not managed or wrapped, you might allow a user access to all features and actions. If an app is wrapped but not managed, you might then restrict certain features or actions. If an app is wrapped and managed, you might put additional restrictions on the app.
Perform actions based on XenMobile policy settingsSuppose that you want to display a notification to users if a XenMobile administrator sets the Require WiFi policy to On, which means that the app is allowed to run on a wireless network. You can use the API to look up the policy setting and then base your code changes on the policy value.
Perform actions based on custom policiesYou can use the APIs to read custom policies in your apps. For example, suppose that you want to enable XenMobile administrators to display a notification in the app. To do that, you can create a custom policy that is empty by default or contains a system message that is supplied by an administrator in the XenMobile console. When your app is managed, it can detect when the XenMobile administrator changes the policy value. If the policy value contains a message, your app displays the notification.
For API definitions, see .
Integrating the SDK into Your App Library by Using Android Studio and Gradle
To add the Worx App SDK to your Android apps, you import or copy the Worx App Java libraries into your app, as described in this section. The steps are based on Android Studio and the Gradle buld system. Going through the steps adds the WorxSDK library to your application so that its classes and methods are accessible to the app.
If you haven't already installed the latest MDX Toolkit, do so now.Log on to the page.Expand .Worx Apps and MDX ToolkitLocate the MDX Toolkit version you want to install and then click its link to begin the download.Open MDXToolkit.mpkg with the Mac OS Finder tool on Mac OS X 10.9.4 or later and Xcode 5.1 or later.
The installation path is Applications/Citrix/MDXToolkit.
The Worx App SDK files are in Applications/Citrix/MDXToolkit/data/MDXSDK_Android.
After installing the MDX Toolkit, install Android Studio from the and then do the following:
In the project directory, create a folder named libs.Add the file worxsdk.aar to the libs folder.
How to Use The Worx App SDKIntegrating the SDK into Your App by Using Android Studio and GradlePublishing an Android App
Worx API for Android
XenMobile downloads
Android developers website
citrix.com 112
3.
4.
Edit the project “build.gradle― to add a rule to search the libs folder as a repository and to include worxsdk.aar from the libs folder as a dependency.Build your APK file.
An example of worxsdk.aar:
command
// Top-level build file where you can add configuration options common to all sub-projects/modules.
buildscript {
repositories {
jcenter()
}
dependencies {
classpath 'com.android.tools.build:gradle:1.1.0'
// NOTE: Do not place your application dependencies here; they belong
// in the individual module build.gradle files
}
}
allprojects {
repositories {
jcenter()
flatDir {
dirs 'libs'
}
}
}
dependencies {
compile(name:'worxsdk', ext:'aar')
The following table lists the libraries that might cause conflicts with similar libraries in Android apps. Citrix recommends that you use the Citrix versions of the libraries to avoid conflicts.
Libraries Conflict Status
OpenSSL Will have conflicts
Publishing an Android App
After you add the Worx App SDK to an Android app, perform the following steps to wrap, test, certify, and publish the app.o When wrapping apps by using the command-line interface, include one of the following options:
–appType Enterprise -appType Premium -appType General
The default is . Use the following guidelines to select the appType:–appType Enterprise
citrix.com 113
1. 2.
3. 4. 5. 6.
7.
Enterprise apps require installing Worx Home on the user device. Also, you must also publish the application in StoreFront and install the app through Worx Home.General ISV Apps can run without Worx Home (initially). The application can transition to managed mode when the app detects Worx Home on the user device and if you publish a matching app. When running as a managed app, General apps behave the same as Enterprise apps. When running as an unmanaged app, Citrix policies are not enforced.Premium ISV apps can run without Worx Home installed on the user device (initially). The app can transition to a managed app if it detects Worx Home on the user device and if you publish a matching app. When the app runs unmanaged, MDX enforces some policies, such as the containment policies (allowing network access, screen capture, or blocking the camera).
If you need to upload the wrapped .apk file to an app store or web server, and you already know the URL, add the -storeURL option. You can also add the URL later, as indicated later in these steps.
The MDX Toolkit outputs a modified .apk file and a .mdx file. You will use those files in the following steps. Use the MDX Toolkit to wrap the .apk file for the app. For details, see Wrapping Android Mobile Apps in the MDX Toolkit documentation. That article includes all wrapping commands, including those specific to ISV apps.
The option to wrap ISV apps by using the MDX Toolkit user interface no longer available. You must wrap Important: ISV apps by using the command line.
Test your app:
Install the modified .apk file on an Android device to verify all app functions.Use the XenMobile console to add the .mdx file to XenMobile and deliver it to an Android device for testing. For details, see . On that device, test the MDX functionality of your app.
If you added custom policies, be sure to verify that those policies appear in the XenMobile console and work as expected. If you changed default_sdk_policies. , test those changes. For details about adding policies and xmlchanging policy defaults, see Policy Defaults and Custom Policies.
Fix any issues found in your app, regenerate its .apk file, and wrap it again with the MDX Toolkit.Submit the original .apk file (not the one output by the MDX Toolkit) to Citrix for validation and certification.After Citrix certifies your app, submit the .apk file generated by the MDX to the Google Play Store for approval.TookitAfter Google approves your app, run the MDX Toolkit to update the app download URL in the .mdx file. Here is an example command that changes the URL:
java -jar /Applications/Citrix/MDXToolkit/ManagedAppUtility.jar \ setinfo \ -in ~/Desktop/ / .mdx \ SampleApps Sample-out ~/Desktop/ / .mdx \ SampleApps wrapped/Sample-storeURL \ “https://play.google.com/store/apps/details?id=com.zenprise―
Provide the final .mdx file to a XenMobile administrator, who will add it to XenMobile and publish it to users. Or, to make your app available for wider distribution, you can list your Worx verified app in the . For details, see .
Considerations for Upgrading Apps
The Citrix XenMobile software changes significantly between releases. To take advantage of the latest features and bug fixes, you must use the latest version of the MDX Toolkit to wrap your app. Be sure to wrap your original .ipa or .apk file, not the modified file that was previously generated by the MDX Toolkit.
Be sure to use the corresponding version of the Worx App SDK.
To add an MDX app to XenMobile
Citrix Ready MarketplaceCitrix Ready Worx Verified Program
citrix.com 114
Best Practices for Android Apps
The best practices discussed in this article improve compatibility between XenMobile and mobile apps for Android devices.
Worx App SDK and Wrapping
If your app uses the Worx App SDK, then you must use the matching MDX Toolkit version for wrapping. A version mismatch between these two components might cause improper operation.
To prevent such a mismatch, wrap the app with an app type of Premium or General. That lets you deliver a pre-wrapped app. As a result, your customer won't need to wrap the app, thus avoiding use of a mismatched MDX Toolkit. For details about wrapping apps, see Wrapping Android Mobile Apps in the MDX Toolkit documentation.
Don't Block the Main Thread
You should not use blocking code when running on the main thread. This is a Google guideline, but it is even more crucial with XenMobile. Some actions may take more time in a managed app or may even block further thread execution.
Blocking code includes, but is not limited, to the following:
File or database operationsNetwork operations
To be clear, all app lifecycle methods, such as onCreate, run on the main thread.
Google provides a StrictMode API which can help detect blocking code. For details, see this blog post: .developers.blogspot.com/2010/12/new-gingerbread-api-strictmode.html
Write Robust Code
In particular, you should check return values or catch exceptions from framework APIs. While this is just a common programming best practice, it is especially important for managed apps.
Various APIs that you'd expect to always work will fail if XenMobile policies block the underlying functionality. Examples would include any of the capabilities described earlier:
Networking APIs fail as if there is no network available.Sensor APIs, such as GPS and camera, return null or throw an exception.Intents directed at a non-managed app fail.File and database access might fail if used from the main thread. For details, see
and , later in this article.Compatibility
When you encounter a failure, your app should handle the issue gracefully instead of crashing.
Hooking Limitations
MDX injects functionality into a binary Android app by modifying the DEX code in the APK. Several limits are present:
XenMobile might not manage deprecated framework classes from the pre-4.0 Android SDK versions. Be sure to avoid those deprecated classes.Most functionality is injected into the Java/Android framework APIs. Native (C/C++) code is generally not managed. One exception is that even for native code, file encryption still occurs.Native code that uses JNI to access Java functionality must only target code in the user app. In other words, don't use JNI to directly invoke Java or Android framework methods. Instead, use the proxy design pattern to "wrap" the desired framework class in a Java class of your own. Then invoke your class from the native code.
Ensure Data Encryption Compatibility
One of the primary features of MDX is that all persisted data is transparently encrypted. You don't need to modify your app to gain this functionality and, in fact, you can't directly avoid it. The administrator has the ability to disable encryption either selectively or entirely, but the app does not.
http://android-developers.blogspot.com/2010/12/new-gingerbread-api-strictmode.html
Ensure Data Encryption Compatibility Encryption User Entropy
citrix.com 115
1.
2.
3. 4.
This is one of the more heavyweight aspects of MDX and requires an understanding of the following points:
File encryption is present for all Java and native code that runs in managed processes.Some framework APIs, such as media players and printing support, actually run in separate OS processes. If you use such an API, you might encounter issues.
Example: Your app saves a file to disk (encrypted) and then passes a reference to the file to a media API. The media API tries to read the file but it doesn't understand the encrypted content. It fails or even crashes the app.Example: You create a file handle (that starts an encrypted file) and give it to the camera API. The camera process directly writes unencrypted data into the encrypted file. When your app tries to read that data, the data is decrypted, yielding garbage.
One method of handling separate processes is to decrypt a file before handing it to the relevant API. Or if the API writes data, then you'd let it write first and then you'd encrypt it when the API finished. A few steps are required:
Designate an area that will remain unencrypted. You must document this for your customer, because a XenMobile administrator must create an encryption exclusion policy.To decrypt, you simply copy the file from the normal (encrypted) location to the decrypted location. Note that you must do a byte copy and not a file move operation.To encrypt, reverse the direction. Copy from unencrypted to encrypted locations.Delete the unencrypted file when no longer needed.
Memory mapping is not supported for encrypted files. If you call an API that does memory mapping, it will fail. You should handle the error. If at all possible, avoid direct and indirect use of memory mapping. One notable case of indirect use is the third-party SqlCipher library.
If you can't avoid memory mapping, the administrator must specify an encryption exclusion policy that omits the relevant files. You must document this policy for your customer.
Encryption adds measurable overhead. Be sure to optimize file I/O to prevent performance degradation. As an example, if you are repeatedly reading and writing the same information, you might want to implement an app level cache.Databases are just files and so they are also encrypted. Performance can be an issue here too. The standard database cache size is 2000 pages or 8 megabytes. If your database is large, you might increase this size.
SQLite WAL mode is not supported due to the memory mapping limitation.
Encryption User Entropy
One XenMobile option for encryption requires the end user to enter a PIN before the encryption key can be generated. This option is called user entropy. It can cause a particular issue for apps.
Specifically, no file or database access can be performed until the user enters a PIN. If such an I/O operation is present in a location that runs before the PIN UI can be displayed, it will always fail. There are a few implications:
Keep file and database operations off the main thread. For example, an attempt to read a file from the app object's onCreate() method will always fail.Background operations, such as services or content providers, may run even though no app activity is present. These background components can't display the PIN UI and therefore they can't perform file or database access. Note that once an activity runs in the app, the background operations are allowed to perform I/O operations.
There are several failure mechanisms if the encryption key isn't available due to user entropy:
If the main thread accesses a database before the PIN is available, the app is killed.If a non-main thread accesses a database before the PIN is available, that thread is blocked until the PIN is entered.For non-database access started before the PIN is available, the open operation will fail. At the C level, an EACCES error is returned. In Java, an exception is thrown.
To ensure that this issue isn't present in your app, test with user entropy enabled. The XenMobile client property, Encrypt secrets using Passcode, adds user entropy. You configure that client property, which is disabled by default, in the XenMobile console under .Configure > Settings > More > Client Properties
Networking and micro VPN
citrix.com 116
1.
2.
3.
4.
5.
1.
Several XenMobile policy options are available to administrators for networking. The Network access policy prevents, permits or redirects app network activity as follows:
By default, the network is completely blocked for an app. If the Network access policy is set to , Blockednetworking APIs used by your app will fail. Per the previous guideline, you should gracefully handle such a failure.If the Network access policy is set to , all network calls go directly and are not tunneled.UnrestrictedIf the Network access policy is set to , all network calls are tunneled through Tunneled to the internal networkthe NetScaler Gateway. The tunneling under this policy is controlled by the Preferred VPN mode policy.
The Preferred VPN mode policy sets the initial mode for connections that tunnel to the internal network:
If the Preferred VPN mode policy is set to , the http/https URL is rewritten. Secure browse Secure browsecan tunnel only http and https traffic. A significant advantage of secure browse is Single Sign On (SSO) for http and https traffic and also PKINIT authentication. On Android, secure browse has low setup overhead and is thus the preferred option for web browsing type of operations.If the Preferred VPN mode policy is set to , all traffic from the managed app is tunneled Full vpn tunnelthrough NetScaler Gateway. On Android, this mode runs a device-wide VPN but its use is restricted to only the managed apps.
Limitation: XenMobile doesn't support socket server. If a socket server is running inside the wrapped app, the network traffic to the socket server is not tunneled through NetScaler Gateway.
Mobile App Development Frameworks Support
Some app frameworks have compatibility issues with XenMobile:
Apps developed with Xamarin are not supported.With PhoneGap, the location service is not blocked.SQLCipher doesn't work with encryption because it uses memory mapping. One solution is to not use SQLCipher. A second solution is to exclude the database file from encryption using an encryption exclusion policy. A XenMobile administrator must configure the policy in the XenMobile console.
Debugging Tips
When debugging a wrapped app, consider these tips.
Determine if the issue is present in an unwrapped version of the app. If the issue occurs when unwrapped, use normal debugging techniques.Try turning off various XenMobile policies.
This can help localize any incompatibility. Disabling a policy means that MDX no longer enforces the related restriction, thus enabling you to test those features as if the app were unwrapped.If disabling a policy fixes the problem, the issue might be that the app isn't checking for errors in the associated APIs.
If an unmodified but re-signed app doesn't run:Un-jar the contents of the APK using JAR:
jar xvf {some.apk}
Delete the META-INF folder:
rm -rf META-INF
Re-jar the contents into a new APK using JAR:
jar cvf {/tmp/new.apk} *
Sign the new APK using JARSIGNER:
jarsigner -keystore {some.keystore} -storepass {keystorepassword} -keypass {keypassword} {/tmp/new.apk} {keyalias}
If the app still doesn't run, you cannot wrap the app using a different signing certificate than the original APK used.
If a decompiled or recompiled .apk doesn't run:Decompile and recompile using APKTOOL:
citrix.com 117
1.
2. 3.
1.
2.
a. b.
c. d.
1.
2.
1. 2. 3.
apktool d {some.apk} -o {some.directory}
apktool b {some.directory} -o {new.apk}
Sign the APK using JARSIGNER as described above.If the app still doesn't run, this is a third-party APKTOOL bug.
If app wrapping doesn't work:Try removing the APKTOOL framework and rewrapping.
Mac/Linux: rm -rf ~/Library/apktool/frameworkWindows: del /q /s C:\Users\{username}\apktool\framework
Compare which APKTOOL is being used by the wrapper with the one you used to successfully decompile and recompile in the previous step.
If it is the same APKTOOL version, then there is a bug in Wrapper.If it is a different APKTOOL version, then there might be a bug in the APKTOOL integrated into the MDX Toolkit utility.
Un-jar the contents of ManagedAppUtility.jar.Overwrite with contents of APKTOOL.jar that you used to successfully wrapped the app in the previous step.Re-jar the contents into a new ManagedAppUtility.jar.Wrap the app to confirm the bug in the embedded APKTOOL.
Run the wrapped app and capture log information.Use grep to investigate what is happening in the app.
To follow the app's Activities: grep "MDX-Activity"
To follow MDX locking of the app: grep "MDX-Locked"
To see both logs together: egrep "MDX-Act|MDX-Loc"
If there is an Application Not Responding error, pull the ANR traces using ADB.If a problem occurs when interacting with multiple apps, such as when using Open in:
Verify encryption policies and security group settings are the same between the apps.Try a different app. It might be a bug in one of the apps being tested.Capture logs from all apps involved. Note that Worx Home can bundle logs and email logs from individual apps. From the My Apps screen, swipe right to the Support screen. Then click the Need Help button at the bottom of the screen.
In addition to the tools mentioned above, the following might also help:
AAPT to dump information about the app.
aapt dump badging {some.apk}
DUMPSYS command on device.
adb shell dumpsys 2>&1 | tee {dumpsys.out}
DEX2JAR to recompile classes into pseudo-Java.
dex2jar {some.apk}
Convert classes from Dual-Dex wrapped apps:
apktool d {some.apk} -o {some.dir}
dex2jar {some.dir}/assets/secondary-1.dex
JD-GUI to view pseudo-Java code.BAKSMALI to decompile app classes from Dual-Dex wrapped apps.
Decompile the wrapped APK:
apktool d {some.apk} -o {some.dir}
Decompile the app's classes that do not get decompiled from above call:
baksmali {some.dir}/assets/secondary-1.dex -o {some.dir}/smali
citrix.com 118
Worx API for Android
The Worx API for Android is based on Java. This article summarizes the Worx APIs by feature and provides the API definitions.
Feature APIs
App managementisManaged
isWrapped
MDX policies
getPoliciesXML
getPolicyValue
setPolicyChangeMessenger
Shared vault MDXDictionary
User data getUserName
Class com.citrix.worx.sdk.MDXApplication
Methods
isManaged
public static boolean isManaged (Context context)
Checks if the app is currently managed by MDX, which means that the Citrix Worx Home app is installed on the device and XenMobile policies are enforced on your app. The XenMobile backend infrastructure (key vaults) are queried for data encryption partial keys (secrets) which MDX will use to encrypt application file data. Returns trueif the app is managed.
Unmanaged Premium apps use the XenMobile policy defaults specified in Applications/Citrix/MDXToolkit/data/MDXSDK_Android/default_sdk_policies.xml. Policies are not enforced for unmanaged General apps.
Parameters:
context – The Android context that is making this call.
Example:
boolean bIsManaged = MDXApplication.isManaged(context);
isWrapped
public static boolean isWrapped (Context context)
Returns if the app is wrapped with the MDX Toolkit.true
Parameters:
context – The Android context that is making this call.
Example:
boolean bIsWrapped = MDXApplication.isWrapped(context);
getUserName
public static String getUserName (Context context)
citrix.com 119
Returns a string containing the user name of an enrolled user running an MDX-managed app, regardless of the user sign-on status. Returns nil if the user isn't enrolled, the app isn't managed, or the app isn't wrapped.
Parameters:
context – The Android context that is making this call.
Example:
String userName = MDXApplication.getUserName(context);
Class com.citrix.worx.sdk.MDXPolicies
Methods
getPoliciesXML
public static String getPoliciesXML (Context context)
Returns the contents of default_sdk_policies.xml, as one line per policy, prefixed with to indicate that the (match)value in the XML file matches the value returned by . Returns an empty String MDXPolicies.getPolicyValue()on failure.
Parameters:
context – The Android context that is making this call.
Example:
String policiesXML = MDXPolicies.getPoliciesXML(context);
getPolicyValue
public static String getPolicyValue (Context context, String policyName)
Returns a String which contains current value of the named policy. Returns if no value is found.null
Parameters:
context – The Android context that is making this call.
policyName – The name of the policy to search for. A policy name is the value of the element in <PolicyName>a policy XML file.
Example:
String value = MDXPolicies.getPolicyValue(context, "DisableCamera");
setPolicyChangeMessenger
public static String setPolicyChangeMessenger (Context context, String policyName, Messenger messenger)
Registers a Messenger to receive a message when the given policy’s value changes. When MDX detects that a policy value changed in the XenMobile console, MDX notifies this messenger. You can then use the other APIs to re-read the policy values and change your app. Returns .null
Parameters:
context – The Android context that is making this call.
policyName – The policy name to monitor. A policy name is the value of the element in a policy <PolicyName>XML file.
citrix.com 120
messenger – The messenger that will receive messages when the policy value changes.
Example:
MDXPolicies.setPolicyChangeMessenger(context, "DisableCamera", messenger);
Class com.citrix.mdx.common.MDXDictionaryMDXDictionary is a container for reading and storing encrypted Android bundles of key-value pairs. Worx apps in the same MDX security group share a dictionary. Use the shared vault API to share managed content between apps that have the same MDX dictionary. For example, you can share certificates and private keys through an enrolled app so that apps can obtain a certificate from the secure vault instead of from Worx Home.
Dictionaries are stored encrypted regardless of the Private file encryption policy and Public file encryption policy settings. Developers must unlock the vault before retrieving dictionaries.
Constructors
public MDXDictionary( MDXDictionary source )
Constructs a copy of an existing MDXDictionary.
Parameters:
source – The MDXDictionary that should be copied.
public MDXDictionary( String name, Bundle bundle, long sequence )
Constructs an MDXDictionary from a name, bundle, and sequence number. If you do not know the sequence number, use the create() factory method.
Parameters:
name – The name of the dictionary.
bundle – The Android bundle.
sequence – A sequence number.
Methods
public static MDXDictionary create( Context context, String name )
Creates a dictionary by first checking if a dictionary with the same name already exists. If the dictionary does not exist, then a new dictionary is returned. Otherwise, the existing dictionary is returned. This method never returns null.
Parameters:
context – The Android context that is making this call.
name – The name of the dictionary.
Example:
// Creates a instance of a dictionary.MDXDictionary dict = MDXDictionary.create(getContext(), "app-settings");
citrix.com 121
public static boolean delete( Context context, String name )
Deletes a dictionary by name. Returns true on success; returns false on failure.
Parameters:
context – The Android context that is making this call.
name – The name of the dictionary.
Example:
// Creates a instance of a dictionary.MDXDictionary.delete(getContext(), "app-settings");
public static MDXDictionary find( Context context, String name )
Finds an existing dictionary. Returns an existing dictionary; returns null if no dictionary is found.
Parameters:
context – The Android context that is making this call.
name – The name of the dictionary.
Example:
MDXDictionary dict = MDXDictionary.find(getContext(), "app-settings");
if( dict != null ) { // Use dictionary }
public boolean isNew( )
Checks whether this is a new dictionary or an existing dictionary. Returns true if a dictionary does not already exist.
Example:
MDXDictionary dict = MDXDictionary.create(getContext(), "app-settings");
if (dict.isNew()) { // Dictionary was not found. } else { // Existing dictionary was found. }
public boolean save( Context context )
Stores an encrypted dictionary. If a dictionary with the same name exists, it will be overwritten. Returns true on success; returns false on failure.
Parameters:
context – The Android context that is making this call.
Example:
citrix.com 122
MDXDictionary dict = MDXDictionary.find(getContext(), "app-settings");
if( dict != null ) { String certificate = getCertificate(); dict.bundle.putString( "secret-certificate", certificate ); // Update bundle by overwriting the existing bundle. dict.save( getContext() ); }
public boolean append( Context context )
Appends an encrypted dictionary to an existing dictionary. If no dictionary exists, then the specified dictionary is stored. Returns true on success; returns false on failure.
Parameters:
context – The Android context that is making this call.
Example:
MDXDictionary dict = MDXDictionary.find(getContext(), "app-settings");
if( dict != null ) { String certificate = getCertificate();
Bundle bundle = new Bundle(); bundle.putString( "secret-certificate", certificate );
dict.bundle = bundle; dict.append( getContext() );
// Note that dict.bundle may not match the state of the // bundle that was stored. The stored bundle could be // larger. }
public boolean delete( Context context )
Deletes the dictionary. Returns true on success; returns false on failure.
Parameters:
context – The Android context that is making this call.
Example:
MDXDictionary dict = MDXDictionary.find(getContext(), "app-settings");
if( dict != null ) { dict.delete( getContext() ); }
Note
Constructors will throw an when bad parameters are passed in.IllegalArgumentExceptionThe operation will never return null. If the encryption policy is enabled, the user is responsible create()for ensuring it is unlocked before is called.create()
citrix.com 123
The operation can fail if a stored object that can be parsed or serialized is not a known Java append()or Android datatype. Worx Home is unable to unmarshal the dictionary because the class is not known internally to Worx Home.The operation will append its bundle to an existing dictionary bundle. If the stored bundle is append()different than the bundle in the dictionary, the local bundle will not reflect the state of the bundle stored. A operation or a operation is necessary to query the state of previously stored bundle.find() create()
citrix.com 124
Developing iOS Apps
You can use the Worx API to enable your mobile apps for Worx. This article describes how to integrate the Worx App SDK into your app library and the steps required to test, certify, and publish your apps.
Quick links to sections in this article
How to Use The Worx App SDKIntegrating the SDK into Your App LibraryAdding the SDKPrep Command-Line ToolConsiderations for Upgrading Apps
How to Use the Worx App SDKHere are some examples of how you might use the APIs.
Place restrictions on appsYou can control whether your app allows access to certain features or actions based on whether API calls indicate that the app is managed or wrapped. For example, if an app isn't managed or wrapped, you might allow a user access to all features and actions. If an app is wrapped but not managed, you might then restrict certain features or actions. If an app is wrapped and managed, you might put additional restrictions on the app.
Perform actions based on XenMobile policy settingsSuppose that you want to display a notification to users if a XenMobile administrator sets the Require WiFi policy to On, which means that the app is allowed to run only from inside your organization's network. You can use the API to look up the policy setting and then base your code changes on the policy value.
Perform actions based on custom policiesYou can use the APIs to read custom policies in your apps. For example, suppose that you want to enable XenMobile administrators to display a notification in the app. To do that, you can create a custom policy that is empty by default or contains a system message that is supplied by an administrator in the XenMobile console. When your app is managed, it can detect when the XenMobile administrator changes the policy value. If the policy value contains a message, your app displays the notification.
For API definitions, see Worx API for iOS
Integrating the SDK into Your App LibraryTo add the Worx App SDK to your iOS apps, link the SDK framework into your app as described in this section. The Worx App SDK for iOS, based on Objective-C, is a collection of header files and a static library.
1. If you haven't already installed the latest MDX Toolkit, do so now.
a. Log on to the page.
b. Expand .Worx Apps and MDX Toolkit
c. Locate the MDX Toolkit version you want to install and click the link to begin the download.
d. Open MDXToolkit.mpkg with the Mac OS Finder tool on Mac OS X 10.9.4 or later and Xcode 7 or later.
The installation path is Applications/Citrix/MDXToolkit.
The Worx App SDK files are in Applications/Citrix/MDXToolkit/data/MDXSDK.
How to Use The Worx App SDKIntegrating the SDK into Your App LibraryAdding the SDKPrep Command-Line ToolConsiderations for Upgrading Apps
Worx API for iOS
XenMobile downloads
citrix.com 125
After installing the MDX Toolkit on your computer, integrate Worx Framework into your Xcode project.
2. Add the data/MDXSDK folder to the Apple Xcode project. To do so, you can drag that folder to the Xcode project.
3. Revise a line of code in the pre-compiled header file in the app project to import WorxEnable.h from Worx.framework as shown in the following example.
command
#ifdef__OBJC___//import MDX extensions#import <AVFoundation/AVFoundation.h>#import <SystemConfiguration/SCNetworkReachability.h>#import <Worx/WorxEnable.h>#endif
4. Add the following to “other linker flags― if they do not already appear:
–lsqlite3–ObjC–lxml2-u _FIPS_text_start-u _FIPS_text_end-u _FIPS_rodata_start-u _FIPS_rodata_end
5. Add the following frameworks and libraries:
AssetsLibrary.frameworkAudioToolbox.frameworkAVFoundation.frameworkCFNetwork.frameworkCoreData.frameworkCoreLocation.frameworkCoreTelephony.frameworkJavaScriptCore.frameworkLocalAuthentication.frameworkMessageUI.frameworkMobileCoreServices.frameworkPhotos.frameworkQuickLook.frameworkSecurity.frameworkSocial.frameworkSystemConfiguration.frameworkLibresolv.dylibLibstdc++.dylibLibz.dylib
The following table lists the libraries that can cause conflicts with similar libraries in your iOS app. Citrix recommends that you use the Citrix versions of the libraries to avoid conflicts.
Libraries Conflict Status
OpenSSL 1.0.1H No major modifications as-is with FIPS support. Will have conflicts.
Thrift No major changes but some improvements done internally. Will have conflicts.
7. Add a run script to add the SDKprep command tool. For more information, see .
Publishing an iOS App by Using Xcode
citrix.com 126
1.
2.
8. For Xcode 5 and later, change the default flag for to . This setting is in the build settings of Strip Linked Product Noyour project.
9. Compile your project and generate the app binaries.
10. Compile and archive the project to generate the app bundle that contains the embedded Worx Framework; that is, the .ipa package.
Adding the SDKPrep Command-Line ToolApps that use the Worx framework must use the command. The wrap command is deprecated for apps with SdkPrep the SDK linked in.
You must run the MDX Toolkit command line as part of the Xcode build process, eliminating the need to wrap the app outside of Xcode. After Xcode builds the SDK app, test, debug, and then upload the app to the app store or to TestFlight directly from Xcode.
If you plan to use the SDK for an Enterprise app, there are two requirements:
Run the command in the Xcode run script and supply the parameter – , which is the SdkPrep Apptype Enterprisedefault parameter.After the Xcode build and archive steps creates the IPA bundle, run the command on the MDX file along with SetInfothe command option to insert the final IPA file into the MDX file. After this, you can upload the app –EmbedBundle to XenMobile.
To publish an iOS app with Xcode
1. Select your project in Xcode and then select the tab. Click the plus (+) icon in the upper-left corner and Build Phasesthen select .New Run Script Phase
2. Open the new Run Script and then type (do not copy or paste) the following text into the field. Be sure to Scriptchange the , , , and variables to values that are applicable to your PACKAGEID APPTYPE STOREURL POLICYFILEapp. The is a unique identifier for your app, typically a UUID.PACKAGEID
Note: The supported keywords for are Enterprise, Premium, and General.APPTYPE Type the following into the field. Copy and paste will not work correctly.Important: Script
export PACKAGEID=" "your-project-PackageIDexport APPTYPE=" "keywordexport STOREURL="http:// "your-store-URLexport POLICYFILE=${SRCROOT}/${EXECUTABLE_NAME}/${EXECUTABLE_NAME}_policy_metadata.xml/Applications/Citrix/MDXToolkit/CGAppCLPrepTool SdkPrep -in "${CODESIGNING_FOLDER_PATH}" -out "${BUILT_PRODUCTS_DIR}/${EXECUTABLE_NAME}.mdx" -storeUrl "${STOREURL}" -appIdPrefix "ABCDEFGH" -packageId "${PACKAGEID}" -policyXML "${POLICYFILE}" -entitlements "${CODE_SIGN_ENTITLEMENTS}"
For example:
export PACKAGEID="a96d6ed5-6632-4739-b9b6-9ad9d5600732"export APPTYPE="Enterpriseexport STOREURL="http://example.com/12345"export POLICYFILE=${SRCROOT}/${EXECUTABLE_NAME}/${EXECUTABLE_NAME}_policy_metadata.xml/Applications/Citrix/MDXToolkit/CGAppCLPrepTool SdkPrep -in "${CODESIGNING_FOLDER_PATH}" -out "${BUILT_PRODUCTS_DIR}/${EXECUTABLE_NAME}.mdx" -storeUrl "${STOREURL}" -appIdPrefix "ABCDEFGH" -packageId "${PACKAGEID}" -policyXML "${POLICYFILE}" -entitlements "${CODE_SIGN_ENTITLEMENTS}"
Parameters Description
-in filename Path to the .app file generated by Xcode. The MDX Toolkit embeds MDX-specific resources into this file.
-out filename Destination path for the .mdx file. Use this file to publish the app on the XenMobile server.
-storeUrl urlApp store URL for the app, embedded into the .mdx file. Cannot use this parameter with -StoreURL.
citrix.com 127
-appType Keyword Keywords are "Enterprise," "Premium," and "General."
-packageId UUIDThe unique package ID for this app, typically a UUID.
-policyXML filenamePath to the MDX policy template file for your app.
-entitlements filename Optional. Path to the entitlements file. The MDX Toolkit adds to this file a keychain access group entry for com.citrix.mdx, needed for your app to share secrets between MDX apps signed with the same certificate. This allows both ISV and regular wrapped apps that are signed with the same certificate to share data using the keychain.
-appIdPrefix prefix (Optional) Application Identifier Prefix (often the same as the Team ID).
3. Build your app in Xcode, verifying that it builds correctly.
4. Archive your app by selecting .Product > Archive
5. The Xcode Organizer should open automatically after your app is archived.
6. Select your archived build in Organizer and then click .Export
7. Select the applicable export method and then click .Next
8. Follow the prompts to export your app to an IPA file.
9. You can also submit directly to the app store or TestFlight, if you have configured the app by using the iTunes Connect website.
10. Go to the directory containing the .app file and add that MDX file to XenMobile. For details, see .to XenMobile
Considerations for Upgrading AppsThe XenMobile software can change significantly between releases. To take advantage of the latest features and bug fixes, you must use the latest version of the MDX Toolkit to wrap your app. Be sure to wrap your original .ipa or .apk file, not the modified file that was previously generated by the MDX Toolkit.
Be sure to use the corresponding version of the Worx App SDK.
To add an MDX app to XenMobile
citrix.com 128
Best Practices for iOS Apps
When developing iOS apps, use these best practices to improve compatibility between XenMobile and mobile apps for iOS devices.
Worx App SDK Framework and Wrapping
If your app uses the Worx App SDK Framework, then you must use the matching MDX Toolkit version for wrapping. A version mismatch between these two components might cause improper operation.
To prevent such a mismatch, wrap the app as an ISV app and specify an app mode of Premium or General. That lets you deliver a pre-wrapped app. As a result, your customer won't need to wrap the app, thus avoiding use of a mismatched MDX Toolkit. For details about ISV wrapping, see in the MDX Toolkit documentation.
Use Explicit App IDs
If your iOS Developer Enterprise account does not support wildcard App IDs, be sure to create an explicit App ID for each app you plan to wrap with the MDX Toolkit and create a provisioning profile for each App ID.
Don't Block the Main Thread
You should not use blocking code when running on the main thread. This is an Apple guideline, but it is even more crucial with XenMobile. Some actions may take more time in a managed app or may even block further thread execution. File, database, and network operations are examples of operations which might block the currently running thread when issued and should be avoided on the main thread.
Write Robust Code
In particular, you should write apps following the best practices as documented in the Apple programming guides, such as the .
Use only Apple published interfaces.
Always check return values from all API calls and handle any exceptions which may occur as a side effect of an API call, to ensure graceful error recovery or graceful termination of the app. While this is a common programming best practice, it is especially important for managed apps.
Various APIs that you'd expect to always work will fail if the underlying functionality has been blocked due to XenMobile policies. Examples would include any of the capabilities described earlier:
Networking APIs fail as if there is no network available.Sensor APIs, such as GPS and camera, return null or throw an exception.
The following Objective-C runtime selectors will return nil if the underlying functionality has been blocked due to XenMobile policies and so should be handled accordingly.
Object Class Name Selector Name
AVCaptureDevice devicesWithMediaType:
MFMailComposeViewController init:
MFMessageComposeViewController initWithNibName:bundle:
NSFileManager URLForUbiquityContainerIdentifier:
NSUbiquitousKeyValueStore defaultStore:
PHPhotoLibrary sharedPhotoLibrary
UIImagePickerController availableCaptureModesForCameraDevice:
Wrapping iOS Mobile Apps
Apple Application Programming Guide
citrix.com 129
UIPasteboard dataForPasteboardType:
valueForPasteboardType:
Items:
dataForPasteboardType:inItemSet:
valuesForPasteboardType:inItemSet:
UIPopoverController initWithContentViewController:
UINavigationController ctxInitWithRootViewController:
ctxPopToViewController:animated:
Redirect Runtime Interfaces
XenMobile provides UI Pin Prompt interaction so you don't have to do it in your app.
To ensure XenMobile readiness, it is suggested that you don't redirect or substitute Objective-C runtime selectors since XenMobile swizzles the underlying methods of several object class selectors to control and/or modify the runtime behavior of an app. The following table lists the Objective-C class selectors which XenMobile redirects:
Object Class Name Selector Name
NSURLProtectionSpace serverTrust
NSURLAuthenticationChallenge sender
NSURLConnection sendSynchronousRequest:returningResponse:error:
initWithRequest:delegate:startImmediately:
initWithRequest:delegate:
connectionWithRequest:delegate:
NSURLConnectionDelegate connection:canAuthenticateAgainstProtectionSpace:
connection:didReceiveAuthenticationChallenge:
connection:willSendRequestForAuthenticationChallenge:
NSURLSessionConfiguration defaultSessionConfiguration
ephemeralSessionConfiguration
ALAssetsLibrary authorizationStatus
AVAudioRecorder record
prepareToRecord
recordForDuration:
recordAtTime:
recordAtTime:ForDuration:
citrix.com 130
AVAudioSession recordPermission
AVCaptureDevice devices
devicesWithMediaType:
AVAsset assetWithURL:
AVURLAsset initWithURL:options:
URLAssetWithURL:options:
AVPlayerItem playerItemWithAsset:
initWithURL:
playerItemWithURL:
AVPlayer playerWithPlayerItem:
playerWithURL:
initWithPlayerItem:
initWithURL:
CLLocationManager startUpdatingLocation
UIScrollView setContentOffset:
MFMailComposeViewController canSendMail
init
MFMessageComposeViewController canSendText
initWithNibName:bundle:
NSFileManager URLForUbiquityContainerIdentifier:
NSUbiquitousKeyValueStore defaultStore
PHPhotoLibrary authorizationStatus
QLPreviewController setDataSource:
canPreviewItem:
QLPreviewControllerDataSource numberOfPreviewItemsInPreviewController:
previewController:previewItemAtIndex:
SLComposeViewController isAvailableForServiceType:
UIActivityViewController initWithActivityItems:applicationActivities:
setExcludedActivityTypes:
UIApplication openURL:
citrix.com 131
canOpenURL:
setApplicationIconBadgeNumber:
UIDocument closeWithCompletionHandler:
contentsForType:error:
UIDocumentInteractionController interactionControllerWithURL:
setURL:
setDelegate:
presentPreviewAnimated:
presentOpenInMenuFromBarButtonItem:animated:
presentOpenInMenuFromRect:inView:animated:
presentOptionsMenuFromBarButtonItem:animated:
presentOptionsMenuFromRect:inView:animated:
UIDocumentMenuViewController initWithDocumentTypes:inMode:
UIImage imageNamed:
UIImagePickerController setSourceType:
takePicture
startVideoCapture
isSourceTypeAvailable:
isCameraDeviceAvailable:
isFlashAvailableForCameraDevice:
availableCaptureModesForCameraDevice:
setMediaTypes
UINavigationController ctxInitWithRootViewController:
ctxPushViewController:animated:
ctxPopToViewController:animated:
UIPasteboard generalPasteboard
pasteboardWithName:create:
pasteboardWithUniqueName
setValue:forPasteboardType:
setData:forPasteboardType:
citrix.com 132
setItems:
addItems:
dataForPasteboardType:
valueForPasteboardType:
numberOfItems
pasteboardTypes
pasteboardTypesForItemSet:
containsPasteboardTypes:
containsPasteboardTypes:inItemSet:
items
itemSetWithPasteboardTypes:
dataForPasteboardType:inItemSet:
valuesForPasteboardType:inItemSet:
string
strings
URL
URLs
image
images
color
colors
UIPopoverController initWithContentViewController
UIPrintInteractionController isPrintingAvailable
presentAnimated:completionHandler:
presentFromBarButtonItem:animated:completionHandler:
presentFromRect:inView:animated:completionHandler:
UIViewController presentViewController:animated:completion:
UIWebView loadRequest:
setDelegate:
citrix.com 133
UIWebViewDelegate webView:shouldStartLoadWithRequest:navigationType:
webViewDidStartLoad:
webViewDidFinishLoad:
webView:didFailLoadWithError:
UIWindow makeKeyAndVisible
UIApplicationDelegate applicationDidFinishLaunching:
application:didFinishLaunchingWithOptions:
application:willFinishLaunchingWithOptions:
applicationWillResignActive:
applicationDidEnterBackground:
applicationWillEnterBackground:
applicationDidBecomeActive:
applicationWillTerminate:
application:openURL:sourceApplication:annotation:
application:handleOpenURL:
applicationProtectedDataWillBecomeUnavailable:
applicationProtectedDataDidBecomeAvailable:
application:performFetchWithCompletionHandler:
application:handleEventsForBackgroundURLSession:completionHandler:
application:didReceiveLocalNotification:
application:didReceiveRemoteNotification:
application:didReceiveRemoteNotification:fetchCompletionHandler:
application:didRegisterForRemoteNotificationsWithDeviceToken:
application:didFailToRegisterForRemoteNotificationsWithError:
applicationSignificantTimeChange:
application:shouldAllowExtensionPointIdentifier:
QLPreviewController allocWithZone:
Data Encryption and iOS 9
Important
citrix.com 134
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 encryption is incompatible with iOS9 for data downloaded to an iOS 9 device from a wrapped app. Apple requires a device passcode to encrypt all app data on the device using iOS file encryption. You can choose from the following options to protect data:
By default, wrapped apps will require a PIN or passcode on an iOS 9 device.In addition to requiring a PIN or passcode, you can also specify a minimum data protection class that is used for the app data unless a higher protection level is already specified in iOS.
To support the iOS level of protection, MDX Toolkit 10.2 includes a new policy, Device passcode, which requires a PIN or passcode on an iOS 9 device. By default, this policy is . The policy applies on a per-app basis and can be used Onwhether you run XenMobile in MDM or MAM mode.
Apps wrapped with MDX Toolkit 10.2 use MDX encryption for Sqlite databases and keychain only. Sqlite databases are the underlying foundation for the more complex Apple Core Data Persistent Storage model. The other Apple Core Data models rely on file objects in the Apple file system in the app sandbox.
Other policies and iOS 9:
The user entropy feature, which is enabled through the key, is not Encrypt secrets using Passcodeaffected by iOS 9. The keychain and 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 Worx App SDK also include 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 iOS. 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 . Default value.NSFileProtectionCompleteUnlessOpen
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.
This policy is hidden. To make the policy visible in XenMobile, open the policy_metadata.xml file for the app (in Applications/Citrix/MDXToolkit/data) and, in the section, change the value of MinimumDataProtectionClass
to . After you wrap your app, the policy appears when you add the app to XenMobile.PolicyHidden false
The user experience:
After a user upgrades to an app wrapped with MDX Toolkit 10.2 and then starts the app, Worx prompts the user to create a device passcode, if none exists. Worx then decrypts existing MDX-encrypted files and uses iOS file encryption to secure the files. 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.
Ensure Data Encryption Compatibility
citrix.com 135
One of the primary features of MDX is that all persisted data is transparently encrypted. You don't need to modify your app to gain this functionality and, in fact, you can't directly avoid it. The XenMobile administrator has the ability to disable encryption either selectively or entirely, but not the app.
This is one of the more heavyweight aspects of MDX and requires an understanding of the following points:
File encryption is present for all native code that runs in managed processes.
The file data encryption implementation supports all native code and not just code for apps using the Apple frameworks and the Apple Objective-C runtime. Any file data encryption implemented within and solely for the Objective-C runtime can be easily subverted.
Some framework APIs, such as AVPlayer class, UIWebView class, and QLPreviewController, are actually implemented by iOS service processes in a different execution context than the user's managed app process.
These service processes are unable to decrypt MDX encrypted file data, so the managed app must provide the service process with a temporary unencrypted copy of the data which is subsequently deleted by the managed app after 5 seconds. It is important that you are aware of the limitation when using these classes because we lose containment control of the data provided to these classes due to Apple implementation of these specific classes.
Memory mapping is problematic for XenMobile encryption since it relies on app calling file I/O system call interfaces.
Once a file is memory mapped, the I/O requests for the file are managed outside of the context of the user app bypassing XenMobile encryption. All POSIX mmap(2) calls by a managed app are mapped as MAP_PRIVATE and MAP_ANON and not associated with any file description. An attempt is made to read in all the mapped data during the mmap call if a file description is specified to fault in all the data since any subsequent paging in of data by the operating system will result in reading encrypted data without it being decrypted by XenMobile. This technique has been successful in all apps tested with XenMobile since the amount of data that is memory mapped is small with no memory page reclaims happening within the app.
Encryption adds measurable overhead. Developers should optimize disk I/O to prevent performance degradation. As an example, if you are repeatedly reading and writing the same information, you might want to implement an app level cache.SQLite databases are encrypted by XenMobile using the SQLite Virtual File System layer.
Performance can be an issue. The standard database cache size is 2000 pages or 8 megabytes. If your database is large, a developer may need to specify SQLite pragma to increase the database cache size. In Objective-C Core Data Framework, the SQLite pragma can be added as an option dictionary when adding the Persistent Store object to the Persistent Store Controller object.
SQLite WAL mode is not supported since the library is relinked to file I/O interfaces and internally uses memory mapping extensively.NSURLCache DiskCache is implemented by iOS using a SQLite database. XenMobile disables the disk cache associated since this database is referenced by unmanaged iOS service processes.The following table lists the hardcoded excluded file path name patterns:
.plist Excluded due to access by iOS system processes outside process context.
.app Legacy substring in the Application Bundle name. This substring will be deprecated because an explicit Application Bundle path is now excluded.
.db A file with this suffix is not encrypted if the file is not a sqlite database.
/System/Library File paths that exist within the app bundle sandbox directory and file paths outside the app data sandbox cannot be encrypted. On iOS, the installed app is read only and is in a different directory than the app data files that the app produces and stores when it is run.
Library/Preferences Files are accessed by iOS directly. Normally only .plist files are present in this directory path.
/com.apple.opengl/ Files are accessed by iOS directly.
csdk.db Legacy Citrix SSLSDK sqlite database
citrix.com 136
/Library/csdk.sql Citrix SSLSDK sqlite database
CtxLog_ Citrix log file name prefix
CitrixMAM.config MDX internal filename
CitrixMAM.traceLog Legacy MDX internal filename
CtxMAM.log MDX internal filename
data.999 MDX internal filename
CTXWrapperPersistentData MDX internal filename
/Documents/CitrixLogs MDX log directory
/Document/CitrixLogs.zip Compressed MDX log directory name
Any file in the app Bundle directory path
Read only directory of app files
XenMobile substitutes an instance of the private XenMobile SecureViewController class for instances of the Apple Objective-C QLPreviewController object class at runtime. XenMobile SecureViewController class is derived from the Apple Objective-C UIWebView object class. The QLPreviewController object class natively supports a few file formats which the UIWebView object class doesn't natively support, such as the audio and pdf types.For best performance, file I/O requests should be issued to file offsets which are a multiple of 4096 bytes and should be issued for a length which is also a multiple of 4096 bytes.The O_NONBLOCK file mode flag is not supported by XenMobile encryption. This file mode flag is removed from the list of modes when processed by XenMobile.The O_APPEND file mode flag is not supported by XenMobile encryption. This file mode flag is removed from the list of modes when processed by XenMobile.
Encryption User Entropy
One XenMobile option for encryption requires the end user to enter a PIN before the encryption key can be generated. This option is called user entropy. It can cause a particular issue for apps.
Specifically, no file or database access can be performed until the user enters a PIN. If such an I/O operation is present in a location that runs before the PIN UI can be displayed, it will always fail.
To ensure that this issue isn't present in your app, test with user entropy enabled. The XenMobile client property, Encrypt secrets using Passcode, adds user entropy. You configure that client property, which is disabled by default, in the XenMobile console under .Configure > Settings > More > Client Properties
Data Containment Compatibility
Any remote view controllers will not have security containment (for example, data encryption; copy, cut, and paste policy blocking; and so on) because a remote view controller runs in a different process context than the MDX-managed app.iOS 8 extensions are not intercepted other than the keyboard extension.CloudKit in iOS8 is not intercepted.The Copy action is only action supported from UIResponder. Other actions, such as Cut and Delete, are not supported.Airdrop is only intercepted at the UI level, not at a lower level.MFI and Bluetooth are not intercepted.
Icon File Support
MDX wrapping requires the presence of at least one icon that can be used as the springboard icon or app icon. App developers can add their icons to the Asset Catalog, or use the CFBundleIcons or CFBundleIconFiles keys in Info.plist.
The MDX Toolkit will pick the first one from the list of known plist locations in Info.plist:
CFBundleIconsCFBundlePrimaryIconCFBundleIconFilesUINewsstandIcon
citrix.com 137
CFBundleDocumentTypes
If none of those keys is found in Info.plist, the MDX Toolkit will identify one of the following icons in the root folder of the app bundle:
Networking and micro VPN
MDX currently manages only those networking calls issued directly by an app. Some DNS queries are issued directly by the Apple framework and so are not managed by MDX.
Several XenMobile policy options are available to administrators for networking. The Network access policy prevents, permits or redirects app network activity as follows:
By default, the network is completely blocked for an app. If the Network access policy is set to , Blockednetworking APIs used by your app will fail. Per the previous guideline, you should gracefully handle such a failure.If the Network access policy is set to , all network calls go directly and are not tunneled.UnrestrictedIf the Network access policy is set to , all network calls are tunneled through Tunneled to the internal networkthe NetScaler Gateway. The tunneling under this policy is controlled by the Preferred VPN mode policy.
The Preferred VPN mode policy sets the initial mode for connections that tunnel to the internal network:
If the Preferred VPN mode policy is set to , the http/https URL is rewritten. Secure browse Secure browsecan tunnel only http and https traffic. A significant advantage of secure browse is single sign on (SSO) for http and https traffic and also PKINIT authentication. On Android, secure browse has low setup overhead and is thus the preferred option for web browsing type of operations.If the Preferred VPN mode policy is set to , all traffic from the managed app is tunneled Full VPN tunnelthrough NetScaler Gateway.
Limitations:
WkWebView is not supported.Users cannot play videos hosted on internal websites in iOS wrapped MDX apps because the videos play in a media player process on the device that MDX does not intercept. NSURLSession background download (NSURLSessionConfiguration backgroundSessionConfigurationWithIdentifier) is not supported.We block UDP traffic if the Network access policy is set to . We don't tunnel UDP traffic if the BlockedNetwork access policy is set to .Tunneled to the internal networkMDX-wrapped apps cannot instantiate a socket server that listens for inbound connections. However, MDX-wrapped apps can use a client socket to connect to a server.
Third Party Library Support
Some app frameworks have compatibility issues with XenMobile:
Apps developed with cross-compilers are not supported.SQLCipher doesn't work with encryption because it uses memory mapping. One solution is to not use SQLCipher. A second solution is to exclude the database file from encryption using an encryption exclusion policy. A XenMobile administrator must configure the policy in the XenMobile console.App and third party libraries which link directly to OpenSSL libcrypto.a and libssl.a libraries can result in link error due to missing symbols and link errors due to multiple symbol definition.Apps requiring support for Apple Push Notification Service will need to follow specific steps which Apple requires.XenMobile explicitly sets the SQLite database version to 1 in order to disable Write Ahead Logging (WAL) file and memory mapped file support within SQLite databases. Any attempt to directly access SQLite interfaces in SQLite version 2 or version 3 will fail.
citrix.com 138
Worx API for iOS
The Worx API for iOS is based on Objective-C. This article summarizes the Worx APIs by feature and provides the API definitions.
Feature APIs
App management
isAppManaged
Interaction with Worx Home
isMDXAccessManagerInstalled logonMdxWithFlag isAppLaunchedByWorxHome
MDX policies
getValueOfPolicy
Shared vault
getVaultDataFromVault saveVaultData updateAndSynchronizeVaultItem updateAndSynchronizeVaultItems deleteVault deleteVaultWithError
User data
managedUserInformation
Class MdxManager
Methods
getValueOfPolicy
+(NSString*) getValueOfPolicy:(NSString*)policyName error:(NSError **) error;
For managed apps, returns the policy value set by XenMobile administrators. For unmanaged Premium apps, returns the policy value set in Applications/Citrix/MDXToolkit/data/MDXSDK/default_policies.xml. For unmanaged General apps, returns .nil
Parameters:
policyName – The name of the policy to search for in default_policies.xml.
Example:
+(NSString*) getValueOfPolicy:(NSString*)DisableCamera error:(NSError **) error;
isMDXAccessManagerInstalled
+(BOOL) isMDXAccessManagerInstalled: (NSError **) error;
Checks if Worx Home is installed, which means that MDX control of the app is enabled even if the app isn't managed. Returns if Worx Home is installed.true
citrix.com 139
isAppManaged
+(BOOL) isAppManaged;
Checks if the app is currently managed by MDX, which means that the MDX policy bundle is embedded in the app as an XML file. The XenMobile backend infrastructure (key vaults) are queried for data encryption partial keys (secrets) which MDX will use to encrypt app database data (iOS 9) and app file and database data (for iOS 8 and earlier). Returns if the app is managed.true
logonMdxWithFlag
+(BOOL) logonMdxWithFlag:(BOOL)force error:(NSError**) error;
Initiates an MDX Logon request with Worx Home.
isAppLaunchedByWorxHome
+(BOOL) isAppLaunchedByWorxHome;
Checks whether an inter-application URL request is from Worx Home or some other app on the device, which is necessary if an app needs to be aware of MDX control communication. On iOS, apps can register for specific URL schemes. A URL scheme is the first part of a URL, up to but not including the colon. If a URL starts with http://..., the scheme is http.
MDX-enabled apps and Worx Home communicate using custom URL schemes. For example, to handle mailto: URLs from other apps, WorxMail requires the URL scheme ctxmail. To handle http or https URLs from other apps, WorxWeb requires the URL scheme ctxmobilebrowser or ctxmobilebrowsers, respectively. For details about the MDX App URL schemes policy and Allowed URLs policy, see in the MDX Toolkit documentation.
Returns accurate results when queried anytime or anywhere during or after the following UIApplication delegate event calls:
When the app loads from springboard or an call:openURL
application:willFinishLaunchingWithOptions: application:didFinishLaunchingWithOptions: applicationDidFinishLaunching:
When the app is activated or re-activated by users from the device springboard
applicationDidBecomeActive:
Important: You must not query during .applicationWillEnterForeground:When the app is activated or re-activated by an call:openURL
application:openURL:sourceApplication:annotation: application:handleOpenURL:
managedUserInformation
extern __attribute__((visibility ("default"))) NSString *const kWorxUsername; +(NSDictionary*) managedUserInformation;
Returns a string containing the UserName of an enrolled user running an MDX-managed app, regardless of the user sign-on status. Returns an empty string if the user isn't enrolled, the app isn't managed, or the app isn't wrapped.
XenMobile MDX Policies for iOS Apps
citrix.com 140
Class WorxSharedKeychainVault
Methods
initWithVaultName
- (instancetype) initWithVaultName:(NSString*)vaultName accessGroup:(NSString*)accessGroup;
Initializes a Worx shared vault.
Use the shared vault API to share managed content between apps that have the same keychain access group. For example, you can share user certificates through an enrolled app so that apps can obtain a certificate from the secure vault instead of from Worx Home.
Parameters:
vaultName – The name of the Worx shared vault.
accessGroup – The name of the keychain access group. This can be the default MDX access group, named . , or a keychain access group you will use to share data between apps.TEAMID_A appOriginalBundleID
Vault Data Type Properties
@property(nonatomic,readonly) BOOL exists; @property(nonatomic,readonly) BOOL isAccessible; @property(nonatomic,strong) NSMutableDictionary* vaultData;
After you initialize a vault, these vault data type properties are returned:
exists – Indicates whether the vault with the specified was found.vaultNameisAccessible – Indicates whether the vault is in the specified and can be accessed.accessGroupvaultData – Is the contents of the shared vault. When you first initialize the vault, is a nil vaultDatadictionary.
getVaultDataFromVault
+ (NSDictionary*) getVaultDataFromVault:(NSString*)vaultName accessGroup:(NSString*)accessGroup error:(NSError *__autoreleasing *)error;
Reads data from the Worx shared vault. This is one of three ways to read vault data, as follows:
Directly use .getVaultDataFromVault:accessGroup:errorCreate the instance and then read the property.WorxSharedKeychainVault vaultDataCreate the instance and then reload vault data using WorxSharedKeychainVault -(BOOL)
and reading the loadDataWithError:(NSError *__autoreleasing *)error; vaultDataproperty.
For example code, see in this article.
Parameters:
vaultName – The name of the Worx shared vault.
accessGroup – The name of the keychain access group. This can be the default MDX access group, named . , or a keychain access group you will use to share data between apps.TEAMID_A appOriginalBundleID
saveVaultData
+ (BOOL) saveVaultData:(NSDictionary*)vaultData toVault:(NSString*)vaultName accessGroup:(NSString*)accessGroup error:(NSError *__autoreleasing *)error;
Shared Vault Example
citrix.com 141
Saves data in the Worx shared vault. This is one of three ways to save vault data, as follows:
Directly use .saveVaultData:toVault:accessGroup:error:Use or (described updateAndSynchronizeVaultItem: updateAndSynchronizeVaultItemsnext in this table).Use by creating - (BOOL)synchronizeWithError:(NSError *__autoreleasing *)error;the instance, loading the vault data, modifying the vault data, and then WorxSharedKeychainVaultsynchronizing the data.
For example code, see in this article.
Parameters:
vaultData – The data to save to the Worx shared vault. Data stored in the share vault is a dictionary of key/value pairs, such as .@{@"username":@"andreo"}
vaultName – The name of the Worx shared vault.
accessGroup – The name of the keychain access group. This can be the default MDX access group, named . , or a keychain access group you will use to share data between apps.TEAMID_A appOriginalBundleID
updateAndSynchronizeVaultItem
updateAndSynchronizeVaultItems
- (BOOL)updateAndSynchronizeVaultItem:(NSString*)vaultItem withValue:(id)itemValue error:(NSError *__autoreleasing *)error;
- (BOOL)updateAndSynchronizeVaultItems:(NSDictionary*)vaultItems error:(NSError *__autoreleasing *)error;
Updates data in the Worx shared vault. To use this method, create the instance and WorxSharedKeychainVaultthen synchronize it by adding or updating vault data items. For example, if the existing vault entry has {a:123, b:234, c:305} and we use this API with data to update {c:345, d:456}, this API will update the vault data to {a:123, b:234, c:345, d:456}. For example code, see in this article.
See , above, for two other ways to save vault data.saveVaultData
Parameters:
vaultItem – A single key/value pair, in the form .@{@"username":@"andreo"}
vaultItems – A list of key/value pairs.
deleteVault
+ (BOOL) deleteVault:(NSString*)vaultName accessGroup:(NSString*)accessGroup error:(NSError *__autoreleasing *)error;
Deletes the specified shared vault.
Parameters:
vaultName – The name of the Worx shared vault.
accessGroup – The name of the keychain access group used by the vault you want to delete.
deleteVaultWithError
-(BOOL) deleteVaultWithError:(NSError *__autoreleasing *)error;
Deletes the shared vault returned by the instance. You must free the object after WorxSharedKeychainVaultdeleting it with .deleteVaultWithError
Shared Vault Example
Shared Vault Example
citrix.com 142
Shared Vault Example
#import "WorxSharedKeychainVault.h" @interface ClassA () ... @property(nonatomic,strong) WorxSharedKeychainVault* worxSharedKeychainVault; ... @end @implementation ClassA ... @synthesize worxSharedKeychainVault = _worxSharedKeychainVault; ... #ifdef USE_CLASS_INSTANCE_METHODS -(WorxSharedKeychainVault*)worxSharedKeychainVault { if(_worxSharedKeychainVault==nil) { _worxSharedKeychainVault = [[WorxSharedKeychainVault alloc] initWithVaultName:<VAULT_NAME> accessGroup:kWorxKeychainAccessGroup]; } return _worxSharedKeychainVault; } #endif -(void)read { NSError* error=nil; #ifdef USE_CLASS_INSTANCE_METHODS NSDictionary* vaultDictionary = nil; if([self.worxSharedKeychainVault loadDataWithError:&error]) { vaultDictionary = [self.worxSharedKeychainVault vaultData]; } #else NSDictionary* vaultDictionary = [WorxSharedKeychainVault getVaultDataFromVault:<VAULT_NAME> accessGroup:kWorxKeychainAccessGroup error:&error]; #endif } -(void)save { NSError* error=nil; /// check error handling here... NSDictionary* dictToSave = @{<VAULT_DATA_DICTIONARY_OBJECTS>}; #ifdef USE_CLASS_INSTANCE_METHODS #ifdef USE_CLASS_INSTANCE_METHODS_TO_UPDATE BOOL result = [self.worxSharedKeychainVault updateAndSynchronizeVaultItems:dictToSave error:&error]; #else self.worxSharedKeychainVault.vaultData = [NSMutableDictionary dictionaryWithDictionary:dictToSave]; BOOL result = [self.worxSharedKeychainVault synchronizeWithError:&error]; #endif #else BOOL result = [WorxSharedKeychainVault saveVaultData:dictToSave toVault:<VAULT_NAME> accessGroup:kWorxKeychainAccessGroup error:&error]; #endif } -(void)delete { NSError* error=nil; #ifdef USE_CLASS_INSTANCE_METHODS BOOL result = [self.worxSharedKeychainVault deleteVaultWithError:&error]; #else
citrix.com 143
BOOL result = [WorxSharedKeychainVault deleteVault:<VAULT_NAME> accessGroup:kWorxKeychainAccessGroup error:&error]; #endif } ... @end
citrix.com 144
1. 2.
3.
1. 2. 3.
4.
Policy Defaults and Custom Policies
This article discusses the ways you can work with policies in your wrapped ISV apps.
Change Policy Defaults for Unmanaged Premium Apps
The Worx App SDK includes the following policy files that specify policy defaults for unmanaged Premium apps only.
Android: Applications/Citrix/MDXToolkit/data/MDXSDK_Android/ default_sdk_policies.xmliOS: Applications/Citrix/MDXToolkit/data/MDXSDK/default_policies.xml
All of the policies in those files are disabled. Any policies not in the file are ignored for unmanaged Premium apps.
You can change the default settings as follows.
Make a backup of any default policy files you plan to change, in case you need them later.To change a policy default for ISV apps, use the policy values specified in the MDX Toolkit documentation, in
and .Include the default policy file with your app resources when you build the Premium app.
Create Custom Policies
The policy files in the MDX Toolkit provide full definitions of the policies, including the policy label and help text displayed in the XenMobile console. When you wrap an app, these policies are are included with the generated .mdx file. You can add custom policies to these files, which are located in the MDX Toolkit installation folder in Applications/Citrix/MDXToolkit/data.
Make a backup of any policy files you plan to change, in case you need them later.To add policies to the policy XML files, use the formats provided in "Policy Formats," next.When you wrap your app, specify the location of your modified policy XML file by including the option -policyxmlwith the wrapping command line:
-policyxml /Applications/Citrix/MDXToolkit/data/policy_metadata.xml
For details about using the command line to wrap ISV apps, see and .Line
To verify the policy names, descriptions, and values in the XenMobile console, upload your app to XenMobile. This is included as part of the publishing steps in and .
Guidelines for adding policies
Change only the items shown in bold.The value of the element is the name called from your app.PolicyNameThe value of the element is the category name under which the policy will be listed in the PolicyCategoryXenMobile console. To look up category names, see the values in the section of CategoryId <Category>the MDX policy files.The value of the element is the default setting of your policy.PolicyDefaultThe in is a unique ID used for the policy. The ID must POLICY_ID <Title res_id=" ―>POLICY_IDstart with a letter, cannot include spaces, and includes only letters, numbers, or the underscore character.The value of the element is the policy label that appears in the XenMobile console.TitleThe in is a unique ID for the policy POLICY_DESC_ID <Description res_id=" ">POLICY_DESC_IDdescription. The ID must start with a letter, cannot include spaces, and includes only letters, numbers, or the underscore character.The value of the element is the policy description that appears in the XenMobile console.Description
String
<Policy> <PolicyName> </PolicyName> PolicyName <PolicyType>string</PolicyType> <PolicyCategory> </PolicyCategory> Category_ID <PolicyDefault> </PolicyDefault> Value <PolicyStrings> <Title res_id=" ―> </Title> POLICY_ID Sample String Policy <Description res_id=" "> POLICY_DESC_ID
XenMobile MDX Policies for Android Apps XenMobile MDX Policies for iOS Apps
ISV iOS App Wrapping Using the Command Line ISV Android App Wrapping Using the Command Line
Publishing an Android App Publishing an iOS App
citrix.com 145
Please enter the policy value. </Description> </PolicyStrings> </Policy>
Boolean
<Policy> <PolicyName> </PolicyName> PolicyName <PolicyType>string</PolicyType> <PolicyCategory> </PolicyCategory> Category_ID <PolicyDefault> </PolicyDefault> false <PolicyStrings> <Title res_id=" ―> </Title> POLICY_ID Sample Boolean Policy <BooleanTrueLabel res_id=" "> </BooleanTrueLabel> POLICY_ON On <BooleanFalseLabel res_id=" "> </BooleanFalseLabel> POLICY_OFF Off <Description res_id=" "> POLICY_DESC_ID If On, the app does something. If Off, the app does something else.
Default value is Off. </Description> </PolicyStrings> </Policy>
Enum
<Policy> <PolicyName> </PolicyName> PolicyName <PolicyType>enum</PolicyType> <PolicyEnumValues> <PolicyEnumValue> <PolicyEnumValueId> </PolicyEnumValueId> Value1 <PolicyEnumValueString res_id=" "> </PolicyEnumValueString> ID_1 Yes </PolicyEnumValue> <PolicyEnumValue> <PolicyEnumValueId> </PolicyEnumValueId> Value2 <PolicyEnumValueString res_id=" "> </PolicyEnumValueString> ID_2 No </PolicyEnumValue> <PolicyEnumValue> <PolicyEnumValueId> </PolicyEnumValueId> Value3 <PolicyEnumValueString res_id=" "> </PolicyEnumValueString> ID_3 Maybe </PolicyEnumValue> </PolicyEnumValues> <PolicyCategory> </PolicyCategory> Category_ID <PolicyDefault> </PolicyDefault> Value1 <PolicyStrings> <Title res_id=" ―> </Title> POLICY_ID Sample Enum Policy <Description res_id=" "> POLICY_DESC_ID Sample policy description.
Default value is Yes. </Description> </PolicyStrings> </Policy>
citrix.com 146
Troubleshooting
To troubleshoot issues that occur when your apps are running in a XenMobile environment, you must first determine whether the issue occurs when your app is unwrapped or wrapped. If the issue occurs when your app is unwrapped, it is specific to your app. Follow your usual troubleshooting procedures.
If the issue occurs when your app is wrapped:
Review the known issues. See and .Verify that the version of the Worx App SDK you are using is from the same MDX Toolkit your are using to wrap the app. For iOS, make sure that the correct line is added to your project. This will ensure the framework has been added and the APIs will work. For Android, make sure that the libs for all the devices you are using have been added to the project and the worxsdk.jar is added to the project dependencies. If you experience additional problems in integrating the SDK with your project, please contact Citrix Ready or Citrix Support.Determine if the issue is an app wrapping error. Review the MDX Toolkit logs in Applications/Citrix/MDXToolkit/logs.
The log files contain the information and progress from wrapping. Check these logs for error messages and warnings. For details, see and
.Wrapping Errors
Collect logs from Worx Home: In Worx Home, tap , tap , and then tap your app Support Need help?name. WorxMail then opens to a new message that has a log from the selected app attached. You can add more information about the problem in the message. Please list the steps needed to reproduce the issue and include the log from the failed wrap attempt, and any additional information about the issue.
Other logs from the device might be useful. See and .App Logs from the Command Line
If you are unable to install a wrapped app on a device:
Verify that you are using a valid keystore for Android apps or a valid provisioning profile and certificate pair for iOS. Be aware of the special considerations for provisioning profiles and certificates in
and .Mobile Apps
If there is an issue with your Apple certificate key:
Request to reissue the certificate from the the Apple Keychain Access app. This will generate a new private key. Then download the certificate and provisioning profile from the Apple developer website.
Known Issues for Worx App SDK Known Issues for MDX Toolkit
Identifying iOS App Wrapping Errors Identifying Android App Wrapping Errors
Collecting System Logs on iOS Devices Collecting App Logs from the Command Line
Wrapping iOS Mobile Apps Wrapping Worx Apps for iOS 8
citrix.com 147
© 1999-2016 Citrix Systems, Inc. All Rights Reserved.
