Skip to main content

Calendar configuration Microsoft Graph API v.1.0.6

Updated

Description

The Zylinc service uses a Microsoft Azure AD App Registration to Read or Read and Write Calendar information on all the Office365 Users.

Requirements

Zylinc Cloud installation: Minimum Version R4.0

Platform 6.5: Minimum release 6.5u5.9 (Zylinc Exchange Sync v3 Provider MS Graph)

For 6.5 Only:

  • Zylinc Calendar MS Graph (Zylinc Exchange Sync v3 Provider MS Graph) is installed
  • Zylinc Gateway is installed
  • A public DNS (for the Callback URI)
  • Certificate corresponding to the public DNS
  • Route incoming traffic on WAN port (default: 35063) to the server running Zylinc Gateway
  • Allow incoming traffic from any public IP Address in the FW on the WAN Port
  • Global application settings are saved (Global appsettings.json)

 

Licenses (both Zylinc Cloud and 6.5)

  • Zylinc Calendar License for all users

MS Azure AD App registration Permissions (both Zylinc Cloud and 6.5)

  • Microsoft Graph
    1. User.Read.All                    (Application Permission)
    2. User.Read                                                     (Delegated  Permission) - Default configured
    3. Calendar.Read.All (Application Permission) >Not possible to add calendar entries

                                                      or

  1. Calendar.ReadWrite (Application Permission) ->Possible to add calendar entries
  • Authentication

Client Secret

MS Azure AD App registration Permissions (only Zylinc Cloud hybrid configuration)

 

  • Microsoft Graph additional permissions
    1. Calendars.Read                                           (Delegated Permission)
    2. Calendars.Read.Shared (Delegated Permission)
    3. EWS.AccessAsUser.All    (Delegated Permission)
    4. User.Read.All                                               (Delegated Permission)
  • Syncronization user and password

On-Premises user must have Delegate - Full Access permissions to view other users calendar.

  • All users must be sync’ed to Azure AD and have User Type = Member

Microsoft Azure AD Registration (both Zylinc Cloud and 6.5)

In the customer tenant Azure AD, a Microsoft Azure App Registration needs to be created, to Read or Read and Write calendar information of all the Office 365 users in the specific mail domain.

 

Create a New Registration

 

Login to the Azure Portal and create a New App Registration

 

1.png

 

Enter a descriptive Name to the Registration

 

2.png

 

Add the required permissions

 

3.png

 

4.png

 

5.png

7.png

8.png

Configure Authentication

9.png

Create the secret

10.png

Enter a given name to the client secret and select an appointed expiration date.

11.png

The Client Secret will expire on the selected date without warnings – Please have some warning system in place for this. A new secret can be created at any time and then entered in the Zylinc solution.

 

Copy and save the Secret Value BEFORE you leave the page. It will only be visible until then.

12.png

 

Save Application (Client) ID and Directory (tenant) ID

In the Azure AD -> Overview information on the created App Registration is listed.

This information is used when configuring the Calendar sync in both Zylinc Cloud and 6.5 release.

13.png

 

Setup Zylinc Cloud

 

Configure Microsoft Online Calendar integration in Zylinc Cloud

 

To add a new ‘Microsoft Calendar integration’

Select Microsoft Calendar integration (+)

14.png

mceclip15.png

The following six steps configures a MS Calendar Integration provider to the customer system:

  1. Enter a descriptive name
  2. Enable the MS Calendar Integration provider
  3. Copy the saved Directory (tenant) ID to ‘Tenant ID’ field
  4. Copy the saved Application (Client) ID to ‘Client ID’ field
  5. Copy the saved Client Secret Value to ‘Client secret’ field
  6. Enter ‘Number of past months to synchronize’
  7. Enter ‘Number of future months to synchronize’
  8. Select Save

’Filter users on tags’ are for later use.

16.png

 

For On-Premise calendar sync to work correctly the Online integration must be configured and completed.
 
For On-Premise calendar sync to work, the Exchange we are targeting has to be in hybrid deployment and meet requirements found in Appendix A : Use REST APIs to access mailboxes in Exchange hybrid deployments


Add the 4 Delegated API Permissions to the Calendar Sync App created for Exchange Sync Online:

Calendars.Read,
Calendars.Read.Shared,

EWS.AccessAsUser.All,
User.Read.All

and grant Admin consent where applicable:

17.png

 

Click Authentication (left panel) and set Yes to Allow public client flows :

18.png

 

Setup the “Hybrid setup configuration” in Zylinc Cloud Configuration Manager

