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.
Registering MyTimetable as an application in Azure AD
- Visit the Microsoft Azure Management Portal at https://portal.azure.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.
- APP ID URI. The URI used as a unique logical identifier for your app. Use for example https://mytimetable.institution.ac.uk.
- Write down the "Client ID".
Your application is now registered with Azure AD.
Generating an application key
- Make sure the application you have just added is visible in the Azure Management Portal.
- Click "Configure" in the top menu.
- Scroll down to "Keys".
- Select the duration for your key.
- Click "Save".
- The Azure Management Portal now displays the app secret.
- Copy and store the key value. The key value is not needed for the MyTimetable integration, but you won't be able to retrieve it after you leave the page.
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 | ||
|---|---|---|
| ||
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.
...
| Code Block | ||
|---|---|---|
| ||
$cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("C:\Full\Path\To\Certificate\certificate.cer")
$bin = $cer.GetRawCertData()
$base64Value = [System.Convert]::ToBase64String($bin)
$bin = $cer.GetCertHash()
$base64Thumbprint = [System.Convert]::ToBase64String($bin)
$keyid = [System.Guid]::NewGuid().ToString() |
- Store the values for $base64Thumbprint, $base64Value and $keyid.
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".
- Open the downloaded manifest in a text editor and replace the empty KeyCredentials property with the following JSON:
| Code Block | ||
|---|---|---|
| ||
"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 app permissions
Finally, we need to 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. Scroll down to "Permissions to other applications", and click "Add application".
- 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.
- Click the "Application permissions" dropdown menu for "Office 365 Exchange Online" and check the box for "Read and write calendars in all mailboxes".
| 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. |
- 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.
- Open the Microsoft Management Console (Start -> Run -> mmc).
- Click "File" -> "Add/remove snap-in".
- Add the "Certificates" snap-in for "My user account".
- Find the new certificate in the "Personal" folder (Certificates - Current user -> Personal -> Certificates).
- Right-click the certificate, and pick "All Tasks" -> "Export".
- Choose "Yes, export the private key".
- Also enter a password for the certificate.
- Export the certificate to a file.
Please make sure the following data is available at the server which will handle the Office 365 synchronisation:
- X.509 certificate exported in the previous step.
- Password for the X.509 certificate.
- Azure AD tentant name.
- Client ID of the registered app.
Sources
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 Semestry, 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:
Azure AD tenant ID
Application (client) ID of the registered app
When using managed hosting, please send this information to the Semestry support department. When using on-premises hosting, you will need to enter these details in the MyTimetable EC configuration.