Using the AppConnect App Wrapper (wrapping tool)

The AppConnect App Wrapper, also known as the wrapping tool, is an MacOS app that MobileIron provides. Its output is a wrapped, signed app. It also can output a wrapped, unsigned app, which you can give to another party to sign. You can run the wrapping tool using either its graphical user interface or using a command-line interface (CLI). The CLI is useful when you want to wrap an app from an automated script.

Important: You cannot wrap an app if you got the app (IPA file) from the Apple App Store.

Before you begin

Before you use the wrapping tool, be sure the unwrapped app installs and runs according to your requirements.

System requirements

The wrapping tool is supported only with the following versions of MacOS and Xcode listed in Product versions required.

Install Xcode

Install Xcode from the Apple App Store. After the installation completes, open Xcode and accept the license agreement. Then enter your administrator password for your MacOS system, if prompted for it.

Before you run the wrapping tool

Before you run the wrapping tool, make sure you have the following:

• Permission on your MacOS computer to allow apps that are not from the Mac App Store.

On your computer, go to System Preferences > Security & Privacy > General. For the setting “Allow apps downloaded from”, select “Mac App Store and identified developers”.

• The signed, unwrapped IPA file for the app that you want to wrap.

Make sure that you or another party signed the app according to Apple’s requirements.

• The signing identity, if you plan to re-sign the wrapped app now.

You can distribute an app only if the app is signed. The wrapping tool gives you the option to sign the wrapped app. To use that option, make sure you have the signing identity that you want to use in the keychain. You can use the same signing identity as the unwrapped app or a different signing identity.

If you are using the CLI, make sure that the keychain containing the signing identity is unlocked. See Unlock the keychain containing the signing identity.

If you do not sign the app with the wrapping tool, you can sign the app later.
MobileIron provides a signing script called sign_wrapped_app.sh for this purpose. Typically, you sign the app with the wrapping tool unless you do not have access to the signing identity. For example, only another person in your enterprise or at a third-party enterprise has the signing identity.

• The provisioning profile, if different from the unwrapped app’s provisioning profile.

Typically, you re-use the provisioning profile from the unwrapped app. However, some reasons to replace it are that it has expired, or the signing identity is different from the unwrapped app. If necessary, install the new provisioning profile on the MacOS computer using Xcode.

To learn about signing identities and provisioning profiles, see Apple documentation at http://developer.apple.com.

Get the wrapping tool and signing script

The wrapping tool and signing script are located at:

https://support.mobileiron.com/mi/appconnect_app_wrapper/iOS/current

The wrapping tool is in AppConnectAppWrapper-<version number>.zip. Download the zip file to an MacOS computer and unzip the file.

The signing script is called sign_wrapped_app.sh.

Unlock the keychain containing the signing identity

If you plan to sign the wrapped app using the wrapping tool CLI, first make sure the keychain containing the signing identity is unlocked.

MacOS computers store signing identities and other security related items in keychains. A keychain is a password-protected file with the .keychain extension. It must be added to the keychain system on the MacOS computer before a program can use it. A keychain is either locked or unlocked. When locked, you cannot sign an app with a signing identity in the keychain unless you provide the keychain’s password.

Therefore, before running the wrapping tool CLI, unlock the keychain if the signing identity is in a locked keychain. If you do not, MacOS prompts you for the password in a dialog box. This graphical prompt occurs when running the wrapping tool with either the graphical user interface or CLI. When using the CLI from an automated script, avoiding this prompt is critical to the script’s success.

The MacOS KeyChain Access application and the command-line program security allow you to view and manipulate keychains and their contents.

Use the following command-line command to unlock the keychain:

security unlock-keychain -p <password> <path to .keychain file>

Important: Signing identities are security sensitive because they can be used to sign malicious apps that appear to be your legitimate app. Take appropriate measures to secure the keychain that contains the signing identity and to secure the keychain’s password.

Run the wrapping tool using its graphical user interface

Run the wrapping tool, following the instructions in the tool’s graphical user interface.

Alternatively, you can run the wrapping tool using a command-line interface from a Terminal window or a script. For details, see Run the wrapping tool using a command-line interface.

Run the separate signing script, if necessary

The wrapping tool gives the option to sign the wrapped app. If you do not sign the wrapped app with the wrapping tool, sign it using the MobileIron-provided script called sign_wrapped_app.sh. This step is necessary if the person using the wrapping tool does not have access to the signing identity for the app.

Instructions for using sign_wrapped_app.sh are in Re-signing the wrapped app.

Run the wrapping tool using a command-line interface

You can run the wrapping tool using a command-line interface (CLI) from a Terminal window or a script. You provide command-line arguments instead of following a graphical user interface. Running the wrapping tool using the command-line interface is useful, for example, to automate wrapping as part of your regular app build process.

Since MacOS apps comprise a directory of resources and executables, the wrapping tool app contains its command-line executable in the following directory:

<wrapping tool installation directory>/AppConnect\ App\ Wrapper.app/Contents/MacOS/

The executable is AppConnect\ App\ Wrapper.

Therefore, to run the wrapping tool using the CLI, use the following command:

<wrapping tool installation directory>/AppConnect\ App\ Wrapper.app/ \
Contents/MacOS/AppConnect\ App\ Wrapper <command-line arguments>

Command-line argument usage

Running the wrapping tool from the command-line requires that you enter command-line arguments. Some of the arguments are the options that determine the action that the wrapping tool takes. Include exactly one of the following options:
-w, -i, -f, -v, -h.

