How To
Archived

How do I update and recompile the iOS Authenticator App 1 or 2.x with custom branding?

Last updated Mar 14, 2023

The purpose of this article is to provide information on updating and recompiling the iOS® ForgeRock Authenticator App so that it can be published to the Apple® App Store. Changes include renaming the App and rebranding changes, such as updating the Splashscreen video, updating the App icon and changing default colors.

Archived

This article has been archived and is no longer maintained by ForgeRock.

Warning

ForgeRock support covers the use of the official binary builds made available and downloaded from our customer portal: BackStage. We will support builds made from source providing no changes have been made to the core code of the product, the product was built from a tag that matches an official release, for example, 6 and said product was built using the ForgeRock build scripts provided as part of the source. In the event that a customer experiences an issue with a ForgeRock product built from source where ForgeRock believe the issue is as a result of the build process, ForgeRock reserves the right to ask the customer to attempt to reproduce the issue on an official ForgeRock binary build. Customers who are running custom builds or who need further clarification should contact their ForgeRock sales representative.

Overview

This article explains how to clone the iOS ForgeRock Authenticator App source code and create your own version of the App that you can publish to the Apple App Store. There is also a section that provides links relevant to setting up Push notifications.

High level steps

  1. Create a new iOS App Bundle ID
  2. Obtain Authenticator source, prepare a project and open in Xcode
  3. Launch the App on an iPhone®
  4. Rename the project
  5. Rename the scheme
  6. Update the CocoaPods configuration
  7. Rename the ForgeRock-Authenticator directory
  8. Rename the Entitlements file
  9. Update the Build settings and rebuild
  10. Update the Test Build settings
  11. Update the Splashscreen video
  12. Update App Permission Request dialogs
  13. Update Localizable.strings
  14. Update About.strings
  15. Update the App icon
  16. Update the Default Account icon
  17. Update the Default colors
  18. Publish your App

These steps were completed using Xcode Version 10.0 (10A255).

Note

Before updating the Authenticator app, please make sure Xcode® is installed and up-to-date.

Create a new iOS App Bundle ID

  1. Log in to your paid Apple Developer account (http://developer.apple.com/account).
  2. Select Certificates, Identifiers & Profiles.
  3. Select App IDs (under Identifiers in the menu on the left).
  4. Select the “+” (Add) icon.
  5. Complete the Registering an App ID form:
    1. Enter an App ID description, for example “ACME Authenticator”.
    2. Select Explicit App ID and enter a bundle ID, for example “com.acme.authenticator”.
    3. Leave default selections for App Services (we will enable “Push Notifications” later in this article):
  1. Select “Register”, then “Done” to complete creation of your new iOS App Bundle ID.

Obtain Authenticator source, prepare a project and open in Xcode

Note

To clone the source code with a SSH URL, you must have created a SSH key and added it to your Bitbucket profile.

  1. Git clone the ForgeRock Authenticator iOS repository: $ git clone ssh://git@stash.forgerock.org:7999/openam/forgerock-authenticator-ios.git
  2. Install CocoaPods. See CocoaPods - Getting Started for further information.
  3. Prepare the project to be opened in Xcode:
    1. Navigate to the project’s root directory on the command line and download the project’s dependencies: $ cd forgerock-authenticator-ios $ pod install
    2. Open the project in Xcode: $ open ForgeRock.xcworkspace/
  4. Select the “ForgeRock” folder from the “Project Navigator View” in Xcode to view the App’s configuration in the main Xcode view.
  5. Update the App Identity settings:
    1. Bundle identifier, this should be the same as set in step 5b in the previous section, for example “com.acme.authenticator”.
    2. Version, for example “1.0.0”.
    3. Build, for example “1”.
  6. Update the App Signing settings:
    1. Enable “Automatically manage signing”; this is enabled for the official ForgeRock App.
    2. Team, this should refer to your Apple developer account.
    3. Provisioning profile, you should have a provisioning profile.
    4. Signing certificate, you should have a signing certificate.

Before making further changes, now would be a good time to verify that you are able to run the code on a physical device as detailed in Launch the App on an iPhone.

Dependency versions

Downloading the project's dependencies captures the versions in the Podfile.lock file (located in the project's root directory). This ensures that the same versions will be downloaded if the pod install command is re-run.

To update to a newer version of a dependency, you can use a combination of pod outdated to identify dependencies that are outdated and pod update to update them. See CocoaPods install vs update documentation for further details. If you make changes to third-party dependencies, you must also update the LIBRARIES file.

Launch the App on an iPhone

  1. Connect an iPhone to the laptop running Xcode.
  2. Accept the dialog displayed on your iPhone asking if you would like to trust your computer.
  3. Select your phone from the devices dropdown in the top-left of Xcode.
  4. Select the “Play” icon.

Rename the project

  1. Select the “ForgeRock” folder from the “Project Navigator View” in Xcode to view the App’s configuration in the main Xcode view.
  2. Select the "File inspector" on the right hand-side; the name of your project should be in there under "Identity and Type":
  1. Change the name of your project to a new name, for example to “ACME”.
  2. Review the contents that will be renamed by Xcode and select “Rename”:

See How do I completely rename an Xcode project (i.e. inclusive of folders)? for further information on these steps.

Rename the scheme

  1. Click on the scheme for your OLD product (in the top bar near the "Stop" icon), then select "Manage schemes":
  1. Click on the OLD name in the scheme to make it editable and change the name:

See How do I completely rename an Xcode project (i.e. inclusive of folders)? for further information on these steps.

