Skip to main content

Cyware Orchestrate

Google Cloud Storage

App Vendor: Google

App Category: Cloud Storage

Connector Version: 1.0.0

API Version: 1.0.0

About App

The Google Cloud Storage app enables security teams to integrate with Google Cloud to manage and retrieve objects stored in scalable, secure cloud storage buckets.

The Google Cloud Storage app is configured with Cyware Orchestrate to perform the following actions:

Action Name

Description

Create Bucket 

This action creates a new bucket in Google Cloud Storage.

Create Bucket Access Control 

This action creates an ACL entry for the specified bucket.

Create Object Access Control 

This action creates an ACL entry for the specified object.

Delete Bucket 

This action deletes a bucket only if it is empty. It fails if live or noncurrent objects are present, but succeeds if the bucket contains only soft-deleted objects or incomplete uploads.

Delete Bucket Access Control 

This action permanently deletes the ACL entry for the specified entity on the given bucket.

Delete Object 

This action deletes an object along with its metadata. If versioning is disabled or a generation is specified, the deletion is permanent.

Generic Action 

This is a general-purpose action for sending requests to any Google Cloud Storage endpoint.

Get Bucket Details 

This action retrieves the details of a specified bucket.

Get Object Details 

This action retrieves metadata for an object in a bucket.

List Bucket Access Controls 

This action retrieves the ACL entries of a specified bucket.

List Buckets 

This action retrieves a list of buckets for the specified project.

List Object Access Controls 

This action lists all the ACL entries for a specified object.

List Objects 

This action retrieves a list of objects in a bucket.

Update Bucket Access Control 

This action updates an ACL entry on the specified bucket.

Update Object Access Control 

This action permanently deletes the Access Control List (ACL) entry for a specified entity on a specified object.

Upload Object 

This action uploads an object and its metadata to the specified bucket, replacing any object with the same name.

Configuration Parameters

The following configuration parameters are required for the Google Cloud Storage app to communicate with the Google Cloud Storage enterprise application. The parameters can be configured by creating instances in the app.

To configure this, you must have the credential file content. For more information about how to generate credentials, see Generate Credentials File for Google Cloud Storage.

Note

You must have an IAM role that includes the storage.buckets.list permission to configure an instance.

Parameter

Description

Field Type

Required/Optional

Comments

Project ID 

Enter the Google Cloud project ID associated with your service account. 

Example:

my-project-123456.

Text

Required

Credential File 

Enter the content of your Google-provided JSON credential file.

Password

Required

Base URL 

Enter the base URL to access Google Cloud Storage.

Example:

https://storage.googleapis.com. 

Text

Optional

Default value:

https://storage.googleapis.com.

Verify 

Choose your preference to verify SSL while making requests. It is recommended to set this option to yes. If no is passed, it may result in an incorrect connection establishment, potentially resulting in a broken connection.

Boolean

Optional

Allowed values: 

  • true 

  • false

Default value: 

true

Timeout 

Enter the timeout value in seconds. This is the number of seconds that requests will wait to establish a connection with Google Cloud Storage.

Integer

Optional

Allowed range:

15 - 120 seconds

Default value:

15 seconds

Action: Create Bucket

This action creates a new bucket in Google Cloud Storage.

Note

To use this action, you must have the storage.buckets.create IAM permission.

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Bucket Name 

Enter the name of the bucket. 

Example:

my-new-bucket

Text

Required

Project ID  

Enter the project name where the created bucket should reside. 

Example: 

my-project-123456

Text

Optional

By default, the project associated with the authentication credentials is used.

Enable Object Retention 

Choose true to enable object retention for this bucket.

Boolean

Optional

Predefined ACL 

Enter predefined access controls for the bucket.

Example:

private

Text

Optional

Allowed values:

authenticatedRead, allAuthenticatedUsers, private, projectPrivate, publicRead, and publicReadWrite

Predefined Default Object ACL 

Enter a predefined set of default access controls for the objects in the bucket.

