Data Connector Definitions - Create Or Update

Reference

Service:: Sentinel

API Version:: 2024-01-01-preview

Creates or updates the data connector definition.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/dataConnectorDefinitions/{dataConnectorDefinitionName}?api-version=2024-01-01-preview

URI Parameters

Name	In	Required	Type	Description
dataConnectorDefinitionName	path	True	string	The data connector definition name. Regex pattern: `^[a-z0-9A-Z-_]*$`
resourceGroupName	path	True	string	The name of the resource group. The name is case insensitive.
subscriptionId	path	True	string	The ID of the target subscription.
workspaceName	path	True	string	The name of the workspace. Regex pattern: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
api-version	query	True	string	The API version to use for this operation.

Request Body

CustomizableConnectorDefinition

Connector definition for kind 'Customizable'.

Name	Required	Type	Description
kind	True	string: Customizable	The data connector kind
properties.connectorUiConfig	True	CustomizableConnectorUiConfig	The UiConfig for 'Customizable' connector definition kind.
etag		string	Etag of the azure resource
properties.connectionsConfig		CustomizableConnectionsConfig	The UiConfig for 'Customizable' connector definition kind.
properties.createdTimeUtc		string	Gets or sets the connector definition created date in UTC format.
properties.lastModifiedUtc		string	Gets or sets the connector definition last modified date in UTC format.

Responses

Name	Type	Description
200 OK	DataConnectorDefinition: CustomizableConnectorDefinition	Updated
201 Created	DataConnectorDefinition: CustomizableConnectorDefinition	Created
Other Status Codes	CloudError	Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Create data connector definition

Sample request

HTTP

PUT https://management.azure.com/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/dataConnectorDefinitions/73e01a99-5cd7-4139-a149-9f2736ff2ab5?api-version=2024-01-01-preview

{
  "kind": "Customizable",
  "etag": "\"0300bf09-0000-0000-0000-5c37296e0000\"",
  "properties": {
    "connectorUiConfig": {
      "title": "GitHub Enterprise Audit Log",
      "publisher": "GitHub",
      "descriptionMarkdown": "The GitHub audit log connector provides the capability to ingest GitHub logs into Azure Sentinel. By connecting GitHub audit logs into Azure Sentinel, you can view this data in workbooks, use it to create custom alerts, and improve your investigation process.",
      "graphQueries": [
        {
          "metricName": "Total events received",
          "legend": "GitHub audit log events",
          "baseQuery": "GitHubAuditLogPolling_CL"
        }
      ],
      "dataTypes": [
        {
          "name": "GitHubAuditLogPolling_CL",
          "lastDataReceivedQuery": "GitHubAuditLogPolling_CL \n            | summarize Time = max(TimeGenerated)\n            | where isnotempty(Time)"
        }
      ],
      "connectivityCriteria": [
        {
          "type": "IsConnectedQuery",
          "value": [
            "GitHubAuditLogPolling_CL \n | summarize LastLogReceived = max(TimeGenerated)\n | project IsConnected = LastLogReceived > ago(30d)"
          ]
        }
      ],
      "availability": {
        "status": 1,
        "isPreview": false
      },
      "permissions": {
        "resourceProvider": [
          {
            "provider": "Microsoft.OperationalInsights/workspaces",
            "permissionsDisplayText": "read and write permissions are required.",
            "providerDisplayName": "Workspace",
            "scope": "Workspace",
            "requiredPermissions": {
              "write": true,
              "read": false,
              "delete": false,
              "action": false
            }
          }
        ],
        "customs": [
          {
            "name": "GitHub API personal token Key",
            "description": "You need access to GitHub personal token, the key should have 'admin:org' scope"
          }
        ]
      },
      "instructionSteps": [
        {
          "title": "Connect GitHub Enterprise Audit Log to Azure Sentinel",
          "description": "Enable GitHub audit Logs. \n Follow [this](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) to create or find your personal key",
          "instructions": [
            {
              "type": "OAuthForm",
              "parameters": {
                "clientIdLabel": "Client ID",
                "clientSecretLabel": "Client Secret",
                "connectButtonLabel": "Connect",
                "disconnectButtonLabel": "Disconnect"
              }
            }
          ]
        }
      ]
    }
  }
}

