Versions Compared

Version Old Version 2 New Version 3
Changes made by

Former 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 REST API. This page describes how to grant 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.

Registering MyTimetable as an application in Azure AD and getting the manifest

  • Visit the Microsoft Azure classic Management Portal at https://portal.azuremanage.windowsazure.com, using the credential of your Microsoft tenant that has the subscription to Office 365 you wish to use.Click "Browse all" to browse all resources.
  • Click "Activity Directory". You will now be redirected to the classic Azure Management Portal. 
  • Click the Active Directory you would like to manage.
  • On the Directory page, click "Applications".
  • Click "Add" in the bottom menu bar.

...

  • Select "Add an application my organization is developing".
  • Enter the Name of the application (e.g. MyTimetable-prod) and specify the Type as "Web application and/or Web API".
  • Enter the App properties:
    • SIGN-ON URL. The URL where users can sign in and use your app. You can change this later as needed. Any URL is possible, MyTimetable does not use this value.
    • APP ID URI. The URI used as a unique logical identifier for your app. Use for example https://mytimetable.institution.ac.uk.
  • Click "Configure".
  • Write down the "Client ID".

Your application is now registered with Azure AD.

Creating and configuring an X.509 certificate

In order to enable service-to-service calls, a X.509 certificate needs to be configured. 

First, we need to obtain an X.509 certificate using the makecert tool. This tool is included in for example the Windows SDK for Windows 8.1. Using this SDK, makecert is available in C:\Program Files\Windows Kits\8.1\bin\x64.

  • From the command line, create a self-signed certificate:
Code Block
languagepowershell
makecert -r -pe -n "CN=MyInstitution MyTimetableProdO365" -m 120 -ss my -len 2048

Now, we need to find some properties of the certificate we have generated.

...

  • In the bottom menu bar, click "Manage manifest" and choose "Download Manifest" and download the manifest.

    Image Added

Your application is now registered with Azure AD. Proceed with the next step to register the authentication certificate with Azure.

Creating and configuring an X.509 certificate

In order to enable service-to-service calls, a X.509 certificate needs to be configured and uploaded to Azure. Our support department will gladly assist you with this, if you send us the manifest from the previous step. If you want to perform these steps yourself, please follow the instructions below.
  • 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 (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

Now, we need to find some properties of the certificate we have generated. This is easiest done using Windows Powershell.

  • From the Windows Powershell prompt, run the following (replace the path to the certificate):

Code Block
languagepowershell
$cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("C:\Full\Path\To\Certificate\certificatecert.cerpem")
$bin = $cer.GetRawCertData()
$base64Value = [System.Convert]::ToBase64String($bin)
$bin = $cer.GetCertHash()
$base64Thumbprint = [System.Convert]::ToBase64String($bin)
$keyid = [System.Guid]::NewGuid().ToString()
$base64Value
$base64Thumbprint
$keyid
  • Store the values for $base64Thumbprint, $base64Value and $keyid (the script echoes them at the end).

Now, we need to update the application manifest in Azure AD.

  • In the Azure Management Portal, select your application and choose Configure in the top menu.
  • In the bottom menu bar, click "Manage manifest" and select "Download Manifest".

Image Removed

 to update the application manifest in Azure AD.

  • Open the downloaded manifest in a text editor and replace the empty KeyCredentials property with the following JSON. Make sure the $-variables are replaced by the values you have stored in a previous step.
Code Block
languagejs
"keyCredentials": [
    {
        "customKeyIdentifier" : "$base64Thumbprint_from_above",
        "keyId": "$keyid_from_above",
        "type": "AsymmetricX509Cert",
        "usage": "Verify",
        "value": "$base64Value_from_above"
    } ],
  • Save your changes and upload the updated manifest by clicking "Manage manifest" in the bottom menu bar, selecting "Upload manifest", browsing to your updated manifest file, and then selecting it.
Specify the 
"$base64Value_from_above"
    }
],
  • Save your changes to the manifest.

Uploading the manifest and specifying app permissions

Finally, we need to upload the manifest and specify the app permissions, allowing read/write access to the calendars of the users.

  • In the Azure Management Portal, select your application and choose "Configure" in the top menu. your application and choose "Configure" in the top menu.
  • In the bottom menu bar, click "Manage manifest" and choose "Upload manifest".
  • Upload the manifest created in the previous section.
  • Scroll down to "Permissions to other applications", and click "Add application".


Image Modified


  • Select the "Office 365 Exchange Online" so that it appears in the "Selected" column. Click the check mark in the lower right to return to the main configuration page. "Office 365 Exchange Online" has now been added to the applications list.


Image Modified

 

  • Click the "Application permissions" dropdown menu for "Office 365 Exchange Online" and check the box for "Read and write calendars in all mailboxes".


Image Modified

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.
  • Remove the "Windows Azure Active Directory" application in the permissions list.
  • Click "Save" to save the configuration.

Information required for MyTimetable configuration

In order to enable service calls to the Outlook Calendar REST API, MyTimetable requires the X.509 certificate generated in the previous steps.

...

the X.509 certificate generated in the previous steps.

  • The certificate needs to be converted to a Java keystore. First convert it to PKCS12, using OpenSSL:
Code Block
languagebash
openssl pkcs12 -export -in cert.pem -inkey key.pem -out cert.pfx
  • Then convert it to 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

Please make sure the following data is available at the server which will handle the Office 365 synchronisation:

  • X.509 certificate JKS keystore exported in the previous step.
  • Password for the X.509 certificateJKS keystore.
  • Azure AD tentant name.
  • Client ID of the registered app.

Sources

...