How to use managed identities with Azure services to connect to Azure Cosmos DB for NoSQL

Use az container create to create a new container instance. Configure the account to use a system-assigned managed identity by using the assign-identity parameter.

az container create \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-new-container>" \
    --image mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled \
    --cpu 1 \
    --memory 2 \
    --assign-identity

Get the details for the system-assigned managed identity using az container show and a JMESPath query.

az container show \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-container>" \
    --query "identity"

Review the output from the command. It should include the unique identifiers for the identity and tenant.

{
  "principalId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "type": "SystemAssigned",
  "userAssignedIdentities": null
}

Create a new Bicep file to define a new container instance. Name the file container-instance.bicep. Set these properties for the container instance:

metadata description = 'Create Azure Container Instance resource with system-assigned managed identity.'

@description('Name of the Azure Container Instances resource.')
param instanceName string

resource instance 'Microsoft.ContainerInstance/containerGroups@2023-05-01' = {
  name: instanceName
  location: resourceGroup().location
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    osType: 'Linux'
    containers: [
      {
        name: 'aspnet-sample'
        properties: {
          image: 'mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled'
          resources: {
            requests: {
              cpu: 1
              memoryInGB: 2
            }
          }
        }
      }
    ]
  }
}

output systemAssignedIdentity object = instance.identity    

Create a new Bicep parameters file named container-instance.bicepparam. In this parameters file, create a unique name for your container instance using the instanceName parameter.

using './container-instance.bicep'

param instanceName = '<name-of-new-container-instance>'

Deploy the Bicep template using az deployment group create. Specify the name of the Bicep template, parameters file, and Azure resource group.

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters "container-instance.bicepparam" \
    --template-file "container-instance.bicep"

Review the output from the deployment. The output contains the identity object from the container instance in the properties.outputs.systemAssignedIdentity.value property.

{
  "principalId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "type": "SystemAssigned"
}

Sign in to the Azure portal (https://portal.azure.com).

Enter Azure Container Instances in the global search bar.

Within Services, select Container instances.

In the Container instances pane, select Create.

Within the Basics pane, configure the following options, and then select Review + create:

On the Review + create pane, wait for validation of your account to finish successfully, and then select Create.

The portal automatically navigates to the Deployment pane. Wait for the deployment to complete.

Once the deployment is complete, select Go to resource to navigate to the new Azure Container Instances resource.

Within the pane for the new container instance, select Identity inside the Settings section of the service menu.

In the Identity pane, enable the system-assigned managed identity by setting the Status option to On. Then, select Save and resolve any prompts to commit the change.

Once the system-assigned managed identity is ready, review the value of the Object (principal) ID property. This property's value is the unique identifier for the identity.

Create an object representing a container using New-AzContainerInstanceObject and store it in a variable named $container. Then, use that container object to create a new container instance with New-AzContainerGroup. Configure the account to use a system-assigned managed identity by setting the IdentityType parameter to SystemAssigned.

$parameters = @{
    Name = "aspnet-sample"
    Image = "mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled"
    RequestCpu = 1 
    RequestMemoryInGb = 2
}
$container = New-AzContainerInstanceObject @parameters

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-new-container>"
    Container = $container
    OsType = "Linux"
    Location = "<azure-region>"
    IdentityType = "SystemAssigned"
}
New-AzContainerGroup @parameters

Get the details for the system-assigned managed identity using Get-AzContainerGroup and Format-List selecting only the Identity property.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-container>"
}
Get-AzContainerGroup @parameters | Format-List Identity

Review the output from the command. It should include the unique identifiers for the identity and tenant.

Identity : {
             "principalId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
             "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
             "type": "SystemAssigned"
           }

Use az identity create to create a new user-assigned managed identity in your Azure resource group.

az identity create \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-new-managed-identity>"

Get the list of user-assigned managed identities in your resource group using az identity list

az identity list \
    --resource-group "<name-of-existing-resource-group>"    

Review the output from the command. Record the value of the id field as this fully qualified resource identifier is used to assign the user-assigned managed identity to your Azure resource.

{
  "clientId": "11112222-bbbb-3333-cccc-4444dddd5555",
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned",
  "location": "<azure-location>",
  "name": "msdocs-identity-example-user-assigned",
  "principalId": "cccccccc-dddd-eeee-3333-444444444444",
  "resourceGroup": "msdocs-identity-example",
  "systemData": null,
  "tags": {},
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

Create a Bicep file to define a user-assigned managed identity and name the file user-assigned-managed-identity.bicep. Set these minimal properties:

metadata description = 'Create a user-assigned managed identity.'

param identityName string = uniqueString(subscription().id, resourceGroup().id)

resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
  name: identityName
  location: resourceGroup().location
}

output id string = identity.id
output name string = identity.name

Deploy the Bicep template using az deployment group create. Specify the name of the Bicep template and Azure resource group.

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --template-file "user-assigned-managed-identity.bicep"

Review the output from the deployment. The output contains the unique identifier of the managed identity in the properties.outputs.name.value property. Record this value as it is required to use when creating a new Azure resource later in this guide.

{
  "type": "String",
  "value": "msdocs-identity-example-user-assigned"
}

Enter Managed identity in the global search bar.

Within Services, select Managed identities.

In the Container instances pane, select Create.

Within the Basics pane, configure the following options, and then select Review + create:

On the Review + create pane, wait for validation of your account to finish successfully, and then select Create.

The portal automatically navigates to the Deployment pane. Wait for the deployment to complete.

Wait for the deployment of the managed identity to complete.

