Sync an Azure Entra ID Attribute to a custom Profile Property

In your Azure Entra ID (previously Azure AD) environment you may have some custom attributes which by default are not  synchronised to the SharePoint User Profiles in Microsoft 365.

If you need to bring in custom attributes to use in the People Directory for example, there is a process available which you can configure and run to synchronise the custom attributes to SharePoint User Profiles, and eventually to make them available in Atlas.

In this article:

• Important notes before starting
• Access the function configuration in Azure
• Access the configuration files
• Create the new User Profile Properties to sync into
• Configure the Sync process
• Enable the Sync process
  • On a schedule
  • Just once / manually
• Check progress and verify
• Still need help?

Important notes before starting

You will need significant administrative rights to be able to configure the whole process, and as such you may need input from multiple different people to complete the configuration.

Additionally it is important to note that the cost for your Azure environment will be increased due to running additional processes. The cost will depend on the frequency of running the function and the amount of data it needs to process for each run, so we don't recommend running it every day unless your user data will be updated that frequently.

Technically, this function utilises the Bulk User Profile API from Microsoft. More information on the API can be found here: https://docs.microsoft.com/en-us/sharepoint/dev/solution-guidance/bulk-user-profile-update-api-for-sharepoint-online but it is not required reading to follow the rest of this article.

Access the function configuration in Azure

I've put this information near the top of the article as you'll need to access this area for a few things. 

1. Go the Azure portal (https://portal.azure.com)
2. From the dashboard click the Resource Groups button:
   
3. Open your Atlas Production resource group
4. Open the func-atlas-uf function app e.g. func-atlas-uf-CLIENTNAME-prod - note that the name will usually be like this but generally just ensure you choose the one containing -uf- (user function). If there are multiple uf functions please get in touch with the support team for clarification.
5. On the left hand menu under Settings click Configuration:
   

We would suggest to keep this open in a separate tab so you can return to it easily.

Access the configuration files

You can find all files related to this process stored in the Atlas Configuration workspace, in the Atlas Configuration Files document library, in the folder "Azure Active Directory Synchronization to SharePoint User Profile properties". If you have not configured this before you will only see the following:

This is the default location for your JSON configuration file that you'll create in the next step. Inside the "DataLogs" folder you'll find the output files from each time the sync runs.

Create the new User Profile Properties to sync into

In order to configure the sync you'll need to create one or more new properties in the User Profiles in SharePoint. You can do this from the SharePoint Admin centre.

1. From the SharePoint Admin centre click More features on the left menu, then open the User Profiles on the right side:
   
2. At the time of writing there is no Modern UI for the User Profiles so these screens can be slow to load. Click Manage User Properties under the "People" heading:
   
3. On this screen, click New Property to start adding your custom property:
   
4. First you'll need to provide the Name and Display Name. For the Name you should remove any spaces and add a prefix to denote that this is custom, for example:
   
5. You should usually leave the type as String and configure the length with consideration to the data you're going to sync to this property. If you know your property might exceed the default 25 length ensure you increase this appropriately. It is also supported to sync Integer values.
6. The rest of this configuration page can be ignored in most cases and will not be covered in this guide. Now you can simply save your new property.

Configure the Sync process

The sync process used here is not a script but instead an Azure function app in a resource group which is deployed as part of your Atlas installation, but by default it is turned off. The sync configuration is controlled by a JSON file which you'll need to edit to target the correct properties in the source and destination.

Below is an example JSON file - in this example we are syncing two properties:

[
{
"SharePointUserProfile_PropertyName": "CustomIsFullTimeEmployee",
"AzureActiveDirectory_PropertyName": "extension_029bc9d19ea18c71849ac58b2cad4fd3_extensionAttribute7"
},
{
"SharePointUserProfile_PropertyName": "CustomEmployeeType",
"AzureActiveDirectory_PropertyName": "extension_029bc9d19ea18c71849ac58b2cad4fd3_extensionAttribute9"
}
]

In the above example custom properties CustomIsFullTimeEmployee and CustomEmployeeType will be populated from the specified extension attributes from Active Directory (in this case 7 and 9). You need to give the full names of these attributes similar to what we're using above.

If you're using the default configuration, see the section above to learn where the configuration files are stored and upload your custom JSON in this folder. 

The path to the JSON file can be configured by accessing the configuration area then finding the line SharePointUserProfileBulkImport:MappingsConfigurationFileRelativeUrl and either updating the file referenced there, or changing the reference to point to your new file.

Enable the Sync process

You can either enable the sync process to run on a schedule, or you can just run it once; either to test the process and mappings or because you prefer to run manually when needed to reduce costs. You'll need permissions in the Azure portal to configure and activate this function app.

On a schedule

1. Access the configuration area of the function app
2. If the option is available, click Show values at the top of this panel, then scroll down and find the DisableUserFunctions line. By default this is set to TRUE, so you'll need to change it FALSE so that the function is no longer disabled.
3. As long as you have configured the mapping file the properties should now start syncing as per the schedule, so generally the first sync will happen the following day.

Just once / manually

If running manually or only once you won't need to enable the function as above, instead we just need to run the function a single time. There is still a "queue" and a timer job that runs the queue so it won't be immediate, but you can check the status from the data log.

Please note that even though we'll be using the "Test/Run" feature of the function this will in fact run the code against your real Active Directory and User Profiles and perform the sync.

1. First, ensure your JSON file is in place and configured. Then access the Azure function app as in the section Access the function configuration in Azure
2. Instead of clicking on Configuration from the left hand menu, click Functions:
   
3. In the list of functions, locate the SharePointUserProfileBulkImportTimerTrigger
4. Click on the function name, then on the left hand side click on Code + Test:
   
5. At the top, click Test/Run then on the panel on the right hand side click Run:
           ------>         
6. The job will probably not start immediately, but usually with 5 minutes. You can see how to check the status by reading the next section of this guide.

Check progress and verify

As the jobs are run via a timer process they may not run immediately, but you can check the status in the DataLog.txt associated with this run which is updated every 5 minutes. By default this file can be found by following the instructions in this section: Access the configuration files

If you've changed the location and you're not sure where to find it, access the configuration area of the function app and then find the line SharePointUserProfileBulkImport: ImportJobsFolderRelativeUrl which will tell you where the file is.

Still need help?

If you need to run this in your environment please contact support or your Atlas CSM to discuss the requirement and arrange for the script to be run.