Microsoft Graph and Calendar Sync

Please be aware, this feature is only available on v15.5.2 and above. You can find information about upgrading/patching here.

 

Pre-Requisites

This document assumes you have a Microsoft Azure account with the licensing required to use the "Entra ID" product (formerly known as Active Directory). If you wish to sync your Outlook calendars to your intranet you will also need a license for Microsoft Office 365 for the users in your organization.

 

We recommend you migrate your users from your local environment into Azure before using this document to setup your Intranet. Since, you will be asked to choose the groups and users you wish to sync to the system. And if they are not in place, then you will need to get that aspect setup.

 

If you are not migrating from a local environment to Azure, then make sure your Azure Entra ID groups and users are created in your Azure environment ahead of time.

 

IMPORTANT FOR USERS MIGRATING FROM LOCAL USERS OR LDAP TO CLOUD (ENTRA ID):

Before you migrate users to Microsoft Entra ID, you must make sure the "Username" field remains the same as it was in your original environment (the username in your Intranet) if you have existing users. Failure to match this field, will result in duplicate users being created on your intranet. If you have already migrated users and the Username field has changed in some way, you may need to re-do it in a way that the Username's match.

 

 

 

Complete the following steps to set up Azure AD Sync and Calendar Sync

Configure Microsoft Azure Entra ID (Formerly known as Active Directory)

1. Login to https://portal.azure.com and click Manage Azure Entra ID "View" button.
   
   
   
2. On left side menu click Enterprise Applications
   
   
   
   
3. Click New Application
   
   
   
4. Click Create your own application
   
   
   
   
5. Set a Name for application and select the Integrate any other application … and click "Create"
   
   
   
   
6. Click Users and Groups
   
   NOTE: If you are migrating from your local environment to Azure, then you must migrate your data before doing the next steps since you will need to choose your desired groups which will have access to the Intranet.
   
   
   
7. Click Add User/Group
   
   
   
8. Click None Selected
   
9. Search and Select User / Group you want to have access to application
   

 

10. Click on Assign Button.

For easier user management, we recommend creating an "intranet users" group in Azure AD, into which appropriate users can be added. Often organizations have non-users in AD (e.g. printers) which end up having accounts on their intranet if this is not done.

11a. Head back to the Azure AD Home screen and select Groups from the Manage menu

 

11.b Click New Group

1. Click Assign
   
   
   

Setup your Enterprise Application's Permissions

1. From the Azure AD menu, click "Enterprise Applications" and then the "All Applications" list will be shown and confirm the new application you just created appears in that list.
2. Click the link to your Application from this page to go into your application's settings.
3. From the menu on the left go to the "Security" section and choose the "Permissions" option.
4. Click the link "app registration" link on the sentence that says:
5. "To configure requested permissions for apps you own, use the app registration."
   
6. This will take you to the "API Permissions" for your app.
   
7. Click the "+ Add A Permission" button.
   
8. Click the box titled "Microsoft Graph"
   
   
9. Click the box titled "Application permissions"
   
   
   
   
10. A Search interface appears. Enter "Directory" into the search and some options will appear below.
    
11. For the option that says "Directory" click the arrow to expand the item.
12. Choose "Users.Read.All" and "Groups.Read.All" option for full compatibility with IC AD Sync features such as the ability to sync users with Azure AD Sync / Azure Entra ID.
13. Additionally, you can choose "Calendars.Read.All" and "Calendars.ReadBasic.All" to allow just syncing your user's calendars from Outlook to your Intranet. Those options are under the "Calendar" section of the permissions. So you will need to search for "Calendar" to get those to appear.
     
    
    
    
14. Click the tick box next to the item you wish to use and then click the blue "Add Permission" button at the bottom.
    
15. Next you will need to click the "Grant Admin Consent For MSFT" button. This might prompt you for your azure password to give permissions to this application.
    
    NOTE: For each of these permissions your Administrator will need to click a button to give "Admin Consent" in order to enable the permission. Without this, it will not work.
    
16. Click "Yes" when it asks for confirmation.
17. Now you will see green check-marks next to your permission items in the list.
    
    If you do not see this next to each permission they will not work.

Create App Client Secret and get Other Necessary Credentials

1. Click back to Azure Home and back into Azure Ad's main menu.
2. From this menu you must click "App Registrations"
   
   
   
3. Click the "All Applications" tab and click into your Enterprise Application from the list.
   
   
   
