Set up Microsoft Online connector for SyncPortal

Learn how to set up Azure Active Directory to synchronize with MRI OnLocation.

How it works

The cloud-based user identity and authentication service Azure Active Directory (Azure AD / Office 365) can be synchronized to MRI OnLocation using an Azure Automation runbook.

First, create a new automation account in the Azure Portal. Then you can use the Powershell script provided in the Sync Profile connectors of your SyncPortal to create a SyncPortal runbook.

This will allow you to automatically sync employee information with OnLocation from your Azure AD.

Step 1: Create a new automation account in the Azure portal

You will need to sign in to the Azure portal with an account that's a member of the subscription Administrators role and a co-administrator of the subscription.

  1. Log in to Microsoft Azure.
  2. Click Create a Resource.

  3. Search for and select Automation. Click Create.

  4. In the Create an Automation Account page, specify the subscription you want to use.
  5. Enter a new resource group or select an existing group.
  6. Enter a name.
  7. Select an Azure data center as the region.
  8. Click Review + Create.

  9. Click Create.


Your automation account will be created and deployed. Wait for an in-app notification to confirm deployment is complete before continuing.

Step 2: Set up the OnLocation SyncPortal runbook

To set up the runbook, you must install the MSOnline Module and create two credentials. This is done from the Automation Account resource. Access this by selecting All Resources from the left-hand menu and select your Automation Account resource from the list.

Install MSOnline Module

Our runbook requires the MSOnline module to be installed. This is not set up as a default option and will likely need to be added.

  1. From the Automation Overview screen, select the Modules from the menu under Shared Resources. If the module is not present, it can be installed from the Gallery.
  2. Click Browse gallery.

  3. Search for MSOnline.
  4. Select the module.

  5. Click Select.

  6. Choose the runtime version, then click Import.


This will install the module to your Automation Account resource. 

Create credentials

OnLocation runbook requires two credentials to be configured: WolSyncExportCredential and WolSyncUploadKey.

To add each credential:

  1. Select Credentials from the resource menu under Shared Resources.
  2. Click Add a credential.


Wol sync export credential

This is used by the script to authenticate to your AzureAD using the Connect-MsolService cmdlet.

Add this using the name WolSyncExportCredential, then enter in a valid AzureAD account's user name and password, which has export permissions over your directory.

This user must:

  • Have at least the Directory Readers role. Check the Microsoft Docs website for more information. 
  • Not have multi-factor authentication enabled. 


Wol sync upload key

This is your OnLocation SyncPortal profile key. It authenticates the upload and routes the uploaded data to your SyncPortal profile for import.

The key is found in your Sync Profile, and each key is unique to that profile. Check the Sync Profile Connectors article to find out where to find the key.

To add this credential, use the following configuration:

  • Name - WolSyncUploadKey.
  • Description - This is optional and not required for your sync.
  • User name - This is ignored by our system, so use a placeholder such as 'key'.
  • Password and Confirm Password - Enter your Sync Profile password here.


(Optional) Export group 

The runbook can optionally export the user list from a distributor/security group instead of the entire user directory.

To configure the export group:

  1. Select Variables from the resource menu under Shared Resources
  2. Click Add a variable.

  3. Add this using the name WolExportGroup.
  4. Enter a valid AzureAD group name into the value. This must match exactly.
  5. Click Create.


To disable export by group membership, delete this variable, and the runbook will go back to exporting all users.

Step 3: Import runbook

With your credentials set up, you can now import the runbook from OnLocation to your Automation Account resource. This will run the sync when the resource is activated.

First, you must download the runbook from your Sync Profile in OnLocation. This is in the same section as the Sync Profile Key under the Sync Profile Connectors tab.

Once you have downloaded this runbook:

  1. Select Runbooks from the resource menu under Process Automation.
  2. Click Import a runbook.

  3. Click the file icon next to Runbook file.
  4. Select the runbook downloaded to your computer.
  5. Select PowerShell as the runbook type.
  6. Select 5.1 as the Runtime version. 
  7. Click Import.

  8. Once the runbook is imported, it will open in edit mode. You can view the Powershell script, which can be used as-is or modified. Make any modifications you require before publishing.
  9. Click Publish, then click Yes to confirm.


Your runbook will be installed, published, and ready to run your sync.

Step 4: Run your sync

You can run your sync manually or automatically from the WolSync runbook overview:

  1. Select Runbooks from the resource menu under Process Automation.
  2. Select the WolSync runbook.

Run manually

You can run your sync manually anytime by clicking Start and selecting Yes on the confirmation pop-up.


Run automatically

To set your sync to run automatically, you must create a schedule to tell the runbook when to run.

  1. Click Link to schedule.

  2. Select Link a schedule to your runbook.
  3. Click Add a schedule.

  4. Add a name.
  5. Enter when the sync should start.
  6. Choose how often it should run: Once or Recurring.
  7. If recurring, set the frequency.
  8. Choose if you want to set an expiration date. This will stop the recurring sync on the date chosen.
  9. If expiring, set the expiry date.
  10. Click Create.


Tips for running your sync

We recommend using 'Do not import anything (Dry Run)' for the SyncPortal profile mode when first deploying this runbook.

This allows the file to be uploaded and processed without actually changing anything in OnLocation, the profile logs can then be used to ensure the data will be imported as expected.

Once satisfied all is set up correctly, it is recommended to change the profile mode to 'Update existing items and import new (ALL)' and set the runbook on a regular automated schedule.