Page tree
Skip to end of metadata
Go to start of metadata

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

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.comusing the credential of your Microsoft tenant that has the subscription to Office 365 you wish to use.
  • Click "Azure Activity Directory" in the left-hand menu. 
  • In the menu, click "App registrations".
  • Click "New application registration".
  • Enter the Name of the application (e.g. MyTimetable-prod).
  • Select "Web app / API" at "Application type".
  • Enter a URL at "Sign-on URL". Any URL is possible, MyTimetable does not use this value.
  • Click "Create".


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.

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.
  • In the Azure Management Portal, click the "Settings" button at the app that was created
  • Pick "Required permissions" in the menu that appears
  • Click "Add"


  • Click "Select an API"
  • Pick "Office 365 Exchange Online (Microsoft.Exchange)"
  • Click "Select"
  • Tick the box "Read and write calendars in all mailboxes"
  • Click "Select"
  • Click "Done"


The default permissions for the Windows Azure Active Directory can be removed
  • Click "Windows Azure Active Directory"
  • Click the "Delete" button and confirm using "Yes"



Finally, we need to consent to the apps permissions on behalf of all users in the tenant, so users do not have to manually consent.

  • Click the "Grant Permissions" button and confirm using "Yes"

Step 3: Generating and uploading a X.509 certificate

In order to enable service-to-service calls, a X.509 certificate needs to be configured and uploaded to Azure. 
  • First 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):
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 3650 -config openssl.cnf
  • Back in the Azure Management Portal, click the "Settings" button at the app that was created
  • Pick "Keys" in the menu that appears
  • Click "Upload Public Key"
  • Upload the "cert.pem" file that was generated by OpenSSL
  • Click "Save"
  • The key should now be visible under "Public Keys"

Information required for MyTimetable configuration

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

  1. Azure AD tenant name
  2. Application ID of the registered app
  3. Public key of the X.509 certificate (cert.pem)
  4. Private key of the X.509 certificate (key.pem)
  5. Password for the private key

Converting the X.509 certificate (optional)

MyTimetable requires the generated X.509 certificate in a Java Keystore format. The Eveoh support department can convert the generated X.509 certificate into a Java Keystore. If you want to do it yourself, please follow these steps:

  • Convert the X.509 certificate into the PKCS12 format using OpenSSL:
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):
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


  • No labels