Deploy the Connector

Overview

This guide takes you from an empty Log Analytics workspace to Britive audit events arriving in Sentinel and confirmed queryable. Every command is given for both Azure CLI and Azure PowerShell — pick one and stay in it, since each step reuses variables set by the last. The Azure CLI path is shown first because it is the one Britive verified end to end; the portal path is included for the deployment step, where it works fine.

For how the integration works and what it puts in your workspace, read Microsoft Sentinel first.

Deployment is two distinct actions, in this order:

1. Deploy the solution template — creates the table, ingestion path, connector page, parsers, rules and workbook.
2. Connect the connector — supplies your Britive tenant URL and API token, which starts the polling.

Your API token is entered in the Connect step, not in the template, so it is never written to a deployment file.

Before You Begin

• A Log Analytics workspace with Microsoft Sentinel enabled. If the Sentinel breadcrumb still reads Add Microsoft Sentinel to a workspace, finish that first.
• Contributor on the resource group that holds the workspace.
• A Britive tenant on Audit Log API v2.
• The Britive Sentinel connector package, provided by Britive Customer Success — see step 1.
• One of the two command-line paths, signed in and pointed at the right subscription:
  • Azure CLI — az login, then az account set --subscription <id>.
  • Azure PowerShell (the Az module, 11.0 or later) — Connect-AzAccount, then Set-AzContext -Subscription <id>.

1. Get the Solution Package

The connector is not in the Sentinel Content Hub yet. Contact Britive Customer Success or Support to request the Britive Sentinel connector package. You will receive a versioned zip:

britiveSentinelConnector.json is the ARM template you deploy. Unzip it somewhere you can reach from the portal file picker or your shell.

2. Create the Britive Service Identity Token

The connector authenticates to Britive with a service identity token.

Full walkthrough: Getting Started with Service Identities.

Note your tenant URL as well. It looks like https://<tenant>.britive-app.com, with no path and no trailing slash.

3. Deploy the Solution Template

The ingestion resources must be created in the workspace’s region, which is often not the resource group’s default. Both paths below make you supply it explicitly — getting it wrong is the most common deployment mistake.

cd <where-you-unzipped-the-package>
ls britiveSentinelConnector.json      # should print the filename, not an error

RG=<your-resource-group>
WS=<your-workspace-name>

SUB=$(az account show --query id -o tsv)
WS_REGION=$(az monitor log-analytics workspace show -g "$RG" -n "$WS" --query location -o tsv)

echo "RG=$RG  WS=$WS  region=$WS_REGION  sub=$SUB"

az deployment group validate \
  --resource-group "$RG" \
  --template-file ./britiveSentinelConnector.json \
  --parameters workspaceName="$WS" location="$WS_REGION"

az deployment group create \
  --resource-group "$RG" \
  --name britive-sentinel-connector \
  --template-file ./britiveSentinelConnector.json \
  --parameters workspaceName="$WS" location="$WS_REGION"

--parameters workspaceName="$WS" location="$WS_REGION" \
             retentionInDays=90 \
             deployContent=true \
             deployAnalyticRules=true

az deployment group show -g "$RG" -n britive-sentinel-connector \
  --query "properties.outputs.{deployed:deployedRegion.value, workspace:workspaceRegion.value}"

Set-Location <where-you-unzipped-the-package>
Get-Item ./britiveSentinelConnector.json    # should print the file, not an error

$RG = '<your-resource-group>'
$WS = '<your-workspace-name>'

$SUB      = (Get-AzContext).Subscription.Id
$WsRegion = (Get-AzOperationalInsightsWorkspace -ResourceGroupName $RG -Name $WS).Location

"RG=$RG  WS=$WS  region=$WsRegion  sub=$SUB"

