Edit

Tutorial: Manage advanced connector policies programmatically

Advanced connector policies (ACP) govern connector usage with a strict allowlist that blocks connectors by default. In addition to the Power Platform admin center experience, you can manage ACP with code by using the Power Platform API and the administration (Admin) SDKs. Automating ACP is useful when you standardize governance across many environment groups, replicate a baseline policy between groups, or manage policies as part of a deployment pipeline.

In this tutorial, learn how to:

  1. Authenticate using Power Platform API.
  2. Understand the ACP policy shape.
  3. Create a policy and add it to an environment group.
  4. Enable an individual connector action.
  5. Apply or update a policy on a single environment.
  6. Copy a policy from one environment group to another.
  7. Remove ACP from an environment group.

Advanced connector policies are exposed through the governance/ruleBasedPolicies operations of the Power Platform API. A policy contains one or more rule sets; the rule set with the ID ConnectorManagement holds the ACP connector allowlist. All examples in the article use API version 2024-10-01.

Prerequisites

Step 1. Authenticate using Power Platform API

All examples authenticate with your app registration's client ID, following the guidance in Authentication. The following examples sign in interactively as the current user. To run unattended as a service principal, see the confidential client flow in the Authentication article and assign the service principal an RBAC role.

# Requires the MSAL.PS module: Install-Module MSAL.PS -Scope CurrentUser
Import-Module "MSAL.PS"

$clientId  = "<application (client) ID of your app registration>"
$apiBaseUrl = "https://api.powerplatform.com"
$apiVersion = "2024-10-01"

# Sign in interactively and request a token for the Power Platform API
$auth = Get-MsalToken -ClientId $clientId -Scope "https://api.powerplatform.com/.default" -Interactive
$headers = @{ Authorization = "Bearer $($auth.AccessToken)" }

Step 2. Understand the ACP policy shape

An advanced connector policy is a rule-based policy that contains a rule set with the ID ConnectorManagement. That rule set carries a version and its inputs hold an AllowedConnectorList, where each entry allows a connector and sets how its actions and connection types are governed:

{
  "name": "Contoso ACP baseline",
  "ruleSets": [
    {
      "id": "ConnectorManagement",
      "version": "1.0",
      "inputs": {
        "AllowedConnectorList": [
          {
            "AllowedConnector": "/providers/Microsoft.PowerApps/apis/shared_office365",
            "AllowedActionsMode": "AllAllowed",
            "AllowedConnectionTypesMode": "AllAllowed"
          },
          {
            "AllowedConnector": "/providers/Microsoft.PowerApps/apis/shared_commondataserviceforapps",
            "AllowedActionsMode": "SomeAllowed",
            "AllowedActions": ["GetItem", "CreateRecord"],
            "AllowedConnectionTypesMode": "AllAllowed"
          }
        ]
      }
    }
  ]
}

Keep the following semantics in mind:

  • A connector that isn't in AllowedConnectorList is blocked (default-deny).
  • Each entry sets AllowedActionsMode. AllAllowed permits every action on the connector. SomeAllowed restricts the connector to the actions listed in the entry's AllowedActions array. Step 4 shows how to add an action and set this mode.
  • AllowedConnectionTypesMode governs which connection types are allowed and follows the same AllAllowed pattern.
  • Include the rule set's version when you create or update a policy. Read it from an existing policy and preserve the value that the service returns.

Tip

The exact value of AllowedConnector is the connector's resource identifier. The most reliable way to learn the shape for connectors already in your tenant is to read an existing policy first (Step 4 shows how) or use the connector catalog (described next), then mirror that shape when you create or update policies.

Find connector and action IDs with the connector catalog

To discover which connectors and actions you can allow, use the Connector Catalog API. It lists the connectors available in an environment, along with the identifiers you place in AllowedConnector and AllowedActions.

Note

The connector catalog operations require an environment ID in the path and an OData $filter that specifies the same environment - for example, $filter=environment eq '<environmentId>'. Both are required.

$environmentId = "<environment ID>"
$filter = [uri]::EscapeDataString("environment eq '$environmentId'")