Sample response

Status code:: 200

{
  "id": "/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/dataConnectorDefinitions/73e01a99-5cd7-4139-a149-9f2736ff2ab5",
  "name": "73e01a99-5cd7-4139-a149-9f2736ff2ab5",
  "type": "Microsoft.SecurityInsights/dataConnectorDefinitions",
  "kind": "Customizable",
  "etag": "\"0300bf09-0000-0000-0000-5c37296e0000\"",
  "properties": {
    "connectorUiConfig": {
      "title": "GitHub Enterprise Audit Log",
      "publisher": "GitHub",
      "descriptionMarkdown": "The GitHub audit log connector provides the capability to ingest GitHub logs into Azure Sentinel. By connecting GitHub audit logs into Azure Sentinel, you can view this data in workbooks, use it to create custom alerts, and improve your investigation process.",
      "graphQueries": [
        {
          "metricName": "Total events received",
          "legend": "GitHub audit log events",
          "baseQuery": "GitHubAuditLogPolling_CL"
        }
      ],
      "sampleQueries": [
        {
          "description": "All logs",
          "query": "GitHubAuditLogPolling_CL \n | take 10"
        }
      ],
      "dataTypes": [
        {
          "name": "GitHubAuditLogPolling_CL",
          "lastDataReceivedQuery": "GitHubAuditLogPolling_CL \n            | summarize Time = max(TimeGenerated)\n            | where isnotempty(Time)"
        }
      ],
      "connectivityCriteria": [
        {
          "type": "IsConnectedQuery",
          "value": [
            "GitHubAuditLogPolling_CL \n | summarize LastLogReceived = max(TimeGenerated)\n | project IsConnected = LastLogReceived > ago(30d)"
          ]
        }
      ],
      "availability": {
        "status": 1,
        "isPreview": false
      },
      "permissions": {
        "resourceProvider": [
          {
            "provider": "Microsoft.OperationalInsights/workspaces",
            "permissionsDisplayText": "read and write permissions are required.",
            "providerDisplayName": "Workspace",
            "scope": "Workspace",
            "requiredPermissions": {
              "write": true,
              "read": false,
              "delete": false,
              "action": false
            }
          }
        ],
        "customs": [
          {
            "name": "GitHub API personal token Key",
            "description": "You need access to GitHub personal token, the key should have 'admin:org' scope"
          }
        ]
      },
      "instructionSteps": [
        {
          "title": "Connect GitHub Enterprise Audit Log to Azure Sentinel",
          "description": "Enable GitHub audit Logs. \n Follow [this](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) to create or find your personal key",
          "instructions": [
            {
              "type": "OAuthForm",
              "parameters": {
                "clientIdLabel": "Client ID",
                "clientSecretLabel": "Client Secret",
                "connectButtonLabel": "Connect",
                "disconnectButtonLabel": "Disconnect"
              }
            }
          ]
        }
      ]
    }
  }
}

Status code:: 201

