Modern Authentication (Microsoft Office365)
What it's about
Â
XCALLY gives the possibility to use Modern Authentication for Email Accounts using Office365 as provider.Â
Â
Modern authentication is an umbrella term for a combination of authentication and authorization methods between a client and a server. It includes:
Authentication methods: Multi-factor authentication (MFA); smart card authentication; client certificate-based authentication
Authorization methods: Microsoft's implementation of Open Authorization (OAuth)
Conditional access policies: Mobile Application Management (MAM) and Azure Active Directory (Azure AD) Conditional Access
Very simplistic we can say, that with modern authentication, the client is talking to the service and getting redirected to Azure AD for authentication with the username and password or other methods like MFA.
How to set up
Â
To activate the Modern Authentication for a new Email Account on XCALLY using Office365 as provider, you need to:Â
Â
A. Register an application in the Azure Portal
B. Configure a new Cloud Provider on XCALLY by choosing Microsoft Azure as a service and Outlook365 as the type
C. Authenticate the Cloud Provider Account
D. Associate the Cloud Provider with the email accounts on XCALLY
Â
If you are configuring a Modern Authentication to use Shared Mailboxes, please pay attention to yellow instructions.
XCALLY Motion supports in-cloud Shared Mailboxes only. The following process does not work with on-premises mailboxes.
Azure AD application registrationÂ
Â
Registering an application in the Azure Portal, the Microsoft identity platform can provide authentication and authorization services for your application and its users.
App Registration
Follow these steps to create the app registration:
Sign in to the Azure portal
If you have access to multiple tenants, use the Directories + subscriptions filter  in the top menu to switch to the tenant in which you want to register the application
Search for and select Azure Active Directory (AD)
Under Manage, select App registrations > New registration
Enter a display Name for your application. Users of your application might see the display name when they use the app, for example during sign-in. You can change the display name at any time and multiple app registrations can share the same name. The app registration's automatically generated Application (client) ID, not its display name, uniquely identifies your app within the identity platform
Specify who can use the application, sometimes called its sign-in audience
Supported account types | Description |
---|---|
Accounts in this organizational directory only | Select this option if you're building an application for use only by users (or guests) in your tenant. |
Accounts in any organizational directory | Select this option if you want users in any Azure Active Directory (Azure AD) tenant to be able to use your application. This option is appropriate if, for example, you're building a software-as-a-service (SaaS) application that you intend to provide to multiple organizations. |
Accounts in any organizational directory and personal Microsoft accounts | Select this option to target the widest set of customers. |
Don't enter anything for Redirect URI (optional). You'll configure a redirect URI in the next section
Select Register to complete the initial app registration
Â
When registration finishes, the Azure Portal displays the app registration's Overview pane. You see the Application (client) ID. Also called the client ID, this value uniquely identifies your application in the Microsoft identity platform.
Your application's code, or more typically an authentication library used in your application, also uses the client ID. The ID is used as part of validating the security tokens it receives from the identity platform.
The Application (client) ID and Directory (tenant) ID values will be needed during the Cloud Provider Configuration phase.Â
Authentication- Redirect URI
Â
The authorization server sends the code or token to the redirect URI, so it's important you register the correct location as part of the app registration process.
A Redirect URI, or reply URL, is the location where the Microsoft identity platform redirects a user's client and sends security tokens after authentication.
Follow these steps to add a Redirect URI:
In the Azure Portal, under Manage, select Authentication (from the left Menu)
Under Platform configuration, select Add a platform
Under Configure platforms, select Web ApplicationsÂ
Enter the following Redirect URI: https://motionserverhost/api/cloudProviders/oauth2/microsoft/callback (Replace "motionserverhost" with your motion server host value)
The Redirect URI will be needed during the Cloud Provider Configuration phase.Â
Â
Credentials- Client Secret
Â
Credentials allow your application to authenticate as itself, requiring no interaction from a user at runtime.
Credentials are used by confidential client applications (apps that run on servers) that access a web API. Types of credentials are Certificates and Client secrets. Will will use Client Secrets.
A client secret is a secret string value your app can uses to prove its identity when requesting a token. Also can be referred to as application password.
Follow these steps to add a Client Secret:
In the Azure portal, under Manage, select Certificates & secrets (from the left Menu)
Select Client secrets > New client secret
Add a description for your client secret
Select an expiration for the secret or specify a custom lifetime
Client secret lifetime is limited to two years (24 months) or less. You can't specify a custom lifetime longer than 24 months
Microsoft recommends that you set an expiration value of less than 12 months
Select Add
Record the secret's value for use in your client application code. This secret value is never displayed again after you leave this page.
The Client secret value will be needed during the Cloud Provider Configuration phase.Â
API Permission
Â
Let's see how to provide a client app registered with the Microsoft identity platform with permissions-based access to the web API and access to Microsoft Graph API.
Client applications typically need to access resources in a web API. Applications are authorized to call APIs when they are granted permissions by users/admins as part of the consent process. The list of configured permissions should include all the permissions the application needs.Â
Configure delegated permission to Microsoft Graph API to enable your client application to perform operations on behalf of the logged-in user, for example reading their email or modifying their profile. By default, users of your client app are asked when they sign in to consent to the delegated permissions you've configured for it.
Select API permissions > Add a permission > Microsoft Graph
Select Delegated permissions.Â
Add the following permissions:
Permission | Type | Description |
Delegated | View users' email address | |
offline_access | Delegated | Maintain access to data you have given it access to |
openid | Delegated | Sign users in |
profile | Delegated | View users' basic profile |
IMAP.AccessAsUser.All | Delegated | Read and write access to mailboxes via IMAP |
SMTP.Send | Delegated | Send emails from mailboxes using SMTP AUTH |
SMTP.Send permission requires that SMTP AUTH is enabled for the mailbox you want to use. https://learn.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/authenticated-client-smtp-submission
If you are configuring a Modern Authentication to use Shared Mailboxes, the following permission must be also added. Ask Azure portal administrator to approve the permission labeled with "Admin consent required". You will find Application type permission under Application permissions.
Permission | Type | Description | Admin consent required |
User.Read | Delegated | Sign in and read user profile | No |
Mailbox.Settings.ReadWrite | Application | Read and write all user mailbox settings | Yes |
Mailbox.Settings.Read | Application | Read all user mailbox settings | Yes |
Mail.Send.Shared | Delegated | Send mail on behalf of others | No |
Mail.Send | Application | Send mail as any user | Yes |
Mail.ReadWrite.Shared | Delegated | Read and write user and shared mail | No |
Mail.ReadWrite | Application | Read and write mail in all mailboxes | Yes |
Mail.ReadBasic.All | Application | Read basic mail in all mailboxes | Yes |
Mail.ReadBasic | Application | Read basic mail in all mailboxes | Yes |
Mail.Read.Shared | Delegated | Read user and shared mail | No |
Mail.Read | Application | Read mail in all mailboxes | Yes |
Contacts.ReadWrite.Shared | Delegated | Read and write user and shared contacts | No |
Contacts.Read.Shared | Delegated | Read user and shared contacts | No |
Select Add permissions to complete the process.
Â
Whenever you configure permissions, users of your app are asked at sign-in for their consent to allow your app to access the resource API on their behalf.
For these permissions, it is not necessary to provide the consent of an Administrator, as indicated by the column Admin consent required.Â
Â
Cloud Provider Configuration
Â
To use Modern Authentication to authenticate Email Accounts, you need to configure Microsoft Azure as service of the Cloud Provider on XCALLY.
Follow these steps to configure the Cloud Provider:
On XCALLY, under Tools, select Cloud Providers (from the left Menu)
Click on the button (on the lower right) and create a New Account
Enter the parameters of the application previously created in the Azure Portal:Â
Name: Enter a NameÂ
Service: Select Microsoft Azure
Type: Select Outlook365
Application Id: Insert the Application (client) ID valueÂ
Tenant Id: Insert the Directory (tenant) ID value
Client Secret: Insert the Client secret value
Redirect URI: Insert the Redirect URI
Cloud Provider Account Authentication
Â
With the use Modern Authentication, the Cloud Provider Account must be authenticated. Â
Follow these steps to authenticate the Cloud Provider:
On XCALLY, under Tools, select Cloud Providers (from the left Menu)
Select the specific Cloud Provider Account, then click on the button
From the menu, select Authenticate
You will be redirected to Microsoft Outlook365, where you insert your Email Credentials (Email address you will insert Email Address when creating a New Email Account, see next paragraph) and you need to accept the App access authorization
If you are configuring a Modern Authentication to use Shared Mailboxes, you will be redirected to Microsoft Outlook365, where you insert the Email Credentials: you must choose one email linked to the shared mailbox to authenticate (identified as Modern Authentication Email or Username Delegante). Then, accept the App access authorization. Fox example, a company developers department uses the shared mailbox developers@xcally.com, to which several developers emails are linked. In this configuration step (Cloud Provider authentication), the company must choose a developer email to do the authentication: Andrea is a developer and uses the email andrea@xcally.com to proceed in the Microsoft Outlook365 authentication process.
The Authentication to the Microsoft Identity Platform will be notified on XCALLY
Â
Â
Â
Cloud Provider association with the Email account
Â
To use Modern Authentication for an Email Account, you need to associate the specific Email Account with the Cloud Provider using Microsoft Azure.
Follow these steps to configure the Cloud Provider:
On XCALLY, under Email, select Email Account (from the left Menu)
Click on the button (on the lower right) and create a New Email Account
Enter the parameters of the application previously created in the Azure Portal:Â
Name: the name of the email account
Key: define a short name (5 character maximum) for the Account that will be shown on the Agents Tabs
Email Address: the origin email address of the messages (shown in the from field).
If you are configuring a Modern Authentication to use Shared Mailboxes, enter the email of the shared mailbox. As in the example used before, developers@xcally.com.
List:Â the default List where the new email contacts will be saved in the Contacts Manager, if it is not already there
Active:Â turn this flag on/off to activate/deactivate the Account
Service: Select Outlook365
Modern Authentication: turn this flag on to activate Security using the following:
Username:Â authentication username (Email Address you have previously entered). If you are configuring a Modern Authentication to use Shared Mailboxes, enter the email of the shared mailbox. As in the example used before, developers@xcally.com.
Cloud Provider: Select the Cloud Provider previously createdÂ
Description: an optional description of your Email Account
4. Click on Add Email Account
Â
If you are configuring a Modern Authentication to use Shared Mailboxes, edit the Email Account Authentication Credentials: add the email linked to the shared mailbox used to authenticate (identified as Modern Authentication Email or Username Delegante) in the Modern Authentication Email field. As in the example used before, andrea@xcally.com.
Client Secret UpdateÂ
Â
Once generated, the Client Secret value is never displayed again neither in the Azure Portal nor on XCALLY.
To edit the Client Secret:Â
Generate a new Client Secret Value on the Azure PortalÂ
Update the Client Secret Value on XCAlly:Â
On XCALLY, under Tools, select Cloud Providers (from the left Menu)
Select the specific Cloud Provider Account, then click on the button
From the menu, select Update Client Secret
Enter the New Client Secret and then click on Save
Troubleshooting
Â
Finding the logs
Logs are written in the log files email-combined.log and email-error.log
Example file name: /var/log/xcally/email-combined.2022-10-04.log
Â
Enable debugging
Change in the .env file the setting XC_DEBUG_LEVEL
XC_DEBUG_LEVEL='DEBUG'
Â
Â
Error authenticated but not connected
Check:
if email IMAP license is enabled for that email
users use MFA authentication (username, password + SMS or authenticator app)
how many email clients are using with that email account
if there is a Shared Mailbox
if you get the same error repeating the login
that the Azure Enteprise App used for the modern authentication has the permission listed above in the page
the user which is used to login with the cloud provider has access to the email account. Check spelling of the email address, then if the user can access the email using Microsoft Outlook.
Â
Error when sending email: SmtpClientAuthentication is disabled for the Tenant
Error: Invalid login: 535 5.7.139 Authentication unsuccessful, SmtpClientAuthentication is disabled for the Tenant. https://aka.ms/smtp_auth_disabled for more information. [FR3P281CA0089.DEUP281.PROD.OUTLOOK.COM 2023-10-24T13:30:31.606Z 08DBD33E9F7E0C34]
Check if SMTP AUTH is enabled for the mailbox you want to send emails from. This error is due a security policy enabled by default by Microsoft from december 2022.
It is recommended to have STMP AUTH disabled by default in tenant settings and override the general setting with a per-mailbox to re-enable SMTP AUTH.
Â
User can log in in the Cloud Provider, but email doesn't work
Check Client Secret validity. If it is expired, create a new one and update the cloud provider.
Â
User disconnected after 15-90 days
Try to repeat login.Â
If you want the user to stay connected for more than 90 days, extend the Session → Sign-in frequency to 365 days.
To do so , follow the guide: https://learn.microsoft.com/en-us/azure/active-directory/conditional-access/howto-conditional-access-session-lifetime
Â
Getting support faster
Microsoft Enterprise Apps have a built in support channel that can be found in the Azure portal → App → Diagnose and solve problems
Â