4. Click "Certificates & Secrets"
5. Click "New Client Secret" button
   
6. The "Add a client secret" screen comes up asking for a "Description" and an expiry time.
   
7. You can give it a name such as "APIAccess" and choose the longest expiry time you can so as to not have to come back and renew it.
8. Click the blue "Add" button at the bottom of the form.
9. Now you will see your new 'client secret' in a list.
10. The item has a "Value" and a "Secret ID". You can copy these values to save them somewhere safe like a password manager.
    
    IMPORTANT: The item we need is the "Value" not the "Secret ID".
11. Copy the Value and save it somewhere secure as this should not be shared anywhere other than in your Intranet settings and password manager.
12. Now that we have the "Client Secret" we need to find the ClientID and TenantID to allow the Intranet to log in to this application.
13. Click "Overview" from the left menu.
    
14. This will show some information about your application. Among this information is the "Application (Client) ID and the Directory (Tenant) ID.
15. Find these values and save them with the client secret to to be input into the Intranet during setup of your Azure AD Sync connection.

Setup Your Connection In Intranet Admin Settings

1. Before making major changes to your employee directory through Active Directory, it is recommended that you take a server snapshot or database backup (Intranet Connections database).
2. Click into "Admin Home" and select the "Security" tab. Then click into "Active Directory Synchronization"
   
3. Click the "Add Connection" button.
   
4. Choose the "MS GRAPH" option at the top of the form.
   
5. Fill out the form. Give the connection a name. This can be anything. You can call it for example "Graph Connection", or just "Azure".
6. Insert the Client ID, Tenant ID, and Client Secret (value, not ID) into the form.
7. Choose a Sync Interval. Select this, with the understanding, that every sync takes server resources from your system during the process so you do not want to have it sync too frequently unnecessarily. So with this in mind 6-12 hours is recommended for companies who change users frequently. If your company does not change users frequently, you can choose the 1 day option. This is best for most scenarios.
8. Click "Test Connection" to confirm the details will work to connect to Microsoft Graph API.
9. After you click "Test Connection". If the test is successful, the "Save & Continue" button will become enabled and you will be taken to the next screen.
   
   NOTE: In some cases where your Azure system has a lot of users and groups in it, this could take a few minutes. Allow the system to inventory your setup as it loads the next screen to choose a target sync group.
   
   
10. You are now on the "Target" screen. This screen will let you setup which groups and items get synced to your intranet.
    
    Tip for customers migrating from one user source to Entra ID: Start with a small subset of users in your Target, verify that everything works well, then expand the scope of your sync to include all the users.
    
    Start by clicking the little arrow next to the name of your connection. This will expand the groups on your system.
    
11. Choose the group you created to sync your users, then click "Add Target". 

    

    You can add multiple groups as targets if you need to. Additionally, you can choose to just sync Logins and not create employee records for the users by clicking on "Logins" from the options above the group select box.

    If you also wish to sync the groups of your Azure AD, then you can choose the "Groups" option and this will simply sync all the groups seen in the list to a group in your Intranet.

    After you click 'Add Target' you will see that the item appears in the "Sync Target List" area below. Just give it a few seconds. It is not an instant process.
    
    
    

    Pay attention to the "Advanced Settings" options and choose the ones that apply to your needs.

    

    "Sync user manager as supervisor" will bring in the "Supervisor" information from Azure AD and assign your user's supervisor to the corresponding user in the Intranet.

    "Disable users who have been disabled or deleted in AD" will force the synchronization engine to pay attention to the "Disabled flag" in Azure AD and automatically disable the users marked as disabled in Entra ID.
    
    Best Practices To Use this feature: Create a group called "Intranet Users" to house your active users. Create another group called "Disabled Users" to house users who you are removing. Add both of them as separate "Targets" on the "Target Screen". As you need to remove users, you revoke them from "Intranet Users" and assign them to the group "Disabled Users". This will allow you to keep your "Intranet Users" list clean, while allowing the Intranet AD Sync Engine to pick up on the "Disabled" flag for the users, in order to disable them from the intranet. After a sync has occurred, the users can be removed from the "Disabled Users" at a later date to clean up the greater Azure AD Environment.
    
    "Grant intranet administrator rights to users in the "Application Administrators" group" option will automatically give "Administrative rights" to any users in a group that you setup in your Azure AD called specifically "Application Administrators". It has to be this exact name and spelling. The system will elevate privileges for users who are a member of this group automatically upon syncing.
    
    "UserName Mapping" This feature is designed to prevent duplicate user creation on Intranet, wherein fields used as the username does not match the prefix of the UserPrinicpleName field in EntraID. The idea is to match up the usernames with a field in Entra ID that is consistent with what is used as the username field in the Intranet. The default, is just the first part of the Entra ID "User Principal Name". Example: If the User Principal Name is jsmith@xyz.onmicrosoft.com, then the username that the system will use to match up users will be "jsmith".
    
    You can choose between 6 fields in Entra ID to map to your username in your Intranet. To decide which field to choose, go to a random user in your Intranet by using "Find Logins", and examine what the "UserName" field looks like. Check if matches one of the following options: Email, Email Prefix, Surname, Employee ID, UserPrincipalName, or the default which is the Prefix (first part) of the UserPrincipalName (before the @ symbol). 
    
    If your Intranet has no users yet, you can safely just use the default option.
    
    If your Intranet has users that have been migrated from an LDAP connection, you must pay attention to this field and choose correctly, or the result will be duplicate users.
    
    
    