# List connectors available in the environment
$connectors = Invoke-RestMethod -Method Get `
    -Uri "$apiBaseUrl/connectivity/environments/$environmentId/connectors?`$filter=$filter&api-version=$apiVersion" `
    -Headers $headers
$connectors.value | Select-Object name, @{ n = "displayName"; e = { $_.properties.displayName } }

# Get a single connector by ID (the connector's name, such as shared_office365)
$connectorId = "shared_office365"
$connector = Invoke-RestMethod -Method Get `
    -Uri "$apiBaseUrl/connectivity/environments/$environmentId/connectors/$connectorId?`$filter=$filter&api-version=$apiVersion" `
    -Headers $headers
$connector.id   # full resource path to use as AllowedConnector

Use the connector's id (its full resource path, such as /providers/Microsoft.PowerApps/apis/shared_office365) as the AllowedConnector value, and the connector's operation IDs as the values in AllowedActions. You can access the same catalog through the connectivity namespace of the Admin SDKs.

Step 3. Create a policy and add it to an environment group

Adding ACP to an environment group is a two-part operation: create the policy, then assign it to the group. The create call returns the new policy id, which you use in the assignment call.

To assign the policy to the whole group, send an assignment request with an empty body ({}). Every environment in the group inherits the policy and stays in sync with it.

$environmentGroupId = "<environment group ID>"

# 1. Create the policy with a ConnectorManagement rule set
$policyBody = @{
    name     = "Contoso ACP baseline"
    ruleSets = @(
        @{
            id      = "ConnectorManagement"
            version = "1.0"
            inputs  = @{
                AllowedConnectorList = @(
                    @{
                        AllowedConnector           = "/providers/Microsoft.PowerApps/apis/shared_office365"
                        AllowedActionsMode         = "AllAllowed"
                        AllowedConnectionTypesMode = "AllAllowed"
                    }
                )
            }
        }
    )
} | ConvertTo-Json -Depth 10

$policy = Invoke-RestMethod -Method Post `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies?api-version=$apiVersion" `
    -Headers $headers -ContentType "application/json" -Body $policyBody
Write-Host "Created policy $($policy.id)"

# 2. Assign the policy to the environment group (empty body = whole group)
Invoke-RestMethod -Method Post `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$($policy.id)/environmentGroups/$environmentGroupId/assignments?api-version=$apiVersion" `
    -Headers $headers -ContentType "application/json" -Body "{}"
Write-Host "Assigned policy $($policy.id) to group $environmentGroupId"

Step 4. Enable an individual connector action

To allow only specific actions on a connector, set its AllowedActionsMode to SomeAllowed and list the permitted actions in AllowedActions. This example adds an action, such as a hidden action that isn't selectable in the admin center, to a connector's allowlist and sets the connector to SomeAllowed. Read the policy, update the connector entry, and send the updated rule set back by using patch. Patch updates a rule set by ID and leaves the policy's other rule sets untouched.

$policyId     = "<policy ID>"
$connectorId  = "shared_commondataserviceforapps"   # last segment of AllowedConnector
$actionToAdd  = "aibuilderpredict_customprompt"

# 1. Read the current policy
$policy = Invoke-RestMethod -Method Get `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$policyId`?api-version=$apiVersion" `
    -Headers $headers

# 2. Find the ConnectorManagement rule set and the connector entry
$ruleSet = $policy.ruleSets | Where-Object { $_.id -eq "ConnectorManagement" }
$entry = $ruleSet.inputs.AllowedConnectorList |
    Where-Object { ($_.AllowedConnector -split "/")[-1] -eq $connectorId }