To configure Hybrid setup configuration in the Configuration Manager it is necessary to click Enable to enable the hybrid configuration section.
If Enable is not selected the fields are hidden from the view.

Provide a URL to Exchange Autodiscovery service. Usually it follows the following pattern, where

customer_domain must be filled with the name of the domain where customer's Autodiscovery service is located:

https://autodiscover.[customer_domain]/autodiscover/autodiscover.json/v1.0/{0}?Protocol=Rest

 

Tenant ID and Client ID must be filled with values obtained from App creation in Azure portal

section.


Provide a Username and Password of a sync user that will be used to retrieve calendars from On-Premise users.
It is essential, that this user is On-Premise user and has delegate permissions to view other users'

Calendars.

The homing of the sync user can be verified with the autodiscover URL,

i.e. for a sync user name "my_sync_user@somedomain.example" enter URL in browser:

https://autodiscover.somedomain.example/autodiscover/autodiscover.json/v1.0/my_sync_user@somedomain.example?Protocol=Rest


Expected result if sync user is homed Online:

{"Protocol":"Rest","Url":"https://outlook.office.com/api"}

 

Expected result if sync user is homed OnPrem:

{"Protocol":"Rest","Url":"https://mail.[domain]/api"}

 

Configuration Manager setup:

19.png

 

20.png

 

Setup 6.5

 

Configure Microsoft Calendar integration in 6.5

  1. Login on to Administration Portal
  2. Select NETWORK-> Exchange synchronization
  3. Select Add Exchange Sync
  4. Enable the Service
  5. Enter a descriptive name in Exchange Service Name (the name of the Windows service)
  6. In Server Address enter the IP Address of the server (the App server)
  7. In Absence port enter the port ZyDesk will communication with the service on when creating Absence (Default: 35099)
  8. In Exchange Service URL enter https://outlook.office365.com/EWS/Exchange.asmx Only Office 365 is supported.
  9. in Domain enter the mail domain all the users
  10. In Sync User some dummy text (not used but cannot be left empty)
  11. In Exchange Version select Office 365
  12. In User Rights Method select Impersonation
  13. In Synchronization Method select Push subscriptions
  14. In Azure Tenant Id enter the saved Tenant id
  15. In Azure Client Id enter saved Application id
  16. In Azure Client Secret enter the saved Secret value
  17. In Callback URL enter the URL MS will send events on to the service, in the following syntax: https://[public DNS/FQDN]:[WAN port]/graph/calendar/events The port is the Zylinc gateway port number: 35063 (default port: 35063) The last part of the URL: ‘Events/’, should NOT be configured in the settings.json-file but is required in the Callback URL The URL should correspond with the setting in the Zylinc gateway settings.json-file
  18. In Notification event Listener enter the URL used by Zylinc Gateway to communicate with Zylinc Calendar Integration. http://[serve IP Address]:[port]/ (default port: 35049)
  19. In the Sync Settings -> Sync Filtering select Group/User filter
  20. Select which users this calendar sync should sync:
    • If All users with an email should be Sync’ed select Exclude
    • Select or search the Users or/and specific AD Groups in ‘Available users/group’ and click the ‘Right’ to add to ‘Selected Users/Groups’ and select Include
  21. Select Save
  22. Start the newly configured Zylinc Exchange Sync v3 Provider MS Graph service

 

21.png

 

22.png

 

 

Zylinc Gateway description

 

The Zylinc Gateway will handle the calendar events received from Microsoft. Every time a user‘s calendar is changed a new event will be sent. The communication between the Zylinc Gateway and Microsoft uses HTTPS protocol.

 

When Zylinc Gateway is installed and setup with default settings, you need to add support for the Zylinc Exchange Sync v3 Provider MS Graph module.

 

This is done in the Zylinc Gateway appsettings.json file. It has a ReRoute section where the data related to Zylinc Exchange Sync v3 Provider MS Graph is configured.


Here you configure how data will be detected and the type of communication between the module and the Zylinc Gateway.
DownstreamPathTemplate is used to detect the event received from Microsoft.

UpstreamPathTemplate is used to configure the communication with the module.

DownstreamScheme determines which communication protocol the Zylinc Gateway communicates with the module (Zylinc Exchange Sync v3 Provider MS Graph).

The communication protocol between the Zylinc Gateway and the module can be set to either HTTP or HTTPS.
If both the Zylinc Gateway and the module are installed on the same server, Zylinc recommend using HTTP. If HTTPS is used, you will the FQDN address of the App server as ‘host’ part of the URL and a certificate corresponding (and password) to the DNS/FQDN.

 

