Training
Certification
Microsoft Certified: Identity and Access Administrator Associate - Certifications
Demonstrate the features of Microsoft Entra ID to modernize identity solutions, implement hybrid solutions, and implement identity governance.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
APPLIES TO: NoSQL
Diagram of the sequence of the deployment guide including these locations, in order: Overview, Concepts, Prepare, Role-based access control, Network, and Reference. The 'Prepare' location is currently highlighted.
This article reviews the steps required to create managed identities to use with a deployed application connected to Azure Cosmos DB for NoSQL.
Managed identities are one of many types of identity resources in Microsoft Entra ID for applications to use when connecting to services that support Microsoft Entra authentication. Managed identities can be used in lieu of traditional resource-owned credentials like keys. In Azure, managed identities provide a way for your applications to obtain a Microsoft Entra token to authenticate to Azure services without you needing to write a large amount of authentication code.
You can use Microsoft Entra to authenticate to Azure services including, but not limited to:
You can use managed identities to represent the principal that authenticates to an Azure service from other Azure services including, but not limited to:
Managed identities enable multiple secure scenarios where various Azure services can connect to each other. Some examples include:
For more information, see managed identities for Azure resources.
Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.
If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.
Create a new Azure service with a system-assigned managed identity. This section creates an Azure Container Instances resource.
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": "aaaaaaaa-bbbb-cccc-1111-222222222222",
"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:
Value | |
---|---|
name |
Use a parameter named instanceName |
location |
Set to resource group's location |
identity.type |
SystemAssigned |
properties.osType |
Linux |
properties.containers[0].name |
aspnet-sample |
properties.containers[0].properties.image |
mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled |
properties.containers[0].properties.resources.requests.cpu |
1 |
properties.containers[0].properties.resources.requests.memoryInGB |
2 |
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": "aaaaaaaa-bbbb-cccc-1111-222222222222",
"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:
Value | |
---|---|
Subscription | Select your Azure subscription |
Resource Group | Create a new resource group or select an existing resource group |
Container name | Provide a globally unique name |
Region | Select a supported Azure region for your subscription |
Tip
You can leave any unspecified options to their default values.
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.
Tip
In this example screenshot, the unique identifier for the system-assigned managed identity is bbbbbbbb-1111-2222-3333-cccccccccccc
.
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": "aaaaaaaa-bbbb-cccc-1111-222222222222",
"tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"type": "SystemAssigned"
}
Create a user-assigned managed identity that can be used with one or more Azure services in a portable manner.
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"
}
Note
In this example, the id
value would be /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned
. This example uses fictitious data and your identifier would be distinct from this example.
Create a Bicep file to define a user-assigned managed identity and name the file user-assigned-managed-identity.bicep. Set these minimal properties:
Value | |
---|---|
name |
Use an optional parameter named identityName and generate a unique default value |
location |
Set to resource group's location |
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"
}
Note
In this example, the name.value
would be msdocs-identity-example-user-assigned
. This example uses fictitious data and your identifier would be distinct from this example.
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:
Value | |
---|---|
Subscription | Select your Azure subscription |
Resource Group | Create a new resource group or select an existing resource group |
Region | Select a supported Azure region for your subscription |
Name | Provide a globally unique name |
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
Note
In this example, the Id
value would be /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.ManagedIdentity/userAssignedIdentities/msdocs-identity-example-user-assigned
. This example uses fictitious data and your identifier would be distinct from this example.
Assign the previously created user-assigned managed identity to a new Azure host service. This section creates an Azure App Services web app resource.
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:
Resource | Value | |
---|---|---|
name |
Existing managed identity | Use a parameter named identityName |
name |
App service plan | Use a parameter named planName |
location |
App service plan | Set to resource group's location |
name |
Web app | Use a parameter named webAppName |
location |
Web app | Set to resource group's location |
identity.type |
UserAssigned |
|
identity.userAssignedIdentities.{identity.id} |
{} |
|
properties.serverFarmId |
plan.id |
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:
Value | |
---|---|
Subscription | Select your Azure subscription |
Resource Group | Create a new resource group or select an existing resource group |
Name | Provide a globally unique name |
Plan | Create a new plan or select an existing plan |
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"
}
}
}
}
Training
Certification
Microsoft Certified: Identity and Access Administrator Associate - Certifications
Demonstrate the features of Microsoft Entra ID to modernize identity solutions, implement hybrid solutions, and implement identity governance.