Configuring the Hyperfish Office 365 Connector

Justin Tung -

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

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

Primary uses include:

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

Using Office 365 Attributes in Hyperfish - Allowing end-users to update SharePoint Online (most Delve attributes) through the Hyperfish Profile page. 

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

Upgrade instructions can be found here

You will also need:

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

Configuration

1   Enabling the O365 Connector

  • Stop the Hyperfish 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 Hyperfish Service from the services.msc snap-in console

2   Configuring Office 365 Connector Settings

  • Confirm that the file "SPOConnectorSettings.json" exists in "C:\User\<hyperfishsvc>\AppData\Local\Hyperfish\connectors" folder. If it isn't there, make sure that step 1 was completed properly.
  • Stop the Hyperfish Service from the services.msc snap-in console
  • Using a text editor of your choice, open "SPOConnectorSettings.json"
  • For "TenantName", enter the name of your Office 365 tenancy, e.g., "contoso" if your tenant is "contoso.onmicrosoft.com"

  • For "AdminUserName", enter the name of your Office 365 Global Administrator account. This should be the full account name you use to sign-in to Office 365 with.
    Note: Accounts requiring multi-factor authentication will not work

NOTE: Feel free to save, but do not close SPOConnectorSettings.json -- we're not quite done with it yet!

3   Generate an Encrypted String for the O365 Admin Password 

These steps will generate the encrypted string that the on-premises Hyperfish service account uses to connect to Office 365 as the Global Administrator account. It involves using an included command line utility, Encryptor.exe, which uses the Windows Data Protection API (DPAPI)

Only the account that generates this string can use it, so it's important to run Encryptor.exe as the Hyperfish Service account. This should be the account that the Hyperfish AppData folder appears under. If unsure, you can always check the Logon options for the Hyperfish Service from Windows Services.

  • Open a command prompt session and use the runas command to start a command prompt session as the Hyperfish Service account

    e.g. "runas /user:DOMAIN\user cmd"

    You will be prompted to enter a password for the Hyperfish Service account.

  • In the new command prompt session, navigate to "C:\Users\<hyperfishsvc>\AppData\Local\Hyperfish\versions\<version number>\agent", where <hyperfishsvc> is the name of your Hyperfish service account, and <version number> is your current Hyperfish agent version

    e.g. "cd C:\Users\hyperfishsvc\AppData\Local\Hyperfish\versions\3.5.X\agent"

  • Run Encryptor.exe followed by the Office 365 Global Administrator password

    e.g. "Encryptor.exe secret", where "secret" is the password (without quotes):

    Warning: The plaintext input will be visible as cleartext during this step



  • Copy the resulting string into a text editor (make sure to capture all of it) and remove all line breaks

  • In SPOConnectorSettings.json, make sure "AdminPassword" field exists. If it doesn't, add a comma to the end of the "AdminUserName" line and add a new line below for "AdminPassword", with a colon after.
  • Paste the unbroken encrypted string to the "AdminPassword" line and wrap it in quotes:



  • Save SPOConnectorSettings.json and start the Hyperfish Service from the services.msc snap-in console

NOTE: Don't worry about the "Attributes" portion of the SPOConnectorSettings.json file contents yet -- they should be generated after you start the service, and don't need to be modified unless you have custom SharePoint Online user profile attributes.

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.

4   Testing Connector Functionality

  • Test Connectivity - Sign-in to the Hyperfish Web Application and browse to your profile to confirm that it loads (https://app.hyperfish.com/self

  • Test Photo Sync - From your Hyperfish Profile page, upload a new profile photo (you may also need to approve it from the Hyperfish '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 Hyperfish Web Application, navigate to Settings -> Attributes. Click on '+ Add Attribute' 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@hyperfish.com 


5   Additional Configuration (Optional)

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

  • Stop the Hyperfish 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 display name of the attribute for "Name", and 'true' or 'false' for the "IsMultiValued" parameter:



  • Start the Hyperfish 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.

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.