Data connector definitions reference for the Codeless Connector Platform

Artikkeli
12/19/2023

To create a data connector with the Codeless Connector Platform (CCP), use this document as a supplement to the Microsoft Sentinel REST API for Data Connector Definitions reference docs. Specifically this reference document expands on the following section:

connectorUiConfig - defines the visual elements and text displayed on the data connector page in Microsoft Sentinel.

For more information, see Create a codeless connector.

Data connector definitions - Create or update

Reference the Create Or Update operation in the REST API docs to find the latest stable or preview API version. Only the update operation requires the etag value.

PUT method

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

URI parameters

For more information about the latest API version, see Data Connector Definitions - Create or Update URI Parameters

Name	Description
dataConnectorDefinitionName	The data connector definition must be a unique name and is the same as the `name` parameter in the request body.
resourceGroupName	The name of the resource group, not case sensitive.
subscriptionId	The ID of the target subscription.
workspaceName	The name of the workspace, not the ID. Regex pattern: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
api-version	The API version to use for this operation.

Request body

The request body for creating a CCP data connector definition with the API has the following structure:

{
    "kind": "Customizable",
    "properties": {
        "connectorUIConfig": {}
    }
}

dataConnectorDefinition has the following properties:

Name	Required	Type	Description
Kind	True	String	`Customizable` for API polling data connector or `Static` otherwise
properties.connectorUiConfig	True	Nested JSON connectorUiConfig	The UI configuration properties of the data connector

Configure your connector's user interface

This section describes the configuration options available to customize the user interface of the data connector page.

The following screenshot shows a sample data connector page, highlighted with numbers that correspond to notable areas of the user interface.

Screenshot of a sample data connector page with sections labeled 1 through 9.

Each of the following elements of the connectorUiConfig section needed to configure the user interface correspond to the CustomizableConnectorUiConfig portion of the API.

Field	Required	Type	Description	Screenshot notable area #
title	True	string	Title displayed in the data connector page	1
id		string	Sets custom connector ID for internal usage
logo		string	Path to image file in SVG format. If no value is configured, a default logo is used.	2
publisher	True	string	The provider of the connector	3
descriptionMarkdown	True	string in markdown	A description for the connector with the ability to add markdown language to enhance it.	4
sampleQueries	True	Nested JSON sampleQueries	Queries for the customer to understand how to find the data in the event log.
graphQueries	True	Nested JSON graphQueries	Queries that present data ingestion over the last two weeks. Provide either one query for all of the data connector's data types, or a different query for each data type.	5
graphQueriesTableName		Sets the name of the table the connector inserts data to. This name can be used in other queries by specifying `{{graphQueriesTableName}}` placeholder in `graphQueries` and `lastDataReceivedQuery` values.
dataTypes	True	Nested JSON dataTypes	A list of all data types for your connector, and a query to fetch the time of the last event for each data type.	6
connectivityCriteria	True	Nested JSON connectivityCriteria	An object that defines how to verify if the connector is connected.	7
permissions	True	Nested JSON permissions	The information displayed under the Prerequisites section of the UI, which lists the permissions required to enable or disable the connector.	8
instructionSteps	True	Nested JSON instructions	An array of widget parts that explain how to install the connector, and actionable controls displayed on the Instructions tab.	9

connectivityCriteria

Field	Required	Type	Description
Type	True	String	One of the two following options: `HasDataConnectors` – this value is best for API polling data connectors such as the CCP. The connector is considered connected with at least one active connection. `isConnectedQuery` – this value is best for other types of data connectors. The connector is considered connected when the provided query returns data.
Value	True when type is `isConnectedQuery`	String	A query to determine if data is received within a certain time period. For example: `CommonSecurityLog \| where DeviceVendor == \"Vectra Networks\"\n\| where DeviceProduct == \"X Series\"\n \| summarize LastLogReceived = max(TimeGenerated)\n \| project IsConnected = LastLogReceived > ago(7d)"`

dataTypes

Array Value	Type	Description
name	String	A meaningful description for the`lastDataReceivedQuery`, including support for the `graphQueriesTableName` variable. Example: `{{graphQueriesTableName}}`
lastDataReceivedQuery	String	A KQL query that returns one row, and indicates the last time data was received, or no data if there are no results. Example: `{{graphQueriesTableName}}\n \| summarize Time = max(TimeGenerated)\n \| where isnotempty(Time)`

