Knowlege base

Email-to-Fax Microsoft OAuth2 Authentication

Article ID: 816
Last updated: 12 May, 2022

This authentication method is supported by Imagicle UC Suite, starting from 2021.Winter.2 release, and it relays on advanced OAuth2 authentication available for cloud-based Office 365 email service. Previous Imagicle releases are supporting OAuth2 basic authentication, which is dismissed by Microsoft starting from July 2021.

Requirements

In order to enable email-to-fax service, interfaced to Microsoft Office 365 cloud service using OAuth2 authentication, you must configure an application on Azure Web Portal, taking note of Application ID, Directory ID and Client Secret data, needed later on while configuring this authentication method on Imagicle UC Suite. Please read the following procedure to create a new application on Azure portal and add it to UC Suite web interface.

Azure web portal configurations

Please access to Azure portal and go to "App Registrations"

Click on "New registration" and choose a name like "MyOAuth2App". Then select "Accounts in this organizational directory only" and hit "Register"

The following window appears, including Application ID and Directory ID. Please copy both data, for later usage.

Now please click on "Certificates & secrets" option, included in left pane, and add a new "client secret" with the name of your choice and a long expiration period.

Once added, you'll get some data associated to it. Please copy "Value" field for later usage. Copy the field immediately after having created the client secret, because it will be automatically hidden after few minutes, for security reasons.

Now click on "Add permissions" and select "API’s my organization users". Then search for "Office 365 Exchange online".

Select "Office 365 Exhange online" and then select "Application Permissions"

From the list of available permission levels, please select "full_access_as_app" from "Other permissions" category.

Once permission has been assigned, you must authorize it for your organization, by clicking on "Grant admin consent for <company_name>".

This is the resulting page.

Optional configurations to restrict EWS Application to a mailbox set

Above described API Permission level privileges allows the application to access all EWS API on all organization mailboxes. 

However, it’s possible to optionally apply an advanced configuration on Microsoft Office 365 to restrict the application to access only a specific mailbox.

This is accomplished by accessing Exchange Online Administration Portal and create a new mail-enabled security group: Go to RecipientsGroups New mail-enabled security group

Fill the form with a name and an alias. Those will be used later as a target of an Application Policy.

Save form and edit the newly created group, go to membership, add a member, search for the mailbox to be granted to Digital Fax and add it:

Connect to Exchange Online PowerShell and create an Application Access Policy to allow Digital Fax application to only access the newly created mail security group, by executing the following command, where:

  • AppId value corresponds to the application “Client ID” value created within Azure app registration portal
  • PolicySecurityGroupId corresponds to "Display Name" of the previously create security group
PS > New-ApplicationAccessPolicy -AccessRight RestrictAccess -AppId "da34bf4b-b01f-47e4-bfac-2f9fc3f1383e" -PolicyScopeGroupId "Imagicle Digital Fax" -Description "Restrict Imagicle Digital Fax accessible mailboxes"

RunspaceId       : 2d08b315-81dd-4140-8a28-4a49431fb44d
ScopeName        : Imagicle Digital Fax
ScopeIdentity    : Imagicle Digital Fax
Identity         : 8f8ccdec-23bd-4452-bdb3-becc0c415a99\da34af4b-b01f-47e4-bfac-2f9fc3f1383e:S-1-5-21-2724517575-989916663-4003715733-16076635;697c4a2-f812-4072-a10f-4455db66025e
AppId            : da34aq4b-b01f-47e4-bfac-2f9fc3f1383e
ScopeIdentityRaw : S-1-5-21-2724537575-989916663-4003715733-16076635;697c48d2-f812-4072-a10f-4455db66025e
Description      : Restrict Imagicle Digital Fax accessible mailboxes
AccessRight      : RestrictAccess
ShardType        : All
IsValid          : True
ObjectState      : Unchanged

Verify the rule, to check if the application can properly access the needed mailbox by executing the following command:

Test-ApplicationAccessPolicy -Identity <mail2fax address> -AppId <clientId>

Output should be:

RunspaceId        : 2e08b315-81dd-4143-8a28-4a49431fa44d
AppId             : da34ee4b-b01f-44e4-bfac-2f9fc3f1383e
Mailbox           : fax
MailboxId         : c82eee91-a3e0-43f0-9a43-03e7ec7b1e96
MailboxSid        : S-1-5-21-2722357575-989916663-4003711733-159675946
AccessCheckResult : Granted

Then please verify the application can't access any other mailbox, by executing the following command:

Test-ApplicationAccessPolicy -Identity <any other mail address> -AppId <clientId>

In this case, output should be similar to below sample:

RunspaceId        : 2d08b235-81dd-4140-8a28-4a49431fa44d
AppId             : da34af4e-b01f-47e4-beec-2f9fc3f1383e
Mailbox           : fax
MailboxId         : c82eee91-a3e0-43f0-9a43-03c7ec7b1e96
MailboxSid        : S-1-5-21-272451125-989916663-4003715733-15450946
AccessCheckResult : Denied

UC Suite configurations

Please access to Imagicle UC Suite admin web portal and go to the following menu item: Digital Fax → Application Settings → Outgoing Faxes.  

Inside "Email to Fax Settings" panel, please select "Office365 (Active)" from Protocol type pull-down menu. New fields appear, to be compiled with data acquired during Azure portal configuration: Application ID, Directory ID and Client Secret.  

Moreover, you need to add the dedicated email account to be used for email-to-fax sending, with proxy support if required. Polling time dictates how often Imagicle Digital Fax polls dedicated fax account to check for new fax document to be sent.

Troubleshooting

  1. When you hit "Test settings" button, you get "Invalid credential" error message.

Possibile reasons:

  • Invalid data entered.
  • Not enough permission levels on Azure application.
  • Dedicated email account does not exist or it is not accessible, due to restrictions applied on Azure portal.
  1. When you hit "Test settings" button, you get "Server is not reachable" error message.

Possibile reasons:

  • Internet is not available
  • Wrong proxy settings
  1. When you hit "Test settings" button, you get "An error has occured testing outgoing faxes Email to Fax setting." error message.

This is a generic error message, related to API crash during a call from Digital Fax web interface.

Article ID: 816
Last updated: 12 May, 2022
Revision: 7
Views: 1574
Print Export to PDF Subscribe Share
This article was:  
Prev   Next
Service management     MS-Office365 configuration for alternative email-to-fax method