Versions Compared

Old Version 21

changes.mady.by.user Former user

Saved on

compared with

New Version 22

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The MyTimetable Office 365 integration is able to connect to a user's calendar using the Outlook Calendar the Microsoft Graph REST API. This page describes how to grant MyTimetable access to the Outlook Calendar Microsoft Graph REST API. MyTimetable will then be able to access calendars without explicit consent of a user.

Table of Contents

Setting up a new Azure AD application

Please follow the following steps to set up the Azure AD application.

Step 1: Registering MyTimetable as an application in Azure AD

First, we need to register a new app in Azure AD, using the Microsoft Azure Management Portal.

  • Visit the Microsoft Azure Management Portal at portal.azure.com, using the credential of your Microsoft tenant that has the subscription to Office 365 you wish to use.
  • Go to "Azure Activity Directory". 
  • In the menu, click "App registrations".
  • Click "New registration".
  • Enter the Name of the application (e.g. MyTimetable-prod).
  • Select 'Accounts in this organizational directory only' as we currently only support single tenant apps.
  • Enter https://<your-mytimetable-site>/schedule?zoneview=0&ec_type=o365 as Redirect URI, replacing <your-mytimetable-site> with the appropriate value.
  • Click "Register".

Image Removed

Image Removed

Your application is now registered with Azure AD. Proceed with the next step to specify the app permissions.

Step 2: Specifying app permissions

Next, we need to make sure the newly created app has the correct permissions to access user calendars.

Note

The "Read and write calendars in all mailboxes" application permission is described by Microsoft as "Allows the app to create, read, update, and delete events of all calendars without a signed-in user". Less restrictive scopes that allow MyTimetable to perform the operations required are not available at the moment. MyTimetable only reads, updates and deletes calendar events it has created itself, but this is something that is enforced in the synchronisation backend, not by Office 365. So while MyTimetable does not read, update or delete other calendar events, it does have the permissions to do so.

When using application-level permissions, this permission can optionally be scoped to specific mailboxes by following the instructions at Scoping application permissions to specific Exchange Online mailboxes.

  • In the newly created application choose "API permissions".
  • Click "Add a permission".

Image Removed

  • When using application-level permissions (e.g., MyTimetable is authorised to sync to all mailboxes by default):
    • Choose "Microsoft Graph" > "Application Permissions" > "Calendars" and tick "Calendars.ReadWrite".
    • Click "Add permissions".
    • Add another permission (required for older MTT versions), click "Add a permission" again.
    • Choose "Exchange" > "Application Permission" > "Calendars" and tick "Calendars.ReadWrite.All".
    • Click "Add permissions".
    • Click "Select"
    • Click "Done"
  • When using delegated-level permissions (e.g., the user still has to authorise MyTimetable itself when enabling the sync):
    • Choose "Microsoft Graph" > "Delegated Permissions" > "OpenId permissions" and tick "offline_access".
    • Also choose "Calendars" and tick "Calendars.ReadWrite".
    • Click "Add permissions".
    • Click "Select"
    • Click "Done"
The default permissions can be removed
  • Click "User.Read"
  • Click the "Remove permissions" button and confirm using "Yes, remove"

Image Removed

...

  • Click the "Grant admin consent" button and confirm using "Yes"

Image Removed

...

In order to enable service-to-service calls, a X.509 certificate needs to be configured and uploaded to Azure. 
  • If you are using MyTimetable managed hosting, Eveoh will provide you with a certificate to upload. If you are an on-premises customer you will need to create this certificate yourself by following:
    • We need to create a self-signed certificate. This can be done using the minimal openssl install found at https://files.eveoh.nl/openssl_min.zip (for Windows) or an OpenSSL install included in the OS (Linux). From the command line, create a self-signed certificate and enter a password (make sure to remember this), the university name, country and domain name of your MyTimetable instance (common name):
Code Block
languagebash
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 3650 -config openssl.cnf
  • Back in the Azure Management Portal, click "Certificates & secrets".
  • Choose "Upload certificate".
  • Upload the "cert.pem" file from Eveoh or generated in the first step.
  • Click "Add"
  • The key should now be visible under "Public Keys".

Image Removed

...

In order to enable service calls to the Outlook Calendar REST API, the Eveoh support department requires the following information

Determine authorization method

There are two ways to authorise MyTimetable to access calendars: application permissions or delegated permissions.

When using application permissions, MyTimetable is granted access to all calendars or a subset of calendars limited by a mail-enabled security group in advance. This means MyTimetable can setup synchronisations without further actions from the user, which is appropriate for scenarios where a synchronisation needs to be setup as soon as a user is provisioned in MyTimetable. This uses the OAuth 2 client credentials flow.

When using delegated permissions, MyTimetable is granted access when the user requests to setup a synchronisation from MyTimetable. Depending on the settings, this will also show the user a consent prompt. This scenario is appropriate when users do not need to have an active synchronisation by default, and limits the security footprint of MyTimetable. This uses the OAuth 2 authorization code flow.

Setup Azure AD application

If MyTimetable is hosted by Eveoh, our support department will supply you with an authentication certificate which you will need in step 1. If you are hosting MyTimetable on-premises, first create this certificate using the steps outlined on On-premises: creating a certificate.

When using application permissions, perform the following steps:

When using delegated permissions, perform the following steps:

In order to enable service calls to the Microsoft Graph REST API, the following information is required:

  1. Azure AD tenant name
  2. Application (client) ID of the registered app
  3. For on-premises hosting:
    1. Public key of the X.509 certificate (cert.pem)
    2. Private key of the X.509 certificate (key.pem)
    3. Password for the private key

Storing the X.509 certificate and private key in a Java Keystore (optional)

MyTimetable requires the generated X.509 certificate and the corresponding private key to be available in a Java Keystore. The Eveoh support department can store the X.509 certificate and its private key into a Java Keystore for you. If you want to do it yourself, please follow these steps:

  • Save the X.509 certificate and the private key into the PKCS12 format using OpenSSL:
Code Block
languagebash
openssl pkcs12 -export -in cert.pem -inkey key.pem -out cert.pfx
  • Convert the PKCS12 format into a JKS file, using keytool (available in the JRE/JDK):
Code Block
languagebash
keytool -importkeystore -srckeystore cert.pfx -srcstoretype pkcs12 -destkeystore cert.jks -deststoretype JKS

Certificate rollover

It is possible to configure multiple X.509 certificates for the application, for example for rollover scenarios in case a certificate expires.

Sources

Anchorgenerate-x509-certificategenerate-x509-certificateWhen using managed hosting, please send this information to the Eveoh support department. When using on-premises hosting, you will need to enter these details in the MyTimetable EC configuration.