Howto13r2:Setting up Calendar with OAuth2

From innovaphone wiki
Jump to navigation Jump to search

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

Azure Portal
Azure Active Directory Overview
  • 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

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

Create client secret
Client secret list
  • 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

Manifest file
  • 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

Exchange Online - Full access as app
EWS - Access all user
  • 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

Permissions not granted
Permissions granted
  • 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:

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.