Quickstart: Create and deploy your first Bicep file with Microsoft Graph resources
In this quickstart, you create a Bicep file that declares a Microsoft Entra security group and a managed service identity (MSI), representing a Microsoft Graph resource and an Azure resource respectively. You then add the MSI as an owner of the group. You also learn how the Bicep extension simplifies development by providing type safety, syntax validation, and autocompletion. Finally, you deploy the Bicep file using a signed-in user.
Important
This quickstart article uses dynamic type references instead of built-in types which are deprecated and will be retired on January 24, 2025. Until the retirement date, built-in types, denoted by extension microsoftGraph, will coexist with the new dynamic types. If any of your existing Bicep files use built-in types, switch to using dynamic types to avoid any future Bicep file deployment issues.
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.
Prerequisites
Have a valid Azure subscription: If you don't own an Azure subscription, create a free account before you begin.
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. The minimum required Bicep version is v0.30.3.
Have a Microsoft Entra role that assigns you permissions to create a security group. Users have this permission by default. However, admins can turn off this default in which case you need to be assigned at least the Groups Administrator role.
Add a Microsoft Graph application group
Launch VS Code and create two new files, main.bicep and bicepconfig.json in the same folder.
Next, to be able to declare Microsoft Graph resources in a Bicep file, you need to enable the Bicep preview feature and specify the Microsoft Graph Bicep type versions, by configuring bicepconfig.json.
This sample uses the v1.0 resources and declares a user-friendly extension name "microsoftGraphV1_0" to reference the br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:0.1.8-preview type version in the Microsoft Artifact Registry.
{
"experimentalFeaturesEnabled": {
"extensibility": true
},
// specify an alias for the version of the v1.0 dynamic types package you want to use
"extensions": {
"microsoftGraphV1_0": "br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:0.1.8-preview"
}
}
You can also declare Microsoft Graph resources from beta and v1.0 in the same Bicep file by adding another reference to a beta type version from the Microsoft Artifact Registry.
In main.bicep, type extension microsoftGraphV1_0, where microsoftGraphV1_0 is your user-friendly name for referencing the dynamic types package in the Microsoft Artifact Registry. The extension statement lets the Bicep compiler know that you're including the Microsoft Graph types you defined in bicepconfig.json. On the next line, define a resource by using the resource keyword. Type resource exampleGroup and add a space.
extension microsoftGraphV1_0
resource exampleGroup
When you add a space after the symbolic name, a list of resource types is displayed. Continue typing group until you can select Microsoft.Graph/Groups from the available options.
Tip
If you don't see the intellisense options in VS Code, make sure you've installed the Bicep extension as specified in Prerequisites. If you have installed the extension, give the Bicep language service some time to start after opening your Bicep file. A notification in the lower right corner indicates that the service is starting. When that notification disappears, the service is running.
After selecting Microsoft.Graph/Groups, you're presented with the available API versions - beta or v1.0. Always select v1.0 unless it's unavailable or the resource properties you need are only available in beta. For this quickstart, use v1.0.
After the single quote for the resource type, add = and a space. You're presented with options for adding properties to the resource. Select required-properties.
This option adds all of the properties for the resource type that are required for deployment. After selecting this option, your group has the following properties:
resource exampleGroup 'Microsoft.Graph/groups@v1.0' = {
displayName:
mailEnabled:
mailNickname:
securityEnabled:
uniqueName:
}
Provide values for those properties, setting mailEnabled to false and securityEnabled to true. uniqueName represents an immutable client-provided key for this group resource.
Add a managed identity resource
VS Code with the Bicep extension simplifies development by providing predefined snippets, such as a snippet that creates a managed identity. In main.bicep, type man, and then select res-managed-identity from the list, and then press [TAB] or [ENTER].
Note: Resource snippets for extensible resources, like Microsoft Graph resources, aren't currently supported.
Your Bicep file now contains the following code:
resource managedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2018-11-30' = {
name: 'name'
location: location
}
You can fix the missing parameter definition error by adding a parameter definition for location. Under the extension definition, add param location string = resourceGroup().location. For more information about the function used here, see resourceGroup(). Change the name for the managed identity from name to exampleManagedIdentity.
Make the managed identity an owner of the group resource
In the exampleGroup resource, create a new line under uniqueName, type ow, which shows owners as the only matching property option, and then press [TAB] or [ENTER].
The owners property is an array, so add [] and now reference the managed identity's principal ID using intellisense, by typing m and picking managedIdentity (the symbolic name for the managed identity), typing a . and picking properties, typing another . and picking principalId.
Your main.bicep file should now look something like:
extension microsoftGraphV1_0
param location string = resourceGroup().location
resource exampleGroup 'Microsoft.Graph/groups@v1.0' = {
displayName: 'My example group'
mailEnabled: false
mailNickname: 'my-example-group'
securityEnabled: true
uniqueName: 'myExampleGroup'
owners: [managedIdentity.properties.principalId]
}
resource managedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2018-11-30' = {
name: 'exampleManagedIdentity'
location: location
}
Deploy the Bicep file using a signed-in user
Deploy the Bicep file by signing in to Azure CLI or Azure PowerShell using the following examples. The Azure CLI examples in this documentation use the Bash console.
## Sign in to Azure CLI
az login
## 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.
Note
Due to replication delays, adding the managed service identity (MSI) as an owner of the Microsoft Entra group may cause the deployment to fail. Wait a little and then deploy the same Bicep file again.
Clean up resources
When the Azure resources are no longer needed, use the Azure CLI or Azure PowerShell module to delete the quickstart resource group.
Note
Resource groups are an Azure concept and have no impact on Microsoft Graph resources. Microsoft Graph resources need to be cleaned up with an additional request to Microsoft Graph. For this you can use Azure CLI or Azure PowerShell, Microsoft Graph CLI, or Microsoft Graph PowerShell.
The following examples show commands to delete the Azure resource first then the Microsoft Graph resource using Azure CLI and Azure PowerShell.
## Delete the resource group
az group delete --name exampleRG
## Delete the Microsoft Graph group
az rest --method delete --url 'https://graph.microsoft.com/v1.0/groups%28uniqueName=%27myExampleGroup%27%29'