Create a new user-assigned managed identity using New-AzUserAssignedIdentity in your Azure resource group.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-new-managed-identity>"
    Location = "<azure-region>"
}
New-AzUserAssignedIdentity @parameters

Use Get-AzUserAssignedIdentity to get a list of user-assigned managed identities in your resource group.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
}
Get-AzUserAssignedIdentity @parameters | Format-List Name, Id

Review the output from the command. Record the value of the Id field as this fully qualified resource identifier is used to assign the user-assigned managed identity to your Azure resource.

Name : msdocs-identity-example-user-assigned
Id   : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned

Create a new app service plan using az appservice plan create.

az appservice plan create \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-new-plan>"

Assign the user-assigned managed identity to a new web app with az webapp create. Use the id field recorded earlier in this guide as the value of the ssign-identity parameter.

az webapp create \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-web-app>" \
    --plan "<name-of-existing-plan>" \
    --assign-identity "<resource-id-recorded-earlier>"

Get the details for all identities assigned to this account using az webapp show and a JMESPath query.

az webapp show \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-account>" \
    --query "identity"   

Review the output from the command. It should include both the user-assigned managed identity.

{
  "principalId": null,
  "tenantId": null,
  "type": "UserAssigned",
  "userAssignedIdentities": {
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned": {
      "clientId": "11112222-bbbb-3333-cccc-4444dddd5555",
      "principalId": "cccccccc-dddd-eeee-3333-444444444444"
    }
  }
}

Create another Bicep file named app-service-web-app.bicep and define an Azure App Service plan and web app. Set these properties for those resources:

metadata description = 'Creates an Azure App Service plan and web app with a user-assigned managed identity.'

@description('The name of the app service plan.')
param planName string

@description('The name of the web app.')
param webAppName string

@description('The name of the user-assigned managed identity.')
param identityName string

resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' existing = {
  name: identityName
}

resource plan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: planName
  location: resourceGroup().location
}

resource webApp 'Microsoft.Web/sites@2023-12-01' = {
  name: webAppName
  location: resourceGroup().location
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity.id}': {}
    }
  }
  properties: {
    serverFarmId: plan.id
  }
}

output userAssignedIdentity object = webApp.identity

Create a Bicep parameters file named app-service-web-app.bicepparam. In this parameters file, create a unique name for your web app and plan using the planName and webAppName parameters respectively. Then, provide the name of the user-assigned managed identity as the value of the identityName parameter.

using './app-service-web-app.bicep'

param planName = '<name-of-new-app-service-plan>'
param webAppName = '<name-of-new-web-app>'
param identityName = '<name-of-existing-managed-identity>'

Deploy the Bicep template using az deployment group create. Specify the name of the Bicep template, parameters file, and Azure resource group.

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters "app-service-web-app.bicepparam" \
    --template-file "app-service-web-app.bicep"

Review the output from the deployment. The output contains the identity object from the container instance in the properties.outputs.userAssignedIdentity.value property.

{
  "type": "UserAssigned",
  "userAssignedIdentities": {
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned": {
      "clientId": "11112222-bbbb-3333-cccc-4444dddd5555",
      "principalId": "cccccccc-dddd-eeee-3333-444444444444"
    }
  }
}

Enter Web app in the global search bar.

Within Services, select App Services.

In the App Services pane, select Create, and then Web App.

Within the Basics pane, configure the following options, and then select Review + create:

On the Review + create pane, wait for validation of your account to finish successfully, and then select Create.

The portal automatically navigates to the Deployment pane. Wait for the deployment to complete.

Once the deployment is complete, select Go to resource to navigate to the new Azure Container Instances resource.

Within the pane for the new container instance, select Identity inside the Settings section of the service menu.

In the Identity pane, select the User assigned option.

Select Add to open a dialog to assign existing user-assigned managed identities. In the dialog, select your existing user-assigned managed identity and then select Add.

Finally, review the list of user-assigned managed identities associated with your web app. It should include the identity's name, resource group name, and subscription identifier.

Use New-AzWebApp to create a new Azure App Service web app.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-new-web-app>"
    Location = "<azure-region>"
}
New-AzWebApp @parameters

Patch the newly created web app to set the identity.type property to UserAssigned and add your existing user-assigned managed identity to the identity.userAssignedIdentities property. To accomplish this task, first provide the id field recorded earlier in this guide as the value of the identityId shell variable. Then, construct a payload object and convert it to JSON. Finally, use Invoke-AzRestMethod with the PATCH HTTP verb to update the existing web app.

$identityId = "<resource-id-recorded-earlier>"

$payload = @{
    identity = @{
        type = "UserAssigned"
        userAssignedIdentities = @{
            "$identityId" = @{}
        }
    }
} | ConvertTo-Json -Depth 3

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-web-app>"
    ResourceProviderName = 'Microsoft.Web'
    ResourceType = 'sites'
    ApiVersion = '2023-12-01'
    Method = 'PATCH'
    Payload = $payload
}
Invoke-AzRestMethod @parameters

Get the details for all identities assigned to the web app using Get-AzWebApp, Select-Object, and ConvertTo-Json selecting only the Identity property.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-web-app>"
}
Get-AzWebApp @parameters | Select-Object Identity | ConvertTo-Json -Depth 3

Review the output from the command. It should include the unique identifiers for the identity and tenant.

{
  "Identity": {
    "Type": "UserAssigned",
    "TenantId": null,
    "PrincipalId": null,
    "UserAssignedIdentities": {
      "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned": {
        "PrincipalId": "cccccccc-dddd-eeee-3333-444444444444",
        "ClientId": "11112222-bbbb-3333-cccc-4444dddd5555"
      }
    }
  }
}