connection-setup

name

connection-setup

description

Create and configure Connector Namespace connections for SDK-supported connectors. USE WHEN: setting up a new connector connection, creating a Connector Namespace, authorizing OAuth consent, adding access policies, or configuring local.settings.json / app settings. Covers Office365, SharePoint, Teams, and any Microsoft.Web/connections connector. NOT FOR: general SDK usage, trigger registration, or code generation.

Connector Namespace Connection Setup

Automates the end-to-end connection lifecycle for SDK-supported connectors, keeping the developer in VS Code.

When to Use

• Developer needs a new connector connection for local dev or a deployed compute host
• Developer needs to authorize (OAuth consent) a connection
• Developer needs to wire connection URLs into local.settings.json or 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: compute host (e.g., Function App, App Service) 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 = "<azure-region>"

$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. If the Connector Namespace was created without an identity, update it:

$nsBody = "{`"location`":`"$location`",`"identity`":{`"type`":`"SystemAssigned`"},`"properties`":{}}"
$tempFile = Join-Path $env:TEMP "ns-identity.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

Step 2: Create Connection

Supported SDK connector names: arm, azuread, azureblob, azureeventgrid, azureiotcentral, azuremonitorlogs, azurequeues, azuretables, box, campfire, clicksendsms, cloudconvert, cloudmersiveconvert, commondataservice, docusign, documentdb, docuware, dropbox, dynamicsax, elfsquaddata, etsy, eventbrite, eventhubs, excelonline, excelonlinebusiness, formstackforms, freshservice, ftp, github, googlecalendar, googledrive, googletasks, impexium, infusionsoft, insightly, jedoxodatahub, jira, kusto, mailchimp, meetingroommap, microsoftforms, monday, mq, msgraphgroupsanduser, office365, office365users, onedrive, onedriveforbusiness, orderful, outlook, pdfco, pipedrive, plivo, plumsail, projectplace, replicon, revai, rss, salesforce, seismicplanner, sendgrid, servicebus, sharepointonline, signinghub, slack, smtp, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , (and any connector name).

$connectorName = "<connector-name>"      # e.g., "arm", "azureblob", "azuremonitorlogs", "kusto", "mq", "msgraphgroupsanduser", "office365", "office365users", "onedriveforbusiness", "sharepointonline", "smtp", "teams"
$connectionName = "<connection-name>"    # e.g., "office365-test", "sharepoint-test"

$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.TrimStart('/'))/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.

For credential-based (non-OAuth) connectors (e.g., azurequeues, azuretables, smtp, eventhubs, servicebus, documentdb), include parameterValues directly in the PUT body instead of using OAuth consent (Step 3). See Step 3b: Credential-Based Authentication.

Step 3: OAuth Consent (In-Browser)

Retrieve the consent link and open it in the default browser — no portal needed:

$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.TrimStart('/'))/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

The user completes OAuth in the browser. After consent, verify:

az rest --method GET `
    --uri "https://management.azure.com/$($nsId.TrimStart('/'))/connections/${connectionName}?api-version=2026-05-01-preview" `
    -o json | ConvertFrom-Json | Select-Object @{n='status';e={$_.properties.statuses[0].status}}

Expected: Connected.

Step 3b: Credential-Based Authentication

For connectors that use connection strings or API keys (not OAuth), include parameterValues directly in the PUT body. The connection becomes Connected immediately without browser consent.

Critical: Always use [System.IO.File]::WriteAllText($tempFile, $connBody, [System.Text.Encoding]::UTF8) and Content-Type=application/json;charset=utf-8 header. Missing the charset=utf-8 header causes credentials with +, =, or / characters (common in base64 keys) to not be stored, leaving the connection in Error state.

