Migrate an existing Azure AD connection to Microsoft Graph API source

If you have enabled the Azure AD connector before October 2021, it will be using the Azure AD Graph API. Microsoft is deprecating this existing API and moving all the functionality of all their APIs to a single Microsoft Graph API.

You will need to migrate to Microsoft Graph before June 30, 2022 to avoid loss of functionality. Ask your IT team if they have set up the new Microsoft Graph API permissions in your Azure portal.

To continue to sync external user accounts, you will need to configure permissions for Microsoft Graph in your Azure AD portal.

Configure permissions for Microsoft Graph API

Ensure that you don’t remove any of your current API permissions for Azure AD Graph API before completing the migration, as you won’t be able to add them back once removed. We recommend fully testing the new configuration before you remove any permissions.

1. In your Azure AD’s API Permission screen, the API you’ll need to give permissions to is “Microsoft Graph”. The specific permissions you’ll need to add are:
   • Application permissions:
     Group.Read.All
     User.Read.All
   • Delegate permissions:
     email
     Group.Read.All
     GroupMember.Read.All
     openid
     profile
     User.Read
     User.Read.All
     User.ReadBasic.All
     
     You will also need to grant consent for OpenCities.

Update the API source in OpenCities

Once your Azure Active Directory is ready with the Microsoft Graph permissions, you can update your OpenCities configuration. 

1. Go to the More > External User Management > Azure AD screen.
   
   
2. You will see a new field called API source which will be set to Azure Graph API (deprecated) before the change. Choose Microsoft Graph API from the dropdown.
   

   

   API source

   This is where you nominate to migrate to Microsoft Graph API once you have configured the permissions in your Azure AD portal. Azure Graph API is marked as legacy and is being deprecated. After setting up permissions in your Azure AD portal, select Microsoft Graph API in the dropdown to access Azure AD and avoid loss of functionality.

3. Ensure all the additional details are still correct and Test your connection.
   
   
4. Save your settings.

Update user detail mappings

As part of the migration from Azure AD Graph to Microsoft Graph, some properties have changed. See the complete list of property differences in the developer resources for Microsoft Graph.

Visit the User detail mapping tab to check your existing mappings against the list of changed properties, and update the configuration if needed.

Other notable property changes:

• Microsoft Graph API does not allow the GET method for user profile images from personal mailboxes. This is supported only for work and school mailbox types.
• In addition to properties with changed names, some properties newly available within Microsoft Graph may also require additional Microsoft licenses. For example, fields like "MySite", "PreferredName", or "AboutMe" require the SharePoint Online license. If fields that require a specific license are used within user detail mapping without that appropriate license, it will display as an error on staff directory pages.