This tool enables admins to sync the membership of Microsoft 365 Groups using one or more security groups that may or may not be nested, and keep the memberships current by syncing with the source groups at regular intervals.

Please read before proceeding

• The tool is based on .Net, Azure Functions and Azure Table Storage. All of these are requirements and must be deployed by the customer onto their Azure subscription.
• The tool interacts with Microsoft cloud using Graph APIs as data source. The app needs to be onboarded and granted permissions by the customer tenant admin.
• The tool allows specifying the source security groups, destination Microsoft 365 Group, frequency of sync, start date of sync.
• Microsoft is releasing the tool without support, other than answering questions about how we use it internally. Link to the demo video: Making IT more efficient with improvements to Microsoft 365 Groups.

Limitations:

• Note that this tool can not use on-premise mastered SGs as destination groups since we are not able to add GMM Graph application (see "Create <solutionAbbreviation>-Graph-<environmentAbbreviation> Azure Application" section.) as owner to such groups as the owner does not sync to AAD.

• Azure Subscription - Try Azure.

• Azure DevOps - Try Azure DevOps Services

  To follow these steps you will need to sign in to Azure Portal and Azure DevOps Portal with an account that has permissions to create new Azure resources.

• Powershell v5.1 or later Download and install Windows PowerShell 5.1

If you would like to customize GMM code, you could do so by using any of the following IDEs:

• Visual Studio Community, Professional or Enterprise Edition(s)
• Visual Studio Code

You can download Visual Studio or Visual Studio Code from here Download.

Currently GMM is targeting .NET SDK version 3.1.405, this is being set in global.json, you can download this specific version from Download .NET Core 3.1 or alternatively download the latest version and update the global.json file.

To find out what .NET SDK versions you currently have installed run this command from the command line:

dotnet --list-sdks

Navigate to GMM repository here to download the source code.

You can download the code as a zip file or clone the repository using this command:

git clone --bare https://github.com/microsoftgraph/group-membership-management.git

The code is provided with three sample environments:

• int - integration
• ua - user acceptance
• prodv2 - production

These names must not be reused, see 'Resource groups' for more details.

The steps in this document will setup a single environment i.e. prodv2, if you would like to setup other enviroments i.e. int and ua, you will need to go through these steps again replacing <EnvironmentAbbreviation> accordingly.

If you would like to add additional environments, follow these steps:

1. Locate and open file vsts-cicd.yml

2. Locate int environment yaml/deploy-pipeline.yml template.

    - template: yaml/deploy-pipeline.yml
    parameters:
        solutionAbbreviation: '$(SolutionAbbreviation)'
        environmentAbbreviation: 'int'
        location: 'westus2'
        serviceConnection: '$(SolutionAbbreviation)-serviceconnection-int'
        dependsOn: BuildFunctions
        stageName: 'int'
        functionApps:
        - name: 'JobTrigger'
        - name: 'GraphUpdater'
        - name: 'SecurityGroup'
        condition: |
        and(
            succeeded('BuildFunctions'),
            eq(variables['Build.SourceBranch'], 'refs/heads/develop'),
            in(variables['Build.Reason'], 'IndividualCI', 'Manual')
        )
   

3. Copy and paste the template located in step two, then replace the values for these settings accordingly using the name of your new environment.

   • environmentAbbreviation
   • serviceConnection
   • stageName

   Save your changes.

4. Navigate to these locations

   • Infrastructure\data\parameters
   • Service\GroupMembershipManagement\Hosts\GraphUpdater\Infrastructure\data\parameters
   • Service\GroupMembershipManagement\Hosts\GraphUpdater\Infrastructure\compute\parameters
   • Service\GroupMembershipManagement\Hosts\JobTrigger\Infrastructure\data\parameters
   • Service\GroupMembershipManagement\Hosts\JobTrigger\Infrastructure\compute\parameters
   • Service\GroupMembershipManagement\Hosts\SecurityGroup\Infrastructure\data\parameters
   • Service\GroupMembershipManagement\Hosts\SecurityGroup\Infrastructure\compute\parameters

   For each location copy the file named parameters.int.json and rename it to parameters.<your-new-environment-name>.json

If you would like to remove environments, follow these steps:

1. Locate and open file vsts-cicd.yml