# 3. Restrict the connector to specific actions: add the action and set SomeAllowed
if ($entry) {
    $actions = @()
    if ($entry.PSObject.Properties.Name -contains "AllowedActions") { $actions = @($entry.AllowedActions) }
    if ($actions -notcontains $actionToAdd) { $actions += $actionToAdd }
    $entry | Add-Member -NotePropertyName AllowedActions -NotePropertyValue $actions -Force
    $entry.AllowedActionsMode = "SomeAllowed"

    # 4. Patch only the modified rule set back to the policy
    $patchBody = @{ name = $policy.name; ruleSets = @($ruleSet) } | ConvertTo-Json -Depth 10
    Invoke-RestMethod -Method Patch `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$policyId`?api-version=$apiVersion" `
        -Headers $headers -ContentType "application/json" -Body $patchBody
    Write-Host "Set '$connectorId' to SomeAllowed with '$actionToAdd' in policy $policyId"
}

Step 5. Apply or update a policy on a single environment

You can target a policy at a single environment instead of an environment group. This approach is useful for high-risk, pilot, or regulated environments. Assign the policy to the environment, and use the same patch pattern from Step 4 to modify it later. Each environment supports one effective ACP policy.

$policyId       = "<policy ID>"
$environmentId  = "<environment ID>"

# Assign the policy directly to the environment
Invoke-RestMethod -Method Post `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$policyId/environments/$environmentId/assignments?api-version=$apiVersion" `
    -Headers $headers -ContentType "application/json" -Body "{}"
Write-Host "Assigned policy $policyId to environment $environmentId"

Step 6. Copy a policy from one environment group to another

When you replicate a governance baseline to another group, choose how much to copy by using the CopyAllRules flag:

  • CopyAllRules = true: Create a new policy from all of the source group's rule sets and assign it to the target group. The target group's governance becomes an independent copy of the source.
  • CopyAllRules = false: Extract only the ConnectorManagement rule set from the source policy and merge it into the target group's existing policy. The patch operation adds or updates the rule set by ID, so the target group keeps its other rules.
$sourceGroupId = "<source environment group ID>"
$targetGroupId = "<target environment group ID>"
$CopyAllRules  = $true

# 1. Find and read the policy assigned to the source group
$sourceAssignments = Invoke-RestMethod -Method Get `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies/environmentGroups/$sourceGroupId/assignments?api-version=$apiVersion" `
    -Headers $headers
$sourcePolicyId = $sourceAssignments.value[0].policyId
$source = Invoke-RestMethod -Method Get `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$sourcePolicyId`?api-version=$apiVersion" `
    -Headers $headers

if ($CopyAllRules) {
    # 2a. Copy ALL rule sets into a new policy and assign it to the target group
    $copyBody = @{ name = "$($source.name) (copy)"; ruleSets = $source.ruleSets } | ConvertTo-Json -Depth 20
    $copy = Invoke-RestMethod -Method Post `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies?api-version=$apiVersion" `
        -Headers $headers -ContentType "application/json" -Body $copyBody
    Invoke-RestMethod -Method Post `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$($copy.id)/environmentGroups/$targetGroupId/assignments?api-version=$apiVersion" `
        -Headers $headers -ContentType "application/json" -Body "{}"
    Write-Host "Copied all rules to policy $($copy.id) and assigned it to group $targetGroupId"
}
else {
    # 2b. Merge ONLY the ConnectorManagement rule into the target group's existing policy
    $sourceCm = $source.ruleSets | Where-Object { $_.id -eq "ConnectorManagement" }

    $targetAssignments = Invoke-RestMethod -Method Get `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies/environmentGroups/$targetGroupId/assignments?api-version=$apiVersion" `
        -Headers $headers
    $targetPolicyId = $targetAssignments.value[0].policyId
    $targetPolicy = Invoke-RestMethod -Method Get `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$targetPolicyId`?api-version=$apiVersion" `
        -Headers $headers

    # Patch adds or updates the ConnectorManagement rule set by ID, keeping the target's other rules
    $patchBody = @{ name = $targetPolicy.name; ruleSets = @($sourceCm) } | ConvertTo-Json -Depth 20
    Invoke-RestMethod -Method Patch `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$targetPolicyId`?api-version=$apiVersion" `
        -Headers $headers -ContentType "application/json" -Body $patchBody
    Write-Host "Merged the ConnectorManagement rule into target policy $targetPolicyId"
}

Step 6b. Copy a policy from one environment group to another including connector actions