{
  "id": "/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/dataConnectorDefinitions/73e01a99-5cd7-4139-a149-9f2736ff2ab5",
  "name": "73e01a99-5cd7-4139-a149-9f2736ff2ab5",
  "type": "Microsoft.SecurityInsights/dataConnectorDefinitions",
  "kind": "Customizable",
  "etag": "\"0300bf09-0000-0000-0000-5c37296e0000\"",
  "properties": {
    "connectorUiConfig": {
      "title": "GitHub Enterprise Audit Log",
      "publisher": "GitHub",
      "descriptionMarkdown": "The GitHub audit log connector provides the capability to ingest GitHub logs into Azure Sentinel. By connecting GitHub audit logs into Azure Sentinel, you can view this data in workbooks, use it to create custom alerts, and improve your investigation process.",
      "graphQueries": [
        {
          "metricName": "Total events received",
          "legend": "GitHub audit log events",
          "baseQuery": "GitHubAuditLogPolling_CL"
        }
      ],
      "sampleQueries": [
        {
          "description": "All logs",
          "query": "GitHubAuditLogPolling_CL \n | take 10"
        }
      ],
      "dataTypes": [
        {
          "name": "GitHubAuditLogPolling_CL",
          "lastDataReceivedQuery": "GitHubAuditLogPolling_CL \n            | summarize Time = max(TimeGenerated)\n            | where isnotempty(Time)"
        }
      ],
      "connectivityCriteria": [
        {
          "type": "IsConnectedQuery",
          "value": [
            "GitHubAuditLogPolling_CL \n | summarize LastLogReceived = max(TimeGenerated)\n | project IsConnected = LastLogReceived > ago(30d)"
          ]
        }
      ],
      "availability": {
        "status": 1,
        "isPreview": false
      },
      "permissions": {
        "resourceProvider": [
          {
            "provider": "Microsoft.OperationalInsights/workspaces",
            "permissionsDisplayText": "read and write permissions are required.",
            "providerDisplayName": "Workspace",
            "scope": "Workspace",
            "requiredPermissions": {
              "write": true,
              "read": false,
              "delete": false,
              "action": false
            }
          }
        ],
        "customs": [
          {
            "name": "GitHub API personal token Key",
            "description": "You need access to GitHub personal token, the key should have 'admin:org' scope"
          }
        ]
      },
      "instructionSteps": [
        {
          "title": "Connect GitHub Enterprise Audit Log to Azure Sentinel",
          "description": "Enable GitHub audit Logs. \n Follow [this](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) to create or find your personal key",
          "instructions": [
            {
              "type": "OAuthForm",
              "parameters": {
                "clientIdLabel": "Client ID",
                "clientSecretLabel": "Client Secret",
                "connectButtonLabel": "Connect",
                "disconnectButtonLabel": "Disconnect"
              }
            }
          ]
        }
      ]
    }
  }
}

Definitions

Name	Description
CloudError	Error response structure.
CloudErrorBody	Error details.
ConnectivityCriterion	The criteria by which we determine whether the connector is connected or not. For Example, use a KQL query to check if the expected data type is flowing).
ConnectorDataType	The data type which is created by the connector, including a query indicated when was the last time that data type was received in the workspace.
ConnectorDefinitionsAvailability	The exposure status of the connector to the customers.
ConnectorDefinitionsPermissions	The required Permissions for the connector.
ConnectorDefinitionsResourceProvider	The resource provider details include the required permissions for the user to create connections. The user should have the required permissions(Read\Write, ..) in the specified scope ProviderPermissionsScope against the specified resource provider.
createdByType	The type of identity that created the resource.
CustomizableConnectionsConfig	The UiConfig for 'Customizable' connector definition kind.
CustomizableConnectorDefinition	Connector definition for kind 'Customizable'.
CustomizableConnectorUiConfig	The UiConfig for 'Customizable' connector definition kind.
CustomPermissionDetails	The Custom permissions required for the connector.
DataConnectorDefinitionKind	The kind of the data connector definitions
GraphQuery	The graph query to show the volume of data arriving into the workspace over time.
InstructionStep	Instruction steps to enable the connector.
InstructionStepDetails	Instruction step details, to be displayed in the Instructions steps section in the connector's page in Sentinel Portal.
ProviderPermissionsScope	The scope on which the user should have permissions, in order to be able to create connections.
ResourceProviderRequiredPermissions	Required permissions for the connector resource provider that define in ResourceProviders. For more information about the permissions see here.
systemData	Metadata pertaining to creation and last modification of the resource.

CloudError

Error response structure.

Name	Type	Description
error	CloudErrorBody	Error data

