Create an Azure connection via API

Latest Dynatrace
How-to guide
Preview

Prerequisites

1. Azure

Actions in this section must be performed by an Azure administrator with appropriate permissions.

Before running Azure CLI commands, ensure:

You have Azure CLI installed and authenticated (az login)
Your Azure account has one of the following:
- Application Administrator role in Microsoft Entra ID
- Cloud Application Administrator role in Microsoft Entra ID
- microsoft.directory/servicePrincipals/create permission.
  
  And one of the following:
- Owner role at the target scope (subscription or management group)
- User Access Administrator role at the target scope
- A custom role with Microsoft.Authorization/roleAssignments/write permission

For Management Group monitoring scope, you need role assignment permissions at the management group level, not just individual subscriptions.

Identify your Azure monitoring scope

Decide which monitoring scope you'll use and gather the required IDs:

Monitoring scope	Required information
`Management Group`	Management Group ID (found in Azure portal under Management groups)
`Subscription`	Subscription ID (found in Azure portal under Subscriptions)

2. Dynatrace

Create a new platform token for the Dynatrace environment with the following scopes:

extensions:configurations:read
extensions:configurations:write
settings:objects:read
settings:objects:write

Create a new Azure connection via REST API

The monitoring configuration requires an Azure connection to access your Azure environment.

Dynatrace supports two authentication methods:

Federated identity Recommended: Uses federated identity credentials—more secure, passwordless authentication.
Client secret: Uses a service principal with client secret—password-based authentication.

Windows