When you replicate a governance baseline to another group, choose how much to copy by using the CopyAllRules flag:

  • CopyAllRules = true: Create a new policy from all of the source group's rule sets and assign it to the target group. The target group's governance becomes an independent copy of the source.
  • CopyAllRules = false: Extract only the ConnectorManagement rule set from the source policy and merge it into the target group's existing policy. The patch operation adds or updates the rule set by ID, so the target group keeps its other rules.
$tenantId   = "<tenant-id>"
$apiBaseUrl = "https://api.powerplatform.com"
$apiVersion = "2024-10-01"

$sourceGroupId = "<source environment group ID>"
$targetGroupId = "<target environment group ID>"
$CopyAllRules  = $true

# ---------- Helpers ----------
function Get-Prop($obj, $name) {
    if ($null -ne $obj -and $obj.PSObject.Properties.Name -contains $name) { return $obj.$name }
    return $null
}

function Get-ConnectorKey($entry) { (([string]$entry.AllowedConnector) -split "/")[-1].ToLowerInvariant() }

function Get-ConnectorManagement($policy) {
    $policy.ruleSets | Where-Object { $_.id -eq "ConnectorManagement" } | Select-Object -First 1
}

function Get-ActionSignature($entry) {
    $mode = Get-Prop $entry "AllowedActionsMode"
    if (-not $mode) { $mode = "AllAllowed" }
    if ($mode -ne "SomeAllowed") { return $mode }
    $actions = (@(Get-Prop $entry "AllowedActions") | Where-Object { $_ } | Sort-Object) -join "|"
    return "$mode::$actions"
}

# Copies AllowedActionsMode/AllowedActions from each source connector to the matching target connector.
# Returns the number of connectors that were changed.
function Sync-ConnectorActions($sourceCm, $targetCm) {
    $changed = 0
    foreach ($src in @($sourceCm.inputs.AllowedConnectorList)) {
        $key = Get-ConnectorKey $src
        $tgt = @($targetCm.inputs.AllowedConnectorList) | Where-Object { (Get-ConnectorKey $_) -eq $key } | Select-Object -First 1
        if (-not $tgt) { Write-Warning "  $key is in the source but not in the target rule - skipped"; continue }
        if ((Get-ActionSignature $src) -eq (Get-ActionSignature $tgt)) { continue }

        $mode = Get-Prop $src "AllowedActionsMode"
        if (-not $mode) { $mode = "AllAllowed" }
        $tgt | Add-Member -NotePropertyName AllowedActionsMode -NotePropertyValue $mode -Force
        if ($mode -eq "SomeAllowed") {
            $actions = [object[]]@(Get-Prop $src "AllowedActions")
            $tgt | Add-Member -NotePropertyName AllowedActions -NotePropertyValue $actions -Force
            Write-Host "  $key -> SomeAllowed ($($actions.Count) allowed): $($actions -join ', ')"
        }
        else {
            $tgt.PSObject.Properties.Remove("AllowedActions")
            Write-Host "  $key -> $mode"
        }
        $changed++
    }
    return $changed
}

if ($MyInvocation.InvocationName -eq ".") { return }  # dot-sourced: load helpers only

# ---------- Authenticate (requires the Az.Accounts module: Install-Module Az.Accounts -Scope CurrentUser) ----------
Connect-AzAccount -Tenant $tenantId | Out-Null
$token = (Get-AzAccessToken -ResourceUrl $apiBaseUrl -AsSecureString).Token | ConvertFrom-SecureString -AsPlainText
$headers = @{ Authorization = "Bearer $token" }

function Invoke-PpApi($method, $path, $body) {
    $params = @{ Method = $method; Uri = "$apiBaseUrl/$path`?api-version=$apiVersion"; Headers = $headers }
    if ($body) { $params.ContentType = "application/json"; $params.Body = $body }
    Invoke-RestMethod @params
}