CloudErrorBody

Error details.

Name	Type	Description
code	string	An identifier for the error. Codes are invariant and are intended to be consumed programmatically.
message	string	A message describing the error, intended to be suitable for display in a user interface.

ConnectivityCriterion

The criteria by which we determine whether the connector is connected or not. For Example, use a KQL query to check if the expected data type is flowing).

Name	Type	Description
type	string	Gets or sets the type of connectivity.
value	string[]	Gets or sets the queries for checking connectivity.

ConnectorDataType

The data type which is created by the connector, including a query indicated when was the last time that data type was received in the workspace.

Name	Type	Description
lastDataReceivedQuery	string	Gets or sets the query to indicate when relevant data was last received in the workspace.
name	string	Gets or sets the name of the data type to show in the graph.

ConnectorDefinitionsAvailability

The exposure status of the connector to the customers.

Name	Type	Description
isPreview	boolean	Gets or sets a value indicating whether the connector is preview.
status	integer	The exposure status of the connector to the customers. Available values are 0-4 (0=None, 1=Available, 2=FeatureFlag, 3=Internal).

ConnectorDefinitionsPermissions

The required Permissions for the connector.

Name	Type	Description
customs	CustomPermissionDetails[]	Gets or sets the customs permissions required for the user to create connections.
licenses	string[]	Gets or sets the required licenses for the user to create connections.
resourceProvider	ConnectorDefinitionsResourceProvider[]	Gets or sets the resource provider permissions required for the user to create connections.
tenant	string[]	Gets or sets the required tenant permissions for the connector.

ConnectorDefinitionsResourceProvider

The resource provider details include the required permissions for the user to create connections. The user should have the required permissions(Read\Write, ..) in the specified scope ProviderPermissionsScope against the specified resource provider.

Name	Type	Description
permissionsDisplayText	string	Gets or sets the permissions description text.
provider	string	Gets or sets the provider name.
providerDisplayName	string	Gets or sets the permissions provider display name.
requiredPermissions	ResourceProviderRequiredPermissions	Required permissions for the connector resource provider that define in ResourceProviders. For more information about the permissions see here.
scope	ProviderPermissionsScope	The scope on which the user should have permissions, in order to be able to create connections.

createdByType

The type of identity that created the resource.

Name	Type	Description
Application	string
Key	string
ManagedIdentity	string
User	string

CustomizableConnectionsConfig

The UiConfig for 'Customizable' connector definition kind.

Name	Type	Description
templateSpecName	string	Gets or sets the template name. The template includes ARM templates that can be created by the connector, usually it will be the dataConnectors ARM templates.
templateSpecVersion	string	Gets or sets the template version.

CustomizableConnectorDefinition

Connector definition for kind 'Customizable'.

Name	Type	Description
etag	string	Etag of the azure resource
id	string	Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
kind	string: Customizable	The data connector kind
name	string	The name of the resource
properties.connectionsConfig	CustomizableConnectionsConfig	The UiConfig for 'Customizable' connector definition kind.
properties.connectorUiConfig	CustomizableConnectorUiConfig	The UiConfig for 'Customizable' connector definition kind.
properties.createdTimeUtc	string	Gets or sets the connector definition created date in UTC format.
properties.lastModifiedUtc	string	Gets or sets the connector definition last modified date in UTC format.
systemData	systemData	Azure Resource Manager metadata containing createdBy and modifiedBy information.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

CustomizableConnectorUiConfig

The UiConfig for 'Customizable' connector definition kind.

