| name | connection-setup |
| description | Create and configure Connector Namespace connections for the Azure Functions Connector Extension. USE WHEN: setting up a new connector connection, creating a Connector Namespace, authorizing OAuth consent, adding access policies, or configuring deployed app settings. Covers Office365, SharePoint, Teams, and any Microsoft.Web/connections connector. NOT FOR: trigger registration (use trigger-registration skill), extension development, or code generation. |
Connector Namespace Connection Setup
Automates the end-to-end connection lifecycle for connector-triggered Azure Functions.
When to Use
- Developer needs a new connector connection for local dev or a deployed Function App
- Developer needs to authorize (OAuth consent) a connection
- Developer needs to wire connection URLs into deployed app settings
- Developer needs to grant access policies (CLI identity for local, managed identity for deployed)
Prerequisites
- Azure CLI installed and authenticated (
az login)
- Target subscription and resource group known
- For deployed scenarios: Function App with managed identity enabled
- Supported regions for Connector Namespace:
brazilsouth, centraluseuap, eastus2euap, centralusstage, eastusstage. Only the Connector Namespace location must be in a supported region; the resource group and Function App can be in any region.
Procedure
Step 1: Create or Select Connector Namespace
Check for an existing Connector Namespace in the resource group:
$subscriptionId = "<subscription-id>"
$resourceGroup = "<resource-group>"
az rest --method GET `
--uri "https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.Web/connectorGateways?api-version=2026-05-01-preview" `
-o json | ConvertFrom-Json | Select-Object -ExpandProperty value | Select-Object name
If none exists, create one:
$namespaceName = "<namespace-name>"
$location = "<supported-region>" # e.g., centraluseuap
$nsBody = "{`"location`":`"$location`",`"identity`":{`"type`":`"SystemAssigned`"},`"properties`":{}}"
$tempFile = Join-Path $env:TEMP "ns-body.json"
[System.IO.File]::WriteAllText($tempFile, $nsBody)
az rest --method PUT `
--uri "https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.Web/connectorGateways/$namespaceName?api-version=2026-05-01-preview" `
--body "@$tempFile" --headers "Content-Type=application/json" -o json
Remove-Item $tempFile -ErrorAction SilentlyContinue
Important: The Connector Namespace must have a managed identity enabled (SystemAssigned) for trigger callback authentication.
Step 2: Create Connection
$connectorName = "<connector-name>" # e.g., "office365", "sharepointonline", "teams"
$connectionName = "<connection-name>" # e.g., "office365-conn"
$nsId = "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.Web/connectorGateways/$namespaceName"
$connBody = "{`"properties`":{`"connectorName`":`"$connectorName`"}}"
$tempFile = Join-Path $env:TEMP "conn-body.json"
[System.IO.File]::WriteAllText($tempFile, $connBody)
az rest --method PUT `
--uri "https://management.azure.com${nsId}/connections/${connectionName}?api-version=2026-05-01-preview" `
--body "@$tempFile" --headers "Content-Type=application/json" -o json | ConvertFrom-Json | Select-Object name, @{n='status';e={$_.properties.statuses[0].status}}
Remove-Item $tempFile -ErrorAction SilentlyContinue
The connection starts in Error state (unauthenticated). Proceed to Step 3.
Step 3: OAuth Consent (In-Browser)
Retrieve the consent link and open it in the default browser:
$consentBody = '{"parameters":[{"redirectUrl":"https://portal.azure.com","parameterName":"token"}]}'
$tempFile = Join-Path $env:TEMP "consent-body.json"
[System.IO.File]::WriteAllText($tempFile, $consentBody)
$result = az rest --method POST `
--uri "https://management.azure.com${nsId}/connections/${connectionName}/listConsentLinks?api-version=2026-05-01-preview" `
--body "@$tempFile" --headers "Content-Type=application/json" -o json | ConvertFrom-Json
Remove-Item $tempFile -ErrorAction SilentlyContinue
$link = $result.value[0].link
Start-Process $link
After consent, verify the connection status:
az rest --method GET `
--uri "https://management.azure.com${nsId}/connections/${connectionName}?api-version=2026-05-01-preview" `
-o json | ConvertFrom-Json | Select-Object @{n='status';e={$_.properties.statuses[0].status}}
Expected: Connected.
Step 4: Get Connection Runtime URL
$conn = az rest --method GET `
--uri "https://management.azure.com${nsId}/connections/${connectionName}?api-version=2026-05-01-preview" `
-o json | ConvertFrom-Json
$runtimeUrl = $conn.properties.connectionRuntimeUrl
Write-Output "Runtime URL: $runtimeUrl"
Step 5: Add Access Policies
Note: Access policies are only needed when your function calls connector actions at runtime. For trigger-only scenarios (function only receives callbacks), skip this step.
For local development (Azure CLI identity)
$userObjectId = az ad signed-in-user show --query "id" -o tsv
$tenantId = az account show --query "tenantId" -o tsv
$policyBody = "{`"properties`":{`"principal`":{`"type`":`"ActiveDirectory`",`"identity`":{`"objectId`":`"$userObjectId`",`"tenantId`":`"$tenantId`"}}}}"
$tempFile = Join-Path $env:TEMP "policy-body.json"
[System.IO.File]::WriteAllText($tempFile, $policyBody)
az rest --method PUT `
--uri "https://management.azure.com${nsId}/connections/${connectionName}/accessPolicies/local-dev?api-version=2026-05-01-preview" `
--body "@$tempFile" --headers "Content-Type=application/json" -o json | ConvertFrom-Json | Select-Object name
Remove-Item $tempFile -ErrorAction SilentlyContinue
For deployed Function App (system-assigned managed identity)
$functionAppName = "<function-app-name>"
$msiObjectId = az functionapp identity show -g $resourceGroup -n $functionAppName --query "principalId" -o tsv
$tenantId = az account show --query "tenantId" -o tsv
$policyBody = "{`"properties`":{`"principal`":{`"type`":`"ActiveDirectory`",`"identity`":{`"objectId`":`"$msiObjectId`",`"tenantId`":`"$tenantId`"}}}}"
$tempFile = Join-Path $env:TEMP "msi-policy-body.json"
[System.IO.File]::WriteAllText($tempFile, $policyBody)
az rest --method PUT `
--uri "https://management.azure.com${nsId}/connections/${connectionName}/accessPolicies/functionapp-msi?api-version=2026-05-01-preview" `
--body "@$tempFile" --headers "Content-Type=application/json" -o json | ConvertFrom-Json | Select-Object name
Remove-Item $tempFile -ErrorAction SilentlyContinue
ACL propagation takes 1-5 minutes. If you get 403 errors immediately after adding, wait and retry.
Supported Connectors
arm, azureblob, azureeventgrid, azuremonitorlogs, office365, office365users, onedriveforbusiness, sharepointonline, teams, kusto, smtp, keyvault, planner, todo, and any Microsoft.Web/connections connector name.
Next Steps
