Jump to

• Request
• Response
• Examples

Update an application instance

put

/api/v1/applications

This API will update an existing application instance in Oracle CASB Cloud Service. You may need to update the instance configuration for any of the following 3 reasons: 1) Credentials have expired or need to be updated. 2) Security controls need to be updated 3) Both need to be updated. All three are supported. The update request type must be set to one of these. The application name must be specified as AWS. If the security control type is set to stringent or standard, then anything passed in the security control parameters body will be ignored, as those values are pre-determined by AWS.

Request

Supported Media Types

• application/json

Query Parameters

• applicationInstanceId: string
  The ID of the application instance to be updated.

Header Parameters

• Authorization: string
  Contains authorization token receieved by making create token API call. The format is 'Bearer' followed by the token which starts with v2.
• X-Apprity-Tenant-Id: string
  The tenant ID for which you are making this call.

Body ()

The body for the request varies, based on the kind of update you want to make. To update security controls only, you pass only the security controls as part of the body, along with the request type and application name.

Root Schema : ApplicationUpdateRequest

Type: object

The body of the update request depends on the kind of update you want to make. CREDENTIALUPDATE, SECURITYCONTROLUPDATE, or SECURITYANDCREDENTIAL are the three options. Depending on your choice of update type, the corresponding fields of security control securityControls and credential credentials must be populated.

Show Source

• applicationName: string
  Name of the application instance to be updated.
• applicationUpdateRequestType: string
  One of these 3 values: CREDENTIALUPDATE, SECURITYCONTROLUPDATE, or SECURITYANDCREDENTIAL.
• credentials: object ApplicationCredentials
  Body for creating credentials for AWS. The fields in the Application Credentials are needed for successfully reaching AWS and creating instance.
• securityControls: object SecurityControls
  This body represents the security controls passed to AWS. The Security Control Type is either Stringent, Standard, or Custom.

{
    "type":"object",
    "description":"The body of the update request depends on the kind of update you want to make. CREDENTIALUPDATE, SECURITYCONTROLUPDATE, or SECURITYANDCREDENTIAL are the three options. Depending on your choice of update type, the corresponding fields of security control securityControls and credential credentials must be populated.",
    "required":[
        "applicationName",
        "applicationUpdateRequestType",
        "credentials",
        "securityControls"
    ],
    "properties":{
        "applicationName":{
            "description":"Name of the application instance to be updated. ",
            "type":"string",
            "xml":{
                "name":"applicationName"
            }
        },
        "applicationUpdateRequestType":{
            "type":"string",
            "description":"One of these 3 values: CREDENTIALUPDATE, SECURITYCONTROLUPDATE, or SECURITYANDCREDENTIAL.",
            "xml":{
                "name":"applicationUpdateRequestType"
            }
        },
        "securityControls":{
            "xml":{
                "name":"securityControls"
            },
            "$ref":"#/definitions/SecurityControls"
        },
        "credentials":{
            "$ref":"#/definitions/ApplicationCredentials"
        }
    }
}

Nested Schema : ApplicationCredentials

Type: object

Body for creating credentials for AWS. The fields in the Application Credentials are needed for successfully reaching AWS and creating instance.

Show Source

• accessKey: string
  AWS specifies an access key and secret key pair to create an instance. The first part of pair is the access key.
• accountId: string
  Can be left blank, if the mode is basic. Only needed in case of cross-account.
• externalId: string
  Can be left blank, if the mode is basic. Only needed in case of cross-account.
• mode: string
  Can be either BASIC or CROSSACCOUNT. If it's cross-account, then role ARN, and external ID are mandatory parameters.
• roleArn: string
  Can be left blank, if the mode is basic. Only needed in case of cross-account.
• roleName: string
  Can be left blank, if the mode is basic. Only needed in case of cross-account.
• secretKey: string
  AWS specifies an access key and secret key pair to create an instance. The second part of pair is the secret key.
• serviceinstancename: string
  Can be left blank, if the mode is basic. Only needed in case of cross-account.
• ssoproperties(optional): array ssoproperties
  Can be left blank, if the mode is basic. Only needed in case of cross-account.

