Google Cloud Pubsub

Google Cloud Pub/Sub is a messaging service that facilitates real-time communication between applications.

Google Cloud Pubsub is a fully-managed real-time messaging service that allows you to send and receive messages between independent applications. By integrating with Swimlane Turbine, users can automate the retrieval and publishing of messages, enhancing the efficiency of their security operations. This integration enables seamless communication between systems, allowing for real-time data processing and improved incident response times.

Prerequisites

Before you can use the Google Cloud Pub/Sub connector for Turbine, you'll need access to the Google Cloud API. This requires the following:

A Google Service Account authentication using the following parameters:

Credentials: JSON file containing the service account key.

Delegate Account: Email address of the user to impersonate.

And OAuth2 authorization using the following parameters:

Client ID: The client ID obtained from the Google Developer Console.

Client Secret: The client secret associated with the client ID.

Refresh Token: Token used to obtain new access tokens.

Asset Setup

Scope:

Google Cloud PubSub requires one of the following OAuth scopes:

https://www.googleapis.com/auth/pubsub

https://www.googleapis.com/auth/cloud-platform

Capabilities

This connector provides the following capabilities:

* Projects Subscriptions Pull
* Projects Topics Publish

GCP Project Creation:

Navigate to this link to create a new project: https://console.cloud.google.com/projectcreate

Name your project and click Create. We recommend specific and recognizable project names.

Navigate to your projects, and select your new project.

Enable the Google Cloud PubSub API:

Go to the API & Services Dashboard in the Cloud Console.

Click on the "Enable APIs and Services" button.

Search for "Google Cloud PubSub API" and enable it for your project.

Asset Configuration:

Configuring a Service Account:

Google Cloud PubSub connector requires a Google service account to authenticate.

Open https://console.developers.google.com/iam-admin/serviceaccounts

Select the appropriate project

Click + CREATE NEW SERVICE ACCOUNT

Assign a name for the service account and add a description, click CREATE AND CONTINUE

Click the Select a Role dropdown and type “Owner” in the filter. Choose Owner and click Continue

For the menu specifying Grant users access to this service account (optional) you may select Users or Skip and click Done. This is not required for the connector

Click on the newly created service account email

Navigate to the KEYS menu

Click ADD KEY, select CREATE NEW KEY, select JSON format, and click CREATE. Make sure you download the .json file presented. This file will be needed when configuring the asset in Swimlane

Navigate to the Details menu at the top of the screen. Copy down the Unique ID to be used in the Setting API Scopes step below

Delegating Domain-Wide Authority (Recommended)

In order to support accessing multiple user's accounts, domain-wide authority must be enabled before creating a service account. Choosing not to delegate domain-wide authority will heavily limit the scope of what this connector can do. If the connector will only operate against a single account, the next section (Setting API Scopes) can be skipped.

Setting API Scopes:

After creating a service account, the necessary API scopes required to be authorized must be set.

From https://admin.google.com, navigate to Security > API Controls and then click Manage Domain Wide Delegation at the bottom of the window.

Click Add new

In the Client ID field, enter the Unique ID from the service account Details menu

Enter the following CSV value into the OAuth Scopes (comma-delimited) input: https://www.googleapis.com/auth/pubsub, https://www.googleapis.com/auth/cloud-platform

Click Authorize

Credentials:

The contents of the JSON credentials key file downloaded when creating a service account must be base64-encoded when creating the Google Cloud PubSub asset.

For Linux and Mac:

$ cat <path_to_credentials.json> | base64

For Windows using Powershell:

[convert]::ToBase64String((Get-Content -path "your_file_path" -Encoding byte))

Now copy the Base64 encoded string and paste it into the Service Account JSON field.

Delegate Account:

The delegate account value is used to determine which account to operate as when running actions. This value should be the email address for the target account (the mailbox you are trying to read/write).

Some actions provide an optional input to override the asset value.