2. Locate the yaml/deploy-pipeline.yml template for the environment you would like to delete.

    - template: yaml/deploy-pipeline.yml
    parameters:
        solutionAbbreviation: '$(SolutionAbbreviation)'
        environmentAbbreviation: 'int'
        location: 'westus2'
        serviceConnection: '$(SolutionAbbreviation)-serviceconnection-int'
        dependsOn: BuildFunctions
        stageName: 'int'
        functionApps:
        - name: 'JobTrigger'
        - name: 'GraphUpdater'
        - name: 'SecurityGroup'
        condition: |
        and(
            succeeded('BuildFunctions'),
            eq(variables['Build.SourceBranch'], 'refs/heads/develop'),
            in(variables['Build.Reason'], 'IndividualCI', 'Manual')
        )
   

3. Delete the template and save your changes. You might need to update any templates that had a dependency on the deleted template. For instance dependsOn and condition settings in prodv2 template reference ua, so these would need to be updated in case ua was removed.

4. Navigate to these locations

   • Infrastructure\data\parameters
   • Service\GroupMembershipManagement\Hosts\GraphUpdater\Infrastructure\data\parameters
   • Service\GroupMembershipManagement\Hosts\GraphUpdater\Infrastructure\compute\parameters
   • Service\GroupMembershipManagement\Hosts\JobTrigger\Infrastructure\data\parameters
   • Service\GroupMembershipManagement\Hosts\JobTrigger\Infrastructure\compute\parameters
   • Service\GroupMembershipManagement\Hosts\SecurityGroup\Infrastructure\data\parameters
   • Service\GroupMembershipManagement\Hosts\SecurityGroup\Infrastructure\compute\parameters

   For each location select the file for the environment you would like to delete (parameters.<EnvironmentAbbreviation>.json) and delete the file.

GMM logically separates the resources it uses into three resource groups.

• prereqs
• data
• compute

Throughout this document we will use these tokens <SolutionAbbreviation>, <ResourceGroupName>, <EnvironmentAbbreviation>as place holders, when setting up GMM you will need to provide the value for each one of them as they will be used to name the Azure resources. Some Azure resources require to have a unique name across all tenants globally. So please avoid using the names used on this document as they are already in use.

• <SolutionAbbreviation> - This is a name prefix (2 to 3 characters long) the current default value is 'gmm'. To change this value see the Notes section below for more information on how to do that.
• <ResourceGroupName> - This is the name of the resource group, the current values supported are prereqs, data, and compute.
• <EnvironmentAbbreviation> - This the name of your environment (2 to 6 characters long), use a unique value here to prevent name collisions. See the Notes section below for more information on how to set the value for this setting.

The naming convention for the resource groups and other resources is <SolutionAbbreviation>-<ResourceGroupName>-<EnvironmentAbbreviation>, i.e gmm-data-ua, gmm-data-prod, gmm-compute-prod.

A PowerShell script has been provided to create the resource groups, see section 'Resource Groups and prereqs keyvault creation script'.

We create these resource groups in order for the ARM templates to be able to create additional resources and deploy the code.

You will need to replace <SolutionAbbreviation> and <EnvironmentAbbreviation> with the values you would like to use.

Currently <SolutionAbbreviation> default value is 'gmm'. To change this value, update the solutionAbbreviation variable in vsts-cicd.yml file. You can make this change as part of 'Getting GMM code ready' step.

<SolutionAbbreviation> currently support names of 2 or 3 characters long. <EnvironmentAbbreviation> currently support names from 2 to 6 characters long. This can be changed in the ARM templates (template.json) by updating the minLength and maxLength settings for solutionAbbreviation and environmentAbbreviation parameters.

We recommend trying to use unique <SolutionAbbreviation> and <EnvironmentAbbreviation> names, since some resources in Azure require to have unique names globally so it is possible to have name collisions.

The changes required are:

• Rename the parameter files provided (parameters.int.json, parameters.ua.json and parameters.prodv2.json) updating the environment part. parameters.<EnvironmentAbbreviation>.json.
  The files are located in these folders:
  • Infrastructure\data\parameters
  • Service\GroupMembershipManagement\Hosts\GraphUpdater\Infrastructure\data\parameters
  • Service\GroupMembershipManagement\Hosts\GraphUpdater\Infrastructure\compute\parameters
  • Service\GroupMembershipManagement\Hosts\JobTrigger\Infrastructure\data\parameters
  • Service\GroupMembershipManagement\Hosts\JobTrigger\Infrastructure\compute\parameters
  • Service\GroupMembershipManagement\Hosts\SecurityGroup\Infrastructure\data\parameters
  • Service\GroupMembershipManagement\Hosts\SecurityGroup\Infrastructure\compute\parameters
• Update vsts-cicd.yml settings.
  • environmentAbbreviation
  • serviceConnection
  • stageName
  • dependsOn (update for prodv2)
  • condition (update for prodv2)

Each resource group will have a corresponding keyvault; The naming convention for the keyvault is the same as the resource groups. In this step we are going to create only the <SolutionAbbreviation>-prereqs-<EnvironmentAbbreviation> keyvault since it needs to be populated before deploying the ARM templates. The keyvault must be created under the corresponding resource group, in this case <SolutionAbbreviation>-prereqs-<EnvironmentAbbreviation> resource group.

These two keyvaults are created by the ARM templates, so no action is needed for these two.

• <SolutionAbbreviation>-data-<EnvironmentAbbreviation>
• <SolutionAbbreviation>-compute-<EnvironmentAbbreviation>

This script is going to create the Azure resource groups required to setup GMM. From your PowerShell command prompt navigate to the Scripts folder then type these commands:

