Share via

Onboard existing Microsoft Graph resources for use in Bicep templates

  • Article

You can reference existing Microsoft Graph resources in Bicep templates by the supported client-provided key property. Resources created via HTTP POST might not have this property set and require a one-time backfill.

Once set, the client-provided key property allows the resource to be declared in a Bicep file for redeployment. To read properties of the resource without redeploying, use the existing keyword.

In this article, you learn how to use the existing keyword and the client-provided key to read the properties of existing Microsoft Graph resources.

Important

Microsoft Graph Bicep is currently in PREVIEW. See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

Bicep lets you read existing resources by using the existing keyword. For Microsoft Graph resources, the resources must first be uniquely identified by a client-provided key property.

Prerequisites

  • Have an Azure subscription. If you don't have one, you can create a free account.
  • Have the least privileged permissions or roles to either read or update the existing resource, or be the owner of the resource. Consult Least privileged roles by task and Default user permissions to see what roles you need to be assigned.
  • Install Bicep tools for authoring and deployment. This quickstart uses VS Code with the Bicep extension for authoring and Azure CLI for deployment. Samples are also provided for Azure PowerShell.
  • You can deploy the Bicep files interactively or via zero-touch (app-only) deployment.

Onboard existing Microsoft Graph resources and use those resources in a Bicep file

In this example, you might have some Microsoft Graph resources that were not created through a Bicep file deployment, that you now need to use or manage in a Bicep file. For example, you want to update an existing application or deploy security group #1 (new deployment or redeployment) with an existing group #2 and service principal #2 as its members.

To reference the existing group #2 in a Bicep file, it must have its uniqueName property set. To reference existing service principal #2 if you don't know its appId, its parent application must have its uniqueName property set.

In this section, you:

  • Add the uniqueName property for an existing group and application by using Azure CLI or Azure PowerShell.
  • Update the existing application in a Bicep file.
  • Use the existing keyword in the same Bicep file to get the ID of an existing group and service principal.
  • In the Bicep file, configure the settings to deploy a security group with an existing group and service principal as its members, and the service principal as its owner.
  • Deploy the Bicep file.

Step 1: Set the uniqueName property for the group and application

The following request sets the uniqueName for an existing group and application to TestGroup-20241202 and TestApp-20241202, respectively.

Important

The client-provided key property uniqueName cannot be changed once set.

# Sign in to Azure
az login

## Create a resource group
az group create --name exampleRG --location eastus

## Update the uniqueName property of the group and application
## Note: Replace cec00de2-08b9-4081-aaf5-55d78ac9b4c4 and 25ae6414-05a1-4cce-9899-ad11d9eedde2 with IDs for your group and application.
az rest --method patch --url 'https://graph.microsoft.com/v1.0/groups/cec00de2-08b9-4081-aaf5-55d78ac9b4c4' --body '{\"uniqueName\": \"TestGroup-20241202\"}' --headers "content-type=application/json"
az rest --method patch --url 'https://graph.microsoft.com/v1.0/applications/25ae6414-05a1-4cce-9899-ad11d9eedde2' --body '{\"uniqueName\": \"TestApp-20241202\"}' --headers "content-type=application/json"

Step 2: Add existing group and service principal to members and owners of another group

You can now use the existing keyword to reference existing group #2 and service principal #2, get their IDs, and add them to the owners and members collections of another group.

  1. Launch VS Code and create two new files, main.bicep and bicepconfig.json, making sure that they are in the same folder.

  2. Enable some preview features by configuring bicepconfig.json:

    {
  "experimentalFeaturesEnabled": {
      "extensibility": true
  }
}

  3. In main.bicep, add the following Bicep code.

    extension 'br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:0.1.8-preview'

// TEMPLATE OVERVIEW: Updates an existing app and 
// uses existing group and existing SP and sets them as members of another group

// existing group #2 to be added as a member
resource groupMember 'Microsoft.Graph/groups@v1.0' existing = {
  uniqueName: 'TestGroup-20241202'
}

// existing application to be updated with a new display name
// and for its SP #2 to be added as a member (to group #1)
resource application 'Microsoft.Graph/applications@v1.0' = {
  uniqueName: 'TestApp-20241202'
  displayName: 'Updating the displayName to something new'
}
resource servicePrincipalMember 'Microsoft.Graph/servicePrincipals@v1.0' existing = {
  appId: application.appId
}

// Add preceding service principal and group as members of another group
// Add preceding service principal as owner of the group. 
// If Group-1 uniqueName doesn't exist, this is a new deployment.
// If Group-1 uniqueName exists, this is a redeployment/update. For redeployments, existing members and owners are retained.
resource group 'Microsoft.Graph/groups@v1.0' = {
  displayName: 'Group-1'
  mailEnabled: false
  mailNickname: 'Group-1'
  securityEnabled: true
  uniqueName: 'Group-1'
  members: [groupMember.id, servicePrincipalMember.id]
  owners: [servicePrincipalMember.id]
}

  4. Deploy the Bicep file using Azure CLI or Azure PowerShell.

    ## Create a resource group
az group create --name exampleRG --location eastus

## Deploy the Bicep file
az deployment group create --resource-group exampleRG --template-file main.bicep

When the deployment finishes, you should see a message indicating the deployment succeeded.

Related content