Initiating Mobile App Scans or Rescans with OneTrust Integrations

You can leverage the Mobile App Scan workflow on Integrations to create new mobile apps with an initial scan or to rescan existing apps against a new SDK package. This allows your developers to remotely integrate app scans in to their application development process as well as to provide the means to scan/rescan apps without logging into the OneTrust application after initial setup.

Note:

This documentation will reference the Postman developer tool to demonstrate the API integration to support creation of a new app with scanning or a rescan of an existing app.

To create the integration workflow

  1. On the Integrations menu, select Gallery. The Integrations gallery screen appears.

  2. Use the search to locate the Generic system tile.


  3. Click the Generic system tile. The Gallery details screen appears.

  4. Click the Add button on the Mobile: Mobile App Scan workflow. The Add workflow name modal appears.


  5. Complete the fields in the modal, then click the Create button. The Integration builder screen appears.


    Field
    Description
    Workflow Name

    Enter a unique name for this new connection.

    Select existing credentials

    Select None. The API call will use Client Credentials to authorize access to the given tenant for security purposes.

    Notification email

    Enter the OneTrust user email that should receive all notification alerts for this workflow.

  6. Click the Activate button.

To obtain the POST URL

  1. In the Integration builder screen, click the Edit icon on the Built-in Webhook Trigger action.
  2. Click the Copy button to copy the HTTP POST URL. Save this for later reference to use during the API call.


To create an OAuth 2.0 Client Credential

You will need to create an OAuth 2.0 Client Credential to authorize the API calls' access to the OneTrust application. This information will need to be provided when configuring the API calls' authentication requirements.

  1. In the OneTrust application, click the gear icon in the upper right-hand corner to access Global Settings.
  2. On the Global Settings menu, select Access management > Client credentials. The Client credentials screen appears.

  3. Click the Add button. The Client credentials section of the Add client credential screen appears.

  4. In the Name field, enter a name for the client credential.
    Note:

    The name cannot be modified once the client credential is created.

  5. Optional: In the Description field, enter a description for the client credential.
  6. In the Access token lifetime field, select the amount of time that should pass before the access token expires. The following options are available:

    • 1 Hour

    • 1 Day

    • 1 Week

    • 1 Month

    • 1 Year

  7. Click the Next button. The Scope section appears.

  8. Enable ALL for the Integration Scope AND the Cookie Scope.




  9. Click the Create button. The Client ID and secret section appears.

  10. In the Download credentials field, click the Download button. A .txt file containing the Client ID and Client secret details will download to your local system.
    Attention:

    The Client ID and Client secret details should be saved to a secure location.



  11. Click the Close button.

API Reference Overview

Authorization Requirements

  • OAuth 2.0 auth type, with added authorization data to Request Headers

  • Client Credential Grant Type

  • Access Token URL (e.g. https://staging.1trust.app/api/access/v1/oauth/token)

  • Client ID and Client Secret

  • Client Authentication, sent as Basic Auth header

  • Access Token, generated by provision of the above requirements

Header Requirements

  • Enabled key-value pair, Content-Type | application/json

Body Requirements

  • Enabled form-data

  • Enabled key-value pair, file | .ipa/.apk file

  • Enabled key-value pair, dataFields | applicable JSON (see below sections for each use case)

To send the New App Scan API call

  1. Ensure the necessary authentication parameters and headers are provided to connect with your given OneTrust environment. See API Reference Overview.
  2. In your developer tool, create a POST call and paste the HTTP POST URL copied from the Webhook Trigger action in the OneTrust application.
  3. In the Body, select a package file. (e.g. .ipa or .apk) for the Value of the field Key.
    Note:

    File upload limit is 2GB.

  4. In the Body, provide the following JSON as the Value of the dataFields Key.
    JSON 
    {
"name": "App Name", # enter your new app name
"platform": "IOS/ANDROID" # choose a platform according to your file type
}


  5. Send the call. Upon a successful response (202), you should receive a request ID. This will be the corresponding string found in the workflow log.


  6. In the OneTrust application, navigate to the Logs tab in the Integration builder screen.
  7. Locate and select the Event ID to review the workflow log. You can also copy and paste the request ID to quickly locate the log.

    Observe the new app name is present, with the correct platform type, and scanned against the uploaded file.



  8. Navigate to the Cookie Consent > Mobile apps menu. The Mobile apps screen appears.

  9. Use the search bar to locate your newly created mobile app.


  10. Click the mobile app. The Mobile app details screen appears.

  11. Navigate to the Scan results tab.
  12. Observe the new app has already been scanned with the populated results.

    Click the arrow on the Show selection field to show the initial scan. The metadata timestamp will be displayed as : V.VV.V - DD/MM/YYYY MM:SS AM/PM



To send the Rescan App API call

  1. Ensure the necessary authentication parameters and headers are provided to connect with your given OneTrust environment. See API Reference Overview.
  2. In your developer tool, create a POST call and paste the HTTP POST URL from the Webhook Trigger action in the OneTrust application.
  3. In the Body, select the new package file. (e.g. .ipa or .apk) for the Value of the field Key.
  4. In the Body, provide the following JSON as the Value of the dataFields Key.
    JSON 
    {
"appId": "app ID for which you want to rescan", # provide mobile app ID
"platform": "IOS/ANDROID" # choose a platform according to your app type
}


    Note:

    The mobile app Production ID can be found in the Instructions tab on the SDK screen.

  5. Send the call. Upon a successful response (202), you should receive a request ID. This will be the corresponding string found in the workflow log.


  6. In the OneTrust application, navigate to the Logs tab in the Integration builder screen.
  7. Locate and select the Event ID to review the log. You can also copy and paste the request ID to quickly locate the log.

    Observe the app ID is present in the log, with the correct platform type, and scanned against the newest file.



  8. Navigate to the Cookie Consent > Mobile apps menu. The Mobile apps screen appears.

  9. Use the search bar to locate your mobile app.
  10. Navigate to the Scan results tab.
  11. Click the arrow on the Show selection field and observe the newest scan for the app. The metadata timestamp will be displayed as : V.VV.V - DD/MM/YYYY MM:SS AM/PM