How to Secure Android & iOS Apps in CircleCI pipelines
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:
- An Appdome SRM account
- Appdome Build-2Secure API token
- Fusion Set ID
- A CircleCI account
- Review Network Requirements for Using Appdome Build-2Secure API
Step 1: Installing the Build-2Secure Orb for CircleCI
Edit your .circleci/config.yml favorite IDE or with the CircleCI in-app configuration editor.
- Ensure that the CircleCI version, which is displayed at the top of your .circleci/config.yml, is 2.1.
version: 2.1
- 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
- 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.
- From the menu on the left, click Environment Variables and then click Add Environment Variable.
- 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>
- In addition to your APPDOME_API_TOKEN, you have to insert your iOS or Android Fusion Set ID to CircleCI’s Environment Variables:
- For iOS apps, add the following variables:
Name: FUSION_SET_ID_IOS
Value: <Appdome_Fusion_Set_ID_For_iOS> - For Android apps, add the following variables:
Name: FUSION_SET_ID_ANDROID
Value: <Appdome_Fusion_Set_ID_For_Android>
- For iOS apps, add the following variables:
- 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")>
- In the code block above, set the following variables with the parameter values as described below:
- runner
Any of the following options, in accordance with the build platform you need and the sign type:- ANDROID_AUTO_SIGNING
For more information follow the instructions in the article
How to Code Sign Secured Android Apps in DevSecOps Build System. - ANDROID_PRIVATE_SIGNING – for more information follow the instructions in the article
How To Privately Code Sign Sealed Android Apps using DevSecOps Build System. - ANDROID_AUTO_DEV_SIGNING – for more information follow the instructions in the article
How to Automate Secure Android App Code Signing in DevOps CI/CD. - IOS_AUTO_SIGNING – for more information follow the instructions in the article
How to Use Code Sign on Mac for Secured iOS Apps. - IOS_PRIVATE_SIGNING – for more information follow the instructions in the article
How to Privately Code Sign Sealed iOS Apps using DevSecOps Build System. - IOS_AUTO_DEV_SIGNING – for more information follow the instructions in the article How to Automate Secure iOS App Code Signing in DevOps CI/CD.
- ANDROID_AUTO_SIGNING
- team-id
Insert your team-id. This line is optional and may be removed when working on a personal workspace. - appFile
Please provide the remote address of the non-protected application. For example, “https://[URL_of_your_non_protected_app]”. - output
The requested name of the secured application is : appdome_secured_app.apk/.aab/ipa - 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. - 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. - 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.
-
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.
- runner
- 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.-
-
-
- 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>
- Name: KEYSTORE_FILE
- ANDROID_PRIVATE_SIGNING
- Name: SIGN_FINGERPRINT
Value: <Your_SHA1_Fingerprint>
- Name: SIGN_FINGERPRINT
- ANDROID_AUTO_DEV_SIGNING
- Name: SIGN_FINGERPRINT
Value: <Your_SHA1_Fingerprint>
- Name: SIGN_FINGERPRINT
- 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>
- Name: KEYSTORE_P12_FILE
- IOS_PRIVATE_SIGNING
- Name: MOBILE_PROVISION_PROFILE_FILE
Value: <Mobile_Provision_profile_base64_file>
- Name: MOBILE_PROVISION_PROFILE_FILE
- IOS_AUTO_DEV_SIGNING
- Name: MOBILE_PROVISION_PROFILE_FILE
Value: <Mobile_Provision_profile_base64_file> - Name: ENTITLEMENTS_FILE
Value: <Entitlement_base64_file>
- Name: MOBILE_PROVISION_PROFILE_FILE
- ANDROID_AUTO_SIGNING
-
-
-
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:
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
- 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:
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:
- Open a terminal.
- 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
- Copy the contents of the text file into the matching environment variable as shown in the images below.
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.