The following table shows the command-line argument usage.

Table 1. Command-line argument usage

Command-line usage

Purpose

./AppConnect\ App\ Wrapper --nogui -w [-s identity] \
[-p profile] [-o outputPath]
[--quiet] <app to wrap>

Wraps an app.

 
./AppConnect\ App\ Wrapper --nogui -i [--verbose|--quiet]

Lists the names of available signing identities.

./AppConnect\ App\ Wrapper --nogui -f [--verbose|--quiet]

Lists the names of available provisioning profiles.

./AppConnect\ App\ Wrapper --nogui -v

Displays the version number of the wrapping tool.

./AppConnect\ App\ Wrapper --nogui -h

Displays the command-line usage.
NOTE: The order of the options does not matter. For example, --nogui can appear before or after -w.

Command-line argument descriptions

The following table describes the command-line arguments.

Note The Following:  

  • For the options -w, -i, -f, -v, and -h, you can also use the corresponding long name: --wrap, --listidentities, --listprofiles, --verbose, and --help.
  • All long names must begin with a double dash whereas the one character options begin with a single dash.
Table 2. Command-line arguments

Argument

Description

<app to wrap>

Specifies the absolute or relative path to the IPA file to wrap.

Use this argument only when you specify the --wrap argument.

--nogui

Suppresses the graphical user interface.

If you do not include --nogui:

• the wrapping tool ignores all other command-line arguments
• the wrapping tool graphical user interface launches

--verbose

Displays more detailed information as follows:

• With --listidentities, displays the expiration date of each signing identity.
• With --listprofiles, displays the expiration date and bundle ID matching rule for each provisioning profile.

--quiet

Does not display command-line help text when an error occurs.

Without --quiet, when an error occurs, the output displays the error information following by the --help text.

--wrap or -w

Wraps the app.

When you use this argument, you can also specify these arguments:

--sign

--provision

--output

<app to wrap>

--listidentities or -i

Lists the names of the available signing identities that you can use with the --sign option.

Use the --verbose option to list more detailed information.

--listprofiles or -f

Lists the names of the available provisioning profiles that you can use with the --provision option.

Use the --verbose option to list more detailed information.

--version or -v

Displays the version number of the wrapping tool.

--help or -h

Displays help text describing the command-line arguments.

--sign <identity name>

or

-s <identity name>

Signs the wrapped app with the specified signing identity. Use this argument only when you specify the
--wrap argument.

If you do not include the --sign argument, the app is wrapped but not signed.

--provision <profile name>

or

-p <profile name>

Provisions the wrapped app with the specified provisioning profile. If multiple provisioning profiles have the specified name, the wrapping tool uses the profile with the most recent creation date.

Use this argument only when you specify the --wrap argument.

Make sure that the provisioning profile:

• embeds the signing identity that you chose in the
--sign argument.
• contains a bundle ID search string that matches the bundle ID of the app.

 

If you do not include the --provision argument, the wrapping tool uses the unwrapped app’s provisioning profile.

--output <output file>

or

-o <output file>

Saves the wrapped app to the specified file. Specify the absolute or relative path to the file. Use this argument only when you specify the --wrap argument.

If you do not include the --output argument, the wrapping tool:

• puts the wrapped app in the same directory as the unwrapped app.
• appends " Wrapped" to the unwrapped app’s file name.

For example, wrapping MyApp.ipa creates MyApp Wrapped.ipa.

Command-line usage examples

The following examples demonstrate command-line usage. Each example assumes that the current directory is:

<wrapping tool installation directory>/AppConnect\ App\ Wrapper.app/Contents/MacOS

Table 3. Command-line usage examples

Example

Wrapping tool’s actions

./AppConnect\ App\ Wrapper --nogui -w \

-o ~/MyApp_Wrapped.ipa ~/MyApp.ipa

• Wraps the app ~/MyApp.ipa.
• Does not sign the wrapped app.
• Uses the unwrapped app’s provisioning profile for the wrapped app.
• Puts the wrapped app in
~/MyApp_Wrapped.ipa

Using short option names:

./AppConnect\ App\ Wrapper --nogui -w \
-s "iPhone Distribution: MyCompany" \
-p "Wildcard Distribution" \
-o ~/MyApp_Wrapped.ipa ~/MyApp.ipa

 

Using long option names:

./AppConnect\ App\ Wrapper --nogui --wrap \
--sign "iPhone Distribution: MyCompany" \
--provision "Wildcard Distribution" \
--output ~/MyApp_Wrapped.ipa ~/MyApp.ipa

• Wraps the app ~/MyApp.ipa.
• Signs the wrapped app with the specified signing identity.
• Provisions the wrapped app with the specified provisioning profile.
• Puts the resulting wrapped app in ~/MyApp_Wrapped.ipa.

./AppConnect\ App\ Wrapper --nogui -i --verbose

Lists the name and expiration date of each available signing identity.

./AppConnect\ App\ Wrapper --nogui -f --verbose

Lists the name, expiration date, and bundle ID matching rule of each available provisioning profile.

./AppConnect\ App\ Wrapper --nogui -v

Displays the version number of the wrapping tool.

./AppConnect\ App\ Wrapper --nogui -h

Displays the command-line usage.

Command-line command exit status

If the command-line command is successful, the command sets the exit status to 0.

If it is unsuccessful, it does the following:

  • Sets the exit status to 1.
  • Outputs a detailed error message and error code to stderr.
  • For appropriate cases, outputs the command-line usage to stderr.