Share via

Reference existing Microsoft Graph resources in Bicep templates

  • Article

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.

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.

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.

Read properties of an existing Microsoft Graph resource

The following steps show how to reference an existing group and application by their unique name in a Bicep file.

  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, which uses the existing keyword to reference the group by its unique name TestGroup-20240816 and the application by TestApp-20240816. This step assumes that the group and application with the specified unique names already exist.

    extension microsoftGraph

@description('Group to use')
param groupName string = 'TestGroup-20240816'

@description('App to use')
param appName string = 'TestApp-20240816'

resource group 'Microsoft.Graph/groups@v1.0' existing = {
    uniqueName: groupName
}

resource application 'Microsoft.Graph/applications@v1.0' existing = {
    uniqueName: appName
}

output groupId string = group.id
output applicationId string = application.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

  DeploymentName          : main
  ResourceGroupName       : exampleRG
  ProvisioningState       : Succeeded
  Timestamp               : 18/04/2024 16:16:42
  Mode                    : Incremental
  TemplateLink            :
  Parameters              :
                          Name             Type                       Value
                          ===============  =========================  ==========
                          groupName        String                     "TestGroup-20240816"
                          appName          String                     "TestApp-20240816"


  Outputs                 :
                          Name             Type                       Value
                          ===============  =========================  ==========
                          group-id         String                     "91ded94c-0144-4422-b33c-c4171447a738"
                          app-id           String                     "cd0bc6bc-fd22-4eb6-9bd3-2f8c5efd6dc9"

You use the ID of the group in the next section.

Update or create a Microsoft Graph resource using settings from existing resources

You might also want to deploy a Microsoft Graph resource and configure some of its properties using the settings from an existing resource. For example, you want to deploy a security group #1 (new deployment or redeployment) with an existing group #2 and service principal #2 as its members. In this case, you use the existing keyword to reference group #2 and service principal #2 and get their IDs, which you then add to the members collection of group #1.

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:

  • Update the uniqueName property for an existing group and application by using Azure CLI or Azure PowerShell.
  • Use the existing keyword in a 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-20240817 and TestApp-20240817, respectively. Assume the group and application are group #2 and parent app of service principal #2 from the preceding scenario.

# 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-20240817\"}' --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-20240817\"}' --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 microsoftGraph

// TEMPLATE OVERVIEW: 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-20240817'
}

// existing SP #2 to be added as a member
resource application 'Microsoft.Graph/applications@v1.0' existing = {
  uniqueName: 'TestApp-20240817'
}
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