Deploy the Connector

Overview

This guide takes you from an empty Log Analytics workspace to Britive audit events arriving in Sentinel and confirmed queryable. It covers both the Azure portal and the Azure CLI at every step, so you can click through it once or script it for repeat deployments.

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

Deployment is two distinct actions, in this order:

Deploy the solution template — creates the table, ingestion path, connector page, parsers, rules and workbook.
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.
Azure CLI if you are taking the CLI path, signed in with az login.

Create a dedicated service identity for the connector and use its token. Do not reuse an administrator token — you cannot scope it, and rotating it breaks unrelated things.

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
- INSTALL.md
- WHATS-INCLUDED.md
- VERSION

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

Keep the version number. It is the first thing Support will ask for, and it is recoverable later from the deployment itself — see Confirm which version you are running.

2. Create the Britive API Token

The connector authenticates to Britive with a service identity token.

Create a service identity

In the Britive console, go to Identity Management → Service Identities → Add Service Identity. Name it for this purpose, for example sentinel-connector.

Grant it audit log read access

Assign the service identity a policy that permits reading audit logs. Follow the same tag → policy model you use for any other identity.

Generate the token

On the service identity, open Tokens → Generate Token. Copy it once — you will not be able to view it again. Store it in your secret manager until you paste it into Sentinel.

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.

Find the workspace region

Open your Log Analytics workspace and note the Location shown on the Overview page. You will need it in a moment.

Open the custom template deployment

In the portal, search for Deploy a custom template, then choose Build your own template in the editor.

Load the template

Select Load file, choose britiveSentinelConnector.json from the unzipped package, then select Save.

Fill in the parameters

Choose the subscription and the resource group holding your workspace, then set the parameters below. Set Location to the workspace region from the first step, not the resource group’s default.

Parameter	Value
Workspace Name	The workspace name, not its resource ID
Location	The workspace’s region
Retention In Days	`90` by default — audit data usually outlives operational logs
Deploy Content	`true` — parsers, hunting queries, workbook
Deploy Analytic Rules	`true` — rules are created disabled regardless

Deploy

Select Review + create, then Create. Deployment takes a few minutes.

Check the region outputs

When it finishes, open the deployment’s Outputs tab and confirm deployedRegion and workspaceRegion match. If they differ, the ingestion path is in the wrong region — redeploy with the correct Location.

Look up the workspace region, then pass it in when you deploy.

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

WS_REGION=$(az monitor log-analytics workspace show \
  --resource-group "$RG" --name "$WS" --query location -o tsv)

echo "Workspace region: $WS_REGION"

Validate first — this checks the template without creating anything:

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

Then deploy:

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

Optional parameters, with their defaults:

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

Confirm both regions agree:

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

A failed deployment can still leave resources behind. Azure does not roll everything back on error, so check what exists before retrying:

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

4. Connect the Connector

This is the step that starts ingestion.

Open Data connectors

In Microsoft Sentinel, go to Data connectors. In the Defender portal, this is Microsoft Sentinel → Configurations → Data connectors.

Find the connector

Search for Britive Audit Logs and select Open connector page.

Enter your Britive details

Field	Value
Tenant URL	`https://<tenant>.britive-app.com` — must begin with `https://`, no path, no trailing slash
API Token	The service identity token from step 2

Connect

Select Connect. The connector page status changes to Connected.

Connected does not yet mean data. The first poll covers a five-minute window, and Log Analytics adds its own ingestion delay. Allow about 10 minutes before checking the table.

Create the connection with az rest. You save the request body to a file, fill in four values, and run one command — no shell-specific scripting, so this works the same in Bash, Zsh, PowerShell and Cloud Shell.

Read the two values the deployment returned

az deployment group show -g <your-resource-group> -n britive-sentinel-connector \
  --query "properties.outputs.{dce:dataCollectionEndpoint.value, dcr:dataCollectionRuleImmutableId.value}"

If you deployed from the portal instead, the deployment name was generated for you — list them with az deployment group list -g <your-resource-group> --query "[].name" -o tsv and use the right one.

Save the request body

Save the JSON below as connector.json in a directory only you can read. Replace the four <...> placeholders and change nothing else — the remaining values are the connector’s fixed configuration, not settings to tune.

connector.json