{
    "type":"object",
    "description":"Body for creating credentials for AWS. The fields in the Application Credentials are needed for successfully reaching AWS and creating instance. ",
    "required":[
        "accessKey",
        "accountId",
        "externalId",
        "mode",
        "roleArn",
        "roleName",
        "secretKey",
        "serviceinstancename"
    ],
    "properties":{
        "accessKey":{
            "type":"string",
            "description":"AWS specifies an access key and secret key pair to create an instance. The first part of pair is the access key. ",
            "xml":{
                "name":"access-key"
            }
        },
        "secretKey":{
            "type":"string",
            "description":"AWS specifies an access key and secret key pair to create an instance. The second part of pair is the secret key. ",
            "xml":{
                "name":"secret-key"
            }
        },
        "roleName":{
            "type":"string",
            "description":"Can be left blank, if the mode is basic. Only needed in case of cross-account. ",
            "xml":{
                "name":"roleName"
            }
        },
        "roleArn":{
            "type":"string",
            "description":"Can be left blank, if the mode is basic. Only needed in case of cross-account. ",
            "xml":{
                "name":"role-arn"
            }
        },
        "mode":{
            "type":"string",
            "description":"Can be either BASIC or CROSSACCOUNT. If it's cross-account, then role ARN, and external ID are mandatory parameters. "
        },
        "serviceinstancename":{
            "description":"Can be left blank, if the mode is basic. Only needed in case of cross-account. ",
            "type":"string"
        },
        "externalId":{
            "type":"string",
            "description":"Can be left blank, if the mode is basic. Only needed in case of cross-account. ",
            "xml":{
                "name":"external-id"
            }
        },
        "accountId":{
            "type":"string",
            "description":"Can be left blank, if the mode is basic. Only needed in case of cross-account. ",
            "xml":{
                "name":"account-id"
            }
        },
        "ssoproperties":{
            "type":"array",
            "description":"Can be left blank, if the mode is basic. Only needed in case of cross-account. ",
            "items":{
                "$ref":"#/definitions/Ssoproperties"
            }
        }
    }
}

Nested Schema : SecurityControls

Type: object

This body represents the security controls passed to AWS. The Security Control Type is either Stringent, Standard, or Custom.

Show Source

• securityControlParameters: object SecurityControlParameters
  These are the controls which AWS provides to define the security posture of an instance. See individual properties for details on each.
• securityControlType: string
  Value set to either Stringent, Standard, or Custom.

{
    "type":"object",
    "description":"This body represents the security controls passed to AWS. The Security Control Type is either Stringent, Standard, or Custom. ",
    "required":[
        "securityControlParameters",
        "securityControlType"
    ],
    "properties":{
        "securityControlType":{
            "type":"string",
            "description":"Value set to either Stringent, Standard, or Custom. ",
            "xml":{
                "name":"securityControlType"
            }
        },
        "securityControlParameters":{
            "xml":{
                "name":"securityControlParameters"
            },
            "$ref":"#/definitions/SecurityControlParameters"
        }
    }
}

Nested Schema : ssoproperties

Type: array

Can be left blank, if the mode is basic. Only needed in case of cross-account.

Show Source

• Array of: object Ssoproperties

{
    "type":"array",
    "description":"Can be left blank, if the mode is basic. Only needed in case of cross-account. ",
    "items":{
        "$ref":"#/definitions/Ssoproperties"
    }
}

Nested Schema : Ssoproperties

Type: object

Show Source

• key: string
• value: string

{
    "type":"object",
    "required":[
        "key",
        "value"
    ],
    "properties":{
        "key":{
            "type":"string"
        },
        "value":{
            "type":"string"
        }
    }
}

Nested Schema : SecurityControlParameters

Type: object

These are the controls which AWS provides to define the security posture of an instance. See individual properties for details on each.

Show Source

• allowUsersToChangePassword(optional): boolean
  Default Value: false

  Set to true to allow all IAM users in your account to use the IAM console to change their own passwords.
• ebsNonEncryptedVolumes(optional): boolean
  Default Value: false

  Set to true to EBS volume encryption status.
