Merge pull request #212 from microsoftgraph/dkershaw10-users-sample

Sample demonstrating the new Users bicep type

Author: dkershaw10

quickstart-templates/security-group-add-user-members/README.md

@@ -0,0 +1,47 @@
+# Configure a security group's user members, referencing users by UPN
+
+This sample demonstrates use of the read-only [`Microsoft.Graph/Users` bicep type][users-ref] which allows you to
+fetch `user` resources by their user principal name (UPN).
+
+This quickstart creates a security group and adds users, referenced via their UPNs, as members.
+The list of users to be added as members are in a txt file, with each user's UPN on a separate line.
+Replace the UPN values in the example "userlist.txt" file with user UPN values from your tenant, before deployment.
+
+## Details
+
+This template sample:
+
+1. Creates a user UPN list from a txt file.
+2. Creates/updates a security group with its members set based on the user UPN list
+
+**NOTE:** Due to current modelling limitations [no more than 20 members can be added/updated at a time][20-members], and only [update semantics][update-only] are supported for members (and owners).
+
+### Prerequisites
+
+- A valid **Azure subscription**: If you don't own an Azure subscription, [create a free account](https://azure.microsoft.com/free/) before you begin.
+- An **Azure resource group** that you own under a valid Azure subscription, or [deploy without an Azure subscription][no-azure-sub].
+- [Bicep tools for authoring and deployment](https://learn.microsoft.com/graph/templates/quickstart-install-bicep-tools). The minimum required Bicep version is [v0.32.4](https://github.com/Azure/bicep/releases/tag/v0.32.4).
+- Have the requisite **Microsoft Entra roles** to deploy this template:
+
+  - Permissions to create security groups. [Users have this permission by default](https://learn.microsoft.com/entra/fundamentals/users-default-permissions#compare-member-and-guest-default-permissions). However, [admins can turn off this default](https://learn.microsoft.com/entra/fundamentals/users-default-permissions#restrict-member-users-default-permissions) in which case you need to be assigned at least the [Groups Administrator](https://learn.microsoft.com/entra/identity/role-based-access-control/permissions-reference#groups-administrator) role.
+
+### Deploy the Bicep template
+
+Before deploying the template, you **must** replace the UPN values in the example "userlist.txt" file with user UPN values from your tenant.
+
+##### Az CLI
+
+```sh
+az deployment group create --resource-group <resource-group> --template-file main.bicep --parameters date='2025-01-24'
+```
+
+##### Az Powershell
+
+```powershell
+New-AzResourceGroupDeployment -ResourceGroupName <resource-group> -TemplateFile .\main.bicep -date "2025-01-24"
+```
+
+[update-only]:https://learn.microsoft.com/graph/templates/known-issues-graph-bicep#deployment-behavior-group-members-and-owners-are-append-only
+[20-members]:https://learn.microsoft.com/graph/templates/limitations#no-more-than-20-members-andor-owners-can-be-declared-for-a-groups-resource
+[no-azure-sub]:https://learn.microsoft.com/graph/templates/how-to-deploy-without-azure-sub?view=graph-bicep-1.0&tabs=CLI
+[users-ref]:https://learn.microsoft.com/graph/templates/reference/users?view=graph-bicep-1.0

quickstart-templates/security-group-add-user-members/bicepconfig.json

@@ -0,0 +1,9 @@
+{
+    "experimentalFeaturesEnabled": {
+        "extensibility": true
+    },
+    // specify an alias for the version of the v1.0 dynamic types package you want to use
+    "extensions": {
+      "microsoftGraphV1": "br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:0.1.9-preview"
+    }
+}

quickstart-templates/security-group-add-user-members/main.bicep

@@ -0,0 +1,42 @@
+extension microsoftGraphV1
+
+// TEMPLATE OVERVIEW:
+// Creates a security group and adds the referenced users as members.
+// The user list are in a txt file, with each user's UPN on a separate line.
+// Replace example userlist.txt file values with user UPNs from your tenant.
+
+@description('Today\'s date used to configure a unique daily app name')
+param date string
+
+// File name/path must be a compile time constant, so this cannot be a param
+var userListFilename = 'userlist.txt'
+
+// Load a text file with a list of users separated by newlines
+var upnListFromFile = loadTextContent(userListFilename)
+var upnList = split(upnListFromFile,'\r\n')
+var upnListLength = length(upnList)
+
+var groupName = 'sg-${date}-${uniqueString(deployer().objectId, 'group')}'
+
+// create a users object list, looking up by the list of UPNs
+// Referencing a user resource that doesn't exist results in a "NotFound" error and deployment failure.
+// Check the name and scope of the resource you're trying to reference. 
+// See https://learn.microsoft.com/azure/azure-resource-manager/bicep/existing-resource
+resource userList 'Microsoft.Graph/[email protected]' existing = [for upn in upnList: {
+  userPrincipalName: upn
+}]
+
+// create security group and add user list as members
+resource group 'Microsoft.Graph/[email protected]' = {
+  displayName: groupName
+  mailEnabled: false
+  mailNickname: uniqueString(groupName)
+  securityEnabled: true
+  uniqueName: groupName
+  members: [for i in range(0, upnListLength): userList[i].id]
+}
+
+// outputs
+output addedUserList array = upnList
+output groupName string = group.displayName
+output groupId string = group.id

quickstart-templates/security-group-add-user-members/userlist.txt

@@ -0,0 +1,3 @@
+[email protected]
+[email protected]
+[email protected]