Configuring the Office 365 Connector

Note: Applies to Directory Premium hybrid (on-premises AD) deployments only

The Directory Office 365 connector provides connectivity options for Office 365 applications.

Primary uses include:

Photo Sync for Office 365 - When users upload a profile photo to Directory, the photo will be committed to Active Directory, resized to optimal resolutions, and uploaded to Office 365 simultaneously. 

Using Office 365 Attributes in Directory - Allowing end-users to update attributes in Office 365 that are not synced via AD Connect through the Directory Profile page. 

 

Modern Office 365 Connector (Agent Version 4.0.0 and higher)

The modern Office 365 Connector uses modern authentication to connect to Office365 attributes through the Microsoft Graph. This replaces the Legacy Office 365 connector, which used Legacy authentication, which is being phased out by Microsoft.

The benefits of using the Modern Office 365 connector are:

• Ease of installation
• Increased performance 
• More secure

However, custom SharePoint Online attributes are not supported as they are not made available through the Graph. If your usage scenarios require management of SharePoint Online custom attributes, refer to set-up for the Legacy Office 365 Connector. 

Before you start, make sure you are using a version of the Directory Agent that supports the Modern O365 Connector (version 4.0 and higher):

Configuration

 

1   Granting Permission Scopes using an Office 365 Global Administrator Account

Sign in to the following URL according to your deployment region using an Office 365 Global Administrator Account from the tenant you wish to enable the Office 365 connector for. 

Region:

UNITED STATES
UNITED KINGDOM
AUSTRALIA

 

2   Enabling the O365 Connector

• Stop the Directory Service from the services.msc snap-in console
• Using a text editor of your choice, open servicesettings.json from "C:\Users\<hyperfishsvc>\AppData\Local\Hyperfish"
  
• Under the "Connectors" section, find the "o365" connector setting and change the "Enabled" value from false to true.
• Start the Directory Service from the services.msc snap-in console

 

 

Legacy Office 365 Connector (Agent Version 3.0.0)

Before you start, make sure you are using a supported version of the Directory Agent (3.15.1 or higher). You can always find out which agent version you have installed, and download the latest agent from Settings -> General in the Directory web application.

Upgrade instructions can be found here. 

You will also need:

• Access to the server hosting the Directory Agent
• Office 365 Global Administrator credentials 
• Directory Service account credentials

Configuration

1   Enabling the O365 Connector

• Stop the Directory Service from the services.msc snap-in console
• Using a text editor of your choice, open servicesettings.json from "C:\Users\<hyperfishsvc>\AppData\Local\Hyperfish"
  
• Under the "Connectors" section, find the "o365" connector setting and change the "Enabled" value from false to true.
• Start the Directory Service from the services.msc snap-in console
• Confirm that the file "SPOConnectorSettings.json" exists in "C:\User\<hyperfishsvc>\AppData\Local\Hyperfish\connectors" folder. If it isn't there, make sure that all of Step 1 was completed properly.

2   Configuring Office 365 Connector Settings

• A configuration utility, O365Config.exe is bundled with the Directory Agent; to locate it, navigate to "C:\Users\hyperfishadmin\AppData\Local\Hyperfish\versions" 
• Open the latest version folder within, and open the agent folder to find O365Config.exe
  Note: If the Directory Agent has never been updated, the version folder may be 0.0.0
  
  
• Stop the Directory Service from the services.msc snap-in console
• Run O365Config.exe as the Directory service account (Run a CMD session as the service account and change directory to the O365Config.exe location if you need to)
• Select option 1 to set up standard username/password authentication
• When prompted to do so, enter the full name and password of the O365 administrator account, e.g. admin@contoso.onmicrosoft.com
  
  
  Accounts requiring multi-factor authentication will not work.
• When prompted for Tenant Name, enter the name of your Office 365 tenant. For example, if your Office 365 tenancy is contoso.onmicrosoft.com, enter 'contoso'
• After doing so, the configuration utility will attempt to lookup the user specified in SharePoint Online User Profiles using the credentials provided:
  
  If the test is unsuccessful, press any key to return to the main menu and perform select option 1 to perform the configuration steps again
  
  If the test is successful, press any key to return to the main menu and make sure to exit O365Config.exe as its running state will prevent the Directory service from starting later 

3   Validate the O365 Connector Settings 

• In an explorer window, navigate to the C:\Users\<hyperfishsvcaccount>\AppData\Local\Hyperfish\connectors folder and open SPOConnectorSettings.json using your text editor of choice
•  Verify that the following sections have your tenant name populated:
  TenantName
  SpoConfig (Agent Versions 3.16 and older only): AdminUri, TenantName, MySiteHost, RootSiteHost
  
  
  Optionally, if you are using a different language pack, the MySiteHostPhotoLocationPath will be different. Make sure you change this appropriately for photo upload to work correctly.
• At the bottom of the SPOConnectorSettings.json make sure that the username is correct and that the password is populated as an encrypted string:
  
  
  If you're unsure about the formatting of the contents of the .json file, you can use a JSON validator to make sure it's formatted correctly.
  
  
• After you've validated the contents of SPOConnectorSettings.json, save any changes if needed, and close it
• Start the Directory Service from the services.msc snap-in console

 

Additional Instructions for Tenants using an International Language Pack    

When the Directory connector uploads profile photos, it is assuming the path is
“https://my-<tenantname>.SharePoint.com/_layouts/15/start.aspx#/UserPhotos/Profile Pictures/".

If your SPO instance is localized to a different language, it will most likely be different from "User Photos/Profile Pictures"

You can find  more information about this here: https://github.com/SharePoint/PnP/issues/1419 

 

Using Directory Agent version 3.9.4 or newer, you can now customize the target SharePoint Online profile photo path.

•  You will need to open Services.msc and stop the Directory Service.

• Then, it is necessary to update the SPOConnectorSettings.json. You can find the folder in the following path: "C:\Users\hyperfishsvc\AppData\Local\Hyperfish\Connectors"

  

• Once you have made the update to your Json file, you can save and close the file.

• Lastly, navigate back to your Services.msc and restart the Directory service.

 

4   Testing Connector Functionality

• Test Photo Sync - From your Directory Profile page, upload a new profile photo (you may also need to approve it from the Directory 'Approve' page)
  
  Sign-in to Outlook Web Access and make sure your profile photo is updated there.
  
  Navigate to your Delve profile (SPO is the photo store for Delve) and make sure your profile photo is updated there.
• Test Office 365 Attributes - From the Directory Web Application, navigate to Settings -> Attributes. Click on '+ Add an attribute' at the bottom, and search for "o365" in 'Field' to make sure SharePoint Online User Profile properties show up:
  

If any of these tests fail, please contact support@livetiles.nyc

5   Additional Configuration (Optional)

If there are custom SharePoint Online user profile properties you would like to add to Directory, an entry must be made for that property in SPOConnectorSettings.json

• Stop the Directory Service from the services.msc snap-in console
• Edit SPOConnectorSettings.json with a text editor
• Under the "Attributes" section, create a new section for each custom attribute you wish to add (you can copy another section to make sure you don't miss any properties)
• For each custom attribute, enter the field name of the attribute for "Name", and 'true' or 'false' for the "IsMultiValued" parameter:
  
  
• Start the Directory Service from the services.msc snap-in console

Your custom attributes should appear when adding attributes from Settings -> Attributes.

NOTE: Again, if you're unsure about the formatting of the contents of the .json file, you can use a JSON validator to make sure it's formatted correctly.