Test-AzResourceGroupDeployment `
  -ResourceGroupName $RG `
  -TemplateFile ./britiveSentinelConnector.json `
  -TemplateParameterObject @{ workspaceName = $WS; location = $WsRegion }

$deploy = @{
  ResourceGroupName       = $RG
  Name                    = 'britive-sentinel-connector'
  TemplateFile            = './britiveSentinelConnector.json'
  TemplateParameterObject = @{ workspaceName = $WS; location = $WsRegion }
}

New-AzResourceGroupDeployment @deploy

TemplateParameterObject = @{
  workspaceName       = $WS
  location            = $WsRegion
  retentionInDays     = 90
  deployContent       = $true
  deployAnalyticRules = $true
}

$out = (Get-AzResourceGroupDeployment -ResourceGroupName $RG -Name britive-sentinel-connector).Outputs

[pscustomobject]@{
  deployed  = $out['deployedRegion'].Value
  workspace = $out['workspaceRegion'].Value
}

az resource list -g "$RG" --query "[?starts_with(name,'ASI-') || contains(name,'britiveDCR1')].{name:name, type:type, location:location}" -o table

Get-AzResource -ResourceGroupName $RG |
  Where-Object { $_.Name -like 'ASI-*' -or $_.Name -like '*britiveDCR1*' } |
  Format-Table Name, ResourceType, Location

4. Connect the Connector

This is the step that starts ingestion.

The request body

Both command-line paths send the same JSON. Save it as connector.json in the directory you are working in, replace the four <...> placeholders, and leave the rest alone — it is the connector’s fixed configuration rather than settings to tune. The dce and dcr values come from the deployment outputs that the first step of each tab reads.

The one field you may want to change is queryParameters.filter. Empty means collect every audit event, which is the right starting point. Step 5 covers what a filter can say and how to check one before it starts dropping events.

{
  "kind": "RestApiPoller",
  "properties": {
    "connectorDefinitionName": "BritiveAuditLogsDefinition",
    "dataType": "BritiveAuditLogs_CL",
    "dcrConfig": {
      "streamName": "Custom-BritiveAuditLogs",
      "dataCollectionEndpoint": "<dce-from-deployment-outputs>",
      "dataCollectionRuleImmutableId": "<dcr-from-deployment-outputs>"
    },
    "auth": {
      "type": "APIKey",
      "ApiKey": "<your-britive-api-token>",
      "ApiKeyName": "Authorization",
      "ApiKeyIdentifier": "TOKEN"
    },
    "request": {
      "apiEndpoint": "https://<tenant>.britive-app.com/api/logs/v2",
      "httpMethod": "GET",
      "queryWindowInMin": 5,
      "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
      "startTimeAttributeName": "from",
      "endTimeAttributeName": "to",
      "retryCount": 3,
      "timeoutInSeconds": 60,
      "rateLimitQPS": 5,
      "paginatedCallsPerSecond": 5,
      "queryParameters": { "size": 100, "filter": "" },
      "headers": {
        "Accept": "application/json",
        "User-Agent": "Britive-Sentinel-Connector/1.0"
      }
    },
    "paging": {
      "pagingType": "NextPageToken",
      "nextPageParaName": "pageToken",
      "nextPageTokenJsonPath": "$.nextPageToken",
      "nextPageTokenResponseHeader": "next-page",
      "pagingInfoPlacement": "QueryString"
    },
    "response": {
      "eventsJsonPaths": ["$.records"],
      "format": "json"
    }
  }
}

The file holds your API token in plain text. Both tabs restrict it before you write the token into it and delete it as soon as the connector exists.

# If you deployed from the portal, the name was generated - list them and pick yours
az deployment group list -g "$RG" --query "[].name" -o tsv

DEP=britive-sentinel-connector

az deployment group show -g "$RG" -n "$DEP" \
  --query "properties.outputs.{dce:dataCollectionEndpoint.value, dcr:dataCollectionRuleImmutableId.value}"

pwd          # confirm where the file will go
umask 077    # so only you can read it

az rest --method put \
  --url "https://management.azure.com/subscriptions/$SUB/resourceGroups/$RG/providers/Microsoft.OperationalInsights/workspaces/$WS/providers/Microsoft.SecurityInsights/dataConnectors/BritiveAuditLogsConnection?api-version=2024-01-01-preview" \
  --body @connector.json \
  --headers "Content-Type=application/json"

rm connector.json

# If you deployed from the portal, the name was generated - list them and pick yours
Get-AzResourceGroupDeployment -ResourceGroupName $RG | Select-Object -ExpandProperty DeploymentName

$DEP = 'britive-sentinel-connector'
$out = (Get-AzResourceGroupDeployment -ResourceGroupName $RG -Name $DEP).Outputs

[pscustomobject]@{
  dce = $out['dataCollectionEndpoint'].Value
  dcr = $out['dataCollectionRuleImmutableId'].Value
}

(Get-Location).Path                     # confirm where the file will go
New-Item -ItemType File ./connector.json

# Windows
icacls .\connector.json /inheritance:r /grant:r "$($env:USERNAME):(R,W)"

# macOS or Linux
chmod 600 ./connector.json

$uri = "/subscriptions/$SUB/resourceGroups/$RG/providers/Microsoft.OperationalInsights/workspaces/$WS/providers/Microsoft.SecurityInsights/dataConnectors/BritiveAuditLogsConnection?api-version=2024-01-01-preview"

$response = Invoke-AzRestMethod -Method PUT -Path $uri -Payload (Get-Content ./connector.json -Raw)

$response.StatusCode
$response.Content

Remove-Item ./connector.json

Azure stores the token as a protected value and will not return it if you read the connector back, so a GET on the same URL is a safe way to confirm the configuration landed. To disconnect later, call the same URL with az rest --method delete or Invoke-AzRestMethod -Method DELETE.

5. Filter What Is Collected (Optional)

Skip this if you want every audit event — that is the default and the recommended starting point.

Set queryParameters.filter in the connection body and Britive applies it server-side, before the events are sent. Two reasons to use it: cutting high-volume automation noise, and keeping a category of event out of the workspace entirely because policy says it must not leave Britive.

"queryParameters": { "size": 100, "filter": "event.eventType neq environment.scan" }

Syntax

A clause is <field> <operator> <value>. Clauses combine with and.

Filterable fields. Only these; anything else is rejected with HTTP 400:

event.consumer, client.country and everything under additionalInfo appear on records but are not filterable.

Examples

Every filter below was run against a live Britive tenant and accepted. Replace obviously site-specific values (AWS Production, @contoso.com) with your own.

Reduce volume — keep everything except the noise:

Collect one category only — name what you want instead:

Scope by who acted:

Scope by where it came from:

Scope by what was touched:

Combinations. Every clause must hold, and the same field may appear more than once:

Change or Remove a Filter Later

A filter takes effect on the next poll. Editing it does not restart collection or affect events already in the workspace, and events dropped while the old filter was in place stay dropped.

az rest --method put \
  --url "https://management.azure.com/subscriptions/$SUB/resourceGroups/$RG/providers/Microsoft.OperationalInsights/workspaces/$WS/providers/Microsoft.SecurityInsights/dataConnectors/BritiveAuditLogsConnection?api-version=2024-01-01-preview" \
  --body @connector.json \
  --headers "Content-Type=application/json"

az rest --method get \
  --url "https://management.azure.com/subscriptions/$SUB/resourceGroups/$RG/providers/Microsoft.OperationalInsights/workspaces/$WS/providers/Microsoft.SecurityInsights/dataConnectors/BritiveAuditLogsConnection?api-version=2024-01-01-preview" \
  --query "properties.request.queryParameters"

$uri = "/subscriptions/$SUB/resourceGroups/$RG/providers/Microsoft.OperationalInsights/workspaces/$WS/providers/Microsoft.SecurityInsights/dataConnectors/BritiveAuditLogsConnection?api-version=2024-01-01-preview"

$response = Invoke-AzRestMethod -Method PUT -Path $uri -Payload (Get-Content ./connector.json -Raw)
$response.StatusCode

$current = Invoke-AzRestMethod -Method GET -Path $uri
($current.Content | ConvertFrom-Json).properties.request.queryParameters

Verify

Allow up to 15 minutes after connecting, then run these in Logs. Run all four — the second one is the check that catches the failure mode that looks like success.

BritiveAuditLogs_CL
| summarize Events = count(), Earliest = min(TimeGenerated), Latest = max(TimeGenerated)

BritiveAuditLogs_CL
| summarize Total      = count(),
            NullActor  = countif(isempty(ActorName)),
            NullType   = countif(isempty(EventType)),
            NullKey    = countif(isempty(EventKey)),
            NullTenant = countif(isempty(BritiveTenantId))

BritiveAuditLogs_CL
| extend Lag = ingestion_time() - TimeGenerated
| summarize avg(Lag), max(Lag), percentile(Lag, 95)

BritiveAuditLogs
| project TimeGenerated, EventType, ActorName, ProfileName, IsNonHumanIdentity, Success
| sort by TimeGenerated desc
| take 20

Enable the detections

Analytic rules deploy disabled so nothing starts paging your on-call before you have reviewed it. In Sentinel, go to Analytics → Rule templates, find the Britive rules, and create and enable the ones you want.

Enable BritiveNoAuditDataReceived first. It is the only thing that will tell you when an expired token silently stops ingestion.

Confirm which version you are running

az deployment group show -g "$RG" -n britive-sentinel-connector \
  --query properties.outputs.solutionVersion.value -o tsv

(Get-AzResourceGroupDeployment -ResourceGroupName $RG -Name britive-sentinel-connector).Outputs['solutionVersion'].Value

Troubleshoot

Clean Up

Disconnect the connector first, then remove the resources. Deleting the ARM deployment record does not delete what it created.

az deployment group delete --resource-group "$RG" --name britive-sentinel-connector

Remove-AzResourceGroupDeployment -ResourceGroupName $RG -Name britive-sentinel-connector

az resource list -g "$RG" --query "[?starts_with(name,'ASI-') || contains(name,'britiveDCR1')].id" -o tsv \
  | xargs -r -n1 az resource delete --ids

Get-AzResource -ResourceGroupName $RG |
  Where-Object { $_.Name -like 'ASI-*' -or $_.Name -like '*britiveDCR1*' } |
  ForEach-Object { Remove-AzResource -ResourceId $_.ResourceId -Force }

Next Steps