Re-signing the Apple iOS client application for Enterprise distribution

Before you begin

1. You must be a member of the Apple Enterprise Program to obtain the required development tools from the Apple Developer Portal. See the following resources for more information:

• 
  
  • Apple Enterprise Program application—Apple requires you to be a company or organization with a D-U-N-S number to apply. An enterprise account allows you to distribute the rebranded application internally. An organization account enables you to distribute applications through the Apple store only.
  • Apple Developer Portal—Contains the development tools and documentation for developing Apple iOS apps.
  • Managing Your Team—Describes how to assign appropriate team roles. To complete the following procedures, you must assign the Team Agent role to the user who will create the certificate.
  • Maintaining Your Signing Identities and Certificates—Provides information about certificates.

2. You must have XCode and Apple root certificates installed.

To install Xcode and the Apple root certificate

You are required to perform this procedure only once. You need Xcode developer tools to install the entitlements file as part of the re-signing process.

1. On an Apple computer running MacOS, install the free Xcode from the App Store.
   Xcode cannot be used on an iPad, iPhone, or other iOS device.
2. Install the Apple root certificate, as follows:
   
   1. Go to http://www.apple.com/certificate authority/.
   2. Download the Apple Inc. Root Certificate.
   3. Double-click the file, and install it in the Keychain (login).

To re-sign the Apple iOS client application

Perform the following steps to re-sign the Apple iOS application:

1. Create an enterprise distribution certificate to re-sign BMC Digital Workplace
2. Create an App Group for BMC Digital Worplace
3. Create an iCloud container for BMC Digital Workplace
4. Create an application ID and bundle ID for your version of BMC Digital Workplace
5. Edit your existing application ID or adding the App Group and iCloud to your version of BMC Digital Workplace
6. Create an in-house distribution provisioning profile
7. Create an Apple Push Notification Service (APNS) certificate
8. Re-sign the mobile application with your enterprise credentials
9. Replace the APNS certificate with your APNS certificate

To create an enterprise distribution certificate to re-sign BMC Digital Workplace

You will use this certificate to sign the BMC Digital Workplace iOS application.

1. Log on with the Team Agent role to the iOS Provisioning Portal at https://developer.apple.com/account/ios/certificate.
2. In the Certificates section, click the plus sign (+) to add the certificate.
3. In the Production section, select In-House and Ad Hoc.
4. Generate a certificate signing request (CSR) by using the Certificate Assistant.
   Follow the instructions that Apple provides on the CSR screen.
5. Upload the CSR to the iOS Provisioning Portal, and download the distribution certificate.
6. Save the certificate, and open it with the Key Chain Access application.
7. To export the certificate to a different build, save it in .p12 format:
   
   1. In Key Chain Access, go to the My Certificates section.
   2. Right-click the downloaded certificate, and click Export.
   3. Save the certificate in .p12 format, and provide a secure password when required.

To create an App Group for BMC Digital Workplace

1. With the Team Agent role, log on to the iOS Provisioning Portal.
2. In the Identifiers section, click the App Groups tab.
3. Click the plus sign (+) to add a new identifier.
4. In the Description field, type a name that will easily identify your application to you within the portal (for example, Calbro Digital Workplace Group ).
5. In the ID field, enter a unique group name (for example,   group.com.companyName.DWP).
6. Click Continue.

7. Click Register.
   The new App Group appears as shown in the following illustration:

   

To create an iCloud container for BMC Digital Workplace

1. With the Team Agent role, log on to the iOS Provisioning Portal. 
2. In the Identifiers section, click the iCloud Containers tab. 
3. Click the plus sign (+) to add a new identifier. 
4. In the Description field, type a name that will easily identify your application to you within the portal (for example, Digital Workplace iCloud Container). 
5. In the ID field, enter a unique group name (for example,  iCloud . group.com.companyName.DWP).
6. Click Continue.

To create an application ID and bundle ID for your version of BMC Digital Workplace

You will need the application ID in To create an in-house distribution provisioning profile. You will need the bundle ID in To re-sign the mobile application with your enterprise credentials.

1. With the Team Agent role, log on to the iOS Provisioning Portal.
2. In the Identifiers section, click the App IDs tab.
3. Click the plus sign (+) to add a new identifier.
4. In the Description field, type a name that will easily identify your application to you within the portal (for example, Calbro Digital Workplace).
5. Make a note of the app ID prefix (team ID), which you will use in the re-signing process.
6. Select Explicit App ID, and enter a unique identifier in the Bundle ID field (for example, com.companyName.DWP).
7. Make a note of the bundle ID for the re-signing process.
8. In the App Services section, leave the defaults as they are, but ensure that Associated Domains, Push Notifications, iCloud, and App Group are selected.
   
   1. For iCloud, select the Include CloudKit support (requires Xcode 6) option. 
   2. For Data Protection select Complete Protection.
