How do I set up App Registration to access mailboxes with Microsoft OAuth?
Office 365 mailboxes
When setting up mailboxes to use OAuth to connect to Office365 mailboxes you must first create an App Registration on Microsoft's Azure Active Directory.
There are several settings particular to our mailboxes outlined below. For assistance outside of what is listed below please work with your IT department or support from your Office365 vendor.
The registration name is simply a descriptive name for the app. Users may have multiple apps granting permissions for various Microsoft products to any number of third party entities therefore we suggest something like "Oracle B2C Email".
Account types (single or multitenant)
This setting determines what type of mailboxes can use OAuth for authentication.
Single tenant supports only mailboxes for the Azure domain in which the app registration is created. For example, if the Azure account is example.onmicrosoft.com, then only mailboxes in the form of email@example.com can use OAuth for authentication. Single tenant is the most straightforward option for most users.
As the name implies, multitenant allows any Azure AD account to use OAuth for authenticating. Select multitenant if you have mailboxes from multiple Azure domains that you want to allow Oracle B2C Service to authenticate. Multitenant account type requires registration with the Microsoft Partner Network, please consult the Microsoft documentation for full details.
The redirect url is based on the interface. It should be of the form <interface>/AgentWeb/Bookmark/Mailboxes/Auth
Delegated API permissions
This setting determines the permissions granted to the App. For OSvC mailbox authentication, users must add "Microsoft Graph - POP.AccessAsUser.All" as a delegated permission. "User.Read" should also be included by default.
Users must create a client secret under "Certificates & secrets". OSvC will use this to prove its identity during the OAuth process. This value is entered in the CUSTOM_CFG_MAILBOX_OA_CLIENT_SECRET configuration.
The client ID is the unique identifier assigned to this app registration. The client ID is automatically generated and can be found in the "Overview" section of the app registration as "Application (client) ID". This value is entered in the CUSTOM_CFG_MAILBOX_OA_CLIENT_ID configuration.
The tenant ID is the unique identifier assigned to the Azure AD account. The tenant ID is also automatically generated and can be found in the "Overview" section of the app registration as "Directory (tenant) ID". This value is entered in the CUSTOM_CFG_MAILBOX_OA_TENANT configuration.
Configure a mailbox to use OAuth
After setting up App Registration and setting the configurations in the product you must enable your mailboxes to use OAuth.
- Verify that the custom configurations are set appropriately.
- Open the mailbox editor in the Browser UI client or in .NET after enabling it as in Enabling the mailboxes editor for OAuth in .NET.
- Open the Office365 mailbox.
- Set SSL Method to "pop3 ssl port" on the security tab.
- Set Pop Server to "outlook.office365.com" on the incoming tab.
- Set Pop Account to the relevant microsoft account (e.g. firstname.lastname@example.org). Note that if you use multiple domains you must have set account type to multitenant.
- Set Authentication Type to "OAuth".
- Click the Authenticate button. This will open a new tab where the user can enter their credentials and grant Oracle B2C Service access to the mailbox.
- If successful, you will see Mailbox Authenticated and then need to scroll down to click the button for 'OK' which will close this tab. Clicking OK is required for the completion of this Authentication process.
- You should now see a green box for 'Authenticated' next to the gray 'Authenticate' button.