Configure Notification event listener in Administration Portal

 

The Notification event listener is required in a 6.5 solution.
The setting is read by the calendar module and tells the module where to listen on events received from the Zylinc Gateway.

Example of Notification event listener URL:

 

http://10.10.10.51:35049

 

Configure Callback URL in Administration Portal 

The Callback URL is required in a 6.5 solution. The setting is sent to the Microsoft Office 365, to indicate where MS should send calendar events to.

Example of Callback URL:

 

https://callbackurl.zylinc.work:35063/graph/calendar/events/

 

This Callback URL can be divided into two text strings:

  • BaseURL: https://callbackurl.zylinc.com:35063
  • DownstreamPathTemplate: /graph/calendar/{any}

 

Note: The last part of the example Callback URL: ‘events/’, is required in the URL but replaced in the ReRoute settings with ‘{any}’.

 

 

Configure ReRoute for the Zylinc Exchange Sync v3 in the Zylinc Gateway appsettings.json file


When the Callback URL is configured as the above example the following should be added to the ReRoute section in the Zylinc Gateway appsettings.json file:

 

                        {

            "_comment25.2": "Zylinc Exchange Sync v3 Provider MS Graph",

                                    "UpstreamPathTemplate": "/graph/calendar/{any}",

                                    "DownstreamPathTemplate": "/graph/calendar/{any}",

            "DownstreamScheme": "http",

            "DownstreamHostAndPorts": [

                {

                                                            "Host": "<appserver_local_IPaddress>",

                                                            "Port": 35049

                }

            ],

            "DangerousAcceptAnyServerCertificateValidator": true,

            "UpstreamHttpMethod": []

        },

....

  "GlobalConfiguration": {

    "BaseUrl": "https://callbackurl.zylinc.com:35063"

 

 

 

Appendix A: Use REST APIs to access mailboxes in Exchange hybrid deployments

Important:
From March 2023 the feature will be deprecated by Microsoft. For more information read here.

The source of the content below comes from old version of the documentation.
The source can be found here.

Microsoft Graph has always provided access to customer mailboxes in the cloud on Exchange Online as part of Microsoft 365. Exchange 2016 Cumulative Update 3 (CU3), released in September 2016 for Exchange on-premises servers, adds support for REST API integration with Microsoft 365. If your app uses v1.0 of the Mail, Calendar, or Contacts API, you will now also find a seamless authentication and application experience in hybrid deployments, regardless of whether the mailbox is on-premises or in the cloud, provided that the deployment meets specific requirements.

Behind the scenes, when Microsoft Graph identifies that a REST API call is attempting to access an on-premises mailbox in a hybrid deployment, it proxies the REST request to an on-premises REST endpoint which then processes the request. This discovery makes accessing the REST API possible.

Note: The ability to use these REST APIs in hybrid deployments is currently in preview.

Only v1.0 of the Mail, Calendar and Contacts API are available for mailboxes in hybrid deployments. Other v1.0 API sets, such as the Groups API, or APIs in other versions, are not. If you attempt to use an API that is not part of the supported set in a hybrid deployment, you will get the following error message:

"REST APIs for this mailbox are currently in preview. You can find more information about the preview REST APIs at https://dev.outlook.com."


Requirements for the REST API to work in hybrid deployments

Microsoft Graph provides openness (open standards support like JSON, OAUTH and ODATA, connecting from most popular platforms) and flexibility (granular, tightly scoped permissions to access

user data). If your organization is interested in enabling Microsoft Graph app development and is currently in or considering a hybrid deployment, be aware of the following deployment requirements:


  • Mailbox requirements
    • All on-premises mailboxes that will use the REST APIs must be located on databases located on Exchange 2016 CU3 servers.
  • Infrastructure requirements
    • All Exchange 2016 servers must be upgraded to CU3 or later.
    • On-premises Active Directory must synchronize with Azure Active Directory.
    • Any Exchange 2013 servers coexisting in the same load-balanced array with Exchange 2016 servers must be removed from the array.
  • Networking requirements
    • From a DNS perspective, the Autodiscover namespace and on-premises client name space must have Internet DNS records.
    • If you have a firewall or application gateway that inspects and restricts access, update the appropriate settings to allow discovery and access.

 

IT administrators can find more information in the following resources:

  • Exchange Server Hybrid Deployments
  • September 2016 Cumulative Update Release
  • On-Premises Architectural Requirements for the REST API