9. Click Continue.

10. To return to the Identifiers list, click Done.

    The new app ID appears as shown in the following illustration:

    

To edit your existing application ID or adding the App Group and iCloud to your version of BMC Digital Workplace

1. Log on to the iOS Provisioning Portal with the Team Agent role.
2. In the Identifiers section, click the App IDs tab.
3. Select your BMC Digital Workplace application ID (for example, com.companyName.DWP).
4. Click Edit.
5. Click the select box next to App Groups.
6. When prompted to Enable App Groups, click OK.
   
7. Click Edit on App Groups.
8. Select the App Group created for BMC Digital Workplace (for example, group.com.companyName.DWP).
9. Click Continue.
10. Click Assign.
11. Click Done.
12. Click Edit next to the iCloud option. 
13. Select the iCloud container you created above (for example,  iCloud . group.com.companyName.DWP).
14. Click Continue.
15. Click Assign.
16. Click Done.

To create an in-house distribution provisioning profile

You need this profile to deploy the BMC Digital Workplace mobile application to your organization.

1. Log on with the Team Agent role to the iOS Provisioning Portal.
2. In the Provisioning section, click the Distribution tab.
3. Click the plus sign (+) to add a new profile.
4. On the Create iOS Provisioning Profile page, complete the following steps:
   1. For the Distribution Method, select In House.
   2. Select the distribution certificate that you created.
   3. Select the application ID that you created in To create an application ID for your version of BMC Digital Workplace .
5. Download the provisioning profile.

To create an Apple Push Notification Service (APNS) certificate

You need this certificate, so that the mobile application can receive notifications.

1. Log on with the Team Agent role to the iOS Provisioning Portal.
2. In the Certificates section, click the Production tab.
3. In the top-right corner, click the plus sign (+).
4. Select Apple Push Notification Service SSL (Production).
5. Select the App Prefix ID (Team ID) that you created.
6. Generate a certificate signing request (CSR) by using the Certificate Assistant.
   Follow the instructions that Apple provides on the CSR screen.
7. Double-click the certificate to download it and import it into your Keychain.

To re-sign the mobile application with your enterprise credentials

You can re-sign the mobile application with your enterprise credentials in any of the following ways:

• (Recommended) Re-sign the mobile application with your enterprise credentials by using the iOS re-signing and rebranding utility

• Re-sign the mobile application with your enterprise credentials manually

  The following video (3:36) shows how to re-sign the mobile application: 

To re-sign the mobile application with your enterprise credentials

The following procedure provides instructions to re-sign the BMC Digital Workplace mobile application by using the iOS re-signing and rebranding utility, which is available with BMC Digital Workplace installation.

1. On your Mac computer, install the enterprise distribution certificate to re-sign the mobile application that you created earlier.
2. On your Mac computer, download the in-house distribution provisioning profile that you created earlier.
   
3. Download or copy the iOS re-signing and rebranding utility Resign.dmg file to your Mac computer.
   The utility is available at DigitalWorkplaceHome\DWP\IPA\download\utils directory, where DigitalWorkplaceHome is the installation directory.
4. Open the Resign.dmg file and run the ResigningUtility.app application.

5. Select 

   BMC Digital Workplace

    application and click Next.

6. Select a version and click Next.

7. Create a new re-signing project or open an existing one. If you are creating a new project, provide the following details:

   1. Project Name—Give the re-signing project a name, for example, DigitalResignDemo.
   2. Project Location—Select a directory on your Mac computer for storing the project.

   The utility creates a project file, for example DigitalResignDemo.resign and different subdirectories within the project directory.

   Note

   You can use the same project file to re-sign a new xarchive file that is provided as a patch or a new build.

    

8. Go to the Configurations tab and enter values for all mandatory parameters and set values for optional parameters, if required.
   The utility displays a short description of each parameter. The parameters marked with an asterisk (*) are mandatory.

1. (Optional) Perform the steps to customize the visual design. For instructions, see Rebranding-the-Apple-iOS-client-application.

   Note

   The re-signing and rebranding is done within the same project.

2. From the list of projects in the left pane, navigate to Projects > projectName > Entitlements.
   Here, projectName is the name of the project you provided earlier, for example, DigitalResignDemo.
