Setting up Microsoft Graph Client Credentials

Background

Affinity customers using SSO for end-user authentication also need to be configured with admin-level authorization to be able to connect to Office 365 on behalf of users so that Affinity can sync end-user email and calendar data. If you have an on-premise Exchange server and aren't using Office 365, this article will not apply to you, but please reach out to your point of contact at Affinity about setting up an Exchange Web Services Impersonation Account. If you already have an Exchange Impersonation Account configured with Affinity, but are using Office 365, please note that the Impersonation approach may eventually be phased out, and your configuration will need to be transitioned to a different approach.

The approach we are using to connect to Office 365 at an admin level is the Microsoft Graph Client Credentials Flow. This allows the Office 365 admin to authorize the Affinity application on behalf of the tenant so that individual users are not required to.

Security Considerations

The Client Credentials flow is an OAuth-based flow which means that access to the tenant's data and resources is secured by an Access Token, Client ID, and Client Secret, whereas Impersonation requires that Affinity know the username and password of the impersonation user. The OAuth approach also means that access to the tenant's data and resources is restricted to only the scopes that the admin authorizes during the OAuth flow, whereas Exchange Impersonation grants full access to all users' data and resources for users who are configured to participate in impersonation. Finally, like how the Exchange Impersonation approach can restrict tenant-wide access by configuring ManagementRoleAssignments and ManagementScopes, the Client Credential Flow approach can also restrict tenant-wide access by configuring ApplicationAccessPolicies. More details on configuring such policies are described below.

Set-Up

Your contact at Affinity will send you an admin consent link for an Office 365 admin to click through to authorize the Affinity application. By clicking the link, the admin will see one of the following screens:

We have seen that some customers see a "Forbidden" error in their browser after completing the admin consent flow. This is safe to ignore, and you should see a "success" message on your screen if you simply refresh the page. Our callback URL from the admin consent flow attempts to use the newly generated access token to get the display name of the Azure tenant that just granted the access, but what can happen at times is that the access token granted by Microsoft is not immediately available for use, resulting in a "Forbidden" error in the UI.

Let your Affinity contact know that you have authorized the application, and we will complete the rest of your setup on our end. If you had previously set up Exchange Impersonation, we will purge all details associated with the impersonation account as well.

As mentioned above, the Office 365 admin can restrict the application's access to a subset of mailboxes using a Windows Powershell command for Exchange Online.

• Connect to Exchange Online using Windows Powershell following the instructions at Connect to Exchange Online PowerShell.
• Follow the instructions at Limiting application permissions to specific Exchange Online mailboxes to run the New-ApplicationAccessPolicy command, which will apply the access restrictions to the Affinity application
  • The Affinity application ID is 42c434ab-8def-400b-8ac0-fc857e194bf0 for standard email access or 63c46447-3636-45ef-9c0b-90d8a9ef2001 for basic email access
  • Note that step 2 in the document indicates that you must use a mail-enabled security group for the policy
  • An example of the command would be: New-ApplicationAccessPolicy -AppId 42c434ab-8def-400b-8ac0-fc857e194bf0 -PolicyScopeGroupId AllowedUsers@customer.com -AccessRight RestrictAccess -Description "Restrict the Affinity app so that it can only access the mailboxes of the AllowedUsers group."
  • You can test the application's ability to access various mailboxes using the Test-ApplicationAccessPolicy command, which is detailed at Test-ApplicationAccessPolicy.

Scoping Microsoft Graph application permissions to specific Exchange Online mailboxes are some additional details from Microsoft about the release of the application restriction feature.

Additional Information

• A transition from Exchange Impersonation to the Client Credentials Flow only affects how Affinity connects to Office 365 and syncs data. End-user authentication to Affinity is not affected; users will continue logging in via SSO.
• The only difference end-users may notice is that there will be an Office 365 logo next to their synced account in the settings area of the Affinity application, rather than an Exchange logo.
• The admin consent screen will always ask for authorization to all users regardless of any ApplicationAccessPolicy configurations. This can be misleading as the Microsoft authorization interface was not designed to display tenant-specific restriction configurations. But note that application access can always be verified by running the Test-ApplicationAccessPolicy command.