Quick Start

Purpose of Oracle CASB Cloud Service APIs

The Oracle CASB Cloud Service REST APIs provide programmatic access to information that is available in the Oracle CASB Cloud Service UI. These APIs allow you to integrate your system events with common security information and event management (SIEM) providers, as well as allowing you to manage your AWS application instances.

This tight integration between SIEM providers and Oracle CASB Cloud Service gets you get a deeper understanding of key risk actions, which may be due to a weak or non-compliant security control settings, policy violations, and behavioral anomalies and potential threats from your Cloud Applications. This integration ensures a safe move to the cloud, and also lets you extract these risk events without having to manage certificates.

Oracle CASB Cloud Service APIs allow you to:

  • Generate an API token to allow API access to your API-enabled Oracle CASB Cloud Service tenants.

  • Create, retrieve, update, and delete AWS application instances.

  • Retrieve a single risk event or all risk events.

  • Retrieve user risk scores.

Prerequisites

Prerequisite More Information

Ask your Oracle CASB Cloud Service administrator to set you up as a user in the tenant you will be accessing with the API.

Tell your Oracle CASB Cloud Service administrator that you need administrator credentials in order to get the tenant ID, and describe the kinds of applications you will be developing with the API. That administrator may want to give you some guidelines to ensure that your testing does not interfere with live data flowing through the system.

Contact your Oracle CASB Cloud Service customer success person to enable the REST API on your Oracle CASB Cloud Service account.

Tell your Oracle CASB Cloud Service customer success person that two control flags must be set to true for all tenants in your account in which you want to use the REST API:

  • The siem.integration.enable flag enables risk events.

  • The app.management.enable flag enables AWS application management.

Ensure that you have a tool in place that lets you make REST API calls.

To make REST API calls, you can use either a command-line tool or a GUI-based tool. Set up the tool to make REST API calls. The examples in this documentation use the cURL command line tool to demonstrate how to access the Oracle CASB Cloud Service REST APIs; you may use any tool you like that lets you make REST API calls.

Step 1: Understand the Resource URL Format

You access the Oracle CASB Cloud Service REST APIs using a URL, which includes the REST endpoint, the resource that you want to access, and any query parameters that you want to include in your request.

The basic endpoint for the Oracle CASB Cloud Service REST API is:

https://api-<CASB-STACK>.palerra.net

Where <CASB-STACK> is the name of the Oracle CASB Cloud Service stack that you are accessing (obtain this from your Oracle CASB Cloud Service tenant administrator):

  • trial: the trial environment for all regions.

  • loric: the production environment for North America south of Canada, and for Latin America.

  • loric-ca: the production environment for Canada.

  • loric-eu: the production environment for Europe, Africa, and the Middle East

Step 2: Get the Oracle CASB Cloud Service Tenant Access Key and Secret Key

Perform this task in the Oracle CASB Cloud Service UI for the tenant your API calls will be accessing.

  1. Log in with administrator credentials to an Oracle CASB Cloud Service tenant where the REST API is enabled.

  2. In the top right corner of the screen, click your user name and select API Credentials from the drop-down list.

  3. In the API Credentials dialog box, click Generate Keys.

    This populates the key values in the Access Key and Secret Key fields.

  4. When the Access Key and Secret Key fields are populated, click Download Keys.

    This downloads the keys to a file named apiKeys.txt.

    Note:

    If you repeat this step later, new keys are generated and the old ones are deactivated.
  5. Copy the Access Key and Secret Key values from the apiKeys.txt to the same place where copied the tenant GUID value, for easy future access.

    These keys and the tenant ID are required for API access to Oracle CASB Cloud Service.

Step 3: Use the Access Key and Secret Key to Retrieve the Access Token

  1. Create a POST request to pass the access key and secret key to the tenant.

    {
      "accessKey": "<access_key_string>",
      "accessSecret": <access_secret_string> 
    }
  2. Copy the access token from the response:

    {
      "accessToken" : "...",
      "tenantId" : "abcdefgh-1234-ijkl-5678-mnopqrstuvwx",
      "expiresAt" : "2017-09-11T00:19:24Z"
    }

    Note:

    The access token and tenant ID are required for each API call in order to access Oracle CASB Cloud Service. You provide these parameters in request headers:
    • X-Apprity-Tenant-Id : "<tenant_ID_string>"

    • Authorization : Bearer "<access_token_string>"

Step 4: Read in Data for an AWS Application

With the access token and tenant ID in your headers, you can now use the Oracle CASB Cloud Service REST APIs to access an API-enabled Oracle CASB Cloud Service tenant. For a first-time access, retrieve data for an AWS application.

  1. Create a GET call to return all information for all applications for applicationType=aws.

  2. Note the values of instanceId and minimumPasswordLength for one of the AWS instances returned in this response:

    {
      "application": [
        {
          "applicationName": "AWS",
          "instanceId": "<string>",
          "instanceName": "<string>",
          "monitoringType": "<string>",
          "securityControls": {
            "securityControlType": "<string>",
            "securityControlParameters": {
              "minimumPasswordLength": 6,
              "requireUppercaseCharacters": false,
              "requireLowercaseCharacters": false,
              "requireNumbers": false,
              "requireSymbols": false,
              "allowUsersToChangePassword": false,
              "maxPasswordAge": 0,
              "passwordReusePrevention": 0,
              "hardExpiry": false,
              "mfaChecker": false,
              "s3ServerSideEncryptChecker": false,
              "s3ServerSideEncryptCheckerFilter": "<string>",
              "s3IsMfaEnableForDeleteBucketChecker": false,
              "ec2SecurityGroupChecker": false,
              "ec2SecurityGroupCheckerFilter": "<string>",
              "ec2NAclPortsChecker": false,
              "ec2NAclPortsCheckerFilter": "<string>",
              "ec2NAclAllowAllChecker": false,
              "r53NoHostedZones": false,
              "r53NoHealthChecks": false,
              "ebsNonEncryptedVolumes": false,
              "ebsNonEncryptedVolumesFilter": "<string>",
              "rdsNonEncryptedDbs": false,
              "rdsNonEncryptedDbsFilter": "<string>"
            }
          },
          "url": "<string>"
        }
      ],
        "tenantId": "<string>",
        "message": "<string>",
        "error": {
        "code": "<string>",
        "message": "<string>"
      }
    }

Step 5: Make a Change in an Application's Security Control Parameter

Now temporarily change the minimum password length for the application instance you noted in the previous task, then change it back to its previous setting.

  1. Create a PUT call to temporarily change the minimumPasswordLength for the applicationInstanceId that you noted, increasing the length by 1.

  2. Create a GET call to return all information for the one AWS application (applicationType=aws) that you noted above.

  3. Verify that the minimumPasswordLength for this instance was changed.

  4. Create a PUT call to revert the temporary change in the minimumPasswordLength that you made in step 1 above.