# ---------- 1. Read the source group's policy ----------
$sourceAssignments = Invoke-PpApi Get "governance/ruleBasedPolicies/environmentGroups/$sourceGroupId/assignments"
if (-not $sourceAssignments.value) { throw "No policy is assigned to source group $sourceGroupId" }
$sourcePolicyId = $sourceAssignments.value[0].policyId
$source   = Invoke-PpApi Get "governance/ruleBasedPolicies/$sourcePolicyId"
$sourceCm = Get-ConnectorManagement $source

# ---------- 2. Copy the rules (unchanged logic) ----------
# A group can have only one assigned policy, so check the target first
$targetAssignments = Invoke-PpApi Get "governance/ruleBasedPolicies/environmentGroups/$targetGroupId/assignments"
$targetPolicyId = if ($targetAssignments.value) { $targetAssignments.value[0].policyId } else { $null }

if ($targetPolicyId) {
    # Target already has a policy: patch the source rule sets into it (patch adds/updates rule sets by ID)
    $targetPolicy = Invoke-PpApi Get "governance/ruleBasedPolicies/$targetPolicyId"
    $ruleSetsToCopy = if ($CopyAllRules) { @($source.ruleSets) } else { @($sourceCm) }
    if (-not $ruleSetsToCopy -or -not $ruleSetsToCopy[0]) { throw "Source policy $sourcePolicyId has no rule sets to copy." }

    $patchBody = @{ name = $targetPolicy.name; ruleSets = $ruleSetsToCopy } | ConvertTo-Json -Depth 20
    Invoke-PpApi Patch "governance/ruleBasedPolicies/$targetPolicyId" $patchBody | Out-Null
    Write-Host "Target group already uses policy $targetPolicyId - updated it with $($ruleSetsToCopy.Count) rule set(s): $(($ruleSetsToCopy.id) -join ', ')"
}
elseif ($CopyAllRules) {
    # No policy on the target: copy ALL rule sets into a new policy and assign it
    $copyBody = @{ name = "$($source.name) (copy)"; ruleSets = $source.ruleSets } | ConvertTo-Json -Depth 20
    $copy = Invoke-PpApi Post "governance/ruleBasedPolicies" $copyBody
    Invoke-PpApi Post "governance/ruleBasedPolicies/$($copy.id)/environmentGroups/$targetGroupId/assignments" "{}" | Out-Null
    $targetPolicyId = $copy.id
    Write-Host "Copied all rules to new policy $targetPolicyId and assigned it to group $targetGroupId"
}
else {
    throw "No policy is assigned to target group $targetGroupId. Set `$CopyAllRules = `$true to create one."
}

# ---------- 3. Copy connector actions for each copied connector rule ----------
if (-not $sourceCm) { Write-Host "Source policy has no ConnectorManagement rule set - no connector actions to copy."; return }

$restricted = @($sourceCm.inputs.AllowedConnectorList | Where-Object { (Get-Prop $_ "AllowedActionsMode") -eq "SomeAllowed" })
Write-Host "Source has $($restricted.Count) connector(s) with restricted (partly disabled) actions."

# Re-read what the service actually stored for the target
$target   = Invoke-PpApi Get "governance/ruleBasedPolicies/$targetPolicyId"
$targetCm = Get-ConnectorManagement $target
if (-not $targetCm) { throw "Target policy $targetPolicyId has no ConnectorManagement rule set after the copy." }

Write-Host "Syncing connector actions into policy $targetPolicyId :"
$changed = Sync-ConnectorActions $sourceCm $targetCm
if ($changed -gt 0) {
    $patchBody = @{ name = $target.name; ruleSets = @($targetCm) } | ConvertTo-Json -Depth 20
    Invoke-PpApi Patch "governance/ruleBasedPolicies/$targetPolicyId" $patchBody | Out-Null
    Write-Host "Updated actions on $changed connector(s)."
}
else {
    Write-Host "Connector actions already match the source - nothing to update."
}

