How to Secure Android & iOS Apps in CircleCI pipelines

Last updated July 19, 2023 by Appdome

This Knowledge Base article provides instructions for using the Appdome Build-2Secure Orb for CiricleCI pipelines. Appdome’s Build-2Secure Orb for CircleCI is an out-of-the-box CircleCI integration, making it easy for mobile developers to secure Android & iOS apps in CircleCI pipelines. Automate the build, signing, and certification of security, anti-fraud, and other protection in Android & iOS apps in CircleCI pipelines. No code and no SDKs are required.

The purpose of Appdome’s Build-2Secure Org for CircleCI is to streamline and accelerate cyber and anti-fraud delivery in CI/CD pipelines. To do this, the Build-2Secure Orb for CircleCI automates three important steps in delivering more secure mobile applications to your users fast: (1) building the selected app-level protections into mobile apps, (2) code signing the Appdome-protected mobile app, and (3) certifying the defenses inside each Appdome-protected mobile app. The Appdome Build-2Secure Orb for CircleCI is used to deliver Certifed Secure™ mobile app security, anti-fraud, anti-malware, mobile anti-bot, and other cyber defense updates in mobile apps on Appdome’s Cyber Defense Automation Platform. Use this Orb for CircleCI as a stand-alone DevSecOps integration or in combination with other DevSecOps integrations in your CI/CD pipeline.

For more general information on this Orb, see Orb Authoring Process on the CircleCI website.

Here are the step-by-step instructions on using the Appdome Build-2Secure Orb for CircleCI. Enjoy!

Prerequisites to Appdome’s Orb for CircleCI

Before you use Appdome’s Orb for CircleCI, there are a few things you need to have:

Step 1: Installing the Build-2Secure Orb for CircleCI

Edit your .circleci/config.yml favorite IDE or with the CircleCI in-app configuration editor.

  1. Ensure that the CircleCI version, which is displayed at the top of your .circleci/config.yml, is 2.1.
    version: 2.1
  2. Add the orbs block (stanza) below your version and install Appdome Build-2secure in CircleCI by adding the following to your .circleci/config.yml, where X.Y.Z represents the version number; for example, 2.3.1.
    orbs:
      build-2secure: appdome/build-2secure@X.Y.Z

    Alternatively, set version to volatile to get the latest version.

    orbs:
      build-2secure: appdome/build-2secure@volatile