1. . ./Set-Environment.ps1
2. Set-Environment  -solutionAbbreviation "<solutionAbbreviation>" `
                    -environmentAbbreviation "<environmentAbbreviation>" `
                    -objectId "<objectId>" `
                    -resourceGroupLocation "<resourceGroupLocation>"

<objectId> is the Azure Object Id of the user, group or service principal to which access to the prereqs keyvault is going to be granted. This object Id must be located in the same Azure tenant where the keyvault is going to be created. <resourceGroupLocation> is the Azure location where the resources are going to be created. Please refer to this documentation to know the available resource locations.

If you get an error stating "script is not digitally signed" when running any of the provided PowerShell scripts, try running this cmdlet

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

We need to create a certificate that is going to be used for authentication, we are going to use the prereqs keyvault to create and store the certificate. Take note of the certificate name since we need to provide it in the next step. See Quickstart: Set and retrieve a certificate from Azure Key Vault using the Azure portal documentation.

You can also use an existing certificate and upload it to the prereqs keyvault, you will need to provide a friendly certificate name that we will need in the next step.

Once the certificate is created, we need to run this PowerShell script in order to create a new application that is going to enable GMM to access Microsoft Graph API, it will also save these settings in the prereqs keyvault.

• graphAppClientId
• graphAppCertificateName
• graphAppTenantId

From your PowerShell command prompt navigate to the Scripts folder then type these commands:

1. . ./Set-GraphCredentialsAzureADApplication.ps1
2. Set-GraphCredentialsAzureADApplication	-SubscriptionName "<SubscriptionName>" `
                                            -SolutionAbbreviation "<SolutionAbbreviation>" `
                                            -EnvironmentAbbreviation "<EnvironmentAbbreviation>" `
                                            -TenantIdToCreateAppIn "<TenantId>" `
                                            -TenantIdWithKeyVault "<TenantId>" ` 
                                            -CertificateName "<CertificateName>" `
                                            -Verbose
	    									
Follow the instructions on the screen.

Once your application is created we need to grant the requested permissions to use Microsoft Graph API.

1. In the Azure Portal navigate to your 'Azure Active Directory'. If you don't see it on your screen you can use the top search bar to locate it.
2. Navigate to 'App registrations' blade on the left menu.
3. Click on 'All applications" to locate and open your <solutionAbbreviation>-Graph-<environmentAbbreviation> application.
4. On your application screen click on 'API permissions' blade on the left menu.
5. Click on the 'Grant admin consent for <YourOrganizationName>' button.
6. You might need to refresh the page to see the permissions status updated.

We need to upload the certificate to the -Graph- application, in order to do that we need to export it from the prerqs keyvault.

Exporting the certificate:

1. In the Azure Portal navigate to your prereqs keyvault, it will be named following this convention -prereqs-.
2. Locate and click on the Certificates blade on the left menu.
3. Click on your certificate from the list.
4. Click on the latest version.
5. On the top menu click on 'Download in CER format' button to download the certificate.

If you need more details on how to export the certificate please see Quickstart: Set and retrieve a certificate from Azure Key Vault using the Azure portal documentation.

Uploading the certificate:

1. In the Azure Portal navigate to your 'Azure Active Directory'. If you don't see it on your screen you can use the top search bar to locate it.
2. Navigate to 'App registrations' blade on the left menu.
3. Click on 'All applications" to locate and open your <solutionAbbreviation>-Graph-<environmentAbbreviation> application.
4. On your application screen click on 'Certificates and secrets' blade on the left menu.
5. Click on the 'Upload certificate' button.
6. Locate and add your certificate.

• Sign in to Azure DevOps

• Install Build Quality Checks

  The pipeline provided with GMM uses Build Quality Checks to add quality gates to the build process.

  You can install Build Quality Checks from here.
  At the time of writing this document the latest version was 8, make sure to update mspremier.BuildQualityChecks.QualityChecks-task.BuildQualityChecks@<version> to the latest one in build-services.yml and build-functionapps.yml.

• Create a project

  • You can use an existing project in your organization.
  • To create a new project see Create a project in AzureDevOps documentation.

• Create a repository

  • Once your project is created in the previous step, it will have an empty repository, we are going to need a repository in the nexts steps, you can use this one or if you prefer to create a new one see Create a new Git repo in your project documentation.

  Make sure to take note of your repository since we are going to need it to push GMM code to it.

• Getting GMM code ready

  GMM uses ARM templates to create all the resources it needs. It requires you to provide information specific to your Azure Subscription in order to create these resources.

  Before being able to deploy GMM code to your environment you will need to provide several parameters to the ARM templates responsible of creating the resources.

  Locate GMM code, it has the following structure.

  • Documentation
  • Infrastructure
    • data
      • parameters
  • Scripts
  • Service
    • Hosts
      • JobTrigger
  • yaml

  Under Service folder, locate Hosts folder, this folder may contain one or more folders each representing a function, all of them will follow the same folder structure, open a function folder (i.e. JobTrigger) and locate the Infrastructure folder, this folder might contain a compute and data folder, similar to what we just did, review the parameters files on both compute and data folders, and provide the required values specific to your environment. This needs to be done to all the functions that may be present under Hosts folder.

  Infrastructure folder contains all the ARM templates, it has separate folders for data and compute resources, which in turn have a parameters folder.

  Note:
  Currently <SolutionAbbreviation> default value is 'gmm'. To change this value, update the solutionAbbreviation variable in vsts-cicd.yml file.

• Pushing GMM code to your repository

  In order to push GMM code to your repository see Manually import a repo documentation.

• Create an "Azure Resource Manager" Service Connection

  • In order be able to deploy GMM resources through a pipeline we need to create a Service Connection and grant permissions to it.

  GMM provides a PowerShell script to accomplish this.

  1. Set-ServicePrincipalAndServiceConnection.ps1

     This script will create a new service principal and a service connection.
     It takes these arguments <SolutionAbbreviation>, <EnvironmentAbbreviation>, <OrganizationName>, <ProjectName>.

     <OrganizationName> - This is the name of your organization used in Azure DevOps.
     <ProjectName> - This is the name of the project in Azure DevOps we just created in a previous step.

     From your PowerShell command prompt navigate to the Scripts folder then type these commands:

     1. . ./Set-ServicePrincipalAndServiceConnection.ps1
     2. Set-ServicePrincipalAndServiceConnection -SolutionAbbreviation "<SolutionAbbreviation>"  `
     		                              -EnvironmentAbbreviation "<EnvironmentAbbreviation>" `
     		                              -OrganizationName "<OrganizationName>" `
     		                              -ProjectName "<ProjectName>" `
     		                              -Verbose
     
     Follow the instructions on the screen.
     

     Locate the service connection name on the screen. It follows this naming convention: <SolutionAbbreviation>-serviceconnection-<EnvironmentAbbreviation>.

• Email Notification

  In order to notify the requestor regarding the synchronization job status, please follow the steps in this documentation.

• Create a pipeline

  In Azure DevOps we need to create a pipeline that will create your resources and deploy your code.

  • See Create your first pipeline documentation.

    1. On Azure DevOps left menu locate and click on Pipelines.

    2. Click on 'Create Pipeline' or 'New Pipeline' depending on which one is presented to you.

    3. Select Azure Repos Git as your code location.

    4. Select the repository created in the previous step.

    5. From the list of options select 'Existing Azure Pipelines YAML file'.

    6. Select your branch.

    7. Select '/vsts-cicd.yml' in the Path field.

    8. Click continue.

    9. You will be presented with the "Review your pipeline YAML" screen. Locate and click on the "Variables" button on the top right side of your screen. We need to create the variables used by the pipeline.

       location - This is your Azure location where the resources are going to be created.  
       
       tenantId - This is your Azure Active Directory tenant Id, where GMM Azure resources were created.  
       
       keyVaultReaders_prod - This is a list of service principals that will have access to the keyvaults in production environment. i.e. your own Azure user id, an Azure group id.
       
       keyVaultReaders_nonprod - This is a list of service principals that will have access to the keyvaults in non-production environments. i.e. your own Azure user id, an Azure group id.
       
       This variable's value is a JSON string that represents an array, notice that each object in the array has two properties:
       
       objectId: This is the group or user object id.
       permissions: This is the list of permissions that will be set.
       
       You can add or remove objects from the json array as needed.
       
        [
            {
            "objectId": "<object-id-1>",
            "permissions": [ "get", "set", "list" ]
            },
            {
            "objectId": "<object-id-2>",
            "permissions": [ "get", "set", "list" ]
            }
        ]
       

       To find the group or user id in Azure follow these steps:

       1. In the Azure Portal navigate to your 'Azure Active Directory'. If you don't see it on your screen you can use the top search bar to locate it.
       2. For users locate the 'Users' blade and for groups locate the 'Groups' blade on the left menu.
       3. Search for the name of the user or group and select it from the results list.
       4. Locate the Object ID field. This is the value that you will need to copy.

    10. Click on the "New variable" button. Provide the name and value, then click on the "OK" button. To add a new variable click on the button with the plus sign icon.

    11. Once all variables have been created click on the "Save" button.

    12. Run your pipeline.

    When running the pipeline for the first time you might be prompted to authorize resources, click on "Authorize resources" buttons.

Once the pipeline has completed building and deploying GMM code and resources to your Azure resource groups, we need to make some final configuration changes.

Once your Function App <SolutionAbbreviation>-compute-<EnvironmentAbbreviation>-SecurityGroup has been created we need to grant it access to the Queue and Topic.

QueueName: membership
TopicName: syncjobs
FunctionAppName: <SolutionAbbreviation>-compute-<EnvironmentAbbreviation>-SecurityGroup

1. . ./Set-ServiceBusManagedIdentityRoles.ps1
2. Set-ServiceBusManagedIdentityRoles  -SolutionAbbreviation "<SolutionAbbreviation>" `
                                    -EnvironmentAbbreviation "<EnvironmentAbbreviation>" `
                                    -FunctionAppName "<FunctionAppName>" `
                                    -QueueName "membership" `
                                    -TopicName "syncjobs" `
                                    -Verbose