Update the CocoaPods configuration

  1. Close Xcode.
  2. Open the Podfile (located in the project's root directory) in a text editor and update as follows:
    • Rename the target “ForgeRock”, for example to “ACME”.
    • Rename the target “ForgeRockTests”, for example to “ACMETests”:
  1. Navigate to the project’s root directory on the command line and and run the pod install command again to apply the CocoaPods changes: $ cd [project_root_dir] $ pod install
  2. Remove the ForgeRock.xcworkspace directory (also in the project’s root directory): $ rm -rf ForgeRock.xcworkspace
  3. Open the updated project in Xcode: $ open ACME.xcworkspace/

Rename the ForgeRock-Authenticator directory

  1. Close Xcode.
  2. Rename the directory using Git in order to preserve the history: $ git mv ForgeRock-Authenticator ACME-Authenticator
  3. Re-open the project in Xcode: $ open ACME.xcworkspace/
  4. Dismiss any warnings regarding missing files.
  5. Select “Authenticator” from the “Project Navigator View” in Xcode; it should be shown in red.
  6. Navigate to the Utilities pane under "Identity and Type" where you will see the "Name" entry.
  7. Select the folder icon to show a new dialog and update the location:

Rename the Entitlements file

  1. Rename the ForgeRock.entitlements file (located in the project's root directory), for example to ACME.entitlements:

Update the Build settings and rebuild

  1. Select the project from the “Project Navigator View” in Xcode.
  2. Select “General”, scroll down to the “Linked Frameworks and Libraries” section and remove the “libPods-ForgeRock.a” entry:
  1. Select "Build Settings", followed by “Packaging” and update the “Info.plist File” path, for example to “ACME-Authenticator/ACME-Info.plist”:
  1. Navigate to "Signing" and update the following:
    1. “Code Signing Entitlements” path, for example to “ACME.entitlements”.
    2. “Prefix header”, for example to “ACME-Authenticator/ACME-Prefix.pch”:
  1. Rebuild the project:
    1. Command + Shift + K to clean.
    2. Command + B to build.

Before making further changes, now would be a good time to verify that you are able to run the code on a physical device as detailed in Launch the App on an iPhone.

Update the Test Build settings

  1. Select the project from the “Project Navigator View” in Xcode.
  2. Select the “ACMETests” target in the main view.
  3. Select "Build Settings", followed by “Bundle Loader” and update the following:
    1. “Debug” path, for example to “$(BUILT_PRODUCTS_DIR)/ACME.app/ACME”.
    2. “Release” path, for example to “$(BUILT_PRODUCTS_DIR)/ACME.app/ACME”:
  1. Select “Build Phases”, followed by “Link Binary with Libraries” and remove the “libPods-ForgeRockTests.a” entry:

Update the Splashscreen video

  1. Replace the splashvideo.mp4 file (located in the [project_root_dir]/ACME-Authenticator directory) with the updated video file. Keeping the same filename means you do not have to update other project files.

Update App Permission Request dialogs

  1. Replace references to ForgeRock within the ACME-Info.plist file (located in the [project_root_dir]/ACME-Authenticator directory). For example, change them to ACME:

Update Localizable.strings

  1. Replace references to ForgeRock within the Localizable.strings file (located in the [project_root_dir]/ACME-Authenticator/en.lproj directory). For example, change them to ACME:

Update About.strings

  1. Replace relevant references to ForgeRock within the About.strings (located in the [project_root_dir]/ACME-Authenticator/Settings.bundle/en.lproj directory). For example, change them to ACME:
Note

ForgeRock and other copyright attributions should not be changed.

Update the App icon

  1. Generate a new set of icon files and a Contents.json file. These can be generated from a single source image using an online service such as https://appicon.co/.
  2. Replace the contents of the [project_root_dir]/ACME-Authenticator/Images.xcassets/AppIcon.appiconset/ directory with the set of icon files and a Contents.json file:

Update the Default Account icon

  1. Replace the forgerock-logo.png file (located in the [project_root_dir]/ACME-Authenticator directory) with an updated icon. If you want to change the name of this file, for example to acme-logo.png, then you must also update the references to it in the following files (using a text editor to find and replace is likely the easiest approach):
    • FRAUIUtils.m (located in the [project_root_dir]/ACME-Authenticator directory).
    • Main.storyboard (located in the [project_root_dir]/ACME-Authenticator directory)
    • project.pbxproj (located in the [project_root_dir]/ACME.xcodeproj directory):

Optional

You can delete the following files (located in the [project_root_dir]/ACME-Authenticator directory) from Xcode and the file system if you want as they are not used:

  • forgerock-logo-text.png 
  • forgerock-logo-opaque.png 

Update the Default colors

  1. Update colors in the following files (located in the [project_root_dir]/ACME-Authenticator directory); colors to update are specified in brackets:
    • FRANotificationsTableViewController.m (seaGreen and dashboardRed)
    • FRACircleProgressView.m (lightGrey)
    • FRAOathMechanismTableViewCellController.m (seaGreen and dashboardRed)
  2. Update colors and layout defined in the Main.storyboard file (located in the [project_root_dir]/ACME-Authenticator directory) if necessary.
Note

Any changes made to the Main.storyboard file will result in merge conflicts when rebasing over later changes to the official App; ForgeRock's development approach allows edits to this file by only one developer at a time.

Publish your App

Once you have completed all your changes and rebuilt the App, you can submit your App to the Apple App Store. The following links provide useful Apple resources on the next steps:

Set up Push notifications

Refer to the following articles for further information on setting up Push notifications:

See Also

FAQ: Source code in AM

Xcode Help

CocoaPods Guides

Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.