• ebsNonEncryptedVolumesFilter: string
  If you don't want to trigger alert for certain nonencrypted volumnes, then you can set those exceptions here.
• ec2NAclAllowAllChecker(optional): boolean
  Default Value: false

  Check if network ACLs have Allow All set as the default.
• ec2NAclPortsChecker(optional): boolean
  Default Value: false

  Set to true to require network ACLs to use secure open ports.
• ec2NAclPortsCheckerFilter: string
  If there are specific unsecured ports that you don???t want to trigger an alert when your security control baseline says that secured ports are required, then you must select the Custom baseline type, and set those exceptions here.
• ec2SecurityGroupChecker(optional): boolean
  Default Value: false

  Set to true to require security group checking for unsecured ports.
• ec2SecurityGroupCheckerFilter: string
  If you don't want to trigger alert for certain ec2 security groups, then you can set those exceptions here.
• hardExpiry(optional): boolean
  Default Value: false

  Set this to true to prevent IAM users from choosing a new password after their current password has expired. For example, if the password policy specifies a password expiration period, but an IAM user fails to choose a new password before the expiration period ends, the IAM user cannot set a new password. In that case, the IAM user must request a password reset from an account administrator in order to regain access to the AWS Management Console. If you leave this check box cleared and an IAM user allows his or her password to expire, the user will be required to set a new password before accessing the AWS Management Console.
• maxPasswordAge(optional): integer(int32)
  Minimum Value: 1

  Maximum Value: 1095

  You can set IAM user passwords to be valid for only the specified number of days. You specify the number of days that passwords remain valid after they are set. For example, when you enable password expiration and set the password expiration period to 90 days, an IAM user can use a password for up to 90 days. After 90 days, the password expires and the IAM user must set a new password before accessing the AWS Management Console. You can choose a password expiration period between 1 and 1095 days, inclusive.
• mfaChecker(optional): boolean
  Default Value: false

  Specify the root user to use multifactor authentication.
• minimumPasswordLength(optional): integer(int32)
  Minimum Value: 6

  Maximum Value: 128

  Specify the minimum number of characters allowed in an IAM user password. You can enter any number from 6 to 128.
• passwordReusePrevention(optional): integer(int32)
  Minimum Value: 1

  Maximum Value: 24

  You can prevent IAM users from reusing a specified number of previous passwords. You can set the number of previous passwords from 1 to 24, inclusive.
• r53NoHealthChecks(optional): boolean
  Default Value: false

  Check use of Route 53 health checks.
• r53NoHostedZones(optional): boolean
  Default Value: false

  Set this to true to check use of Route 53 hosted zones.
• rdsNonEncryptedDbs(optional): boolean
  Default Value: false

  Check RDS encryption status.
• rdsNonEncryptedDbsFilter: string
  If you don't want to trigger alert for certain non encrypted Dbs, then you can set those exceptions here.
• requireLowercaseCharacters(optional): boolean
  Default Value: false

  You can require that IAM user passwords contain at least one lowercase character from the ISO basic Latin alphabet (a to z).
• requireNumbers(optional): boolean
  Default Value: false

  You can require that IAM user passwords contain at least one numeric character (0 to 9).
• requireSymbols(optional): boolean
  Default Value: false

  You can require that IAM user passwords contain at least one of the following nonalphanumeric characters:! @ # $ % ^ & * ( ) _ + - = [ ] { } | '
• requireUppercaseCharacters(optional): boolean
  Default Value: false

  You can require that IAM user passwords contain at least one uppercase character from the ISO basic Latin alphabet (A to Z).
• s3IsMfaEnableForDeleteBucketChecker(optional): boolean
  Default Value: false

  Require multifactor authentication when deleting an S3 bucket.
• s3ServerSideEncryptChecker(optional): boolean
  Default Value: false

  Ensure that all S3 server buckets are encrypted.
• s3ServerSideEncryptCheckerFilter: string
  You can filter the results by providing the s3 buckets that are to be excluded/allowed.