# ---------- 4. Verify ----------
$verifyCm = Get-ConnectorManagement (Invoke-PpApi Get "governance/ruleBasedPolicies/$targetPolicyId")
$mismatches = 0
foreach ($src in @($sourceCm.inputs.AllowedConnectorList)) {
    $key = Get-ConnectorKey $src
    $tgt = @($verifyCm.inputs.AllowedConnectorList) | Where-Object { (Get-ConnectorKey $_) -eq $key } | Select-Object -First 1
    if (-not $tgt -or (Get-ActionSignature $src) -ne (Get-ActionSignature $tgt)) {
        Write-Warning "Mismatch for $key - source: $(Get-ActionSignature $src) | target: $(Get-ActionSignature $tgt)"
        $mismatches++
    }
}
if ($mismatches -eq 0) { Write-Host "Verified: connector actions in $targetPolicyId match the source." }

Step 7. Remove ACP from an environment group

While a group has an active ACP rule, every environment in the group matches the group's policy. How you remove enforcement depends on whether you want those environments to keep their current configuration or clear ACP entirely:

  • Remove the rule from the group's policy to stop the group from managing ACP. Use the removeRule operation to remove the ConnectorManagement rule set from the group's policy. The environments keep their last-applied ACP configuration, but they're no longer kept in sync with the group. You can manage each environment individually and let them diverge.
  • Remove ACP from the group and from every environment to turn ACP off everywhere. Remove the rule from the group's policy, then loop through the group's environments and remove the ConnectorManagement rule set from each environment's policy as well.

Note

Removing the rule from a group's policy doesn't automatically clear ACP from the environments that inherited it. Those environments retain their last-applied configuration to avoid an enforcement gap. To clear ACP everywhere, remove it from each environment, as shown in the loop example. For more information, see Advanced connector policies.

Remove the rule from the group's policy

The following example removes the ConnectorManagement rule set from a policy by using the removeRule operation.

$policyId = "<policy ID>"

# Read the policy, then send the rule set to remove
$policy = Invoke-RestMethod -Method Get `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$policyId`?api-version=$apiVersion" `
    -Headers $headers
$ruleSet = $policy.ruleSets | Where-Object { $_.id -eq "ConnectorManagement" }

$body = @{ name = $policy.name; ruleSets = @($ruleSet) } | ConvertTo-Json -Depth 10
Invoke-RestMethod -Method Patch `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$policyId/removeRule?api-version=$apiVersion" `
    -Headers $headers -ContentType "application/json" -Body $body
Write-Host "Removed the ConnectorManagement rule set from policy $policyId"

Remove ACP from every environment in the group

To turn off ACP across all environments in a group, first remove the rule from the group's policy (previous example), then repeat the removal for each environment's own policy. Read each environment's assigned policy from its environment assignment, then call removeRule on that policy. Provide the environment IDs that belong to the group, or enumerate them by using the environment management APIs.

# Environment IDs that belong to the group
$environmentIds = @("<environment ID 1>", "<environment ID 2>")

foreach ($environmentId in $environmentIds) {
    # Find the policy currently assigned to the environment
    $envAssignments = Invoke-RestMethod -Method Get `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies/environments/$environmentId/assignments?api-version=$apiVersion" `
        -Headers $headers
    if (-not $envAssignments.value) { continue }
    $envPolicyId = $envAssignments.value[0].policyId

    # Remove the ConnectorManagement rule set from that environment's policy
    $envPolicy = Invoke-RestMethod -Method Get `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$envPolicyId`?api-version=$apiVersion" `
        -Headers $headers
    $ruleSet = $envPolicy.ruleSets | Where-Object { $_.id -eq "ConnectorManagement" }
    if ($ruleSet) {
        $body = @{ name = $envPolicy.name; ruleSets = @($ruleSet) } | ConvertTo-Json -Depth 10
        Invoke-RestMethod -Method Patch `
            -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$envPolicyId/removeRule?api-version=$apiVersion" `
            -Headers $headers -ContentType "application/json" -Body $body
        Write-Host "Removed ACP from environment $environmentId"
    }
}

The same per-environment removeRule call works with the C# and Python SDKs shown earlier. Wrap the call in a loop over the group's environment IDs.

Related content

Advanced connector policies
Rule Based Policies - REST API reference
Authentication
Tutorial: Assign roles to service principals
Programmability and extensibility overview

  • Last updated on