graphQueries

Defines a query that presents data ingestion over the last two weeks.

Provide either one query for all of the data connector's data types, or a different query for each data type.

Array Value	Type	Description
metricName	String	A meaningful name for your graph. Example: `Total data received`
legend	String	The string that appears in the legend to the right of the chart, including a variable reference. Example: `{{graphQueriesTableName}}`
baseQuery	String	The query that filters for relevant events, including a variable reference. Example: `TableName_CL \| where ProviderName == "myprovider"` or `{{graphQueriesTableName}}`

permissions

Array value	Type	Description
customs	String	Describes any custom permissions required for your data connection, in the following syntax: `{` `"name":`string`,` `"description":`string `}` Example: The customs value displays in Microsoft Sentinel Prerequisites section with a blue informational icon. In the GitHub example, this value correlates to the line GitHub API personal token Key: You need access to GitHub personal token...
licenses	ENUM	Defines the required licenses, as one of the following values: `OfficeIRM`,`OfficeATP`, `Office365`, `AadP1P2`, `Mcas`, `Aatp`, `Mdatp`, `Mtp`, `IoT` Example: The licenses value displays in Microsoft Sentinel as: License: Required Azure AD Premium P2
resourceProvider	resourceProvider	Describes any prerequisites for your Azure resource. Example: The resourceProvider value displays in Microsoft Sentinel Prerequisites section as: Workspace: read and write permission is required. Keys: read permissions to shared keys for the workspace are required.
tenant	array of ENUM values Example: `"tenant": [` `"GlobalADmin",` `"SecurityAdmin"` `]`	Defines the required permissions, as one or more of the following values: `"GlobalAdmin"`, `"SecurityAdmin"`, `"SecurityReader"`, `"InformationProtection"` Example: displays the tenant value in Microsoft Sentinel as: Tenant Permissions: Requires `Global Administrator` or `Security Administrator` on the workspace's tenant

Important

Microsoft recommends that you use roles with the fewest permissions. This helps improve security for your organization. Global Administrator is a highly privileged role that should be limited to emergency scenarios when you can't use an existing role.

resourceProvider

sub array value	Type	Description
provider	ENUM	Describes the resource provider, with one of the following values: - `Microsoft.OperationalInsights/workspaces` - `Microsoft.OperationalInsights/solutions` - `Microsoft.OperationalInsights/workspaces/datasources` - `microsoft.aadiam/diagnosticSettings` - `Microsoft.OperationalInsights/workspaces/sharedKeys` - `Microsoft.Authorization/policyAssignments`
providerDisplayName	String	A list item under Prerequisites that displays a red "x" or green checkmark when the requiredPermissions are validated in the connector page. Example, `"Workspace"`
permissionsDisplayText	String	Display text for Read, Write, or Read and Write permissions that should correspond to the values configured in requiredPermissions
requiredPermissions	`{` `"action":`Boolean`,` `"delete":`Boolean`,` `"read":`Boolean`,` `"write":`Boolean `}`	Describes the minimum permissions required for the connector.
scope	ENUM	Describes the scope of the data connector, as one of the following values: `"Subscription"`, `"ResourceGroup"`, `"Workspace"`

sampleQueries

array value	Type	Description
description	String	A meaningful description for the sample query. Example: `Top 10 vulnerabilities detected`
query	String	Sample query used to fetch the data type's data. Example: `{{graphQueriesTableName}}\n \| sort by TimeGenerated\n \| take 10`

Configure other link options

To define an inline link using markdown, use the following example.

{
   "title": "",
   "description": "Make sure to configure the machine's security according to your organization's security policy\n\n\n[Learn more >](https://aka.ms/SecureCEF)"
}

To define a link as an ARM template, use the following example as a guide:

{
   "title": "Azure Resource Manager (ARM) template",
   "description": "1. Click the **Deploy to Azure** button below.\n\n\t[![Deploy To Azure](https://aka.ms/deploytoazurebutton)]({URL to custom ARM template})"
}

instructionSteps

This section provides parameters that define the set of instructions that appear on your data connector page in Microsoft Sentinel and has the following structure:

"instructionSteps": [
    {
        "title": "",
        "description": "",
        "instructions": [
        {
            "type": "",
            "parameters": {}
        }
        ],
        "innerSteps": {}
    }
]

Array Property	Required	Type	Description
title		String	Defines a title for your instructions.
description		String	Defines a meaningful description for your instructions.
innerSteps		Array	Defines an array of inner instruction steps.
instructions	True	Array of instructions	Defines an array of instructions of a specific parameter type.

instructions

Displays a group of instructions, with various parameters and the ability to nest more instructionSteps in groups. Parameters defined here correspond

Type	Array property	Description
OAuthForm	OAuthForm	Connect with OAuth
Textbox	Textbox	This pairs with `ConnectionToggleButton`. There are 4 available types: `password` `text` `number` `email`
ConnectionToggleButton	ConnectionToggleButton	Trigger the deployment of the DCR based on the connection information provided through placeholder parameters. The following parameters are supported: `name` : mandatory `disabled` `isPrimary` `connectLabel` `disconnectLabel`
CopyableLabel	CopyableLabel	Shows a text field with a copy button at the end. When the button is selected, the field's value is copied.
InfoMessage	InfoMessage	Defines an inline information message.
InstructionStepsGroup	InstructionStepsGroup	Displays a group of instructions, optionally expanded or collapsible, in a separate instructions section.
InstallAgent	InstallAgent	Displays a link to other portions of Azure to accomplish various installation requirements.

OAuthForm

This component requires that the OAuth2 type is present in the auth property of the data connector template.

"instructions": [
{
  "type": "OAuthForm",
  "parameters": {
    "clientIdLabel": "Client ID",
    "clientSecretLabel": "Client Secret",
    "connectButtonLabel": "Connect",
    "disconnectButtonLabel": "Disconnect"
  }          
}
]

Textbox

Here are some examples of the Textbox type. These examples correspond to the parameters used in the example auth section in Data connectors reference for the Codeless Connector Platform. For each of the 4 types, each has label, placeholder, and name.

"instructions": [
{
  "type": "Textbox",
  "parameters": {
      {
        "label": "User name",
        "placeholder": "User name",
        "type": "text",
        "name": "username"
      }
  }
},
{
  "type": "Textbox",
  "parameters": {
      "label": "Secret",
      "placeholder": "Secret",
      "type": "password",
      "name": "password"
  }
}
]

ConnectionToggleButton

"instructions": [
{
  "type": "ConnectionToggleButton",
  "parameters": {
    "connectLabel": "toggle",
    "name": "toggle"
  }          
}
]

CopyableLabel

Example:

Screenshot of a copy value button in a field.

Sample code:

{
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}

Array Value	Required	Type	Description
fillWith		ENUM	Array of environment variables used to populate a placeholder. Separate multiple placeholders with commas. For example: `{0},{1}` Supported values: `workspaceId`, `workspaceName`, `primaryKey`, `MicrosoftAwsAccount`, `subscriptionId`
label	True	String	Defines the text for the label above a text box.
value	True	String	Defines the value to present in the text box, supports placeholders.
rows		Rows	Defines the rows in the user interface area. By default, set to 1.
wideLabel		Boolean	Determines a wide label for long strings. By default, set to `false`.

InfoMessage

Here's an example of an inline information message:

Screenshot of an inline information message.

In contrast, the following image shows an information message that's not inline:

Screenshot of an information message that's not inline.

Array Value	Type	Description
text	String	Define the text to display in the message.
visible	Boolean	Determines whether the message is displayed.
inline	Boolean	Determines how the information message is displayed. - `true`: (Recommended) Shows the information message embedded in the instructions. - `false`: Adds a blue background.

InstructionStepsGroup

Here's an example of an expandable instruction group:

Screenshot of an expandable, extra instruction group.

Array Value	Required	Type	Description
title	True	String	Defines the title for the instruction step.
description		String	Optional descriptive text.
canCollapseAllSections		Boolean	Determines whether the section is a collapsible accordion or not.
noFxPadding		Boolean	If `true`, reduces the height padding to save space.
expanded		Boolean	If `true`, shows as expanded by default.

For a detailed example, see the configuration JSON for the Windows DNS connector.

InstallAgent

Some InstallAgent types appear as a button, others appear as a link. Here are examples of both:

Screenshot of a link added as inline text.

Array Values	Required	Type	Description
linkType	True	ENUM	Determines the link type, as one of the following values: `InstallAgentOnWindowsVirtualMachine` `InstallAgentOnWindowsNonAzure` `InstallAgentOnLinuxVirtualMachine` `InstallAgentOnLinuxNonAzure` `OpenSyslogSettings` `OpenCustomLogsSettings` `OpenWaf` `OpenAzureFirewall` `OpenMicrosoftAzureMonitoring` `OpenFrontDoors` `OpenCdnProfile` `AutomaticDeploymentCEF` `OpenAzureInformationProtection` `OpenAzureActivityLog` `OpenIotPricingModel` `OpenPolicyAssignment` `OpenAllAssignmentsBlade` `OpenCreateDataCollectionRule`
policyDefinitionGuid	True when using `OpenPolicyAssignment` linkType.	String	For policy-based connectors, defines the GUID of the built-in policy definition.
assignMode		ENUM	For policy-based connectors, defines the assign mode, as one of the following values: `Initiative`, `Policy`
dataCollectionRuleType		ENUM	For DCR-based connectors, defines the type of data collection rule type as either `SecurityEvent`, or `ForwardEvent`.

Example data connector definition

The following example brings together some of the components defined in this article as a JSON body format to use with the Create Or Update data connector definition API.

For more examples of the connectorUiConfig review other CCP data connectors. Even connectors using the legacy CCP have valid examples of the UI creation.

{
    "kind": "Customizable",
    "properties": {
        "connectorUiConfig": {
          "title": "Example CCP Data Connector",
          "publisher": "My Company",
          "descriptionMarkdown": "This is an example of data connector",
          "graphQueriesTableName": "ExampleConnectorAlerts_CL",
          "graphQueries": [
            {
              "metricName": "Alerts received",
              "legend": "My data connector alerts",
              "baseQuery": "{{graphQueriesTableName}}"
            },   
           {
              "metricName": "Events received",
              "legend": "My data connector events",
              "baseQuery": "ASIMFileEventLogs"
            }
          ],
            "sampleQueries": [
            {
                "description": "All alert logs",
                "query": "{{graphQueriesTableName}} \n | take 10"
            }
          ],
          "dataTypes": [
            {
              "name": "{{graphQueriesTableName}}",
              "lastDataReceivedQuery": "{{graphQueriesTableName}} \n | summarize Time = max(TimeGenerated)\n | where isnotempty(Time)"
            },
             {
              "name": "ASIMFileEventLogs",
              "lastDataReceivedQuery": "ASIMFileEventLogs \n | summarize Time = max(TimeGenerated)\n | where isnotempty(Time)"
             }
          ],
          "connectivityCriteria": [
            {
              "type": "HasDataConnectors"
            }
          ],
          "permissions": {
            "resourceProvider": [
              {
                "provider": "Microsoft.OperationalInsights/workspaces",
                "permissionsDisplayText": "Read and Write permissions are required.",
                "providerDisplayName": "Workspace",
                "scope": "Workspace",
                "requiredPermissions": {
                  "write": true,
                  "read": true,
                  "delete": true
                }
              },
            ],
            "customs": [
              {
                "name": "Example Connector API Key",
                "description": "The connector API key username and password is required"
              }
            ] 
        },
          "instructionSteps": [
            {
              "title": "Connect My Connector to Microsoft Sentinel",
              "description": "To enable the connector provide the required information below and click on Connect.\n>",
              "instructions": [
               {
                  "type": "Textbox",
                  "parameters": {
                    "label": "User name",
                    "placeholder": "User name",
                    "type": "text",
                    "name": "username"
                  }
                },
                {
                  "type": "Textbox",
                  "parameters": {
                    "label": "Secret",
                    "placeholder": "Secret",
                    "type": "password",
                    "name": "password"
                  }
                },
                {
                  "type": "ConnectionToggleButton",
                  "parameters": {
                    "connectLabel": "toggle",
                    "name": "toggle"
                  }
                }
              ]
            }
          ]
        }
    }
}

Jaa