{
    "type":"object",
    "description":"These are the controls which AWS provides to define the security posture of an instance. See individual properties for details on each. ",
    "required":[
        "ebsNonEncryptedVolumesFilter",
        "ec2NAclPortsCheckerFilter",
        "ec2SecurityGroupCheckerFilter",
        "rdsNonEncryptedDbsFilter",
        "s3ServerSideEncryptCheckerFilter"
    ],
    "properties":{
        "minimumPasswordLength":{
            "type":"integer",
            "minimum":6,
            "maximum":128,
            "description":"Specify the minimum number of characters allowed in an IAM user password. You can enter any number from 6 to 128. ",
            "format":"int32"
        },
        "requireUppercaseCharacters":{
            "type":"boolean",
            "description":"You can require that IAM user passwords contain at least one uppercase character from the ISO basic Latin alphabet (A to Z). ",
            "default":false
        },
        "requireLowercaseCharacters":{
            "type":"boolean",
            "description":"You can require that IAM user passwords contain at least one lowercase character from the ISO basic Latin alphabet (a to z). ",
            "default":false
        },
        "requireNumbers":{
            "type":"boolean",
            "description":"You can require that IAM user passwords contain at least one numeric character (0 to 9). ",
            "default":false
        },
        "requireSymbols":{
            "type":"boolean",
            "description":"You can require that IAM user passwords contain at least one of the following nonalphanumeric characters:! @ # $ % ^ & * ( ) _ + - = [ ] { } | '",
            "default":false
        },
        "allowUsersToChangePassword":{
            "type":"boolean",
            "description":"Set to true to allow all IAM users in your account to use the IAM console to change their own passwords. ",
            "default":false
        },
        "maxPasswordAge":{
            "type":"integer",
            "minimum":1,
            "maximum":1095,
            "description":"You can set IAM user passwords to be valid for only the specified number of days. You specify the number of days that passwords remain valid after they are set. For example, when you enable password expiration and set the password expiration period to 90 days, an IAM user can use a password for up to 90 days. After 90 days, the password expires and the IAM user must set a new password before accessing the AWS Management Console. You can choose a password expiration period between 1 and 1095 days, inclusive. ",
            "format":"int32"
        },
        "passwordReusePrevention":{
            "type":"integer",
            "minimum":1,
            "maximum":24,
            "description":"You can prevent IAM users from reusing a specified number of previous passwords. You can set the number of previous passwords from 1 to 24, inclusive. ",
            "format":"int32"
        },
        "hardExpiry":{
            "type":"boolean",
            "description":"Set this to true to prevent IAM users from choosing a new password after their current password has expired. For example, if the password policy specifies a password expiration period, but an IAM user fails to choose a new password before the expiration period ends, the IAM user cannot set a new password. In that case, the IAM user must request a password reset from an account administrator in order to regain access to the AWS Management Console. If you leave this check box cleared and an IAM user allows his or her password to expire, the user will be required to set a new password before accessing the AWS Management Console. ",
            "default":false
        },
        "mfaChecker":{
            "type":"boolean",
            "description":"Specify the root user to use multifactor authentication.",
            "default":false
        },
        "s3ServerSideEncryptChecker":{
            "type":"boolean",
            "description":"Ensure that all S3 server buckets are encrypted.",
            "default":false
        },
        "s3ServerSideEncryptCheckerFilter":{
            "type":"string",
            "description":"You can filter the results by providing the s3 buckets that are to be excluded/allowed."
        },
        "s3IsMfaEnableForDeleteBucketChecker":{
            "type":"boolean",
            "description":"Require multifactor authentication when deleting an S3 bucket.",
            "default":false
        },
        "ec2SecurityGroupChecker":{
            "type":"boolean",
            "description":"Set to true to require security group checking for unsecured ports.",
            "default":false
        },
        "ec2SecurityGroupCheckerFilter":{
            "type":"string",
            "description":"If you don't want to trigger alert for certain ec2 security groups, then you can set those exceptions here."
        },
        "ec2NAclPortsChecker":{
            "type":"boolean",
            "description":"Set to true to require network ACLs to use secure open ports.",
            "default":false
        },
        "ec2NAclPortsCheckerFilter":{
            "type":"string",
            "description":"If there are specific unsecured ports that you don???t want to trigger an alert when your security control baseline says that secured ports are required, then you must select the Custom baseline type, and set those exceptions here."
        },
        "ec2NAclAllowAllChecker":{
            "type":"boolean",
            "description":"Check if network ACLs have Allow All set as the default.",
            "default":false
        },
        "r53NoHostedZones":{
            "type":"boolean",
            "description":"Set this to true to check use of Route 53 hosted zones.",
            "default":false
        },
        "r53NoHealthChecks":{
            "type":"boolean",
            "description":"Check use of Route 53 health checks.",
            "default":false
        },
        "ebsNonEncryptedVolumes":{
            "type":"boolean",
            "description":"Set to true to EBS volume encryption status.",
            "default":false
        },
        "ebsNonEncryptedVolumesFilter":{
            "type":"string",
            "description":"If you don't want to trigger alert for certain nonencrypted volumnes, then you can set those exceptions here."
        },
        "rdsNonEncryptedDbs":{
            "type":"boolean",
            "description":"Check RDS encryption status.",
            "default":false
        },
        "rdsNonEncryptedDbsFilter":{
            "type":"string",
            "description":"If you don't want to trigger alert for certain non encrypted Dbs, then you can set those exceptions here."
        }
    }
}