3. Select the MyIT.entitlements file.
   You can preview the content of the entitlements file in the right pane.

4. Click Open to Edit and update the values of application-identifier and keychain-access-groups.

   1. Replace the value for the application-identifier key with your team prefix and App ID.
      For example, replace ABCDE-ID.com.bmc.bsmapps.MyIT with  TEAMBUNDLEID.com.companyName.DWP
   2. Replace the keychain-access-groups key value with your team prefix and App ID.
      For example, replace ABCDE-ID.com.bmc.bsmapps.MyIT with TEAMBUNDLEID.com.companyName.DWP

   Note

   You must update the entitlements file only the first time you are re-signing a particular version of BMC Digital Workplace. You can reuse the same entitlements file every time you re-sign that version of BMC Digital Workplace.

5. From the list of projects on the left pane, navigate to Projects > projectName > xcarchive > exportOptions.plist, and click Open to Edit.

6. Enter values for the provisioningProfiles, signingCertificate, and teamID parameters that you used for your app.

   Note

   Do not forget to replace the example values in your code as shown below. If you are copying and pasting the code sample directly, also remember to remove the comments.

   
   

   {
   compileBitcode = 0
   method = enterprise
   provisioningProfiles = {
   com.bmc.testdistmyit = "TestDistMyITDist"; //example value, replace value with profile value provided for app
   }
   signingCertificate = "iPhone Distribution: BMC Software, Inc." //example value, replace value with enterprise certificate create earlier
   signingStyle = manual
   stripSwiftSymbols = 1
   teamID = "M2H62N6SQK" //example value, replace value with team's ID provided for app
   thinning =
   }
7. Save the file.
8. Right-click the project name, and click Re-sign.
9. Select the following items:

   1. The xcarchive file to re-sign and generate an .ipa file from it. 

      Note

      BMC Remedy Service Management OnDemand customers must download the BMC iOS Rebranding Utility Version 18.02.00 xcarchive file from the EPD (found under BMC Digital Workplace Basic Cloud and BMC Digital Workplace Advanced Cloud products for version 18.02.00), and unzip it.

   2. Your enterprise certificate, which was created previously.
      
   3. Your provisioning profile created for the enterprise certificate.
10. Click Re-sign.
    An .ipa file is created in the IPA sub-directory within your re-signing project directory. Provide this .ipa file to your iOS users for installing the BMC Digital Workplace application. 

 To re-sign the mobile application with your enterprise credentials manually

This procedure provides instructions to re-sign the BMC Digital Workplace mobile application manually.

You are now ready to re-sign the mobile application. You will work with the dwp.ipa file.

1. In the terminal application, unzip the dwp.ipa file by entering the following commands. Replace /path/ with a specific path on your system; for example, /User/bill/DWP-working/.

   mkdir /path/DWP-ResignDir
   cd /path/DWP-ResignDir
   unzip –oq /path/dwp.ipa

2. Clear out the previous build files, by entering the following commands:

   rm -rf "$(getconf DARWIN_USER_CACHE_DIR)/org.llvm.clang/ModuleCache"
   rm -rf ~/Library/Developer/Xcode/DerivedData
   rm -rf ~/Library/Caches/com.apple.dt.Xcode
   
3. Create the exportOptions.plist file, and click Open to Edit.

4. Enter values for the provisioning profiles, signingCertificate, and teamID parameters.  You can find the values for these parameters in the Apple Developer portal.

   {
   compileBitcode = 0
   method = enterprise
   provisioningProfiles = {
   com.bmc.testdistmyit = "TestDistMyITDist";
   }
   signingCertificate = "iPhone Distribution: BMC Software, Inc."
   signingStyle = manual
   stripSwiftSymbols = 1
   teamID = "M2H62N6SQK"
   thinning =
   }

5. From the command line, run the following commands:

   
   

   xcodebuild -exportArchive -archivePath dwp.xcarchive \
   -exportPath ./dwp.ipa \
   -exportOptionsPlist exportOptions.plist