In most - if not all cases an Admin account of the Google Workspace should be used. It should not be the service account email.

Customer ID:

The unique ID for the customer's Google Workspace account. As an account administrator, you can also use the my_customer alias to represent your account's customerId. The customerId is also returned as part of the users resource.

In order to get this value, navigate to https://admin.google.com. Then go to Account - Account Settings, and you will find it listed.

OAuth 2.0

To configure OAuth 2.0 for the Google Cloud PubSub Connector, follow these steps:

Navigate to the Google Cloud Console.

Select your project from the top menu.

In the left sidebar, select "APIs & Services" > "Credentials."

Click the "+ CREATE CREDENTIALS" button and select "OAuth 2.0 Client ID."

Under "Application type," select "Web application."

Enter a name for the OAuth 2.0 client.

Click "Create." A dialog with your client ID and client secret will appear.

Click "OK" to close the dialog.

Next to the OAuth 2.0 client you just created, click on the pencil icon to edit the client.

Under "Scopes for Google APIs," add the necessary scopes that are required for your connector (as specified in the "Setting API Scopes" section of this README).

Click "Save."

Your OAuth 2.0 client is now configured and ready to be used with the Google Cloud PubSub Connector.

Once this is configured, you need to provide the refresh token in the asset. If you dont know how to achieve this, Swimlane will provide you with a script that will help you to get the refresh token.

Notes

Google Cloud PubSub API Authentication

Google Cloud PubSub Subscriptions API Documentation

Google Cloud PubSub Topics API Documentation

Additional Documentation

Google Cloud Pubsub Connector Documentation

Google Cloud Pubsub API Documentation

Configurations

Google Cloud PubSub Authentication

Authenticates Google Forms using Google credentials

Configuration Parameters

Parameter	Description	Type	Required
client_id	The client ID for the OAuth 2.0 application.	string	Required
client_secret	The client secret for the OAuth 2.0 application.	string	Required
refresh_token	OAuth 2.0 refresh token used to obtain new access tokens. If using a refresh token, you must also provide a client ID and secret.	string	Required
scope	Permission scopes for this action.	array	Optional

Google Cloud PubSub Service Account Authentication

Authenticates Google Forms using Service Account.

Configuration Parameters

Parameter	Description	Type	Required
credentials	Base64-encoded contents from Service Account JSON credentials file. See README for setup instructions	string	Required
delegate_account	Account to execute integrations under. If not specified, the integration will run as a service account. Using a Service Account will introduce limitations. See Readme	string	Required
scope	Permission scopes for this action.	array	Optional

Actions

Projects Subscriptions Pull

Retrieve a specified number of messages from a Google Cloud Pubsub subscription using the subscription and maxMessages inputs.

Input

Argument Name	Type	Required	Description
subscription	string	Required	The subscription from which messages should be pulled. Format is projects//subscriptions/.
returnImmediately	boolean	Optional	If this field set to true, the system will respond immediately even if it there are no messages available to return in the subscriptions.pull response.
maxMessages	number	Required	The maximum number of messages to return for this request. Must be a positive integer.

Input Example

{"subscription":"projects/{project1}/subscriptions/{sub1}.","returnImmediately":true,"maxMessages":10}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
response	object	Output field: response
response.receivedMessages	array	Response message
response.receivedMessages.data	string	Response data

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","response":{"receivedMessages":[{}]}}

Projects Topics Publish

Publish messages to a specified Google Cloud Pubsub topic using 'topic' and 'messages' as inputs.

Input

Argument Name	Type	Required	Description
topic	string	Required	The messages in the request will be published on this topic. Format is projects//topics/.
messages	array	Required	Response message
messages.data	string	Optional	Response data

Input Example

{"topic":"xyz","messages":[{"data":"c2FtcGxlIGRhdGE="}]}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
response	object	Output field: response
response.messageIds	array	Unique identifier

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","response":{"messageIds":["10696178334573752"]}}

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT