connection-setup

name	connection-setup
description	Create and configure AI Gateway connections for SDK-supported connectors. USE WHEN: setting up a new connector connection, creating an AI Gateway, authorizing OAuth consent, adding access policies, or configuring environment variables. Covers Office365, SharePoint, Teams, Kusto, and any Microsoft.Web/connections connector. NOT FOR: general SDK usage, trigger registration, or code generation.

AI Gateway 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 environment variables 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

Procedure

Step 1: Create or Select AI Gateway

Check for an existing AI Gateway 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/aigateways?api-version=2026-03-01-preview" `
    -o json | ConvertFrom-Json | Select-Object -ExpandProperty value | Select-Object name

If none exists, create one:

$gatewayName = "<gateway-name>"
$location = "<azure-region>"

$gwBody = "{`"location`":`"$location`",`"properties`":{}}"
$tempFile = Join-Path $env:TEMP "gw-body.json"
[System.IO.File]::WriteAllText($tempFile, $gwBody)
az rest --method PUT `
    --uri "https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.Web/aigateways/$gatewayName?api-version=2026-03-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, azureblob, azureeventgrid, azureiotcentral, azuremonitorlogs, box, campfire, clicksendsms, cloudmersiveconvert, docusign, docuware, dropbox, dynamicsax, excelonline, freshservice, ftp, github, googlecalendar, googledrive, googletasks, infusionsoft, insightly, jira, kusto, mailchimp, microsoftforms, monday, mq, msgraphgroupsanduser, office365, office365groupsmail, office365users, onedriveforbusiness, pdfco, pipedrive, plumsail, powerbi, projectplace, rss, salesforce, sendgrid, sharepointonline, shifts, signinghub, slack, smtp, sql, teams, textrequest, todo, webex, zendesk (and any Microsoft.Web/connections connector name).

$connectorName = "<connector-name>"      # e.g., "office365", "sharepointonline", "teams"
$connectionName = "<connection-name>"    # e.g., "office365-test", "sharepoint-test"

$gwId = "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.Web/aigateways/$gatewayName"
$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${gwId}/connections/${connectionName}?api-version=2026-03-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 — 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${gwId}/connections/${connectionName}/listConsentLinks?api-version=2026-03-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${gwId}/connections/${connectionName}?api-version=2026-03-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${gwId}/connections/${connectionName}?api-version=2026-03-01-preview" `
    -o json | ConvertFrom-Json
$runtimeUrl = $conn.properties.connectionRuntimeUrl
Write-Output "Runtime URL: $runtimeUrl"

Step 5: Add Access Policies

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${gwId}/connections/${connectionName}/accessPolicies/local-dev?api-version=2026-03-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${gwId}/connections/${connectionName}/accessPolicies/functionapp-msi?api-version=2026-03-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 Environment Variables

The SDK reads connection URLs from environment variables.

For local development

Set the environment variable directly:

$env:OFFICE365_CONNECTION_URL = "<runtime-url-from-step-4>"

Or create a .env file (add .env to .gitignore):

OFFICE365_CONNECTION_URL=<runtime-url-from-step-4>
SHAREPOINT_CONNECTION_URL=<runtime-url-from-step-4>

For Azure Functions (local.settings.json)

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "OFFICE365_CONNECTION_URL": "<runtime-url-from-step-4>",
    "SHAREPOINT_CONNECTION_URL": "<runtime-url-from-step-4>"
  }
}

For deployed compute host (e.g., Function App)

az functionapp config appsettings set `
    -g $resourceGroup -n $functionAppName `
    --settings "OFFICE365_CONNECTION_URL=$runtimeUrl"

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