Howto13r2:Setting up Calendar with OAuth2

How-to setup the Calendar for OAut2

This tutorial shows you, how to setup an Azure Active Directory App to let the calendar work with Microsoft 365 and OAuth2. Please note, that this is not a complete administration guide. Instead, it is a simply step-by-step tutorial which should work but maybe not the most accurate administration of your Azure AD – it’s just the way how we managed to use it. It is highly recommended to ask your Azure Administrator for details and / or read the Microsoft documentation. It is expected, that you have an Exchange user with the Application Impersonation right. More information about how to assign this role to a user can be find in the Microsoft documentation.

Note: The screenshot and labels may change because of updates done by Microsoft. The following steps had been made with the version with the Azure portal from August 2021. Note also that the images are scaled. If you need a sharper image, just click on it to see it in full size

Preparation

During the creation of an app, you need some information provided by the configuration of the Calendar and also add some information given by Azure. Because of that it is recommended to open the PBX Manager / AP Calendar in myApps (click on Configure and select “Cloud (Exchange Online)” as Sync Type) and the Azure Portal in your browser at the same time. You also have to login to the Azure Portal with an admin user to be able to add an application registration as well as to configure it.

If you get stuck or you need additional information, or if you are unsure if the way describe here is the best solution for your company, be free to use all the documentation and help links Microsoft provides in the Azure portal.

Registering the Calendar app to the Azure Active Directory

Create an App registration inside the Azure Active Directory

Open the Azure Portal Active Directory

Azure Portal

Azure Active Directory Overview

• Go to the Azure Portal homepage and sign in with your admin user (portal.azure.com)
  • Select “Manage Azure Active Directory” or click on one of the “Azure Active Directory” links.
  • You will be redirected to the Azure Active Directory Overview

Add a new App registration

Add new app registration

Registered app overview

• Create an app registration
  • Click on “+ Add” and select “App registration” (alternatively click on “App Registration” on the side bar and add an App registration by clicking on “New registration”)
  • Set a name for the registration (e. G. innovaphone Calendar)
  • Select the supported account type (see note below).
  • Select "Web" in the dropdown list under "Redirect URI" (just enter the URI that you can find in the "Redirect URI" field of the PBX Manager / Calendar configuration).
  • Click "Register" to save the App Registration. On success, you should see the overview page for the registered app.

Note: The account type should be either “Accounts in this organizational directory only (YourCompanyName only - Single tenant)” (which is recommended) or “Accounts in any organizational directory (YourCompanyName - Multitenant)”. If you go with the single tenant, you have to select “My organization only” in as “Selected account types” for the Calendar configuration. If you select multitenant, “Multiple organizations” have to be configured.

Configure the client secret

The client secret is a security key you need to add, since it is mandatory for the OAuth2 authentication process used by the Calendar. To create one, click on “Certificates & Secrets” in the list on the left. Then click on “New client secret” under the “Client secrets” section:

The client secret will be randomly created by Azure, the only thing you may set is a description (which is optionally) and an expiration date. After clicking on “Add”, you should see the new client secret listed:

Now copy the “Value” (again, simply click on the icon beside the Value) and insert that at the Calendar configuration in the field “Client secret”. Note that after a couple of minutes, the Value of the client secret will be grayed out by Azure and you can’t copy it anymore. If that happens, just delete the old, create a new one and copy the value.

Configure the permissions

There are two API permission to be set. The first one will be added by editing the manifest file (as described at the Microsoft documentation (https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth). Click on “Manifest” in the sidebar. Scroll down the Manifest-File until you see the “requiredResourceAccess” property and add the following block to it:

{
    "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
    "resourceAccess": [
        {
            "id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40",
            "type": "Role"
        }
    ]
},

Click on “Save”. The manifest now should look like this:

(Note: If you want, you can replace the existing part with the one above. In that case, the above part must be added without the comma after the closing ‘}’ bracket. This will remove the Users.Read right, which isn’t used anyways (but it also won’t hurt, if the right still exist)).

Click on API permissions on the right. Here you should find an entry called “Office 365 Exchange Online” with a sub item named “full_access_as_app”.

The next permission will be added by selecting it from a list. Click on “Add a permission”. In the following dialog click on “Microsoft Graph” and then on “Delegate permissions”. To make things easier, type “EWS” into the search field, open the entry and select “EWS.AccessAsUser.All”:

Click on “Add permission” to close the dialog. You should now have at least “full_access_as_app” and “EWS.AccessAsUser.All” in the list of permission:

However, the status column will show no or a “Not granted” entry. This can be simply resolved by clicking on “Grant admin consent for …”. Answer the upcoming dialog box with “Yes” and the status column should show “Granted for…” for every permission. The app registration for the Calendar is now completed.

Setting up the Calendar configuration on the App Platform

You have now registered you App to the Azure Active Directory. The last step is to finalize the setup for the innovaphone Calendar using the PBX Manager. Just fill in the fields as follows:

Field	Value
Sync-Type:	Cloud (Exchange online)
User:	The user with the Application Impersonation right in Exchange
Autodiscover URL:	https://autodiscover-s.outlook.com
Exchange server to use:	Either external or internal, depending on your configuration. However, external should be fine for most Exchange 365 installations.
Client ID:	The Application (client) ID from you AD app registration
Supported account:	“My organization only” or “Multiple organization”, depending what you configured during app registration (see above).
Redirect URI:	Nothing to change here - leave it unchanged
Scopes:	https://outlook.office365.com/.default
Client Secret:	The value of the client secret you from your application registration (see above).

Now click on “Authenticate…” and follow the instructions. If everything works as expected, the Calendar should now communicate with Exchange Online, using OAuth2 authentication.

Troubleshooting

Authenticating error with Autodiscover

If you run into authentication problems with the Autodiscover server, it can be that the default security settings are enabled for your Active Directory (which probably will be the case for new Exchange Online Setups). In that case, configure the security settings to allow access to the Autodiscover server or disable the default security settings, like described here:

https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/concept-fundamentals-security-defaults

Finding an alternative Autodiscover server

You can also try to find an alternative Autodiscover server by using the Microsoft Autodiscover V2 API. To do so, just enter the following URL to your browser (replacing the email address placeholder first): https://outlook.office365.com/autodiscover/autodiscover.json/v1.0/<Email-Address-Of-Your-Impersonation-User>?Protocol=AutodiscoverV1

If your impersonation user has the email address impersonation@mycompany.com, the URL will be: https://outlook.office365.com/autodiscover/autodiscover.json/v1.0/impersonation@mycompany.com?Protocol=AutodiscoverV1

You should receive a simple text message that may be similar to the following:

"Protocol":"AutodiscoverV1","Url":"https://outlook.office365.com/autodiscover/autodiscover.xml"}

Your Autodiscover server will be the part from https to the first /autodiscover part (in this example https://outlook.office365.com)

Using On-Premises as fallback

If because of some configuration on the Exchange / Active Directory side or whatever reason the above guide won’t help, you still should be able to switch to On-Premises connection even with Exchange Online. Just configure the Calendar using the PBX Manager as follows:

Field	Value
Sync-Type:	On-Premises (local network)
User:	The user with the Application Impersonation right in Exchange
Password:	The password of the user
Autodiscover URL:	https://autodiscover-s.outlook.com
Exchange server to use:	Either external or internal, depending on your configuration. However, external should be fine for most Exchange 365 installations.

If the connection to the Autodiscover server failed, you can use the above way to get an alternative server and / or disable the default security settings for your AD.