12. Click the "Save & Continue" button. This will take us to the "Mapping Screen"  .
13. On the mapping screen we are presented with a list of Intranet Employee Fields and a pull down menu next to each one allowing you to "Map" the field in Azure AD that you wish to include on your Intranet user's sync.

Select as many fields as you wish to map. And then click the "Save & Finish" button at the top to complete the setup.

 

 

 

 

We are next brought back to the main "Active Directory Synchronization" screen. You should see your connection in the list of "Connections" on lower portion of the page. 

Click "Enable/Disable" to temporarily pause the syncing of a connection

Click "Test" to confirm at any time that your API Keys are still valid. If you have noticed your users have stopped syncing, this is a good place to check that your credentials have not expired.

Use the "Sync Arrows" icon to manually force the system to run a synchronization. Note this takes a few minutes for it to complete. If you have a lot of users, it could take up to 15 minutes.

Use the "Pencil" icon to edit your connection details.

Use the "Trash can" icon to remove the connection.

If you have problems getting it to work, you can always check the "Active Directory Log" for errors. Or send the log to our customer support team to diagnose to assist in diagnosing the issue.

 

Setting Up Outlook Calendar Sync

Prerequisites:

• You must have an active Azure Graph AD Connection setup in Active Directory Synchronizations in your Intranet Admin Settings.
  
  
• In addition to this you must have the "Calendar.Read" permission configured with "Application" level delegation.
  
  
• You must have an Office365 subscription for your company so that your users can create events in their user's outlook Calendars.

 

Best Practices

What the Outlook Calendar Sync feature allows you to do is sync the calendar of one of your Microsoft Office 365 user's calendar, to an Intranet Calendar Application of your choosing.

Since this reveals potentially what is a private calendar to your Intranet users, you may want to create a user specifically to use as the "Delegated Calendar" for your purpose.

Example: Marketing Events Calendar

• You can create a user in Office 365 called "marketingcalendar@yourcompany.com" and designate this user's calendar as the main calendar you wish to be synced to your Intranet.
  
  
• Then log in as this user and share the user's calendar to all those who will be allowed to add events to this calendar. 
  
  
• Next you create a "Intranet Calendar Application" inside of your Intranet. And delegate this calendar as your "Marketing Calendar" by giving it this label.
  
  
• You configure this calendar to sync to this user.
  
  
• Users of your company's Office 365 Outlook can then create events on this user's calendar to be synced to your Intranet.
  
  
• The calendar can then be synced to your Intranet Marketing page as a widget.

How To Set Up Your Calendar Application To Synchronize To Outlook

1. Go to the "Admin Home" and click into "Assets" and locate your "Site" housing the calendar. Open the site, and choose the "Apps" button which will list the applications for the site.  Find the calendar app you wish to sync and click into it to open its Settings Admin page.
   
   Then click "Sync Events From Office365 Calendar" from the right side menu.
   
   
2. Select the connection you set up to connect your Azure Enterprise Application to your Intranet:
3. Next you will choose the user whose calendar you wish to sync. Click the box next to the user you wish to use, choose a Category, and a sub category if it is relevant for your calendar.
4. After you click the "Sync Selected User Calendar" the user will appear in the list to the right of the form. You can now click the "Sync Events Now" button to force the system to get the events. Note that this sync button syncs all events from all calendars not just one setup. (if you have multiple set up)