Example:

private

Text

Optional

Allowed values:

authenticatedRead, bucketOwnerFullControl, bucketOwnerRead, private, projectPrivate, publicRead

Projection 

Enter the set of properties to include in the response.

Example:

full

Text

Optional

Allowed values:

full, noAcl

Extra Params 

Enter the extra parameters to create a bucket. 

Key Value

Optional

Allowed key:

fields

Additional Data 

Enter the additional parameters to create a bucket. 

Example:

{\"location\": \"us-east1\", \"storageclass\": \"standard\"}

Key Value

Optional

Allowed keys:

location, locationType, storageClass, acl, autoclass, billing, cors, customPlacementConfig, defaultEventBaseHold, defaultObjectAcl, encryption, etag, generation, hardDeleteTime, hierarchicalNamespace, iamConfiguration, id, kind, labels, lifecycle, logging, metageneration, objectRetention, owner, projectNumber, retentionPolicy, rpo, satisfiesPZI, satisfiesPZS, selfLink, softDeletePolicy, softDeleteTime, storageClass, timeCreated, updated, versioning, website.

Example Request 

[
  {
    "projection": "noAcl",
    "bucket_name": "my-new-bucket",
    "extra_params": {},
    "enable_object_retention": true,
    "predefined_default_object_acl": "bucketOwnerFullControl"
  }
]
Action: Create Bucket Access Control

This action creates an ACL entry for the specified bucket.

Note

You must have the following IAM permissions on the bucket to use this action:

  • storage.buckets.get

  • storage.buckets.getIamPolicy

  • storage.buckets.setIamPolicy

  • storage.buckets.update

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Bucket Name 

Enter the name of the bucket where the ACL entry will be created. 

Example:

my-data-bucket

Text

Required

Entity 

Enter the entity holding the permission.

Text

Required

Allowed formats:

user-email, group-groupid, group-email, domain-domain, project-team-projectid, allUsers, and allAuthenticatedUsers

Role 

Enter the access permission for the entity.

Text

Required

Allowed values:

owner, reader, writer

Extra Params 

Enter the extra parameters to create an ACL entity.

Key Value

Optional

Allowed values:

kind, selflink, domain, bucket, email, entityID, etag, ID, projectTeam

Example Request 

[
  {
    "role": "OWNER",
    "entity": "user-john.john@example.com",
    "bucket_name": "bucket_form_api_ui_2",
    "extra_params": {}
  }
]
Action: Create Object Access Control

This action creates an ACL entry for the specified object.

Note

You must have one of the following permissions to use this action:

  • The storage.objects.setIamPolicy IAM permission for the bucket containing the object

  • The OWNER ACL permission for the object

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Bucket Name 

Enter the name of the bucket that contains the object. Example:

my-data-bucket

Text

Required

Object Name 

Enter the name of the object on which you want to create the access control entry. 

Example:

my-data

Text

Required

Entity 

Enter the entity that will hold the permission.

Text

Required

Allowed formats:

user-email, group-groupid, group-email, domain-domain, project-team-projectid, allUsers, and allAuthenticatedUsers

Role 

Enter the permission role to assign to the entity. 

Text

Required

Allowed values:

owner and reader

Extra Params 

Enter the extra parameters to create the ACL entity.

Key Value

Optional

Allowed keys:

generation and fields

Example Request 

[
  {
    "role": "OWNER",
    "entity": "user-john.john@example.com",
    "bucket_name": "bucket_form_api_ui_2",
    "object_name": "my-object",
    "extra_params": {}
  }
]
Action: Delete Bucket

This action deletes an empty bucket. It fails if the bucket contains live or noncurrent objects, but succeeds with soft-deleted objects or incomplete uploads.

Note

You must have the storage.buckets.delete IAM permission to use this action.

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Bucket Name 

Enter the name of the bucket to delete. 

Example:

my-bucket-to-delete

Text

Required

Example Request 

[
    {
        "bucket_name": "my-bucket-to-delete"
    }
]
Action: Delete Bucket Access Control

This action permanently deletes the ACL entry for the specified entity on the given bucket.

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Bucket Name 

Enter the name of the bucket where the access control entry resides.

Example:

my-data-bucket

Text

Required

Entity 

Enter the entity holding the permission. 

Text

Required

Allowed formats: 

user-email, group-groupid, group-email, domain-domain, project-team-projectid, allUsers, and allAuthenticatedUsers

Example Request 

[
  {
    "entity": "user-john.john@example.com",
    "bucket_name": "my-data-bucket",
    "extra_params": {}
  }
] 
Action: Delete Object

This action deletes an object and its metadata. If versioning is disabled or the generation parameter is specified, the deletion is permanent.

Note

You must have the storage.objects.delete IAM permission to use this action.

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Bucket Name 

Enter the name of the bucket containing the object to delete. 

Example:

my-data-bucket

Text

Required

Object Name 

Enter the name of the object to delete. 

Example:

path/to/file.txt

Text

Required

Extra Params 

Enter any extra parameters to delete the object. 

Example:

{"generation": "1587397692104000"}

Key Value

Optional

Allowed key:

generation

Example Request

[
  {
    "bucket_name": "my-data-bucket",
    "object_name": "path/to/file.txt",
    "extra_params": {"generation": "1587397692104000"}
  }
]
Action: Get Bucket Details

This action retrieves the details of the specified bucket.

Note

You must have the storage.buckets.get IAM permission to use this action.

Additionally, to return specific bucket metadata, you must have the following permissions:

  • To return the bucket IP filtering rules: storage.buckets.getIpFilter

  • To return the IAM policies: storage.buckets.getIamPolicy

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Bucket Name 

Enter the name of the bucket to retrieve metadata.

Example:

my-bucket-name

Text

Required

Extra Params 

Enter the extra parameters to retrieve bucket details.

Key Value

Optional

Allowed keys: 

fields, projection, generation, ifMetagenerationMatch, ifMetagenerationNotMatch, softDeleted, userProject, alt, prettyPrint, quotaUser, userIp, and uploadType

Example Request 

[
  {
    "bucket_name": "my-bucket-name",
    "extra_params": {}
  }
]
Action: Get Object Details

This action retrieves metadata or downloads the contents of an object stored in a bucket. To download the file, you must set the Response Type parameter to media.

Note

You must have the storage.objects.get IAM permission to use this action. To return object ACLs, the authenticated user must also have the storage.objects.getIamPolicy permission.

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Bucket Name 

Enter the name of the bucket containing the object. 

Example:

my-data-bucket

Text

Required

Object Name 

Enter the name of the object to retrieve. 

Example: 

sample_object

Text

Required

Response Type 

Enter the type of data to retrieve. 

Note

To download the object, enter media as the Response Type.

Text

Optional

Allowed values: 

json, media

Default value:

json

File Name 

If you set the response type to media, enter the file name (with extension) to store the object in Cyware Orchestrate. The response will include the file path where the object will be stored. 

Example:

sample.txt

Text

Optional

Default value:

object.txt

Encryption Headers 

Enter the type of encryption algorithm to use for customer-managed encryption keys. 

Example:

 {"x-goog-encryption-algorithm": "aes256", "x-goog-encryption-key": "your-base64-key", "x-goog-encryption-key-sha256": "your-key-sha256"}

Key Value

Optional

Allowed keys:

x-goog-encryption-algorithm, x-goog-encryption-key, and x-goog-encryption-key-sha256

Extra Params 

Enter the extra parameters to retrieve object metadata.

Key Value

Optional

Allowed keys:

generation, ifGenerationMatch, ifGenerationNotMatch, ifMetagenerationMatch, ifMetagenerationNotMatch, restoreToken,softDeleted, userProject, projection

Display Response 

Choose true to display file content in the UI.

Boolean

Optional

Allowed values:

true, false

Default value:

false

Example Request 

[
  {
    "bucket_name": "my-data-bucket",
    "object_name": "sample_object",
    "extra_params": {},
    "encryption_headers": {}
  }
]
Action: List Bucket Access Controls

This action retrieves the ACL entries on a specified bucket.

Note

You must have the following IAM permissions on the bucket to use this action:

  • storage.buckets.get

  • storage.buckets.getIamPolicy

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Bucket Name 

Enter the name of the bucket to retrieve ACL entries. 

Example:

my-data-bucket

Text

Required

Extra Params 

Enter the extra parameters to retrieve ACL entries.

Key Value

Optional

Example Request

[
  {
    "bucket_name": "my-data-bucket",
    "extra_params": {}
  }
]
Action: List Buckets

This action retrieves a list of buckets for the specified project.

Note

You must have the storage.buckets.list IAM permission to use this action.

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Project ID  

Enter the project ID to list buckets from. 

Example: 

my-project-123456

Text

Optional

Extra Params 

Enter the extra parameters to list buckets.

Key Value

Optional

Allowed keys:

fields, maxResults, pageToken, prefix, projection, softDeleted, userProject.

Example Request 

[
  {
    "extra_params": {}
  }
]
Action: List Object Access Controls

This action lists all the ACL entries for a specified object.

Note

You must have one of the following permissions to use this method:

  • The storage.objects.getIamPolicy IAM permission for the bucket containing the object

  • The OWNER ACL permission for the object

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Bucket name 

Enter the name of the bucket containing the object.

Example: 

my-data-bucket

Text

Required

Object name 

Enter the name of the object whose acl entries you want to retrieve. 

Example:

my-data

Text

Required

Extra params 

Enter the extra parameters to list ACL entries.

Key Value

Optional

Allowed key:

generation

Example Request 

[
  {
    "bucket_name": "bucket_form_api_ui_2",
    "object_name": "test_final",
    "extra_params": {}
  }
]
Action: List Objects

This action retrieves a list of objects in a bucket.

Note

The authenticated user must have the storage.objects.list IAM permission to use this action.

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Bucket Name 

Enter the name of the bucket to list objects.

Example:

my-data-bucket

Text

Required

Delimiter 

Enter delimiter to retrieve results in a directory-like mode. 

Text

Optional

Use / for folder-like navigation. Object names without the delimiter are listed in items[], and truncated names with the delimiter are listed in prefixes[]. Set delimiter to / when using match glob or include folders as prefixes.

Include Folders as Prefixes 

Choose true to include empty folders and managed folders in the prefixes[] list. 

Boolean

Optional

Default value: 

false

Note: If you use this parameter, delimiter must be set to /.

Max Results 

Enter the maximum combined number of entries from items[] and prefixes[] to return in a single page of response. 

Example: 

100

Integer

Optional

Match Glob 

Enter a glob pattern to filter results. 

Example:

.jpg to match only jpeg images

Text

Optional

Page Token 

Enter the nextPagetoken value from a previous response to retrieve the next set of results.

Text

Optional

 

Prefix 

Enter a prefix to include only objects whose names begin with this prefix.

Example:

documents/

Text

Optional

Extra Params 

Enter the extra parameters to list objects. 

Key Value

Optional

Allowed keys: 

fields, projection, versions, delimiter, endOffset, includeFoldersAsPrefixes, includeTrailingDelimiter, matchGlob, maxResults, pageToken, prefix, softDeleted, startOffset, userProject, alt, prettyPrint, quotaUser, userIp, and uploadType

Example Request 

[
  [
    {
      "bucket_name": "my-data-bucket",
      "extra_params": {}
    }
  ]
]
Action: Update Bucket Access Control

This action updates an ACL entry on the specified bucket.

Note

You must have the following IAM permissions on the bucket to use this action:

  • storage.buckets.get

  • storage.buckets.getIamPolicy

  • storage.buckets.setIamPolicy

  • storage.buckets.update

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Bucket Name 

Enter the name of the bucket to update the access control entry.

Example:

my-data-bucket

Text

Required

Entity 

Enter the entity holding the permission.

Text

Required

Allowed formats:

user-email, group-groupid, group-email, domain-domain, project-team-projectid, allUsers, and allAuthenticatedUsers

Role 

Enter the access permission for the entity. 

Text

Required

Allowed values:

owner, reader, writer

Extra Params 

Enter the extra parameters to update ACL entry.

Key Value

Optional

Additional Data 

Enter the additional parameters to update the ACL entry.

Key Value

Optional

Allowed keys:

bucket, role, projectTeam, domain, email, entity, entityId, etag, id, kind, projectTeam, role, and selfLink.

Example Request 

[
  {
    "role": "WRITER",
    "entity": "user-john.john@example.com",
    "bucket_name": "my-data-bucket",
    "extra_fields": {},
    "extra_params": {}
  }
]
Action: Update Object Access Control

This action permanently deletes the Access Control List (ACL) entry for a specified entity on a specified object.

Note

You must have one of the following permissions to use this method:

  • The storage.objects.setIamPolicy IAM permission for the bucket containing the object.

  • The OWNER ACL permission for the object

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Bucket Name 

Enter the name of the bucket where the object is stored. 

Example:

my-data-bucket

Text

Required

Object Name 

Enter the name of the object you want to update.

Example:

my-data

Text

Required

Entity 

Enter the entity that holds the permission.

Text

Required

Allowed formats:

user-emailAddress, group-groupId, group-emailAddress, allUsers, and allAuthenticatedUsers.

Extra Params 

Enter the extra parameters to update the ACL entry. 

Key Value

Optional

Allowed keys:

generation, fields

Additional Data 

Enter the additional parameters to update the ACL entry. 

Key Value

Optional

Allowed keys:

kind, object, role, bucket, domain, email, entity, entityId, etag, generation, id, projectTeam, role

Example Request 

[
  {
    "entity": "user-akshar.anup@cyware.com",
    "bucket_name": "bucket_form_api_ui_2",
    "object_name": "test_final",
    "extra_fields": {
      "role": "OWNER"
    },
    "extra_params": {}
  }
]
Action: Upload Object

This action uploads a new object and its metadata to a bucket. It replaces any existing object with the same name.

Note

You must have the storage.objects.create IAM permission to use this action. If the object being uploaded has the same name as an existing object, you must also have the storage.objects.delete permission to overwrite the existing object.

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

File Path 

Enter the dynamic file path of the file to upload. 

Example:

/tmp/data.txt.

Text

Required

Bucket Name 

Enter the name of the bucket where you want to upload the object. 

Example:

my-data-bucket

Text

Required

Object Name 

Enter the name you want to assign to the uploaded object.

Example:

path/to/new-file.txt

Text

Required

Upload Type 

Enter the type of upload request to the /upload uri. 

Text

Required

Allowed values: 

media, multipart, and resumable

Default value:

 media

Projection 

Enter the set of properties to retrieve.

Text

Optional

Allowed values: full and noAcl

Default value is noacl unless the object resource specifies an ACL property, in which case it defaults to full

Encryption Headers 

Enter the type of encryption algorithm to use for customer-managed encryption keys. 

Example:

{"x-goog-encryption-algorithm": "aes256", "x-goog-encryption-key": "your-base64-key"}

Key Value

Optional

Allowed keys:

x-goog-encryption-algorithm, x-goog-encryption-key, x-goog-encryption-key-sha256, and x-goog-meta-owner

Extra Params 

Enter the extra parameters to make the request.

Example:

{"predefinedacl": "publicread", "kmskeyname": "projects/my-project/locations/global/keyrings/my-kr/cryptokeys/my-key"}

Key Value

Optional

Allowed keys:

contentEncoding, ifGenerationMatch, ifGenerationNotMatch, ifMetagenerationMatch,   predefinedacl, kmskeyname, ifmetagenerationnotmatch, projection.

Additional Metadata Fields 

Enter the additional metadata fields for the uploaded object.  for example, {"contenttype": "text/plain", "cachecontrol": "public, max-age=3600"}

Key Value

Optional

Allowed keys:

cachecontrol, contentEncoding, contenttype, acl[], cacheControl, contentDisposition, contentLanguage, contentType, crc32c, customTime, eventBasedHold, md5Hash, metadata, name, retention, retention.mode, retention.retainUntilTime, storageClass, and temporaryHold.  

Example Request 

[
  {
    "file_path": "/tmp/9adb82ba-fde3-47f4-a304-1c5f3b137af0/object.txt",
    "bucket_name": "my-data-bucket",
    "object_name": "path/to/new-file.txt",
    "upload_type": "media",
    "extra_fields": {},
    "extra_params": {},
    "encryption_headers": {}
  }
]
Action: Generic Action

This is a generic action used to make requests to any Google Cloud Storage endpoint.

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

Method 

Enter the HTTP method to make the request. 

Example: 

get

Text

Required

Allowed values: get, put, post, delete

Endpoint 

Enter the endpoint to make the request. 

Example:

/storage/v1/b

Text

Required

Query Params 

Enter the query parameters to pass to the API.

Key Value

Optional

Payload 

Enter the payload to pass to the API.

Any

Optional

Extra Fields 

Enter the extra fields to pass to the API.

Key Value

Optional

Allowed keys:

payload_json, headers, download, files, filename, retry_wait, retry_count, custom_output, and response_type

Example Request 

[
  {
    "method": "get",
    "endpoint": "/storage/v1/b",
    "extra_fields": {},
    "query_params": {
      "project": "project-456613-c5"
    }
  }
]
Generate Credentials File for Google Cloud Storage

You must generate a credentials file to authenticate with the Google Cloud Storage. For more information on the usage of the credentials file, see Credentials File.

Steps 

To generate a credentials file for Google Cloud Storage, follow these steps:

  1. Create a Project  

  2. Create a Service Account, Assign Roles, and Generate Keys

Create a Project

You must create a project in the Google Cloud Console to manage APIs, permissions for Google Cloud resources, and more. For more information on creating projects in Google Cloud Console, see Create Projects.

Steps 

To create a project in the Google Cloud Console, follow these steps:

  1. Sign in to the Google Cloud Console.

  2. Click Select a Project and click New Project.

  3. Enter the project name, organization, and location.

  4. Click Create.

Create a Service Account, Assign Roles, and Generate Keys

To configure access, you must create a service account, assign the necessary roles, and generate a key file. The credentials file downloaded in this process is required when setting up the integration. A service account is identified by its email address, which is unique to the account. For more information on service accounts, see Service Accounts.

Steps 

To create a service account and add keys, follow these steps:

  1. From the main menu, go to the API and Services > Credentials.

  2. Click Create Credentials and select Service Account.

  3. Enter service account details such as service account name, service account ID, and service account description.

  4. Click Create and Continue.

  5. (Optional) Grant the service account access to the project by selecting a role.

  6. (Optional) Grant users access to this service account.

  7. To assign a role and add a key, go to Service Accounts and select the service account that you have created. Use the following information:

    • Assign roles: Go to the Permissions tab and click Manage Access. Under Assign roles, click Add role and select a role from the dropdown. To review the available roles and the associated permissions, click Manage Roles.

      Note

      Ensure that the selected role includes all required permissions necessary for performing the actions. To successfully test the connectivity of the instance you configure in Cyware Orchestrate with Google Cloud Storage API, the role must have storage.buckets.list permission.

    • Generate a key: Go to the Keys tab and click Add Key > Create New Key. Select JSON as the key type and click Create. Download and securely store the key file. You will not be able to access the credentials after closing the dialog.

  8. Copy the contents of the downloaded JSON key file and use it as input for the Credential File parameter during instance configuration. For more information, see Configuration Parameters.