|
| 1 | +--- |
| 2 | +title: GCP data connector reference for the Codeless Connector Platform |
| 3 | +titleSuffix: Microsoft Sentinel |
| 4 | +description: This article provides reference JSON fields and properties for creating the GCP data connector type and its data connection rules as part of the Codeless Connector Platform. |
| 5 | +services: sentinel |
| 6 | +author: austinmccollum |
| 7 | +ms.topic: reference |
| 8 | +ms.date: 9/30/2024 |
| 9 | +ms.author: austinmc |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +# GCP data connector reference for the Codeless Connector Platform |
| 14 | + |
| 15 | +To create a Google Cloud Platform (GCP) data connector with the Codeless Connector Platform (CCP), use this reference as a supplement to the [Microsoft Sentinel REST API for Data Connectors](/rest/api/securityinsights/data-connectors/create-or-update?view=rest-securityinsights-2024-01-01-preview&tabs=HTTP#gcpdataconnector&preserve-view=true) docs. |
| 16 | + |
| 17 | +Each `dataConnector` represents a specific *connection* of a Microsoft Sentinel data connector. One data connector might have multiple connections, which fetch data from different endpoints. The JSON configuration built using this reference document is used to complete the deployment template for the CCP data connector. |
| 18 | + |
| 19 | +For more information, see [Create a codeless connector for Microsoft Sentinel](create-codeless-connector.md#create-the-deployment-template). |
| 20 | + |
| 21 | +## Build the GCP CCP data connector |
| 22 | + |
| 23 | +A sample GCP CCP data connector deployment template is available [here](https://github.com/austinmccollum/Azure-Sentinel/blob/patch-5/DataConnectors/Templates/Connector_GCP_CCP_template.json) to ease the development of connecting your data source. With most of the deployment template sections filled out, only the first two components need to be built. For more information on building the first two components, see the [Output table definition](create-codeless-connector.md#output-table-definition) and [Data Collection Rule (DCR)](create-codeless-connector.md#data-collection-rule) sections. |
| 24 | + |
| 25 | +## Data Connectors - Create or update |
| 26 | + |
| 27 | +Reference the [Create or Update](/rest/api/securityinsights/data-connectors/create-or-update) operation in the REST API docs to find the latest stable or preview API version. The difference between the *create* and the *update* operation is the update requires the **etag** value. |
| 28 | + |
| 29 | +**PUT** method |
| 30 | +```http |
| 31 | +https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.OperationalInsights/workspaces/{{workspaceName}}/providers/Microsoft.SecurityInsights/dataConnectors/{{dataConnectorId}}?api-version={{apiVersion}} |
| 32 | +``` |
| 33 | + |
| 34 | +## URI parameters |
| 35 | + |
| 36 | +For more information about the latest API version, see [Data Connectors - Create or Update URI Parameters](/rest/api/securityinsights/data-connectors/create-or-update#uri-parameters). |
| 37 | + |
| 38 | +|Name | Description | |
| 39 | +|---------|---------| |
| 40 | +| **dataConnectorId** | The data connector ID must be a unique name and is the same as the `name` parameter in the [request body](#request-body).| |
| 41 | +| **resourceGroupName** | The name of the resource group, not case sensitive. | |
| 42 | +| **subscriptionId** | The ID of the target subscription. | |
| 43 | +| **workspaceName** | The *name* of the workspace, not the ID.<br>Regex pattern: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$` | |
| 44 | +| **api-version** | The API version to use for this operation. | |
| 45 | + |
| 46 | +## Request body |
| 47 | + |
| 48 | +The request body for a `GCP` CCP data connector has the following structure: |
| 49 | + |
| 50 | +```json |
| 51 | +{ |
| 52 | + "name": "{{dataConnectorId}}", |
| 53 | + "kind": "GCP", |
| 54 | + "etag": "", |
| 55 | + "properties": { |
| 56 | + "connectorDefinitionName": "", |
| 57 | + "auth": {}, |
| 58 | + "request": {}, |
| 59 | + "dcrConfig": "" |
| 60 | + } |
| 61 | +} |
| 62 | + |
| 63 | +``` |
| 64 | + |
| 65 | +### GCP |
| 66 | + |
| 67 | +**GCP** represents a CCP data connector where the paging and expected response payloads for your Google Cloud Platform (GCP) data source has already been configured. Configuring your GCP service to send data to a GCP Pub/Sub must be done separately. For more information, see [Publish message in Pub/Sub overview](https://cloud.google.com/pubsub/docs/publish-message-overview). |
| 68 | + |
| 69 | +| Name | Required | Type | Description | |
| 70 | +| ---- | ---- | ---- | ---- | |
| 71 | +| **name** | True | string | The unique name of the connection matching the URI parameter | |
| 72 | +| **kind** | True | string | Must be `GCP` | |
| 73 | +| **etag** | | GUID | Leave empty for creation of new connectors. For update operations, the etag must match the existing connector's etag (GUID). | |
| 74 | +| properties.connectorDefinitionName | | string | The name of the DataConnectorDefinition resource that defines the UI configuration of the data connector. For more information, see [Data Connector Definition](create-codeless-connector.md#data-connector-user-interface). | |
| 75 | +| properties.**auth** | True | Nested JSON | Describes the credentials for polling the GCP data. For more information, see [authentication configuration](#authentication-configuration). | |
| 76 | +| properties.**request** | True | Nested JSON | Describes the GCP project Id and GCP subscription for polling the data. For more information, see [request configuration](#request-configuration). | |
| 77 | +| properties.**dcrConfig** | | Nested JSON | Required parameters when the data is sent to a Data Collection Rule (DCR). For more information, see [DCR configuration](#dcr-configuration). | |
| 78 | + |
| 79 | +## Authentication configuration |
| 80 | + |
| 81 | +Authentication to GCP from Microsoft Sentinel uses a GCP Pub/Sub. You must configure the authentication separately. Use the Terraform scripts [here](https://github.com/Azure/Azure-Sentinel/blob/master/DataConnectors/GCP/Terraform/sentinel_resources_creation/GCPInitialAuthenticationSetup/GCPInitialAuthenticationSetup.tf). For more information, see [GCP Pub/Sub authentication from another cloud provider](https://cloud.google.com/docs/authentication/provide-credentials-adc#wlif). |
| 82 | + |
| 83 | +As a best practice, use parameters in the auth section instead of hard-coding credentials. For more information, see [Secure confidential input](create-codeless-connector.md#secure-confidential-input). |
| 84 | + |
| 85 | +In order to create the deployment template which also uses parameters, you need to escape the parameters in this section with an extra starting `[`. This allows the parameters to assign a value based on the user interaction with the connector. For more information, see [Template expressions escape characters](../azure-resource-manager/templates/template-expressions.md#escape-characters). |
| 86 | + |
| 87 | +To enable the credentials to be entered from the UI, the `connectorUIConfig` section requires `instructions` with the desired parameters. For more information, see [Data connector definitions reference for the Codeless Connector Platform](data-connector-ui-definitions-reference.md#instructions). |
| 88 | + |
| 89 | +GCP auth example: |
| 90 | +```json |
| 91 | +"auth": { |
| 92 | + "serviceAccountEmail": "[[parameters('GCPServiceAccountEmail')]", |
| 93 | + "projectNumber": "[[parameters('GCPProjectNumber')]", |
| 94 | + "workloadIdentityProviderId": "[[parameters('GCPWorkloadIdentityProviderId')]" |
| 95 | +} |
| 96 | +``` |
| 97 | + |
| 98 | +## Request configuration |
| 99 | + |
| 100 | +The request section requires the `projectId` and `subscriptionNames` from the GCP Pub/Sub. |
| 101 | + |
| 102 | +GCP request example: |
| 103 | +```json |
| 104 | +"request": { |
| 105 | + "projectId": "[[parameters('GCPProjectId')]", |
| 106 | + "subscriptionNames": [ |
| 107 | + "[[parameters('GCPSubscriptionName')]" |
| 108 | + ] |
| 109 | +} |
| 110 | +``` |
| 111 | + |
| 112 | +## DCR configuration |
| 113 | + |
| 114 | +| Field | Required | Type | Description | |
| 115 | +|----|----|----|----| |
| 116 | +| **DataCollectionEndpoint** | True | String | DCE (Data Collection Endpoint) for example: `https://example.ingest.monitor.azure.com`. | |
| 117 | +| **DataCollectionRuleImmutableId** | True | String | The DCR immutable ID. Find it by viewing the DCR creation response or using the [DCR API](/rest/api/monitor/data-collection-rules/get) | |
| 118 | +| **StreamName** | True | string | This value is the `streamDeclaration` defined in the DCR (prefix must begin with *Custom-*) | |
| 119 | + |
| 120 | +## Example CCP data connector |
| 121 | + |
| 122 | +Here's an example of all the components of the `GCP` CCP data connector JSON together. |
| 123 | + |
| 124 | +```json |
| 125 | +{ |
| 126 | + "kind": "GCP", |
| 127 | + "properties": { |
| 128 | + "connectorDefinitionName": "[[parameters('connectorDefinitionName')]", |
| 129 | + "dcrConfig": { |
| 130 | + "streamName": "[variables('streamName')]", |
| 131 | + "dataCollectionEndpoint": "[[parameters('dcrConfig').dataCollectionEndpoint]", |
| 132 | + "dataCollectionRuleImmutableId": "[[parameters('dcrConfig').dataCollectionRuleImmutableId]" |
| 133 | + }, |
| 134 | + "dataType": "[variables('dataType')]", |
| 135 | + "auth": { |
| 136 | + "serviceAccountEmail": "[[parameters('GCPServiceAccountEmail')]", |
| 137 | + "projectNumber": "[[parameters('GCPProjectNumber')]", |
| 138 | + "workloadIdentityProviderId": "[[parameters('GCPWorkloadIdentityProviderId')]" |
| 139 | + }, |
| 140 | + "request": { |
| 141 | + "projectId": "[[parameters('GCPProjectId')]", |
| 142 | + "subscriptionNames": [ |
| 143 | + "[[parameters('GCPSubscriptionName')]" |
| 144 | + ] |
| 145 | + } |
| 146 | + } |
| 147 | +} |
| 148 | +``` |
| 149 | + |
| 150 | +For more information, see [Create GCP data connector REST API example](/rest/api/securityinsights/data-connectors/create-or-update?view=rest-securityinsights-2024-01-01-preview&tabs=HTTP#creates-or-updates-a-gcp-data-connector&preserve-view=true). |
0 commit comments