Step 2: Configuring the Build-2Secure Orb for CircleCI

  1. In order to use Appdome Build-2Secure Orb, it’s necessary to obtain the Appdome Build-2Secure API Token by copying it, as described in the article Getting and resetting your API Token, then add it as an environment variable in CircleCI. To do so, navigate to the Project Settings section on CircleCI’s platform.
    Appdome Orb for CircleCI - Project Settings button
  2. From the menu on the left, click Environment Variables and then click Add Environment Variable.
    Appdome Orb for CircleCI - Add Environment Variables
  3. Use the App Environment Variable dialog box to add the Appdome Build-2Secure API Token variable by entering the following values:
    Name: APPDOME_API_TOKEN
    Value: <YOUR_APPDOME_TOKEN>
    Appdome Orb for CircleCI - Add API Key as env. variable
  4. In addition to your APPDOME_API_TOKEN, you have to insert your iOS or Android Fusion Set ID to CircleCI’s Environment Variables:
    1. For iOS apps, add the following variables:
      Name: FUSION_SET_ID_IOS
      Value: <Appdome_Fusion_Set_ID_For_iOS>
    2. For Android apps, add the following variables:
      Name: FUSION_SET_ID_ANDROID
      Value: <Appdome_Fusion_Set_ID_For_Android>
  5. Add Appdome Build-2Secure to your job by calling it from the jobs block of your .circleci/config.yml file, as shown in the base template below.
    For additional usage examples, see Appdome page on CircleCI website.

    workflows:
    	 Appdome fusion:
    	 	 jobs:
    	 	  - build-2secure/appdome_runner:
    	 	   runner: <type_of_run> 
    	 	   team-id: <your_team_ID> - remove this line when working on personal workspace. 
    	 	   appFile: <remote_app_location_of_the_non-protected_app> 
    	 	   output: <secured_app_file_name> 
    	 	   sign-overrides: <path_to_remote_JSON_download_file_location> 
    	 	   google-play-signing: <true_or_false> - (For Android only!). 
    	 	   build-with-logs: <true_or_false>
                       second-output: <true_or_false>
                       build-to-test: <vendor_name_to_testing("BITBAR" or "BROWSERSTACK" or "LAMBDATEST" or "SAUCELABS")>
  6. In the code block above, set the following variables with the parameter values as described below:
    1. runner
      Any of the following options, in accordance with the build platform you need and the sign type:

    2. team-id
      Insert your team-id. This line is optional and may be removed when working on a personal workspace.
    3. appFile
      Please provide the remote address of the non-protected application. For example, “https://[URL_of_your_non_protected_app]”.
    4. output
      The requested name of the secured application is : appdome_secured_app.apk/.aab/ipa
    5. sign-overrides
      Include this parameter with the path to a JSON file, only if you want to override signing with a custom JSON file. Otherwise, remove this line.
    6. google-play-signing
      For Android only. Either leave the default value False or, if you use Google Play App Signing to allow developers to offload the signing of their release APKs onto Google, change the value to True.
    7. Second Output (.aab apps only): If you’d like to use this option, change code to ‘true’. Set a path for the second .apk file to be downloaded.
      Specify a full path for the application. The second output will be saved under the name “Appdome_Universal_App.apk”. If you’d like to continue working with the universal apk in the next job, you must use this path to access the universal apk:

      $HOME/appdome_workspace/appdome_outputs/Appdome_Universal_App.apk

      Note: this option is relevant only for apps signed with Appdome Auto Sign or Private Sign. Not applicable for Auto-Dev Private Signed apps.

    8. Build to test: allows automated testing of Appdome Secured Apps in standard DevOps testing suites.
      Do not use this service for individual device testing.
      Specify the supported Testing Service: “BITBAR” or “BROWSERSTACK” or “LAMBDATEST” or “SAUCELABS”
      Note: for iOS – only Saucelabs is supported.

  7. For each type of sign, you have to add the following environment variables as explained above.

    Note
    : Certain sign options require  files. To accomplish this, file must first be encoded by using the base64 method, and the output of this process must be stored within the specified environment variable, as described in section “Adding Files as Environment Variables Using Base64 Encoding” below.

          1. ANDROID_AUTO_SIGNING
            • Name:  KEYSTORE_FILE
              Value: <Keystore_base64_File>
            • Name:  KEYSTORE_PASSWORD
              Value: <Your_Keystore_Password>
            • Name:  KEYSTORE_ALIAS
              Value: <Your_Keystore_Alias_Name>
            • Name:  KEYSTORE_KEY_PASSWORD
              Value: <Your_Keystore_Key_Password>
          2. ANDROID_PRIVATE_SIGNING
            • Name:  SIGN_FINGERPRINT
              Value:  <Your_SHA1_Fingerprint>
          3. ANDROID_AUTO_DEV_SIGNING
            • Name:  SIGN_FINGERPRINT
              Value:  <Your_SHA1_Fingerprint>
          4. IOS_AUTO_SIGNING
            • Name:  KEYSTORE_P12_FILE
              Value: <P12_Keystore_base64_File>
            • Name:  P12_PASSWORD
              Value: <Your_P12_Keystore_Password>
            • Name:  MOBILE_PROVISION_PROFILE_FILE
              Value: <Mobile_Provision_profile_base64_file>
            • Name:  ENTITLEMENTS_FILE
              Value: <Entitlement_base64_file>
          5. IOS_PRIVATE_SIGNING
            • Name:  MOBILE_PROVISION_PROFILE_FILE
              Value: <Mobile_Provision_profile_base64_file>
          6. IOS_AUTO_DEV_SIGNING
            • Name:  MOBILE_PROVISION_PROFILE_FILE
              Value: <Mobile_Provision_profile_base64_file>
            • Name:  ENTITLEMENTS_FILE
              Value: <Entitlement_base64_file>

Continuous Integration with Orb