# Example: Azure Storage (azurequeues / azuretables)
$connObj = @{
    properties = @{
        connectorName = "azurequeues"
        parameterValues = @{
            storageaccount = "<storage-account-name>"
            sharedkey = "<storage-account-key>"
        }
    }
}
$connBody = $connObj | ConvertTo-Json -Depth 5 -Compress
$tempFile = Join-Path $env:TEMP "conn-body.json"
[System.IO.File]::WriteAllText($tempFile, $connBody, [System.Text.Encoding]::UTF8)
az rest --method PUT `
    --uri "https://management.azure.com/$($nsId.TrimStart('/'))/connections/${connectionName}?api-version=2026-05-01-preview" `
    --body "@$tempFile" --headers "Content-Type=application/json;charset=utf-8" -o json | ConvertFrom-Json | Select-Object name, @{n='status';e={$_.properties.overallStatus}}
Remove-Item $tempFile -ErrorAction SilentlyContinue
# Expected: status = Connected

Parameter names by connector:

Connector	Parameters
azurequeues, azuretables	storageaccount (name), sharedkey (access key)
eventhubs, servicebus	connectionString (namespace connection string)
documentdb	databaseAccount (account name), accessKey (primary key)
smtp	serverAddress, port, enableSSL, userName, password
mq	see managed API definition for parameter names

If the connection shows Error after PUT: The credentials may not have been stored. Delete the connection and recreate it — do NOT retry PUT on an existing connection. The first PUT after DELETE reliably stores parameterValues.

Step 4: Get Connection Runtime URL

$conn = az rest --method GET `
    --uri "https://management.azure.com/$($nsId.TrimStart('/'))/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 control which identities can call the connection's runtime URL for connector actions (e.g., send email, list files). For trigger-only scenarios, the Connector Namespace polls server-side and does not need an access policy on the connection. Skip this step if your function only receives trigger callbacks and does not call connector actions at runtime.

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.TrimStart('/'))/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 compute host (e.g., Function App with system-assigned MSI)

$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.TrimStart('/'))/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.

Step 6: Configure App Settings

Note: Connection app settings are only needed when your function code calls connector actions at runtime using ConnectorConnectionResolver. For trigger-only scenarios, the function receives callbacks directly from the Connector Namespace and does not need these settings. Skip this step if your function only receives trigger callbacks.

The SDK's ConnectorConnectionResolver reads connection settings using the Azure Functions __ (double-underscore) environment variable separator convention.

Connection setting name

Choose a connection setting name (e.g., office365, sharepoint, teams). This is passed to ConnectorConnectionResolver.Resolve(connectionSettingName) and used as the prefix for the __ keys.

Format B — Direct URL (actions only)

Add to local.settings.json under "Values":

{
  "{connectionSettingName}__connectionRuntimeUrl": "<runtime-url-from-step-4>"
}

Format A — Connector Namespace (triggers + actions)

{
  "{connectionSettingName}__connectorGatewayName": "<namespace-name>",
  "{connectionSettingName}__connectionName": "<connection-name>"
}

Deployed compute host (e.g., Function App)

Format B:

az functionapp config appsettings set `
    -g $resourceGroup -n $functionAppName `
    --settings "{connectionSettingName}__connectionRuntimeUrl=$runtimeUrl"

Format A:

az functionapp config appsettings set `
    -g $resourceGroup -n $functionAppName `
    --settings "{connectionSettingName}__connectorGatewayName=$namespaceName" "{connectionSettingName}__connectionName=$connectionName"

Step 7: Verify Connection

Test the connection works end-to-end:

# Office365
az rest --method GET --uri "$runtimeUrl/Categories" --resource "https://apihub.azure.com" -o json

# SharePoint
az rest --method GET --uri "$runtimeUrl/datasets" --resource "https://apihub.azure.com" -o json

# Teams — list joined teams to verify Teams connection
az rest --method GET --uri "$runtimeUrl/beta/me/joinedTeams" --resource "https://apihub.azure.com" -o json

# OneDrive for Business — list root folder
az rest --method GET --uri "$runtimeUrl/datasets/default/folders" --resource "https://apihub.azure.com" -o json

Next Steps

• Triggers: To register polling triggers (e.g., OnNewEmail, OnNewFile), use the trigger-registration skill.