oAuth for Planner, or how to set up Exchange integration for Office 365 / Exchange online

This guide will take you through setting up integration between Planner and Exchange, using Exchange web services for Exchange Online/Office 365, and authenticating using OAuth. You will need administrator rights in Planner and Azure Active Directory.

Planner requires information from Outlook if you want them integrated so you can move meetings in your Outlook calendar. This guide shows you how you can integrate Planner with Exchange using Exchange Web Services (EWS) if you’re using Office 365 or Exchange Online and want to authenticate using OAuth. You will need administrator rights in Planner and Azure Active Directory.

Go to https://portal.azure.com

Choose Azure Active Directory and then Properties as shown

Here you can see your Tenant ID. Please copy it as you will need it later.

Then go to App registrations and press "(+) New registration"

Give the application a name. In this guide I chose the name Pronestor. Set the application type to web app / api and set the sign-on URL to be your Planner site and press "Register". An example could be this:

Redirect URL: HTTPS://.pronestor.com>/Booking.NET/Login.mvc/Login

After you press "Register" you see the app's information. Please press "API permissions" and then "Add permission".

Under "Add a permission" press "APIs my organization uses", then under add API access choose "Office 365 Exchange Online" and then press "Select" as shown here:

Then it asks which permission to get. Please choose "Application permissions".

Correction: API Permissions → Add a permission → Exchange → full_access_as_app

Now press "Add permission".

Then press "Grant permission" and choose "Yes".

In this example, the user did not have admin rights, so he could not press "Grant permission".

Press the "Overview" and copy the Application ID for later users.

Now we go to the Planner solution. Please open your Planner site and go here

Check the box for "Exchange online". This will give you the option to check off "Use OAuth".

Then it will look like this

Put application ID in the Client ID field and the directory ID in the directory ID field.

Now we need a default booker. When a meeting is imported from Exchange online, it has an owner.

If this owner doesn't exist in Planner, Planner needs to know which user to set as the meeting owner.

In this example, I created a user named Default for this purpose, but you can choose an existing user or create your own default user. Once you have chosen the user, press "Save".

Now press "Create new certificate"

This guide is made in Chrome. If you are using another browser, please be aware that the download process can look different.

Go to the default download folder, or please save the file to your machine in a place where you can find it again.

Go back to Azure Active Directory and find your app from before and click it. Please disregard that the app in this guide has changed name.

Then press "Settings", "Keys" and "Upload Public Key".

Then press the little folder to open a file explorer and upload the certificate from Pronestor

Please press "Open" and then it will look like this:

Press "Add"

Then we return to Planner and press "Test connection"

The little text up here changes to "OK" and that means it is configured correctly.

!! Only relevant when using EWS API

This guide will show you how to create an Azure application for Exchange, user import and SSO integration, so you only need one application instead of one for each.

If you only want to setup an Exchange integration, please see this guide instead oAuth for Planner, or how to set up Exchange integration for Office 365 / Exchange online

You will need administrator rights in Planner and Azure Active Directory. This guide uses the demo site https://guidedemo.tryingplanner.com/ as an example, please remember to use your own Planner link instead.

Note, this is essential for Single sign on, but if you don't need single sign on, you can skip this chapter and chapter "Set Application ID URI"

Login to your azure at https://portal.azure.com/

Scroll down and click "Custom domain names"

Click "+Add custom domain"

Type in your link. The link needs to be based on your Planner url. In the picture I used guidedemo.tryingplanner.com but your link should be [customername].pronestor.com where [customername] is replaced with your customername.

Click "Add domain"

Then you get your Destination or points to address. Please copy it since you need to send it to [email protected] for verification.

Login to your azure at https://portal.azure.com/

Click "App Registrations"

Click "+New registration"

Give the Application a name and choose single tenant and click register

Click "Add a Redirect URI"

Click "+Add a platform"

Click "Web"

Now you need to add a link. The link needs to be based on your Planner url. In the picture I used https://guidedemo.tryingplanner.com/Booking.NET/Login.mvc/Login but your link should be https://[customername].pronestor.com/Booking.NET/Login.mvc/Login where [customername] is replaced with your customername.

Then click "Configure"

Click "Add URI"

Here we add another URL that you need to build. The link needs to be based on your Planner url. In the picture I used https://guidedemo.tryingplanner.com/Booking.NET/Login.mvc/RedeemAuthorizationCode but your link should be https://[customername].pronestor.com/Booking.NET/Login.mvc/RedeemAuthorizationCode where [customername] is replaced with your customername.

Then click "Save"

Click "Add an Application ID URI"

Click "Set"

The link needs to be based on your Planner url. In the picture I used https://guidedemo.tryingplanner.com/Booking.NET/Login.mvc/Login but your link should be https://[customername].pronestor.com/Booking.NET/Login.mvc/Login where [customername] is replaced with your customername.

