Howto13r2:Setting up Calendar with OAuth2
How-to setup the Calendar for OAuth2
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 found 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 CalendarApp 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
Open the Azure Portal Active Directory
- Go to the Azure Portal homepage and sign in with your admin user
- 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
- 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
- Click on “Certificates & Secrets” in the list on the left
- Then click on “New client secret” under the “Client secrets” section
- Define an expiration date (the client secret itself will be randomly created)
- Optional: add a description
- Click on "Add" - the secret should be visible in the list
- Copy the value (click in the icon beside the value) and insert it to the "Client secret" field in the Calendar configuration
Note: 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 first permissions - the manifest
- Click on “Manifest” in the sidebar
- Scroll down the Manifest-File until you see the “requiredResourceAccess” property
- Add the data block from box below (including the ',')
- Click on save - the manifest should similar to the one in the screenshot
Note: If you want, you can replace the existing part with in the manifest with the block below (in that case 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).
{ "resourceAppId": "00000002-0000-0ff1-ce00-000000000000", "resourceAccess": [ { "id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40", "type": "Role" } ] },
Configure the second permissions - Microsoft Graph
- Click on API permissions on the right
- Due the changes in the manifest an entry "Office 365 Exchange Online" with the subitem "full_access_as_app" should be visible
- Click on “Add a permission”.
- In the following dialog click on “Microsoft Graph”
- Click on “Delegate permissions”
- Type “EWS” into the search field
- Click on the arrow before "EWS" and select “EWS.AccessAsUser.All”
- Click on "Add permission"
- You should see "EWS.AccessAsUser.All" under the "Microsoft Graph" section of the list
Configure permission - set rights
- The permissions should may have the status "Not granted..." or no status at all.
- Click on "Grant admin consent for...." button above the list
- Confirm the question shown by a message box
- All premissions should now have the status "Granted for..."
The Calendar app registration is now successfully completed.
Setting up the Calendar configuration on the App Platform
- Open the PBX Manager in myApps, click on Calendar and then on "Configre" (if not already done)
- Set the fields like shown in the table below
- Click on "Authenticate" and follow the instructions
- On success, the Calendar OAuth2 configuration is completed
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). |
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:
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.