Overview
This Guide describes the configuration steps for OAuth authentication in an Office 365 domain following the installation of Exchange Connector 1.2.5. For steps detailing the Exchange Connector installation process please review the Microsoft Exchange On-Prem or Online Connector Install.
Background
Microsoft support for Basic Authentication is set to end in the second half of 2021. To prepare for this upcoming change a new Office 365 Connector was created that utilizes a more secure authentication mechanism called OAuth. This authentication mechanism utilizes tokens as opposed to passing a username and password between the Connector and Office 365 environment. For additional information please access the following link: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow
OAuth Parameters
Administrator access to Microsoft Azure is required to complete the configuration for the OAuth parameters. The following will need to be created:
- Application ID: The application registration is essentially an identity created in Azure to be used by external applications to authenticate themselves when accessing Azure resources. This identity will be assigned Permissions and will be used by the O365 Connector to create tokens to pass between itself and Azure/Office 365. The application ID will take the form of a string that can be copied over from Azure to the appropriate O365 Connector setup parameter once the application registration is created.
- Directory ID: This is an ID for the entire domain that should remain static for all Application IDs within a specific domain
- Client Secret: This is a long, unique string used to authenticate communications between the O365 Connector and Azure/Office 365 environment. Without the correct Secret Key, communications between the O365 Connector and Azure/Office 365 will fail.
NOTE:
The GCC High option above is used by Government and defense customers. Commercial customers should leave the box unchecked for proper operation.
OAuth Configuration
To begin the OAuth Configuration, login to the appropriate Azure Active Directory account for the domain that hosts the O365 Connector. Once logged into Azure, select App registrations.
Select New registration to begin the process for creating the Application that will direct communications between Office 365 and the O365 Connector.
Complete the necessary information. The Application will require a name and a support account type.
Complete the necessary information. The Application will require a name, support account type, and redirect URI (this can be http://localhost:8080 or any relevant URI).
Once this is completed click on the Register Button at the bottom.
Once Registered the Application will now appear under All applications as shown below.
Double click on the new Application. Copy and paste the Application ID and Directory ID to a file. These will be needed when authenticating with the actual O365 Connector.
Choose the option to create a Key under Certificates & Secrets.
Add a Key with a chosen name. Choose the appropriate expiration date and click Add.
This will create the secret key. Immediately copy and paste the Value to a secure location. Please note that the Value will NOT be visible later and this will be the only chance to copy and save it.
Notice in the picture above that the Connector Secret Value is now hidden.
Navigate back to Settings and select Required Permissions under API Access.
Note: It is known that the O365 Connector will not function if Permissions are not added. However, Graph Permissions will suffice for connector functionality. It is always recommended to enable only the Permissions needed for connector functionality.
Clicking API permissions will load the following page.
Click on User.Read. Follow the steps to remove.
Click on Add a permission.
Choose “Microsoft Graph” found under Microsoft APIs.
Choose Application Permissions. Once complete, select whether the permissions should be applied to one account or all accounts. See pictures on the following pages of all available Office 365 Permissions. Delegation Permissions not required for connector functionality.
Select the following Permissions only: Calendars.ReadWrite, as shown below.
Click on Grant Admin Consent
Click the Yes button for the Grant admin consent permissions to take effect. After the Permissions are granted, click under Overview in Azure. If you did not copy the Application ID and Directory ID earlier, please copy them now as this will be needed for authenticating with the O365 Connector.
Once this is copied, authentication is ready for testing. Copy the Application ID, Directory ID, and Secret Key to the appropriate fields on the O365 Connector Website, as shown below. Next, select a valid Room Resource that is currently in the Office 365 environment. Enter it in the Test Resource field, then click Connection Test and wait for a confirmation of Success.
After success is confirmed the new Exchange Connector configuration can be downloaded to the following directory:
C:\Sites\<Connector Installation Directory>\bin. Here, you will be required to overwrite the Site.config file with the one that is currently being downloaded.
Once saved the website will display OAuth at the top of the Exchange Connector as the configured authentication.
Scoping the Application ID for Room Resources
An application with the Calendars.ReadWrite access can read/write all mailboxes in an Office 365 environment. This is not desirable from a security standpoint. Fortunately, Microsoft provides a method for scoping the Read/Write Permission of the newly created application to just specific mailboxes, in this case Room Resources affiliated with Room Wizard devices. The link below has additional information:
https://docs.microsoft.com/en-us/graph/auth-limit-mailbox-access
To begin, the user needs to login to Office 365 using PowerShell and a browser.
From Office 365 create a Mail-enabled security Group. This Group should have all Room Resources that are affiliated with RoomWizard devices added as members.
The next step is to map the Mail-enabled security Group to the Application created with Read/Write Calendar credentials. Run the following command:
New-ApplicationAccessPolicy -AppId <Application ID> -PolicyScopeGroupId <emailaddress> -AccessRight RestrictAccess
The New-ApplicationAccessPolicy command will allow only members of a specified Mail-enabled Security Group associated with the Application to use the Permissions assigned to the application. All mailboxes that are not members of this Mail-enabled Security Group will be blocked from using the permissions assigned to the application. This means nonmembers will not be able to schedule or view meetings in Office 365 using this specific application.
To test whether a Room Resource is granted/denied access to the application, run the following command, where “AppId” is the Azure ID of the application registration from Azure:
Test-ApplicationAccessPolicy -Identity <Room Resource ID> -AppId <Application ID>
Note that once the command is run, the list of Room Resources can be updated by adding/removing members of the Mail-enabled security Group.
Debug Logging
Debug logs allow the connector to display detailed information of the Room Resources at each Poll Interval. These logs can be useful when analyzing and troubleshooting issues between the Office 365 Connector and Office 365 environment. The debug logs are disabled by default. Careful consideration should be made when enabling these logs as they can grow large over time and place stress on the IIS Server.
Steps to enable:
- Open the file in the root of the Connector installation directory and under the bin folder.
- Open the NLog file and change the value for minlevel from Info to Debug and save:
- View the Application Logs. Each Poll Interval will display a log transaction for each RoomWizard utilizing the Graph Connector. Logs appear even if no errors are displayed between the Office 365 Connector and Office 365 environment.