If Appdome’s orb is the last job in your configuration, you can find the outputs under the “Artifacts” tab in the CircleCI web app. To download the artifacts, you can use curl by following the instructions provided here: Link to CircleCI documentation on downloading all artifacts for a build or Access uploaded artifact URL in job.

If Appdome is not the last job in your CircleCI configuration, you can continue working with the artifacts of Appdome using the path:  $HOME/appdome_workspace/appdome_outputs/<output_name>.apk/.aab/.ipa.
This path will lead you to the protected application.

To use the protected app (artifacts from Appdome’s orb) in your next job, use executors. In that job, you should include the step attach_workspace as follows:

steps: 
   - attach_workspace: 
       at: ~/appdome_workspace/

Make sure to use ~/appdome_workspace/ as the path.
To access the protected application as an input, you must use the path: $HOME/appdome_workspace/appdome_outputs/<output_name>.apk/.aab/.ipa.

For example, if you want to view the artifacts from another job, you can create a job that executes the command: ls -la on the path where the Appdome artifacts are located. Here’s an example configuration:

version: 2.1
orbs:
  appdome-orb: appdome/build-2secure@X.Y.Z
  orb-tools: circleci/orb-tools@11.5

executors:
  my-executor:
    docker:
      - image: cimg/python:3.11.3

jobs:
  downstream:
    executor: my-executor
    steps:
      - attach_workspace:
          at: ~/appdome_workspace/
      - run: |
          ls -la "$HOME/appdome_workspace/appdome_outputs/"

workflows:
  test-deploy:
    jobs:
      - appdome-orb/appdome_runner:
          name: "test-android-auto-sign"
          runner: "ANDROID_AUTO_SIGNING"
          team-id: "your team ID"
          appFile: <path to your app>
          output: "appname.apk"
          filters: *filters
      - downstream:
          requires:
            - test-android-auto-sign

Remember to replace X.Y.Z with the actual version of the Appdome orb you want to use.
The output should be as follows:

Circle Ci Orb Output

If an output name isn’t inserted by the user,  for the application then the default name will be appdome_secured_app.apk/ipa/aab
If you want to work on your next job in circleci with the appdome protected app, configure your next job with the following parameters:

jobs:
  downstream:
    executor: my-executor
    steps:
      - attach_workspace:
          at: ~/appdome_workspace/
      - run: |
          export APPDOME_SECURED_APP=$(ls $HOME/appdome_workspace/appdome_outputs/*appdome_secured_app*)

Note: With the assumption that the user didn’t provide an output name, the name ‘appdome_secured_app’ will be used.

Step 3: Build Android & iOS Security with Build-2Secure

Trigger the pipeline which contains the Appdome Build-2Secure job. This job initiates Appdome Build-2Secure which automatically integrates the requested security features into your app based on the Fusion Set ID.

Step 4: Retrieve DevSecOps Certification with Build-2Secure

  1. After the build is complete, you can download the secured app from the Artifacts tab in the CircleCI platform.
    The following artifacts will be available for download:

Appdome Orb for CircleCI - Artifacts available for download

The name of the secured output app will match the name selected in the output parameter.

Adding Files as Environment Variables by Using Base64 Encoding

To add files as environment variables:

  1. Open a terminal.
  2. Encode the requested file with base64, and save (paste) it in a temporary text file:
    Usage:	base64 [-i in_file] [-o out_file]

    For example:

    base64 -i appdome.keystore -o example_temp.txt
  3. Copy the contents of the text file into the matching environment variable as shown in the images below.
    Appdome Orb for CircleCI - Copy text to environment variableAppdome Orb for CircleCI - Add environment variable filled

Conclusion

The description above is designed to help you secure Android & IOS apps in CircleCI CI/CD pipelines. If you have questions about using this Build2Secure step for CircleCI, please send them our way at support.appdome.com or via the chat window on the Appdome platform.

Thank you!

Thanks for visiting Appdome! Our mission is to secure every app on the planet by making mobile app security easy. We hope we’re living up to the mission with your project.

NEED HELP?

let's solve it together

JingMaking your security project a success!
By filling out this form, you opt-in to recieve emails from us.