Name	Type	Description
availability	ConnectorDefinitionsAvailability	The exposure status of the connector to the customers.
connectivityCriteria	ConnectivityCriterion[]	Gets or sets the way the connector checks whether the connector is connected.
dataTypes	ConnectorDataType[]	Gets or sets the data types to check for last data received.
descriptionMarkdown	string	Gets or sets the connector description in markdown format.
graphQueries	GraphQuery[]	Gets or sets the graph queries to show the current data volume over time.
id	string	Gets or sets custom connector id. optional field.
instructionSteps	InstructionStep[]	Gets or sets the instruction steps to enable the connector.
isConnectivityCriteriasMatchSome	boolean	Gets or sets a value indicating whether to use 'OR'(SOME) or 'AND' between ConnectivityCriteria items.
logo	string	Gets or sets the connector logo to be used when displaying the connector within Azure Sentinel's connector's gallery. The logo value should be in SVG format.
permissions	ConnectorDefinitionsPermissions	The required Permissions for the connector.
publisher	string	Gets or sets the connector publisher name.
title	string	Gets or sets the connector blade title.

CustomPermissionDetails

The Custom permissions required for the connector.

Name	Type	Description
description	string	Gets or sets the custom permissions description.
name	string	Gets or sets the custom permissions name.

DataConnectorDefinitionKind

The kind of the data connector definitions

Name	Type	Description
Customizable	string

GraphQuery

The graph query to show the volume of data arriving into the workspace over time.

Name	Type	Description
baseQuery	string	Gets or sets the base query for the graph. The base query is wrapped by Sentinel UI infra with a KQL query, that measures the volume over time.
legend	string	Gets or sets the legend for the graph.
metricName	string	Gets or sets the metric name that the query is checking. For example: 'Total data receive'.

InstructionStep

Instruction steps to enable the connector.

Name	Type	Description
description	string	Gets or sets the instruction step description.
innerSteps	InstructionStep[]	Gets or sets the inner instruction steps details. Foe Example: instruction step 1 might contain inner instruction steps: [instruction step 1.1, instruction step 1.2].
instructions	InstructionStepDetails[]	Gets or sets the instruction step details.
title	string	Gets or sets the instruction step title.

InstructionStepDetails

Instruction step details, to be displayed in the Instructions steps section in the connector's page in Sentinel Portal.

Name	Type	Description
parameters	object	Gets or sets the instruction type parameters settings.
type	string	Gets or sets the instruction type name.

ProviderPermissionsScope

The scope on which the user should have permissions, in order to be able to create connections.

Name	Type	Description
ResourceGroup	string
Subscription	string
Workspace	string

ResourceProviderRequiredPermissions

Required permissions for the connector resource provider that define in ResourceProviders. For more information about the permissions see here.

Name	Type	Description
action	boolean	Gets or sets a value indicating whether the permission is custom actions (POST).
delete	boolean	Gets or sets a value indicating whether the permission is delete action (DELETE).
read	boolean	Gets or sets a value indicating whether the permission is read action (GET).
write	boolean	Gets or sets a value indicating whether the permission is write action (PUT or PATCH).

systemData

Metadata pertaining to creation and last modification of the resource.

Name	Type	Description
createdAt	string	The timestamp of resource creation (UTC).
createdBy	string	The identity that created the resource.
createdByType	createdByType	The type of identity that created the resource.
lastModifiedAt	string	The timestamp of resource last modification (UTC)
lastModifiedBy	string	The identity that last modified the resource.
lastModifiedByType	createdByType	The type of identity that last modified the resource.

Share via

Data Connector Definitions - Create Or Update

URI Parameters

Request Body

CustomizableConnectorDefinition

Responses

Security

azure_auth

Scopes

Examples

Create data connector definition

Sample request

Sample response

Definitions

CloudError

CloudErrorBody

ConnectivityCriterion

ConnectorDataType

ConnectorDefinitionsAvailability

ConnectorDefinitionsPermissions

ConnectorDefinitionsResourceProvider

createdByType

CustomizableConnectionsConfig

CustomizableConnectorDefinition

CustomizableConnectorUiConfig

CustomPermissionDetails

DataConnectorDefinitionKind

GraphQuery

InstructionStep

InstructionStepDetails

ProviderPermissionsScope

ResourceProviderRequiredPermissions

systemData

Additional resources