Page Comparison

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.

Table of Contents

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

• Visit the Microsoft Azure classic Management Portal at manage.windowsazure.com, using the credential of your Microsoft tenant that has the subscription to Office 365 you wish to use.
• Click "Activity Directory". 
• Click the Active Directory you would like to manage.
• On the Directory page, click "Applications".
• Click "Add" in the bottom menu bar.

Image Removed

...

• 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.
  

...

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

Generating a X.509 certificate and configuring 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 (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

Now, we need to find some properties of the certificate we have generated. This can be done using the Unix shell or using Windows Powershell.

• From the Unix command line, run the following:
  

# keyid
uuidgen | tr "[:upper:]" "[:lower:]"
 
# base64Value
openssl x509 -in cert.pem -outform DER | openssl base64
 
# base64Thumbprint
openssl x509 -in cert.pem -outform DER | openssl dgst -binary -sha1 | openssl base64

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

$cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("C:\Full\Path\To\Certificate\cert.pem")
$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 Powershell script echoes them at the end).
  

Configuring Azure AD 

Now, we need 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 the "Generating the X.509 certificate" previous step.

"keyCredentials": [
    {
        "customKeyIdentifier" : "$base64Thumbprint_from_above",
        "keyId": "$keyid_from_above",
        "type": "AsymmetricX509Cert",
        "usage": "Verify",
        "value": "$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.
• 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 Removed

• 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 Removed

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

Image Removed

• 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 certificate needs to be converted to a Java keystore. First convert it to PKCS12, using OpenSSL:
  

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):

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:

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

Certificate rollover

It is possible to configure multiple X.509 certificates for the application, for example for rollover scenarios. 

• First, generate a new X.509 certificate, as described in "Generating the X.509 certificate". Store the values for keyid, base64Thumbprint and base64Value.
• Visit the Microsoft Azure classic Management Portal at manage.windowsazure.com, using the credential of your Microsoft tenant that has the subscription to Office 365 you wish to use.
• Click "Activity Directory". 
• Click the Active Directory you would like to manage.
• On the Directory page, click "Applications".
• Select the previously defined application for MyTimetable.
• In the bottom menu bar, click "Manage manifest" and choose "Download Manifest" and download the manifest.
• Open the downloaded manifest in a text editor and add a new KeyCredentials property to the JSON. Make sure the $-variables are replaced by the values you have stored in the "Generating the X.509 certificate" previous step. In the example below, the first block contains the original KeyCredential. A second one is added with the newly generated values.

"keyCredentials": [
	{
        "customKeyIdentifier" : "IgGH4KCp1BBMAEjV+PfyLZdujno=",
        "keyId": "580bdcde-c31f-4559-8f16-ce03863404d6",
        "type": "AsymmetricX509Cert",
        "usage": "Verify",
        "value": "MIIDsDCCApgCCQCg...IAg3"
    },
    {
        "customKeyIdentifier" : "$base64Thumbprint_from_above",
        "keyId": "$keyid_from_above",
        "type": "AsymmetricX509Cert",
        "usage": "Verify",
        "value": "$base64Value_from_above"
    }
],

...

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.com, using 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 "Sing-on URL". Any URL is possible, MyTimetable does not use this value.
• Click "Create".

Image Added

• Copy the Application ID of the registered app, so you can provide it to the Eveoh support department (see Information required for MyTimetable configuration).

Image Added

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.

• 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"

Image Added

• 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"

Image Added

• Click "Windows Azure Active Directory"
• Click the "Delete" button and confirm using "Yes"

Image Added

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"

Image Added

Anchor
generating-and-uploading-a-certificate generating-and-uploading-a-certificate

Step 3: Generating and uploading a X.509 certificate

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 3650 -config openssl.cnf

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.

• Follow the steps as specified at Generating and uploading a X.509 certificate. 
• Securely send the new private and public key to Eveoh, including the password for the private key. 

Sources

• https://msdn.microsoft.com/library/office/dn707383.aspx