6. Re-sign the swift code dylibs with the following command. Replace BMC Software, Inc. with the name of your organization.

   /usr/bin/codesign -f -s "iPhone Distribution: BMC Software, Inc." ./Payload/MyIT.app/Frameworks/*.dylib
   

7. In Xcode, create a MyIT.entitlements file in the /path/DWP-resign-ipa directory, and add the following lines. You can download a copy of MyIT.entitlementsto use as a starting point.

   MyIT.Entitlements file

   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
   <key>application-identifier</key>
   <string>ABCDE-ID.com.bmc.bsmapps.MyIT</string>
   <key>aps-environment</key>
   <string>production</string>
   <key>get-task-allow</key>
   <false/>
   <key>keychain-access-groups</key>
   <array>
   <string>ABCDE-ID.com.bmc.bsmapps.MyIT</string>
   </array>
   </dict>
   </plist>
8. In the sample entitlements file, perform the following actions:
   • Replace the value for the application-identifier key with your team prefix and App ID.
     For example, replace ABCDE-ID .com.bmc.bsmapps.MyIT with TEAMBUNDLEID.com.companyName.DWP.
     
   • Replace the the keychain-access-groups key value with your team prefix and App ID.
     For example, replace ABCDE-ID.com.bmc.bsmapps.MyIT with TEAMBUNDLEID.com.companyName.DWP.
     
9. Perform the steps to customize the visual design. For instructions, see Rebranding-the-Apple-iOS-client-application.
10. Place the provisioning profile that you created into the /path/DWP-ResignDir folder , and rename the file to MyIT.mobileprovision. For instructions, see Creating your in-house distribution provisioning profile for details about creating your own provisioning profile.

11. Navigate to the /path/DWP-ResignDir folder.

    cd /path/DWP-ResignDir
    
12. From the /path/DWP-ResignDir folder, perform the following actions:

    1. Set the bundle ID (see the Apple Developer Site for more information), where CompanyDomain is your domain in reverse DNS format (for example, com.acme), and MYIT-APPNAME is the unique internal application name for BMC Digital Workplace (for example, Digital-Acme):

       /usr/libexec/PlistBuddy -c "Set CFBundleIdentifier CompanyDomain.MYIT-APPNAME" ./Payload/MyIT.app/Info.plist

    2. Set the application name displayed on the iOS devices, where ApplicationName is the name of your BMC Digital Workplace application (for example, Digital Workplace or Acme Digital Workplace):

       /usr/libexec/PlistBuddy -c "Set CFBundleDisplayName ApplicationName" ./Payload/MyIT.app/Info.plist

    3. Set the default BMC Digital Workplace server to your BMC Digital Workplace server, where SERVER is your BMC Digital Workplace server name (for example, DWP.acme.com):

       /usr/libexec/PlistBuddy -c "Set myit-server SERVER" ./Payload/MyIT.app/Info.plist

    4. Set the default port for your BMC Digital Workplace server, where PORT is the TCP port for clients to access the server (for example, 80 or 443):

       /usr/libexec/PlistBuddy -c "Set myit-port PORT" ./Payload/MyIT.app/Info.plist

    5. Replace the mobile provision file as shown in the example:

       cp "MyIT.mobileprovision" "./Payload/MyIT.app/embedded.mobileprovision"

    6. Remove the the BMC code signature as shown in the example:

       rm -r "./Payload/MyIT.app/_CodeSignature"

    7. Issue the following command to re-sign the IPA. Replace BMC Software, Inc. with the name of your organization.

       /usr/bin/codesign -f -s "iPhone Distribution: BMC Software, Inc." --entitlements "./MyIT.entitlements" "./Payload/MyIT.app"
       

13. Create the IPA zip file as shown in the example:

    zip -qr "DWP-rebranded.ipa" Payload

To replace the BMC Digital Workplace APNS certificate with your APNS certificate

After you complete this procedures, any notifications to iOS devices from your server (or tenant in multitenant environments) are sent using the new certificate.

1. Log on to the server that hosts the BMC Digital Workplace server.
2. Stop the Apache Tomcat instance that executes the BMC Digital Workplace server.
3. Find the external-conf folder under the Tomcat home folder.
4. Create a subfolder called certification.
5. Place the p12 file exported from the APNS certificate, which you created in To create an enterprise distribution certificate to re-sign the mobile client, into the following subfolders: 
   
   • Tomcat8.5\external-conf\certification\ 
   • ux\WEB-INF\classes\certification.
6. Log on to the Oracle or Microsoft SQL database used for BMC Digital Workplace.
7. Go to the PUSH_NOTIFICATION_CERT table, and query for records. 
8. If you are changing the iOS APNS certificate, perform the following actions:
   1. In the iOS_Cert field, replace the current value with the name of the p12 file that contains your new APNS certificate. The default value is BMCiOSAPNSMyITMobile.p12.
   2. In the iOS_Password row, replace the current password with the password of your p12 file. Enter the password in plain text.
9. Click Save. 
10. Start the Tomcat instance.

Where to go from here

Updating-the-server-location-in-the-Apple-iOS-client