Scan Active Directory

Overview

This guide configures an Active Directory scan using the Britive Access Broker. The scan collects all AD users and groups and writes a structured JSON payload to Britive Resource Manager — making AD principals available as targets for JIT access profiles.

Once a scan is configured and run:

• AD users appear as identities in Resource Manager
• AD security groups appear as groups, with direct member lists
• Britive can enforce JIT policies that reference real AD group memberships

The scan does not modify anything in AD — it is read-only.

Before You Begin

• The Britive Access Broker is running (see Getting Started)
• The broker service account (gMSA) is a domain user — any authenticated domain account can read AD objects by default; no additional delegation is required for scanning
• RSAT Active Directory module installed on the broker host

How It Works

The broker executes a PowerShell scan script on a schedule or on demand. The script:

1. Loads the ActiveDirectory module
2. Queries all users (Get-ADUser) and groups (Get-ADGroup) in the domain
3. For each group, enumerates direct members (user objects only)
4. Builds a JSON payload matching the Britive Resource Manager schema
5. Writes the JSON to the path supplied by BROKER_INJECTED_SCAN_OUTPUT_PATH — an environment variable the broker injects at runtime

Britive reads the output file and ingests the identities and groups. No data leaves the customer network except through the broker’s existing outbound connection to Britive.

Identity resolution: User SamAccountName is used as the identity id. Group member lists also reference SamAccountName, so attribute_resolution.group_membership = "id" in the output metadata resolves memberships correctly.

Scan Script

The full script is in the access-broker-examples repository. Key sections:

Validate and load:

if (-not $env:BROKER_INJECTED_SCAN_OUTPUT_PATH) {
    throw "BROKER_INJECTED_SCAN_OUTPUT_PATH environment variable is not set."
}
Import-Module ActiveDirectory -ErrorAction Stop
$domain = Get-ADDomain

Collect users — SamAccountName becomes the identity id:

$adUsers = Get-ADUser -Filter * -Properties Mail, GivenName, Surname, UserPrincipalName, Enabled

foreach ($user in $adUsers) {
    $identities += @{
        id       = $user.SamAccountName
        name     = $user.SamAccountName
        type     = "User"
        is_active = [bool]$user.Enabled
        attributes = @{ email = $user.Mail; ... }
    }
}

Collect groups with direct member lists:

foreach ($group in (Get-ADGroup -Filter *)) {
    $members = Get-ADGroupMember -Identity $group.ObjectGUID |
        Where-Object { $_.objectClass -eq "user" } |
        ForEach-Object { $_.SamAccountName }

    $groups += @{ id = $group.Name; members = $members }
}

Write output to broker-injected path:

$output | ConvertTo-Json -Depth 10 | Out-File $env:BROKER_INJECTED_SCAN_OUTPUT_PATH -Encoding utf8 -Force

Output Schema

{
  "data": {
    "identities": [
      {
        "id": "jdoe",
        "name": "jdoe",
        "type": "User",
        "is_active": true,
        "attributes": {
          "email": "jdoe@contoso.com",
          "samaccountname": "jdoe",
          "user_principal_name": "jdoe@contoso.com"
        }
      }
    ],
    "groups": [
      {
        "id": "Server-Admins",
        "name": "Server-Admins",
        "type": "User group",
        "members": ["jdoe", "bsmith"]
      }
    ],
    "permissions": [],
    "permission_mapping": []
  },
  "metadata": {
    "resource_type": "ActiveDirectory",
    "attribute_resolution": {
      "group_membership": "id"
    }
  }
}

groups.members contains SamAccountName values that match identities[].id. Setting attribute_resolution.group_membership = "id" tells Britive to resolve membership using the id field rather than name.

Configure in Britive

# Resource type — defines the ActiveDirectory class with scan enabled
resource "britive_resource_manager_resource_type" "ad" {
name        = "ActiveDirectory"
description = "Active Directory domain"

parameters {
  param_name   = "domain"
  param_type   = "string"
  is_mandatory = true
}
parameters {
  param_name   = "domain_controller"
  param_type   = "string"
  is_mandatory = false
}
}

# Resource label — categorize AD resources by environment
resource "britive_resource_manager_resource_label" "env" {
name        = "environment"
description = "Deployment environment"
label_color = "#2563eb"

values { name = "Production";  description = "Production domain" }
values { name = "Staging";     description = "Staging domain" }
}

# Resource — the AD domain instance to scan
resource "britive_resource_manager_resource" "contoso" {
name          = "contoso-ad"
description   = "Contoso Active Directory"
resource_type = britive_resource_manager_resource_type.ad.name

parameter_values = {
  domain             = "contoso.com"
  domain_controller  = "dc01.contoso.com"
}

resource_labels = {
  environment = "Production"
}
}

Verify

After the first scan completes:

# On the broker host: verify the scan output file was written
$outputDir = "C:\Program Files (x86)\Britive Inc\Britive Broker\scan-output"
Get-ChildItem $outputDir | Sort-Object LastWriteTime -Descending | Select-Object -First 5

In the Britive console:

Troubleshoot