Back to Top

Response

Supported Media Types

• application/json
• application/gzip

200 Response

Successfully updated the instance.

Body ()

Root Schema : ApplicationUpdateResponse

Type: object

The response for a successful update will have information of the instance which got updated, and a message which indicates success or failure.

Show Source

• applicationName(optional): string
  Name of the application, typically set to AWS, BOX, O365 etc.
• instanceId(optional): string
  Name of the Instance ID that was created by the request.
• instanceName(optional): string
  Name of the instance which got updated.
• message(optional): string
  Message indicating success or failure of the API
• tenantId(optional): string
  The tenant id for which update is being called

{
    "type":"object",
    "description":"The response for a successful update will have information of the instance which got updated, and a message which indicates success or failure. ",
    "properties":{
        "applicationName":{
            "type":"string",
            "description":"Name of the application, typically set to AWS, BOX, O365 etc. ",
            "xml":{
                "name":"applicationName"
            }
        },
        "tenantId":{
            "type":"string",
            "description":"The tenant id for which update is being called ",
            "xml":{
                "name":"tenantId"
            }
        },
        "instanceName":{
            "type":"string",
            "description":"Name of the instance which got updated. ",
            "xml":{
                "name":"instanceName"
            }
        },
        "instanceId":{
            "type":"string",
            "description":"Name of the Instance ID that was created by the request.",
            "xml":{
                "name":"instanceId"
            }
        },
        "message":{
            "type":"string",
            "description":"Message indicating success or failure of the API "
        }
    }
}

204 Response

The instance is missing, and cannot be updated. See response for more details.

Body ()

Root Schema : Error

Type: object

Show Source

• code(optional): string
  HTTP Status Code.
• message(optional): string
  The error message.

{
    "type":"object",
    "properties":{
        "code":{
            "description":"HTTP Status Code.",
            "type":"string"
        },
        "message":{
            "description":"The error message.",
            "type":"string"
        }
    }
}

400 Response

Bad request format. Check the response for more information on which fields are inaccurate. Ensure that you have a request which follows the format.

Body ()

Root Schema : Error

Type: object

Show Source

• code(optional): string
  HTTP Status Code.
• message(optional): string
  The error message.

{
    "type":"object",
    "properties":{
        "code":{
            "description":"HTTP Status Code.",
            "type":"string"
        },
        "message":{
            "description":"The error message.",
            "type":"string"
        }
    }
}

401 Response

Unauthorized API call. See response for more details

Body ()

Root Schema : Error

Type: object

Show Source

• code(optional): string
  HTTP Status Code.
• message(optional): string
  The error message.

{
    "type":"object",
    "properties":{
        "code":{
            "description":"HTTP Status Code.",
            "type":"string"
        },
        "message":{
            "description":"The error message.",
            "type":"string"
        }
    }
}

403 Response

Request is forbidden. It is likely the Oracle CASB Cloud Service APIs aren???t enabled for the tenant.

Body ()

Root Schema : Error

Type: object

Show Source