{
  "kind": "RestApiPoller",
  "properties": {
    "connectorDefinitionName": "BritiveAuditLogsDefinition",
    "dataType": "BritiveAuditLogs_CL",
    "dcrConfig": {
      "streamName": "Custom-BritiveAuditLogs",
      "dataCollectionEndpoint": "<dce-from-previous-step>",
      "dataCollectionRuleImmutableId": "<dcr-from-previous-step>"
    },
    "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 },
      "headers": {
        "Accept": "application/json",
        "User-Agent": "Britive-Sentinel-Connector/1.0"
      }
    },
    "paging": {
      "pagingType": "NextPageToken",
      "nextPageParaName": "pageToken",
      "nextPageTokenJsonPath": "$.nextPageToken",
      "nextPageTokenResponseHeader": "Next-Page-Token",
      "pagingInfoPlacement": "QueryString"
    },
    "response": {
      "eventsJsonPaths": ["$.records"],
      "format": "json"
    }
  }
}

Create the connection

Fill in your subscription ID, resource group and workspace name. Keep the URL in quotes — the ? in ?api-version= is a wildcard in most shells if left unquoted.

az rest --method put \
  --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.OperationalInsights/workspaces/<your-workspace-name>/providers/Microsoft.SecurityInsights/dataConnectors/BritiveAuditLogsConnection?api-version=2024-01-01-preview" \
  --body @connector.json \
  --headers "Content-Type=application/json"

az account show --query id -o tsv prints your subscription ID if you need it.

A successful call echoes the created resource back, with "kind": "RestApiPoller".

Delete the body file

It holds your API token in plain text.

rm 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 --method delete.

Verify

Allow about 10 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.

Confirm events are arriving

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

You want a non-zero count and a Latest within the last 15 minutes.

Confirm the columns are populated

A schema mismatch produces rows full of blanks while the connector still reports Connected. This is the check that catches it.

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

Every null count should be 0. EventId being empty is expected and correct — Britive returns no server-side event identifier.

Confirm TimeGenerated is event time

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

Expect a lag of roughly 10 minutes. A lag near zero means TimeGenerated is holding ingestion time rather than the time the event happened in Britive — redeploy the template.

Confirm the parser works

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

If this fails with an unknown-function error, the parsers did not deploy — check that you left Deploy Content set to true.

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

Troubleshoot

Symptom	Likely cause	Fix
Connector not in the gallery	The connector definition failed to deploy, or you are in a different workspace	Confirm the deployment succeeded and that you opened Sentinel on the workspace you targeted
Connect fails immediately	Tenant URL or token wrong	Tenant URL must be `https://<tenant>.britive-app.com` with no path. Regenerate the token if unsure
Status Connected, no data after 20 minutes	Wrong tenant URL, or the tenant is genuinely quiet	Generate activity in Britive — log in, check out a profile — and re-check. Confirm the token’s identity has audit log read access
Data arrives, columns are blank	The connector version predates a change in the Britive API	Contact Britive Support with your package version — the connector needs an update
`TimeGenerated` looks like ingestion time	The transform did not deploy intact	Redeploy the template
Deployment fails on the table	`BritiveAuditLogs_CL` already exists with a different schema	Delete the table under Log Analytics workspace → Tables and redeploy
`InvalidResourceLocation` on the endpoint	A previous attempt created it in another region	Delete the stray `britive-audit-dce-*` resource and redeploy with the workspace’s region
Parser queries fail with unknown function	Content was skipped at deployment	Redeploy with `deployContent=true`
Ingestion stopped with no error anywhere	Token expired or was revoked — the connector still reports Connected	Generate a new token and reconnect. Enable `BritiveNoAuditDataReceived` so this surfaces automatically

Clean Up

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

Disconnect

On the Britive Audit Logs connector page, select Disconnect. Or from the CLI, az rest --method delete against the connector URL from step 4.

Remove the deployment record

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

Remove the resources

Delete the data collection endpoint and rule, the Britive analytic rules and saved searches, and the BritiveAuditLogs_CL table under Log Analytics workspace → Tables.

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

Next Steps

Recommended Alerts

Build a broader detection catalog on Britive audit events.

How It Works

The integration pattern, the table schema, and the limitations to plan around.

More Operations Integrations

ITSM, incident management, and operational workflows.

Last updated on August 10, 2026