Fill in the link and click "Save"

These rights are used by the user import to read your groups and users properly.

Click "Add a permission"

Click "APIs my organization uses"

Click "Office 365 Exchange Online"

Click "Select"

Choose "Application permissions"

API Permissions → Add a permission → Exchange → full_access_as_app

This right lets the application connect with Exchange

See our guide that includes advice on your ad groups. https://helpdesk.pronestor.com/hc/en-us/articles/360035378312-Azure-Active-Directory-integration

This should be done AFTER you have imported users, or you won't be able to login.

Send an email to [email protected] with:

Then the Helpdesk will enable it.

Open your Planner site

Go to Administration -> Settings

Click Exchange - note if you don't have exchange as an option, please contact [email protected] to get Exchange enabled

Click "Exchange online"

Click "Use OAuth"

Fill out Application ID and Directory id

Fill in a default booker. This user is used as the host if the host in Exchange doesn't exist in Planner. We recommend using a system user and not a real user for this fallback mechanism.

Click "Save"

Click "Create new certificate"

This will download a certificate that needs to be added to your Azure application to authorize communication between Planner and Exchange.

Open Azure and find your application

Click "Certificate & secrets"

Click "Upload certificate" and find the downloaded file.

Click "Add"

You're done in Azure, return to Planner

Click "Test connection"

If the little text up here changes to "OK" and that means it is configured correctly.

The AADSTS700016 Error:

This following error is generated because there is missing an Application URL ID.

Which need to be set under the app registration - Expose an API as shown in the video below.

The URL ID you need to set is:

But instead of [booking], you need to type in your site name

Example:

The Import From Azure Error:

The following Error is generated by a faulty Client Secret.

The following error shows when doing an import:

"Microsoft.Identity.Client.MsalServiceException: 401: Unauthorized - invalid_client. at PronestorWebAdmin.MsGraph.MsGraphAuthenticator.HandleMsalServiceException(MsalServiceException)"

the Error is resolved by going to your Pronestor app registration - Certificates & Secrets

and then renewing and setting a new Client Secret as shown in the video below.

The Error 500 when accessing "My settings"

When ever a user tries to go to the tab "My settings" they are the met with an "Error 500" page.

It is caused by either a missing or incorrect URL setting in the App registrations - Authentication section.

It can be fixed be setting the URL

Here you have to remember that [booking] needs to be changed into your own site name

Example:

Failed to update Application ID URI application property error

This means the Client id or url is incorrect. Please doublecheck that it is filled out according to the guide

!! Only relevant when using EWS API

Planner can be integrated with your Exchange environment so that your meetings are synchronized. This is done with a service account that has the right application impersonation in Exchange.

We don't directly support this, as it is done in Exchange and not in Sign In Workspace (SiW), but we have gathered some knowledge and frequently asked questions to help you set it up, as well as some links to guides on the internet.

If you want to know more about how Planner and Exchange works and why the service account needs application impersonation rights, please see this guide instead: https://helpdesk.pronestor.com/hc/en-us/articles/360028374592-Application-impersonation-rights-in-exchange-for-Pronestor-

-

For Planner, the service account needs to have application impersonation rights on all users and all meeting rooms connected to Planner.

The Exchange service account must have a mailbox and the primary email address for that account must be the original one and not an alias.

If you want, you can limit the scope of the account to just the users who book the meeting rooms through Outlook, the users who use Planner, and the meeting rooms you have imported. It is important that the service account has application impersonation rights towards all users who book the meeting rooms, or you will risk double bookings.

Please note Setting permissions on Exchange can have some latency before the permissions are set and available. Please allow up to 30 min. for Exchange to have the permissions committed.

Please ensure that you set the password for the Service account never to expire. If that isn't possible, then it is the responsibility of the customer to ensure that the password is always updated in Exchange and in SiW before it expires.

You can check whether the service account has the correct access by running a script in PowerShell. This has to be done on your Exchange server.

The script:

Get-ManagementRoleAssignment -roleassignee "[email protected]" -role applicationimpersonation

The results of the script. The "[email protected]" has the application impersonation rights. The "[email protected]" is a regular employee without application impersonation rights. If your account has application impersonation, the script response will show you the role applicationimpersonation.

Exchange 2013

http://technet.microsoft.com/en-us/library/dd776119(v=exchg.150).aspx

Example:

New-ManagementRoleAssignment -Name PronestorServiceGroup -Role applicationImpersonation -User [email protected]

Here are some very helpful third-party guides we found. Please note that SiW is not responsible for the content of these guides.

https://www.sharepointsapiens.com/blog/how-to-configure-applicaiton-impersonation-exchange/

https://cloudsolutions.atlassian.net/wiki/spaces/CKB/pages/4358166/Setting+up+Application+Impersonation+for+Exchange+or+Office+365