In the event that you need to grant access to the queue and topic to an Azure active directory group (i.e. a group that contains your development team) in your tenant, you may need to use the provided powershell script below:

1. . ./Set-ServiceBusManagedIdentityRolesToADGroup.ps1
2. Set-ServiceBusManagedIdentityRolesToADGroup  -SolutionAbbreviation "<SolutionAbbreviation>" `
                                    -EnvironmentAbbreviation "<EnvironmentAbbreviation>" `
                                    -GroupName "<GroupName>" `
                                    -QueueName "membership" `
                                    -TopicName "syncjobs" `
                                    -Verbose

Once GMM is up and running you might want to start creating synchronization jobs for your groups.

A synchronization job must have the following properties populated:

• PartitionKey
• RowKey
• Requestor
• Type
• TargetOfficeGroupId
• Status
• LastRunTime
• Period
• Query
• StartDate
• Enabled

Partition key, the value added here represents the date the job was added to the table.

• DataType: string
• Format: YYYY-M-D

Unique key of the synchronization job.

• DataType: string
• Format: Guid

Email address of the person who requested the synchronization job.

• DataType: string
• Format: Email address

Type of synchronization job.

• DataType: string
• Valid value(s): SecurityGroup

Azure Object Id of destination group.

• DataType: Guid

Current synchronization job status; Set to Idle for new synchronization jobs.

• DataType: string
• Valid values: Idle, InProgress, Error

Last date time the synchronization job ran. Set to 1601-01-01T00:00:00.000Z for new synchronization jobs.

• DataType: DateTime
• Format: YYYY-MM-DDThh:mm:ss.zzzZ

Defines in hours, how often a synchronization job will run.

• DataType: int

Defines the Azure ObjectId of the security group that will be used as the source for the synchronization. One or multiple ids separated by semicolon ";" can be provided.
i.e. (single id) dffad54b-88fe-4459-9dd1-e2e2a415d586
i.e. (multiple ids) dffad54b-88fe-4459-9dd1-e2e2a415d586;065cfbc2-ad4f-47c8-8233-3cf55edd0509

• DataType: string
• Format: Guid

Defines the date and time when the synchronization job should start running, this allows to schedule jobs to run in the future. i.e. 2021-01-01T00:00:00.000Z

• DataType: DateTime
• Format: YYYY-MM-DDThh:mm:ss.zzzZ

Flag to enable or disable a synchronization job.

• DataType: bool

A PowerShell script New-GmmSecurityGroupSyncJob.ps1 is provided to help you create the synchronization jobs.

The script can be found in \Service\GroupMembershipManagement\Hosts\SecurityGroup\Scripts folder.

1. . ./New-GmmSecurityGroupSyncJob.ps1
2. New-GmmSecurityGroupSyncJob	-SubscriptionName "<SubscriptionName>" `
						-EnvironmentAbbreviation "<EnvironmentAbbreviation>" `
						-Requestor "<RequestorEmailAddress>" `
						-TargetOfficeGroupId "<DestinationGroupObjectId>" `
						-Query "<source group object id(s) (separated by ';')>" `
						-Enabled $True `
						-Verbose    

You can also use Microsoft Azure Storage Explorer to add, edit or delete synchronization jobs. see Get started with Storage Explorer.

<solutionAbbreviation>-Graph-<environmentAbbreviation> application must be added as an owner to any destination group that will be managed by GMM in order for GMM to have the right permissions to update the group.

In order to add the application as an owner of a group follow the next steps:

1. In the Azure Portal navigate to your 'Azure Active Directory'. If you don't see it on your screen, you can use the top search bar to locate it.
2. Navigate to 'Groups' blade on the left menu.
3. Locate and open the group you would like to use.
4. Take note of the group's Object Id.
5. Navigate back (out of the 'Groups' blade) to the Azure Active Directory section of the portal.
6. Navigate to the Enterprise applications blade on the left menu.
7. Locate and open the <solutionAbbreviation>-Graph-<environmentAbbreviation> application and select it from the results list.
8. Take note of the enterprise application's Object ID.
9. Open a PowerShell terminal as an administrator.
10. If not already installed, install the AzureAD module version 2.0.2.128 or higher.
    Install-Module -Name AzureAD -RequiredVersion 2.0.2.128
11. Import the AzureAD PowerShell Module
    Import-Module -Name AzureAD -RequiredVersion 2.0.2.128
12. Connect with an authenticated account to use Active Directory cmdlet requests: Connect-AzureAD
13. Execute the following command:
    Add-AzureADGroupOwner -ObjectId [Group Id (from step 4)] -RefObjectId [Object Id (from step 8)]

Note: regarding steps 10 - 13:
A newer version of this cmdlet is under development. It will be available in an entirely different PowerShell module, Az.Resources. The cmdlet will be renamed to Add-AzADGroupOwner.

In the event that you are setting up GMM in a demo tenant refer to Setting GMM in a demo tenant for additional guidance.

To troubleshoot any issues that might occur we can use Log Analytics and Application Insights.

1. Find Logs in the Log analytics workspace following the instructions here.
2. Find failures and exceptions with Application Insights here.