• code(optional): string
  HTTP Status Code.
• message(optional): string
  The error message.

{
    "type":"object",
    "properties":{
        "code":{
            "description":"HTTP Status Code.",
            "type":"string"
        },
        "message":{
            "description":"The error message.",
            "type":"string"
        }
    }
}

404 Response

Resource requested was not found.

Body ()

Root Schema : Error

Type: object

Show Source

• code(optional): string
  HTTP Status Code.
• message(optional): string
  The error message.

{
    "type":"object",
    "properties":{
        "code":{
            "description":"HTTP Status Code.",
            "type":"string"
        },
        "message":{
            "description":"The error message.",
            "type":"string"
        }
    }
}

500 Response

Internal Server error occured. See response for more details.

Body ()

Root Schema : Error

Type: object

Show Source

• code(optional): string
  HTTP Status Code.
• message(optional): string
  The error message.

{
    "type":"object",
    "properties":{
        "code":{
            "description":"HTTP Status Code.",
            "type":"string"
        },
        "message":{
            "description":"The error message.",
            "type":"string"
        }
    }
}

Back to Top

Examples

The following examples show how to update an AWS application instance by submitting a PUT request.

Example 1 URL: Updating Credentials for an AWS Application Instance

https://<CASB-STACK>.casb.ocp.oraclecloud.com/api/v1/applications?applicationInstanceId=64909d3d-3855-5de1-49ed-6452ae9f6365

Example 1 Request Body: Updating Credentials for an AWS Application Instance

{
  "applicationName": "AWS",
  "applicationUpdateRequestType":"CREDENTIALUPDATE",
  "credentials": {
    "accessKey": "BLHZKSBNTO7DIYRB3DRQ",
    "secretKey": "uQHUJdDrb08png%7K2guKbADYKnZKz05xke9LjTlEs",
    "roleName": "",
    "roleArn": "",
    "mode": "BASIC",
    "serviceinstancename": "",
    "externalId": "",
    "accountId": "",
    "ssoproperties": {}
  }
}

Example 1 Response Body: Updating Credentials for an AWS Application Instance

The following example shows the contents of the response body in JSON format:

{
  "applicationName": "AWS",
  "tenantId": "e7d56a92-dacf-6fda-c53b-89c87792ed20",
  "instanceId": "64909d3d-3855-5de1-49ed-6452ae9f6365",
  "message": "Successfully updated the application instance."
}

Example 2 URL: Updating Security Credentials for an AWS Application Instance

https://<CASB-STACK>.casb.ocp.oraclecloud.com/api/v1/applications?applicationInstanceId=64909d3d-3855-5de1-49ed-6452ae9f6365

Example 2 Request Body: Updating Security Credentials for an AWS Application Instance

{
  "applicationName":"AWS",
  "applicationUpdateRequestType":"SECURITYCONTROLUPDATE",
  "securityControls":{
    "securityControlType":"stringent",
    "securityControlParameters": {
      "minimumPasswordLength": 7,
      "requireUppercaseCharacters": false,
      "requireLowercaseCharacters": false,
      "requireNumbers": false,
      "requireSymbols": false,
      "allowUsersToChangePassword": false,
      "maxPasswordAge": 45,
      "passwordReusePrevention": 5,
      "hardExpiry": false,
      "mfaChecker": false,
      "s3ServerSideEncryptChecker": false,
      "s3IsMfaEnableForDeleteBucketChecker": false,
      "ec2SecurityGroupChecker": false,
      "ec2NAclPortsChecker": false,
      "ec2NAclAllowAllChecker": false,
      "r53NoHostedZones": false,
      "r53NoHealthChecks": false,
      "ebsNonEncryptedVolumes": false,
      "rdsNonEncryptedDbs": false
    }
  }
}

Example 2 Response Body: Updating Security Credentials for an AWS Application Instance

The following example shows the contents of the response body in JSON format:

{
  "applicationName": "AWS",
  "tenantId": "abcdefgh-1234-ijkl-5678-mnopqrstuvwx",
  "instanceId": "12345678-9101-abcd-efgh-ijklmnopqrst",
  "message": "Successfully updated the application instance."
}

Back to Top