The shell commands on this page use \ for line continuation (bash/zsh). On Windows, replace \ with a backtick (`) in PowerShell, or ^ in Command Prompt.

Federated identity authentication

Client secret authentication

Federated identity credentials provide passwordless authentication and are more secure than client secrets.

This is the recommended approach for production environments.

1. Create an empty Azure connection

Prepare the request payload.

Placeholder	Description
`<CONNECTION_NAME>`	Descriptive name for the connection

[
   {
      "value": {
            "federatedIdentityCredentials": {
               "consumers": ["SVC:com.dynatrace.da"]
            },
            "name": "<CONNECTION_NAME>",
            "type": "federatedIdentityCredentials"
      },
      "schemaId": "builtin:hyperscaler-authentication.connections.azure"
   }
]

Send the request to the REST API endpoint.

Placeholder	Description
`<YOUR_BEARER_TOKEN>`	Settings platform token
`<YOUR_ENVIRONMENT_URL>`	URL of your Dynatrace environment
`<REQUEST_PAYLOAD>`	Request payload prepared in the previous step

curl -X 'POST' \
'<YOUR_ENVIRONMENT_URL>/platform/classic/environment-api/v2/settings/objects?validateOnly=false&adminAccess=false' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
-d '<REQUEST_PAYLOAD>'

Successful request will respond with a connection ID:

[
   {
      "code": 200,
      "objectId": "vu9U3hXa3q0AAAABADRidWlsdGlu..."
   }
]

Save the objectId value—you will need it for the next steps.

2. Configure federated credentials in Azure

Configure the federated identity credential in Microsoft Entra ID for your service principal using the connection ID from the last step above.

Register a new application in your Microsoft Entra ID tenant.

See How to register an app in Microsoft Entra ID to learn more.

Placeholder Description
<CONNECTION_NAME>
Descriptive name for the connection (used in Dynatrace)
```
az ad sp create-for-rbac \
--name "<CONNECTION_NAME>" \
--create-password false \
--query "{CLIENT_ID:appId, TENANT_ID:tenant}" \
--output table
```

Placeholder	Description
`<CONNECTION_NAME>`	Descriptive name for the connection (used in Dynatrace)

Create a federated credential for the Microsoft Entra ID app. Dynatrace uses this for OIDC token exchange.

See az ad app federated-credential to learn more.

Placeholder	Description
`<CLIENT_ID>`	Application (client) ID from the previous step
`<CONNECTION_NAME>`	Descriptive name for the federated credential
`<CONNECTION_ID_FROM_STEP_1>`	The connection ID returned in step 1
`<DYNATRACE_TENANT_ID>`	Your Dynatrace tenant ID (for example, `abc12345`)

az ad app federated-credential create \
--id "<CLIENT_ID>" \
--parameters '{"name": "<CONNECTION_NAME>-Federated-Credential", \
"issuer": "https://token.dynatrace.com", \
"subject": "dt:connection-id/<CONNECTION_ID_FROM_STEP_1>", \
"audiences": ["<DYNATRACE_TENANT_ID>.apps.dynatrace.com/svc-id/com.dynatrace.da"]}'

Assign the Monitoring Reader Azure RBAC built-in role to the service principal at the appropriate monitoring scope.

For the Management Group scope:

az role assignment create \
--assignee "<CLIENT_ID>" \
--role "Monitoring Reader" \
--scope "/providers/Microsoft.Management/managementGroups/<MANAGEMENT_GROUP_ID>" \
--assignee-principal-type ServicePrincipal \
--description "Dynatrace Monitoring"

For the Subscription scope:

az role assignment create \
--assignee "<CLIENT_ID>" \
--role "Monitoring Reader" \
--scope "/subscriptions/<SUBSCRIPTION_ID>" \
--assignee-principal-type ServicePrincipal \
--description "Dynatrace Monitoring"

Verify the role assignment was successful:
```
az role assignment list --assignee "<CLIENT_ID>" --output table
```
You should see the Monitoring Reader role listed at your specified scope.

3. Update the Azure connection with service principal details

Prepare the update payload.

Placeholder	Description
`<CONNECTION_NAME>`	Descriptive name for the connection (same as Step 1)
`<TENANT_ID>`	Microsoft Entra ID tenant (directory) ID
`<CLIENT_ID>`	Application (client) ID of the service principal

[
   {
      "value": {
            "federatedIdentityCredentials": {
               "directoryId": "<TENANT_ID>",
               "applicationId": "<CLIENT_ID>",
               "consumers": ["SVC:com.dynatrace.da"]
            },
            "name": "<CONNECTION_NAME>",
            "type": "federatedIdentityCredentials"
      },
      "schemaId": "builtin:hyperscaler-authentication.connections.azure"
   }
]

Send the PUT request to update the connection.

Placeholder	Description
`<YOUR_BEARER_TOKEN>`	Settings platform token
`<YOUR_ENVIRONMENT_URL>`	URL of your Dynatrace environment
`<AZURE_CONNECTION_ID>`	The `objectId` returned in step 1
`<UPDATE_PAYLOAD>`	Request payload prepared above

curl -X 'PUT' \
'<YOUR_ENVIRONMENT_URL>/platform/classic/environment-api/v2/settings/objects/<AZURE_CONNECTION_ID>?validateOnly=false' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
-d '<UPDATE_PAYLOAD>'

Successful request will respond with the updated connection ID:

{
   "code": 200,
   "objectId": "vu9U3hXa3q0AAAABADRidWlsdGlu..."
}

If the API call fails, validate that: you have access to the Settings API, your settings platform token is valid and assigned to the correct Dynatrace environment/account.

After successful completion, you can proceed to Create the Azure monitoring configuration.

Placeholder	Description
`<CONNECTION_NAME>`	Descriptive name for the connection (used in Dynatrace)

Placeholder	Description
`<TENANT_ID>`	Microsoft Entra ID tenant (directory) ID
`<CLIENT_ID>`	Application (client) ID of the service principal
`<CLIENT_SECRET>`	Client secret value from step 1
`<CONNECTION_NAME>`	Descriptive name for the connection

Create a new Azure monitoring configuration via REST API

The monitoring configuration is the blueprint that contains all the settings that will be used on initial Azure onboarding (Azure services to poll metrics for, monitored regions, filtering rules, and more).

Settings can be modified post onboarding.

Basic monitoring configuration

Prepare the request payload.

Placeholder	Description
`<CONFIGURATION_NAME>`	Name of the monitoring configuration (letters, numbers, hyphens only; must start with a letter)
`<AZURE_CONNECTION_ID>`	The `objectId` returned in the Azure connection step
`<CLIENT_ID>`	Application (client) ID of the service principal
`<MONITORED_REGION_*>`	Azure regions to monitor (for example, `eastus`, `westeurope`, `northeurope`)

Required

To allow telemetry signals in context and inventory on all relevant regions, the topology service must poll for topology signals on all regions where any signal is ingested.

[
	{
		"scope": "integration-azure",
		"value": {
			"enabled": true,
			"description": "<CONFIGURATION_NAME>",
			"version": "1.0.0",
			"activationContext": "DATA_ACQUISITION",
			"featureSets": [
				"microsoft_apimanagement.service_essential",
				"microsoft_network.applicationgateways_essential",
				"microsoft_cache.redis_essential",
				"microsoft_app.containerapps_essential",
				"microsoft_documentdb.databaseaccounts_essential",
				"microsoft_eventhub.namespaces_essential",
				"microsoft_web.sites_functionapp_essential",
				"microsoft_devices.iothubs_essential",
				"microsoft_network.loadbalancers_essential",
				"microsoft_logic.workflows_essential",
				"microsoft_web.sites_functionapp_workflowapp_essential",
				"microsoft_cache.redisenterprise_essential",
				"microsoft_cognitiveservices.accounts_essential",
				"microsoft_servicebus.namespaces_essential",
				"microsoft_sql.servers.databases_essential",
				"microsoft_storage.storageaccounts_essential",
				"microsoft_storage.storageaccounts.blobservices_essential",
				"microsoft_storage.storageaccounts.fileservices_essential",
				"microsoft_storage.storageaccounts.queueservices_essential",
				"microsoft_storage.storageaccounts.tableservices_essential",
				"microsoft_compute.virtualmachinescalesets_essential",
				"microsoft_compute.virtualmachines_essential",
				"microsoft_web.sites_app_essential"
			],
			"azure": {
				"smartscapeConfiguration": {
					"enabled": true
				},
				"credentials": [
					{
						"description": "{configuration-name}",
						"enabled": true,
						"connectionId": "{azure-connection-id}",
						"servicePrincipalId": "{service-principal-id}"
					}
				],
				"locationFiltering": [
					"<MONITORED_REGION_*>",
					"{monitored-region-b}",
					"{monitored-region-n}"
				]
			}
		}
	}
]

Advanced configuration options

The monitoring configuration supports additional filtering and enrichment options to customize what resources are monitored and how data is enriched in Dynatrace.

Subscription filtering

Control which Azure subscriptions to monitor using subscriptionFiltering and subscriptionFilteringMode.

Include mode: Monitor only specified subscriptions:

"subscriptionFiltering": [
	"00000000-0000-0000-0000-000000000001",
	"00000000-0000-0000-0000-000000000002"
],
"subscriptionFilteringMode": "INCLUDE"

Exclude mode: Monitor all subscriptions except specified ones:

"subscriptionFiltering": [
	"00000000-0000-0000-0000-000000000001"
],
"subscriptionFilteringMode": "EXCLUDE"

Tag filtering

Filter which Azure resources to monitor based on their tags using tagFiltering.

Include mode: Monitor only resources with matching tags:

"tagFiltering": {
	"mode": "INCLUDE",
	"tags": [
		{
			"key": "environment",
			"value": "production"
		},
		{
			"key": "monitoring",
			"value": "enabled"
		}
	]
}

Exclude mode: Monitor all resources except those with matching tags:

"tagFiltering": {
   "mode": "EXCLUDE",
   "tags": [
      {
         "key": "monitoring",
         "value": "disabled"
      }
   ]
}

Tag enrichment

Enrich Dynatrace signals with Azure resource tags by specifying tag keys in tagEnrichment. The specified Azure tag keys will be added as attributes to signals in Dynatrace.

"tagEnrichment": [
	"environment",
	"cost-center",
	"application",
	"team"
]

Label mapping for cost allocation and security context

Map Azure tags or literal values to Dynatrace labels using labelMapping. This is particularly useful for cost allocation (dt.cost.costcenter, dt.cost.product) and security context (dt.security_context).

Using literal values

"labelMapping": [
	{
		"labelKey": "dt.security_context",
		"labelValueType": "LITERAL",
		"labelValue": "production"
	},
	{
		"labelKey": "dt.cost.costcenter",
		"labelValueType": "LITERAL",
		"labelValue": "CC-12345"
	},
	{
		"labelKey": "dt.cost.product",
		"labelValueType": "LITERAL",
		"labelValue": "MyProduct"
	}
]

Using Azure tags

"labelMapping": [
	{
		"labelKey": "dt.security_context",
		"labelValueType": "AZURE_TAG",
		"labelValue": "environment"
	},
	{
		"labelKey": "dt.cost.costcenter",
		"labelValueType": "AZURE_TAG",
		"labelValue": "cost-center"
	},
	{
		"labelKey": "dt.cost.product",
		"labelValueType": "AZURE_TAG",
		"labelValue": "product-name"
	}
]

When using AZURE_TAG, the value of the specified Azure tag will be used as the label value in Dynatrace.

Complete example with advanced options

[
	{
		"scope": "integration-azure",
		"value": {
			"enabled": true,
			"description": "production-monitoring",
			"version": "1.0.0",
			"activationContext": "DATA_ACQUISITION",
			"featureSets": [
				"microsoft_apimanagement.service_essential",
				"microsoft_network.applicationgateways_essential",
				"microsoft_cache.redis_essential",
				"microsoft_app.containerapps_essential",
				"microsoft_documentdb.databaseaccounts_essential",
				"microsoft_eventhub.namespaces_essential",
				"microsoft_web.sites_functionapp_essential",
				"microsoft_devices.iothubs_essential",
				"microsoft_network.loadbalancers_essential",
				"microsoft_logic.workflows_essential",
				"microsoft_web.sites_functionapp_workflowapp_essential",
				"microsoft_cache.redisenterprise_essential",
				"microsoft_cognitiveservices.accounts_essential",
				"microsoft_servicebus.namespaces_essential",
				"microsoft_sql.servers.databases_essential",
				"microsoft_storage.storageaccounts_essential",
				"microsoft_storage.storageaccounts.blobservices_essential",
				"microsoft_storage.storageaccounts.fileservices_essential",
				"microsoft_storage.storageaccounts.queueservices_essential",
				"microsoft_storage.storageaccounts.tableservices_essential",
				"microsoft_compute.virtualmachinescalesets_essential",
				"microsoft_compute.virtualmachines_essential",
				"microsoft_web.sites_app_essential"
			],
			"azure": {
				"smartscapeConfiguration": {
					"enabled": true
				},
				"credentials": [
					{
						"description": "production-monitoring",
						"enabled": true,
						"connectionId": "vu9U3hXa3q0AAAABADRidWlsdGlu...",
						"servicePrincipalId": "00000000-0000-0000-0000-000000000000"
					}
				],
				"locationFiltering": [
					"westeurope",
					"northeurope",
					"eastus"
				],
				"subscriptionFiltering": [
					"00000000-0000-0000-0000-000000000001",
					"00000000-0000-0000-0000-000000000002"
				],
				"subscriptionFilteringMode": "INCLUDE",
				"tagFiltering": {
					"mode": "INCLUDE",
					"tags": [
						{
							"key": "environment",
							"value": "production"
						},
						{
							"key": "monitoring",
							"value": "enabled"
						}
					]
				},
				"tagEnrichment": [
					"environment",
					"cost-center",
					"application",
					"team"
				],
				"labelMapping": [
					{
						"labelKey": "dt.security_context",
						"labelValueType": "AZURE_TAG",
						"labelValue": "environment"
					},
					{
						"labelKey": "dt.cost.costcenter",
						"labelValueType": "AZURE_TAG",
						"labelValue": "cost-center"
					},
					{
						"labelKey": "dt.cost.product",
						"labelValueType": "LITERAL",
						"labelValue": "Platform"
					}
				]
			}
		}
	}
]

Send the REST API request.

Placeholder	Description
`<YOUR_BEARER_TOKEN>`	Settings platform token (from Prerequisites)
`<YOUR_ENVIRONMENT_URL>`	URL of your Dynatrace environment (for example, `https://abc12345.apps.dynatrace.com`)
`<MONITORING_CONFIG_PAYLOAD>`	Request payload prepared in the previous step

curl -X 'POST' \
'<YOUR_ENVIRONMENT_URL>/platform/extensions/v1/com.dynatrace.extension.da-azure/monitoring-configuration' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
-d '<MONITORING_CONFIG_PAYLOAD>'

Successful request will respond with new monitoring configuration ID (in objectId field):
```
[
{
   "objectId": "e4bf05f3-d829-3689-8dd4-a9d2aeab0607",
   "code": 200
}
]
```
If the API call fails, validate that
You have access to the Settings API
Your settings platform token is valid and assigned to the correct Dynatrace environment/account
After successful completion, head over to Settings > Cloud and virtualization > Azure (Preview).

In the next few minutes the newly created connection should be visible and in Healthy state.

Modify an existing monitoring configuration

To modify an existing monitoring configuration

Retrieve existing configuration using GET request.

Placeholder	Description
`<YOUR_BEARER_TOKEN>`	Settings platform token
`<YOUR_ENVIRONMENT_URL>`	URL of your Dynatrace environment (for example, `https://abc12345.apps.dynatrace.com`)
`<MONITORING_CONFIG_ID>`	ID of the monitoring configuration you want to modify

curl -X 'GET' \
'<YOUR_ENVIRONMENT_URL>/platform/extensions/v1/com.dynatrace.extension.da-azure/monitoring-configuration/<MONITORING_CONFIG_ID>' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Modify the retrieved configuration JSON as needed (for example, add/remove monitored regions, enable/disable feature sets, update filtering rules).

Update the configuration using PUT request.

Placeholder	Description
`<YOUR_BEARER_TOKEN>`	Settings platform token
`<YOUR_ENVIRONMENT_URL>`	URL of your Dynatrace environment
`<MONITORING_CONFIG_ID>`	ID of the monitoring configuration to modify
`<MODIFIED_CONFIG_PAYLOAD>`	Modified configuration JSON from step 2

curl -X 'PUT' \
'<YOUR_ENVIRONMENT_URL>/platform/extensions/v1/com.dynatrace.extension.da-azure/monitoring-configuration/<MONITORING_CONFIG_ID>' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
-d '<MODIFIED_CONFIG_PAYLOAD>'

Successful request will respond with updated monitoring configuration ID:

{
"objectId": "e4bf05f3-d829-3689-8dd4-a9d2aeab0607",
"code": 200
}

Delete an existing monitoring configuration

To delete an existing monitoring configuration

Placeholder	Description
`<YOUR_BEARER_TOKEN>`	Settings platform token
`<YOUR_ENVIRONMENT_URL>`	URL of your Dynatrace environment (for example, `https://abc12345.apps.dynatrace.com`)
`<MONITORING_CONFIG_ID>`	ID of the monitoring configuration you want to delete

curl -X 'DELETE' \
'<YOUR_ENVIRONMENT_URL>/platform/extensions/v1/com.dynatrace.extension.da-azure/monitoring-configuration/<MONITORING_CONFIG_ID>' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Successful request will respond with 204 No Content status, indicating that the configuration has been deleted successfully.

A deleted monitoring configuration does not delete any supporting Azure resources deployed in your environment (for example, logs infrastructure).

You must delete these manually to avoid lingering resources which will incur Azure and Dynatrace costs.

What's next?

Go to Clouds. Azure resources with telemetry should start to appear shortly.

Supported Azure services

For a full list of supported Azure services, including topology relationships and available metric collection sets, see Supported Azure services.

Troubleshooting

Error: "Authorization_RequestDenied" when creating the service principal

This error occurs when your Azure identity lacks permission to create applications in Microsoft Entra ID.

Solution: Ask your Azure administrator to grant you the Application Administrator role or create the service principal on your behalf.

Error: "AuthorizationFailed" when assigning the Monitoring Reader role

This error occurs when your Azure identity lacks permission to assign roles at the specified scope.

Solution:

Ensure you have the Owner or User Access Administrator role at the target subscription or management group.
For the Management Group scope, confirm you have permissions at the management group level, not just individual subscriptions.

Error: "AADSTS70025" when updating the Azure connection

This error indicates that Microsoft Entra ID has not yet propagated the federated credential.

Solution: Wait a few seconds for propagation to complete, then retry the API call.