citrix.com 1
MDX Toolkit
http://docs.citrix.com/content/docs/en-us/mdx-toolkit/10.htmlSep. 18, 2015
Docs.Citrix.com
citrix.com 2
MDX Toolkit
iOS 9 and XenMobile
About the MDX Toolkit
System Requirements
XenMobile Compatibility
Installing the MDX Toolkit
Wrapping iOS Mobile Apps
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
iOS 9 and XenMobile
About the MDX Toolkit
System Requirements
XenMobile Compatibility
Installing the MDX Toolkit
Wrapping iOS Mobile Apps
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 .
Quick links to sections in this article
About App WrappingWhat's New:
MDX Toolkit 10.2.1MDX Toolkit 10.0.7MDX Toolkit 10.0.5MDX Toolkit 10.0.4MDX Toolkit 10.0.3MDX Toolkit 10.0
About Client PropertiesKnown Issues in MDX ToolkitFixed Issues in MDX Toolkit
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.
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 .
http://www.citrix.com/downloads/xenmobile/product-software.html
About App Wrapping
MDX Toolkit 10.2.1MDX Toolkit 10.0.7MDX Toolkit 10.0.5MDX Toolkit 10.0.4MDX Toolkit 10.0.3MDX Toolkit 10.0
About Client PropertiesKnown Issues in MDX ToolkitFixed Issues in MDX Toolkit
MDX Developer's Guide
MDX Developer's Guide
citrix.com 5
The MDX Toolkit for Windows Phone 8.1The MDX Toolkit for Windows Phone 8.1 contains a Windows command-line tool that wraps WorxMail and WorxWeb. While 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 requires all apps to be signed by the same certificate to enable enrollment of deployed apps.
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
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.
citrix.com 6
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.
Enable encryption policyOn 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.
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.
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.
citrix.com 7
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.
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)
citrix.com 8
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.
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 .
Australian Signals Directorate Data Protection
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 9
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.
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 .
What's New in MDX Toolkit 10.0.7MDX Toolkit for iOS and Android interface improvements. The GUI tool now provides guidance to help you ensure that you wrap an app with the correct app ID, whether your provisioning profile supports explicit or wildcard app IDs. For sample screens, see .Proxy Automatic Configuration (PAC) file support for iOS. You can use a PAC file with a full VPN tunnel deployment for iOS devices. PAC file rules can specify handling for both internal and external sites. WorxWeb parses PAC file rules and sends the proxy server information to NetScaler Gateway. For details, see .
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
Enterprise App Wrapping Using the Graphical Interface
Full VPN Tunneling with PAC
citrix.com 10
Open-in support for Office 365 apps on iOS. Users can open documents from Office 365 apps in WorxMail or WorxEdit for iOS. In addition, Worx users can open the following documents in Office 365 apps on iOS devices:
WorxMail attachmentsDocuments downloaded by WorxNotes or WorxWeb
This feature is provided by the Restricted Open-In exception list policy, which contains a list of Office 365 apps. For details about the policy, see .
Open-in and encryption interaction change. When the Document exchange (Open In) policy is and the Enable encryption policy is On, users can now open documents in unwrapped apps. If Unrestricted
the receiving app is unwrapped or has encryption disabled, Worx decrypts the document.Worx shared vault for iOS. The Worx shared vault is a secure storage area for sensitive app data such as certificates. Only Worx-enabled apps can access the shared vault. The Worx shared vault is used for the following features in this release:
Automatic ID registration with ShareFile. If you modify the app ID or bundle ID for ShareFile Worx for iOS, you no longer need to register your ID with ShareFile.S/MIME certificate storage by a supported third-party identity provider. For details, see
.Digital Identity ProviderNew features for Android apps:
You can restrict Clipboard paste operations for wrapped Android apps. By default, the Paste policy is Unrestricted.You can prevent an app from accessing the Gallery on a device. By default, the Block Gallery policy is Off.
Regular expression matching for file and database encryption exclusions. As of this release, the File encryption exclusions policy and Database encryption exclusions policy support regular expression matching instead of wildcard matching.Xamarin app support. The MDX Toolkit for iOS now support apps developed on the Xamarin platform.Multiple Android failure (crash) logs. Up to 10 failure logs for each Worx app for Android are now included with the product logs in Support bundles.New MDX policies. The following list shows new policies for supported device operating systems. For details, see the articles under and
.Worx Mobile Apps
iOS
Email classification, Email classification markings, Email classification namespace, Email classification version, Default email classificationEnable auto-save of email draftsInformation Rights ManagementPAC file URL or proxy serverPush notifications, Push notifications customer ID, Push notifications regionS/MIME certificate source, Enable S/MIME during first WorxMail startupUsage analytics
Android
Block GalleryEnable auto-save of email draftsEncrypt logsPasteUsage analyticsThe Open In exclusions policy is renamed to Restricted Open-In exception list.
Windows Phone
Block cameraUsage analytics
For a description of Worx App SDK enhancements, see .
XenMobile MDX Policies for iOS
Integrating with a Digital Identity Provider
MDX Policies at a Glance for iOS, Android, Windows Phone 8.1 About Worx Mobile Apps
What's New in the Worx App SDK
citrix.com 11
What's New in MDX Toolkit 10.0.5MDX Toolkit 10.0.5 fixes an issue with WorxWeb for Android that prevented users from opening external HTTPS pages on Android 5.0 and 5.1 devices.
What's New in MDX Toolkit 10.0.4MDX Toolkit 10.0.4 fixes a compatibility issue in the Worx App SDK that impacted Apple App Store submission. It also fixes an issue with the Toolkit that could occur after you upgraded to Xcode Command Line Tools version 6.3. The toolkit was sometimes unable to wrap iOS apps and displayed the error “[ToolkitLib] This Application is a App Store app―.
What's New in MDX Toolkit 10.0.3XenMobile support for certificate pinning. Worx Home for iOS and Worx Home for Android now support SSL certificate pinning. This feature ensures that the certificate signed by your enterprise is used when Worx communicates with XenMobile. Certificate pinning prevents connections from Worx clients to XenMobile when installation of a root certificate on the device compromises the SSL session. When Worx Home detects any changes to the server public key, it denies the connection.
For more information, see in the Worx Home article.
iOS app wrapping for new Apple Enterprise accounts. The MDX Toolkit now enables you to specify the bundle ID for an iOS app. You no longer need to manually re-sign each app or rename policy XML files.64-bit support for iOS wrapped apps. Apps wrapped with the MDX Toolkit now include 64-bit support and are built with the iOS 8 SDK. This change meets the Apple requirement for new iOS apps uploaded to the App Store, effective February 1, 2015.Prevent apps from accessing the photo library. You can now prevent iOS and Android apps from accessing the photo library on a device. To do that, set the Block photo library policy to On.Convenient iOS failure (crash) logs. Failure logs for all Worx apps for iOS are now included with the product logs in Support bundles. XenMobile retains a maximum of 10 failure reports.Support for FaceTime audio calls. A contact card in WorxMail for iOS now includes a FaceTime audio button. To prevent the calls, update the Allowed URLs policy for iOS.Minimum connection security level for WorxMail for iOS. By default, connections from WorxMail for iOS use TLS 1.0. If you use Lotus Notes 9.0 with SSL 3.0, be sure to change the Connection security level policy to tlsv10_sslv3.Secure viewer for ShareFile documents. ShareFile Worx for iOS now uses a secure viewer instead of the iOS Quick Look preview feature. The MDX-based secure viewer ensures that cut, copy, and paste operations occur only between MDX apps. To change the viewer used, update the Enable secure viewer policy.Printing blocked from MDX apps on Android. MDX apps for Android are blocked from printing by default. To enable printing, update the Block printing policy.STA ticket support for WorxMail for Windows Phone. WorxMail for Windows Phone now supports certificate-based authentication to the mail server.Worx App SDK support for ShareFile Worx clients. You can now use the Worx App SDK to integrate ShareFile Worx clients for iOS with the Citrix Worx Store.Worx App SDK requirements. The Worx App SDK now requires these additional frameworks and libraries: AssetsLibrary.framework, Photos.framework, and Libstdc++.dylib.Unified timestamping. Synced timestamping across all components eliminates confusion and makes it easier to track and correlate logs.Additional language support. The MDX Toolkit now includes support for Danish, Italian, and Swedish.
This release of the MDX Toolkits also supports the new Worx app features that are discussed in .Mobile Apps
For issues fixed with each XenMobile release, see .
Certificate Pinning
What's New in Worx Mobile Apps
http://support.citrix.com/article/CTX141840
citrix.com 12
1.
2.
What's New in MDX Toolkit 10.0You can now use the MDX Toolkit for iOS and Android to wrap apps created with PhoneGap.For issues fixed with each XenMobile release, 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 in . Settings > More > Client Properties
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.
http://support.citrix.com/article/CTX141840
citrix.com 13
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.
To configure Touch ID authentication
Important: If User Entropy is , XenMobile ignores the property that is enabled On Enable Touch ID Authenticationthrough the key.Encrypt secrets using Passcode
1. In the XenMobile console, go to . Configure > Settings > More > Client Properties
2. Click .Add
3. 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 MDX ToolkitThe following are known issues in the current releases of MDX Toolkit.
MDX Toolkit, Version 10.2
MDX Toolkit, Version 10.0.x
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]
When you set the Inbound document exchange (Open In) policy to , when you try to open a Restrictedfile in another app or within the same app, an error message appears.
[#582587]
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]
MDX Toolkit, Version 10.2
MDX Toolkit, Version 10.0.x
citrix.com 14
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]
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]
MDX Toolkit 10.2 also includes the following issues reported for Version 10.0.x.
MDX Toolkit, Version 10.0.x
If you use XenMobile 9, you must install a XenMobile Device Manager patch before wrapping Android apps. Important:
To download the patch, go to http://www.citrix.com/downloads/xenmobile, navigate to Legacy Software > Product
Software > Patches, and then download XenMobile Device Manager 9.0 Patch.
Android PhoneGap apps that use the JavaScript Location Services API cannot use the MDX Block location services policy.
Android users upgrading to version 10.0 of an MDX app intermittently see an Update Available message the entire time the app is downloading.
[#504227]
When users first log on to a wrapped Social Site app, the app fails. Workaround: Use private file exclusion rules to exclude the app's database files from Citrix encryption; for example, by using the rule
which excludes all files ending in .dat$ dat
[#509471]
The MDX Toolkit supports ARM architecture for processors and does not support X86.
[#515366]
On Android 4.4 (KitKat) and 5.0 (Lollipop) devices, WorxWeb fails when users open a link in a wrapped WorxMail app that then opens a Microsoft Excel web app in a browser, such as a SharePoint site. This is a third-party issue.
[#521669]
On an Android device with WorxMail installed, if users change the sync period from to in 3 days All and then in WorxMail tap and then tap to view messages again, the app stops Settings Contacts
responding and the following message appears: WorxMail isn't responding.
[#522486]
On an iOS device, if the App passcode policy is configured and the Network access policy is set to Tunneled to internal network, this issue occurs: After users install Worx Home and WorxWeb and then sign off of Worx Home and open WorxWeb from the springboard, they are prompted for their PIN. When prompted to connect to the network, after tapping , users are prompted for their PIN again, in OKerror. The issue only occurs the first time users start WorxWeb in this way.
[#522907]
On an iOS device, if the App passcode policy is configured and the Network access policy is set to , this issue occurs: If the online session grace period expires for an MDX Tunneled to internal network
app, users can use the app for a few seconds.
[#522909]
http://www.citrix.com/downloads/xenmobile
citrix.com 15
On an Android device, if the property (Encrypt secrets using Passcode Configure > Settings > ) is and the device is restarted, the user is prompted to authenticate both More > Client Properties On
WorxHome and the Worx app.
[#523193]
WorxTasks for Android does not open after users restart a device if the Encrypt secrets using property is . As a workaround, users can sign on WorxMail before WorxTasks or can Passcode On
unlock their WorxMail account after opening WorxTasks.
[#542144]
On devices running iOS 8.2 or earlier, if the Inbound document exchange (Open In) policy is Restrictedor , users cannot use non-MDX apps to open documents from MDX apps that are on the Blockedinbound document exchange whitelist. As a workaround, change the Inbound document exchange (Open In) policy to . This is a third-party issue.Unrestricted
[#542434]
If the property is , MDX apps for iOS prompt users twice for their Encrypt secrets using Passcode OnPIN after a device restarts. As a workaround, you can set the Encrypt secrets using Passcodeproperty to in .Off Configure > Settings > More > Client Properties
[#542999]
If the Block iCloud policy is , users cannot use MDX apps to access iCloud. If the Block iCloud policy Offis , an MDX app does not alert users that iCloud is blocked.On
[#543646]
If the Background network services policy is configured, a STA ticket is not issued after a user upgrades WorxMail for Windows Phone. As a workaround, users must exit and then restart WorxMail after upgrading it.
[#544093]
After you upgrade an app using MDX Toolkit, the app prompts users to update the app within the time period configured for the App update grace period policy but does not force the update when the grace period elapses. In addition, the update prompt disappears if users rotate the device. As a workaround, users must exit and reopen the app and then tap now.Update
[#545518]
If you used MDX Toolkit 10.0.x to wrap iOS apps with a partial wildcard certificate and then use MDX Toolkit 10.0.7 to wrap the apps with a full wildcard certificate, users can upgrade the apps on iOS 7.1.2 devices although the code signing entitlements do not match those in your provisioning profile. This issue occurs on iOS 7.1.2 and not iOS 8.3 because Apple added entitlement checks for iOS 8.3.
[#561671]
The Require internal network policy is not supported for XenMobile 10. For XenMobile 9, if you require an internal network to run apps, you must configure the page of the XenMobile console (Beacons
). Be sure to select the following check boxes: , Configure > Settings > More > Beacons Use internal, and .Check internal beacon first for Citrix Receiver and Worx Home Use NetScaler Gateway
[#565370]
Fixed Issues in MDX Toolkit
citrix.com 16
The following are fixed issues in the current release of the MDX Toolkit. For fixed issues in MDX Toolkit 10.0.x, see .
The Worx App SDK does not support append mode for various iOS file operations. This can cause crashes in some wrapped third-party apps.
[#508704]
Attempts to open apps directly from the device, instead of from Worx Home, fail after users enter their personal identification number (PIN).
[#523807]
On Samsung devices with version 4.3 and later, the restriction policy for the camera fails.
[#553502]
When the Block camera policy is , tapping the camera icon can crash a wrapped iOS app.On
[#565232]
Some third-party wrapped apps do not sync data in full VPN mode.
[#569425]
The Worx App SDK is missing a required framework, JavascriptCore.framework.
[#570154]
In third-party apps developed using Xamarin and wrapped with MDX Toolkit 10.0.7.106, connections to internal endpoints time out.
[#576671]
After wrapping apps with MDX Toolkit version 10.0.5.1, apps started from the App Drawer or springboard do not make a VPN connection.
[#577134]
Opening a customized Android app shows an error when invoking sendOrderedBroadcast().
[#579639]
Third-party wrapped apps can crash in the MDX-redirected keychain call SecItemCopyMatching().
[#579685]
When starting the most recent update of a custom application that is wrapped with MDX Toolkit version 10.0.5 or 10.0.7, the application exits unexpectedly.
[#581857]
App content remains visible on iOS 9 devices after the maximum offline period expires for a wrapped app and the "Please sign on to Worx Home" message appears.
[#586242]
URLs specified for the App URL schemes policy are not included when an iOS app is wrapped.
[#586704]
Third-party wrapped apps can crash when opened after first-time use.
[#586715]
XenMobile MDX Toolkit 10.0.x - Fixed Issues
citrix.com 17
System Requirements
This article provides the system requirements for using the MDX Toolkit 10.2.1 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.
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:OS X 10.10 (Yosemite; minimum version)
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 18
1. 2.
3.
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,
Note: Download the Xcode command-line tools from the . Mac OS X 10.10 does web sitenot 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 install any prerequisites.Xcodeto
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.
For details, see on the Google developer website.
Add the location of the newly installed folders to the PATH variable in your environment.Valid (containing digitally signed certificates used to sign your Android apps)keystore
You create a one time and retain this file for current and future wrapping. If you do not use the keystoresame when wrapping the new version of an app you previously deployed, upgrades of that keystoreapp won't work. Instead, users need to manually remove the older version before installing the new version.
A can contain multiple private keys; in most cases, the will only have one key.keystore keystore
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 ( )keyalgSHA1with DSA signing algorithm ( )sigalg
Other Requirements for Wrapping Worx Apps for Windows Phone
Windows Store requirements:An open Microsoft Windows Store Developer Account (Corporate account type). For details, see
.types, locations, and fees
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
Note: The AET file is also needed when creating an Enterprise Hub device policy for Windows Phone 8.1. For more information, see .
Xcode Apple Developer
download page
Installing the Android SDK
Signing Your Applications
Account types, locations, and fees
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 19
XenMobile Compatibility
This article summarizes the versions of the supported XenMobile components that you can integrate, including NetScaler Gateway and the version of the MDX Toolkit needed to wrap, configure, and distribute Worx Mobile Apps.
Quick links to sections in this article
XenMobile 10.xXenMobile 9Device Manager 8.7.1 and App Controller 2.10Device Manager 8.6.1 and App Controller 2.9
XenMobile 10.xSupported NetScaler Gateway versions:
11.x10.5.x10.5.x MR versions10.1.x MR versions
XenMobile client components generally follow these compatibility requirements:
The latest version of Worx Home and the MDX Toolkit are compatible with the last two versions of XenMobile server.The latest version of the MDX Toolkit is compatible with the latest Worx Mobile Apps.Recent MDX Toolkit versions are compatible with the following versions of Worx Home:
MDX Toolkit for iOS and Android versions
Compatible Worx Home versions
Android iOS
10.2.1 10.2.1 10.2.1
10.0.7 10.0.8 10.0.8
10.0.5 - 10.0.3 10.0.3 10.0.3
MDX Toolkit for Windows Phone 8.1 versions Compatible Worx Home versions
10.0.7 10.0.3
10.0.5 - 10.0.3 10.0.3
10.0.0 10.0.0
XenMobile 10.x supports the Worx Mobile Apps versions listed in the following table.
An * indicates that an app isn’t available for the platform.
App Android iOS Windows Phone 8.1
XenMobile 10.xXenMobile 9Device Manager 8.7.1 and App Controller 2.10Device Manager 8.6.1 and App Controller 2.9
citrix.com 20
Worx Home 10.2.1
10.0.8
10.0.3
10.0.0
10.2.1
10.0.8
10.0.3
10.0.0
10.2
10.0.3
10.0.0
WorxMail 10.2
10.0.7
10.0.3
10.0.0
10.2
10.0.7
10.0.3
10.0.0
10.2 (Windows Phone 10)
10.0.7
WorxNotes 10.2
10.0.7
10.0.0
10.2
10.0.7
10.0.0
*
WorxTasks 10.2
10.0.7
10.2
10.0.7
*
WorxWeb 10.2
10.0.7
10.0.3
10.0.0
10.2
10.0.7
10.0.3
10.0.0
10.2 (Windows Phone 10)
10.0.3
QuickEdit/WorxEdit 1
1.2
1.1
1.0.1
1.0
5.9.3
5.9.1
5.8
5.7
5.6.1
5.5.3
*
ShareConnect/WorxDesktop1
3.0
2.5
2.4
2.3
2.1
2.0
1.2
1.0
2.5
2.4
2.3
2.2
2.1
2.0
1.3
1.2
*
ShareFile (Worx apps)2 3.9.8
3.9.7
3.9.6
3.9.5
3.2.13
3.2.12
3.2.11
3.2.10
*
citrix.com 21
3.9
3.8.1
3.7.1
3.6.5
3.6.1
3.6.0
3.4.1
3.2.8
3.2.6
3.2.5
3.2.4
Citrix for Salesforce * 10.2
10.0.7
*
1 Previously, the Worx version of QuickEdit was named WorxEdit and the Worx version of ShareConnect was named WorxDesktop. As of the latest releases, both the MDX and non-MDX versions have the same names: QuickEdit and ShareConnect.
2 The download page includes a separate version of ShareFile Worx for iOS that is required for use with restricted StorageZones.
XenMobile 9
XenMobile 9 includes Device Manager 9.0 and App Controller 9.0.
Supported NetScaler Gateway versions:
11.x10.5.x10.5.x MR versions10.5.x.e10.1.x10.1.x.e
XenMobile client components generally follow these compatibility requirements:
The latest version of Worx Home and the MDX Toolkit are compatible with the last two versions of XenMobile server.The latest version of the MDX Toolkit is compatible with the latest Worx Mobile Apps.Recent MDX Toolkit versions are compatible with the following versions of Worx Home:
MDX Toolkit for iOS and Android versions
Compatible Worx Home versions
Android iOS
10.2.1 10.2.1 10.2.1
10.0.7 10.0.8 10.0.8
10.0.5 - 10.0.3 10.0.3 10.0.3
MDX Toolkit for Windows Phone 8.1 versions Compatible Worx Home versions
citrix.com 22
10.2.1 10.2
10.0.5 - 10.0.3 10.0.3
10.0.0 10.0.0
XenMobile 10.x supports the Worx Mobile Apps versions listed in the following table.
An * indicates that an app isn’t available for the platform.
App Android iOS Windows Phone 8.1
Worx Home 10.2.1
10.0.3
10.0.0
10.2.1
10.0.8
10.0.3
10.0.0
10.2
10.0.3
10.0.0
WorxMail 10.2
10.0.3
10.0.0
10.2
10.0.7
10.0.3
10.0.0
10.2 (Windows Phone 10)
10.0.7
WorxNotes 10.2
10.0.0
10.2
10.0.7
10.0.0
*
WorxTasks 10.2 10.2
10.0.7
*
WorxWeb 10.2
10.0.3
10.0.0
10.2
10.0.7
10.0.3
10.0.0
10.2 (Windows Phone 10)
10.0.3
QuickEdit/WorxEdit 1
1.2
1.1
1.0.1
1.0
5.9.1
5.8
5.7
5.6.1
5.5.3
*
ShareConnect/WorxDesktop1
3.0
2.5
2.4
2.3
2.5
2.4
2.3
2.2
*
citrix.com 23
2.1
2.0
1.2
1.0
2.1
2.0
1.3
1.2
ShareFile (Worx apps)2 3.9.8
3.9.7
3.9.6
3.9.5
3.9
3.8.1
3.7.1
3.6.5
3.6.1
3.6.0
3.4.1
3.2.13
3.2.12
3.2.11
3.2.10
3.2.8
3.2.6
3.2.5
3.2.4
*
Citrix for Salesforce * 10.2
10.0.7
*
1 Previously, the Worx version of QuickEdit was named WorxEdit and the Worx version of ShareConnect was named WorxDesktop. As of the latest releases, both the MDX and non-MDX versions have the same names: QuickEdit and ShareConnect.
2 The download page includes a separate version of ShareFile Worx for iOS that is required for use with restricted StorageZones.
Device Manager 8.7.1 and App Controller 2.10Supported NetScaler Gateway versions: 10.1.126.1203.e and 10.1.124.1308.e
Supported client versions:
MDX Toolkit Worx HomeWorxMail, WorxWeb, WorxNotes
WorxEdit ShareFile WorxDesktop
10.2.1
10.0.0
9.0.4
10.2.1: iOS and Android
10.0.0: iOS and Android
9.0.1: iOS
9.0.3: Android
10.0.0: iOS and Android
10.0.0: iOS and Android
9.0.2: iOS
9.0.3: Android
5.5.3: iOS
1.0: Android
1.2 Android
3.9: Android
3.2.3: iOS
3.3.2: Android
3.0 Android
1.2: iOS
1.0: Android
2.3 WorxMail 1.5: iOS
1.5: Android
citrix.com 24
WorxWeb1.3.1: iOS
1.3.3: Android
** **
2.2.1
WorxMail 1.3.3: iOS
1.3.13: Android
WorxWeb1.3.1: iOS
1.3.3: Android
** **
* MDX Toolkit 2.3 and 2.2.1 do not support WorxNotes.
** Not applicable
Device Manager 8.6.1 and App Controller 2.9Supported NetScaler Gateway version: 10.1.124.1308.e
Supported client versions:
MDX Toolkit Worx HomeWorxMail, WorxWeb, WorxNotes*
WorxEdit ShareFile WorxDesktop
9.0.4 9.0.1: iOS
9.0.3: Android
9.0.2: iOS
9.0.3: Android
5.5.3: iOS
1.0: Android
3.2.3: iOS
3.3.2: Android
1.2: iOS
1.0: Android
2.2.1
1.3: iOS
1.3: Android** **
* MDX Toolkit 2.2.1 does not support WorxNotes.
** Not applicable
citrix.com 25
1. 2. 3. 4.
5.
6.
a. b.
c.
d.
1.
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 or just iOS apps.A Java command-line tool that wraps Android apps. You can also run this tool on a Windows computer.
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):
“:/Android/SDK/platform-tools:/Android/SDK/build-tools/20.0.0:/Android/SDK/tools―
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.
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.
XenMobile downloads
System Requirements
MDX Toolkit System Requirements
http://www.citrix.com/downloads/xenmobile
citrix.com 26
1. 2. 3. 4.
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.
XenMobile downloads
citrix.com 27
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 28
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 a 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 29
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 30
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 31
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 32
–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 33
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.
-Sdk Optional. Used, with , to generate wrapped ISV apps. If this option is omitted, defaults to -appMode no. If included without a value, defaults to .yes
-AppMode Optional. Used, with , to indicate whether the ISV app is Premium (value of ) or General (value -sdk 1of ).2
-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.
citrix.com 34
1.
2.
-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.
-ExcludedDevices
Optional. List of device types on which the app is not allowed to run. Remains unchanged if not 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
Apple Developer
citrix.com 35
1. 2.
3. 4.
5. 6. 7. 8. 9.
10.
1.
2. 3. 4. 5. 6. 7.
1.
2. 3.
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.
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 System Preferences iCloud Keychainbox.
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 36
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 37
1.
2.
3. 4. 5.
6.
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 validate an existing iOS Developer for Enterprise certificate and provisioning profile for iOS 8 or 9To generate a new enterprise certificate for iOS 8 or 9To create a new provisioning profile for iOS 8 or 9
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
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
Wrapping iOS Mobile Apps
To validate an existing iOS Developer for Enterprise certificate and provisioning profile for iOS 8 or 9To generate a new enterprise certificate for iOS 8 or 9To create a new provisioning profile for iOS 8 or 9
Creating Provisioning Profiles
citrix.com 38
6.
7.
1. 2. 3.
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.
To generate a new enterprise certificate 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
citrix.com 39
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 40
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 41
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 42
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 43
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 44
6. 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.
citrix.com 45
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 46
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 47
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 48
-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 49
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 50
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 51
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 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 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.exeRun the MDX Toolkit for Windows Phone 8.1 on a Windows 8.1 64-bit operating system.
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 52
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.
CGAppPrepTool.exe -in:"tests\unsigned\mytest.appx" -out:"tests\output\WorxWeb.mdx" -T:"Templates\WorxWeb" -C:"tests\Mytestcert.pfx" -verbose -resign -password:mypw
citrix.com 53
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" -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"
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"
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 54
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
Default setting Notes
Authentication
Device passcode
X On
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
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.
Policy iOS Android Windows Phone 8.1
Default setting Notes
Network Requirements
Require WiFi X X Off
Administering Worx Home
citrix.com 55
Policy iOS Android Windows Phone 8.1
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
Default setting Notes
Encryption
Encryption keys X Offline access permitted
Private file encryption
X Security Group
Private file encryption exclusions
X Empty
Access limits for public files
X Empty This policy is enforced only when the Public file encryption policy is enabled (changed from the Disable option to the SecurityGroup or Application option). This policy is applicable only to existing, unencrypted public files and specifies when these files are encrypted.
X Security Group
citrix.com 56
Public file encryption
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 Complete unless open 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
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
X X Empty
citrix.com 57
Inbound document exchange whitelist
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
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 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 email compose
X On
X On
XenMobile MDX Policies for iOS Apps
citrix.com 58
Block screen capture
Block device sensor
X On
Block NFC X On
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
Policy iOS Android Windows Phone 8.1
Default setting Notes
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
citrix.com 59
PAC file URL or proxy server
X Empty
App Logs
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
Policy iOS Android Windows Phone 8.1
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.
Background services ticket expiration
X X X 168 hours (7 days)
Background network service gateway
X X X Empty If you configure this policy, set the network access policy to Tunneled to the internal
citrix.com 60
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 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.
Enable week number
X X Off
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 Security Classifications
citrix.com 61
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
Default setting Notes
WorxNotes App Settings
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
citrix.com 62
Accept all SSL certificates
X X Off
Google analytics X X On
Information Rights Management
X Off
Policy iOS Android Windows Phone 8.1
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 Windows Phone 8.1
Default setting Notes
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
citrix.com 63
Disable cookies
X Off
Disable HTML5 local storage
X Off
File protection X Off
Policy iOS Android Windows Phone 8.1
Default setting Notes
ShareFile Worx Client App Settings
Enable secure viewer
X On
Policy iOS Android Windows Phone 8.1
Default setting Notes
ShareConnect App Settings
Save password X X On For ShareConnect only.
Google analytics X X On
Quick links to related articles
Refer to the following articles for policy descriptions:
XenMobile MDX Policies for Android AppsXenMobile MDX Policies for iOS AppsXenMobile MDX Policies for Windows Phone Apps
XenMobile MDX Policies for Android AppsXenMobile MDX Policies for iOS AppsXenMobile MDX Policies for Windows Phone Apps
citrix.com 64
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 RestrictionsNetwork AccessApp LogsShareConnect 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 RestrictionsNetwork AccessApp LogsShareConnect App SettingsWorxMail App SettingsWorxNotes App SettingsWorxTasks App SettingsWorxWeb App Settings
citrix.com 65
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 that an app can continue to be used after the system has discovered that an app update is available. Default value is hours (7 days).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. 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. is the only Offline access permittedavailable 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.
Private file encryptionControls the encryption of private data files in the following locations: /data/data/appname and /mnt/sdcard/Android/data/appname. If , private files are not encrypted. If , private files are Disabled Security Groupencrypted using a key shared by all MDX apps in the same security group. If , private files are encrypted Applicationusing a key unique to this app. Default value is .Security Group
Private 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 internal and external sandboxes. Default value is empty.
Access limits for public filesContains a comma-separated list. Each entry is a regular expression path followed by (NA), (RO), or (RW). Files matching the path are limited to No Access, Read Only, or Read Write access. The list is processed in order and the first matching path is used to set the access limit. Default value is empty.
citrix.com 66
This policy is enforced only when is enabled (changed from the option to the Public file encryption Disable or option). This policy is applicable only to existing, unencrypted public files and specifies SecurityGroup Application
when these files are encrypted.
Public file encryption
Controls the encryption of public files. If , public files are not encrypted. If , public files are Disabled SecurityGroupencrypted by using a key shared by all MDX apps in the same security group. If , public files are Applicationencrypted 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 migrationThis policy is enforced only when you enable the Public file encryption policy (changed from to Disabled SecurityGroupor ). This policy is applicable only to existing, unencrypted public files and specifies when these files are Applicationencrypted. 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.
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).Caution: If you change this policy for an existing app, users must delete and reinstall the app to apply the policy 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. 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.
citrix.com 67
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
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 .On Off
If the Block Gallery policy is and the Inbound document exchange (Open In) policy is , users On Restrictedworking in managed apps cannot open images from other apps.
If the Block Gallery policy is and there is an intent created from an app, such as the action Open_Document On(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 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 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 screen capture
If , 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 sensor
If , prevents an app from using the device sensors, such as accelerometer, motion sensor, or gyroscope. OnDefault value is On.
Block NFCIf , prevents an app from using the Near Field Communications (NFC). Default value is .On On
Block app logs
citrix.com 68
If , 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 Onin) to or to fully block printing. Default value is .Restricted Blocked On
Network Access
Network accessPrevents, permits or redirects app network activity. If , no restrictions are placed on network access; apps Unrestrictedhave unrestricted access to networks to which the device is connected. If , all network access is blocked. If Blocked
, a per-application VPN tunnel back to the internal network is used for all network Tunneled to the internal networkaccess and NetScaler split tunnel settings are used.
Default value for WorxWeb and Citrix for Salesforce is . Default value for Tunneled to the internal networkWorxMail and WorxNotes is . Default value for other apps is .Unrestricted 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
, a network request that fails due to an authentication request that cannot be handled in the preferred VPN mode is Onretried 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 , the mode specified in the Preferred VPN mode policy is Offthe only mode that is used. Default value is .Off
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
citrix.com 69
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
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 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 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 export
Configuring the Secure Ticket Authority on NetScaler Gateway
citrix.com 70
Controls 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
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 , 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
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 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.
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 expiration
citrix.com 71
Time 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 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 bookmarks
citrix.com 72
Defines 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 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 73
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 RestrictionsNetwork AccessApp 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 .On
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 60
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
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 RestrictionsNetwork AccessApp LogsShareConnect App SettingsWorxMail App SettingsWorxNotes App SettingsWorxTasks App SettingsWorxWeb App SettingsShareFile Worx Client App Settings
citrix.com 74
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. Complete
If , uses NSFileProtectionCompleteUnlessOpen or higher; if a file is open when a device Complete unless open
locks, the file continues to be available to the app.
If , uses NSFileProtectionCompleteUntilFirstUserAuthentication or higher; when a device Until first unlock
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, 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 class
citrix.com 75
Note: 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.
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 Copy
citrix.com 76
Blocks, 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 , 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.
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 section, change the value of DocumentExchangeExceptionList
to . After you wrap your app, the Restricted Open-In exception list policy appears when you PolicyHidden falseadd 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
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 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
citrix.com 77
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:
+^facetime-audio:
+^ctxnotes:
+^ctxtasks:
By leaving the setting blank, all URLs are blocked, except for the following:
http:=ctxmobilebrowser:
citrix.com 78
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
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 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 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
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 email composeIf , prevents an app from using the email compose feature used to send email messages from the app. Default Onvalue is .On
Block iCloudIf , prevents an app from using iCloud for storing and sharing settings and data.OnNote: iCloud data file backup is controlled by the Block file backup policy.Default value is .On
Block file backupIf , prevents data files from being backed up by iCloud or iTunes. Default value is .On On
Block AirPrint
citrix.com 79
If , 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 attachmentNote: This policy is only enforced on iOS 9.
If , disables sending a note as an email with a PDF attachment. Default value is .On Off
Block file attachmentsNote: This policy is only enforced on iOS 9.
If , disables downloading attachments in WorxMail. Default value is .On Off
Block Facebook and Twitter APIs
If , prevents an app from using the iOS Facebook and Twitter APIs. Default value is .On On
Obscure screen contents
If , 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
Network Access
Network accessPrevents, permits or redirects app network activity. If , no restrictions are placed on network access; apps Unrestrictedhave unrestricted access to networks to which the device is connected. If , all network access is blocked. If Blocked
, a per-app VPN tunnel back to the internal network is used for all network access and Tunneled to the internal networkNetScaler split tunnel settings are used.
Default value for WorxWeb and Citrix for Salesforce is . Default value for Tunneled to the internal networkWorxMail and WorxNotes is . Default value for other apps is .Unrestricted 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. is recommended for Full VPN tunnelconnections that employ client certificates or end-to-end SSL to a resource in the internal network. is Secure browserecommended 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
, a network request that fails due to an authentication request that cannot be handled in the preferred VPN mode is Onretried 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 , the mode specified in the Preferred VPN mode policy is Offthe 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.
App Logs
citrix.com 80
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
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.
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 GatewayConfiguring the Secure Ticket Authority on
NetScaler Gateway
citrix.com 81
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 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
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.
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 Security Classifications
citrix.com 82
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 domainDefault Active Directory domain name for Exchange users. Default value is empty.
Background network services
citrix.com 83
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 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.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
citrix.com 84
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
ShareFile Worx Client App Settings
Enable secure viewer
citrix.com 85
If , 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 86
XenMobile MDX Policies for Windows Phone Apps
This article describes the MDX policies for Windows Phone 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
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 87
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 88
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 89
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 90
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 91
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 92
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 93
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 94
1. 2.
3.
System Requirements
This article includes the system requirements for MDX Toolkit 10.2 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 6 (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 95
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 96
1. a. b. c. d.
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 LibraryPublishing 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 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 the company 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 Android.
Integrating the SDK into Your App Library Using Eclipse
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 the Eclipse IDE. Android Studio and other IDEs might have different steps.
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.
2. Rename worxsdk.aar to worxsdk.zip. Unzip the worxsdk.zip into a temporary directory called worxsdk-temp. The directory structure should resemble the following:
How to Use The Worx App SDKIntegrating the SDK into Your App LibraryPublishing an Android App
XenMobile downloads
citrix.com 97
1.
3. Set up your project libs folder:
a. If your project does not have a libs folder, create it.
b. Rename worxsdk-temp/classes.jar to WorxSDK.jar and copy it into your project's libs folder.
c. Copy the contents of the -temp/libs folder into your project's libs folder.worxsdk
d. Copy the contents of the -temp/ folder into your project's libs folder.worxsdk jni
4. Click the build properties for the application and add the WorxSDK as a library on your Java build path. You should then be able to use the APIs shown in the following image.
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.
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.
Notes for ISV apps:
citrix.com 98
1.
2. a. b.
c. 3. 4. 5.
6.
If you use the GUI tool, choose the Deployment option . If For Independent Software Vendors (ISVs)you use the command-line interface, include the or -appType Premium -appType Generaloption.Note: For General apps, XenMobile ignores all Citrix policies for unmanaged users. For Premium apps, XenMobile enforces some policies even for unmanaged users.If you need to upload the wrapped .apk file to an app store or web server and you already know the URL, add the option. You can also add the URL later, as indicated later in these steps.-storeURLThe MDX Toolkit outputs a modified .apk file and file. You will use those files in the following an .mdxsteps.
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 xmlpolicies and changing 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 99
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:
MDX manages only the primary DEX file.If your app APK contains more than one DEX file, MDX doesn't alter the code in secondary files, which then run unmanaged.If you app dynamically generates DEX code or downloads DEX code, these also remain unmanaged.
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
http://android-developers.blogspot.com/2010/12/new-gingerbread-api-strictmode.html
Ensure Data Encryption Compatibility Encryption User Entropy
citrix.com 100
1.
2.
3. 4.
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.
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.
citrix.com 101
1.
2.
3.
4.
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
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:
citrix.com 102
4.
5.
1.
2. 3.
1.
2.
a. b.
c. d.
1.
2.
1. 2. 3.
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:
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.
citrix.com 103
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 104
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 105
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 106
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 107
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 108
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 109
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 110
Developing iOS Apps
Use the Worx API in your mobile apps to Worx-enable them. 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 LibraryPublishing an iOS App Using XcodePublishing an iOS App Outside of XcodeConsiderations 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 the company 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 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 5.1 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 LibraryPublishing an iOS App Using XcodePublishing an iOS App Outside of XcodeConsiderations for Upgrading Apps
Worx API for iOS
XenMobile downloads
citrix.com 111
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.
#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.frameworkCoreLocation.frameworkCoreTelephony.frameworkJavaScriptCore.frameworkLocalAuthentication.frameworkMessageUI.frameworkMobileCoreServices.frameworkPhotos.frameworkQuickLook.frameworkSecurity.frameworkSocial.frameworkSystemConfiguration.frameworkLibresolv.dylibLibstdc++.dylibLibz.dylib
The following table lists the libraries that might 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.
6. Add “Run Script Build Phase― for the project with the following script:
/Applications/Citrix/MDXToolkit/incore_macho --debug -exe"$CONFIGURATION_BUILD_DIR/$EXECUTABLE_PATH"
If needed, replace the path of MDXToolkit with the path in your environment.
7. For XCODE 5 and later change the default flag for to .Strip Linked Product No
This setting is in the build settings of your project.
8. Compile your project and generate the app binaries.
citrix.com 112
9. Compile and archive the project to generate the app bundle that contains the embedded Worx framework; that is, the .ipa package.
Publishing an iOS App Using XcodeYou can 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.
1. Select your project in Xcode, and select the tab. Click the icon in the upper left corner and then Build Phases +select .New Run Script Phase
2. Open the new Run Script, and type (do not copy/paste) the following text into the field. Be sure to change the Script, , , and variables to values that are applicable to your app. The PACKAGEID APPMODE STOREURL POLICYFILE is a unique identifier for your app, typically a UUID.PACKAGEID
Type the following into the field. Copy and paste will not work correctly.Important: Script
export PACKAGEID=" "your-project-PackageIDexport APPMODE="2"export 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}" -appMode"${APPMODE}" -packageId "${PACKAGEID}" -policyXML "${POLICYFILE}" -entitlements "${CODE_SIGN_ENTITLEMENTS}"
For example:
export PACKAGEID="a96d6ed5-6632-4739-b9b6-9ad9d5600732"export APPMODE="2"export 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}" -appMode"${APPMODE}" -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.
-appMode modeIndicates whether the ISV app is Premium (value of ) or General (value of ).1 2
-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.
3. Build your app in Xcode, verifying that it builds correctly.
4. Archive your app by selecting .Product > Archive
citrix.com 113
1.
2. a. b.
c. 3.
4.
5.
6.
5. The Xcode Organizer should open automatically after your app is archived.
6. Select your archived build in Organizer and then click the button.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 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
Publishing an iOS App Outside of XcodeYou can also wrap and publish an iOS app outside of Xcode. After you add the Worx App SDK to an iOS app, perform the following steps to wrap, test, certify, and publish the app.
Use the MDX Toolkit to wrap the .ipa file for the app. For details, see in the MDX Toolkit documentation. That article includes all wrapping commands, including those specific to ISV apps..
Notes for ISV apps:
If you use the GUI tool, choose the Deployment option . If For Independent Software Vendors (ISVs)you use the command-line interface, include either (for Premium apps) or - -appMode "1"sdk -
(for General apps). -appMode "2"sdkNote: For General apps, XenMobile ignores all Citrix policies for unmanaged users. For Premium apps, XenMobile enforces some policies even for unmanaged users.If you need to upload the wrapped .ipa file to an app store or web server and you already know the URL, add the option. You can also add the URL later, as indicated later in these steps.-storeURLThe MDX Toolkit outputs a modified .ipa file and file. You will use those files in the following an .mdxsteps.
Test your app:Install the modified .ipa file on an iOS device to verify all app functions.Use the XenMobile console to add the .mdx file to XenMobile and deliver it to an iOS 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_policies. , test those changes. For details about adding xmlpolicies and changing policy defaults, see .
Fix any issues found in your app, regenerate its .ipa file, and wrap it again with the MDX Toolkit.Submit the following files to Citrix for verification:
The original .ipa fileThe .ipa file with the embedded Worx frameworkThe modified .ipa file and .mdx file generated by the MDX Toolkit
After Citrix verifies your app, use the Apple Application Loader tool to submit the .ipa file generated by the MDX Tookitto the Apple App Store for approval.After Apple 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:
./CGAppCLPrepTool \ setinfo \ -in "~/Desktop/ / .mdx" \ SampleApps Sample-out “~/Desktop/ / / .mdx" \ SampleApps wrapped Sample-storeURL "https://itunes.apple.com/us/app/w1browser/id579414750?ls=1&mt=8"
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
To add an MDX app to XenMobile
Wrapping iOS Mobile Apps
To add an MDX app to XenMobile
Policy Defaults and Custom Policies
Citrix Ready MarketplaceCitrix Ready Worx Verified Program
citrix.com 114
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.
citrix.com 115
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 116
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 117
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 118
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 119
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 120
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 121
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 (iOS 8 and earlier)
citrix.com 122
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 123
/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
For icon files with Xcode 5 and above:
The files must support icons for devices having iOS 6 and above (some icon entries must be present in info.plist).Citrix doesn't currently support asset files for icons. This is due to the Apple proprietary format which currently cannot be interpreted.MDX wrapping requires the presence of at least one icon which can be used as the springboard icon or app icon.If icons are not properly named, Citrix will pick the first one from the list of known plist locations:
citrix.com 124
CFBundleIconsCFBundlePrimaryIconCFBundleIconFilesUINewsstandIconCFBundleDocumentTypes
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.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 125
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 126
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 127
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 128
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 129
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 130
BOOL result = [WorxSharedKeychainVault deleteVault:<VAULT_NAME> accessGroup:kWorxKeychainAccessGroup error:&error]; #endif } ... @end
citrix.com 131
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 132
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 133
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 134
© 1999-2015 Citrix Systems, Inc. All Rights Reserved.
Top Related