Modern Authentication (Microsoft Office365)

Overview

XCALLY supports Modern Authentication for connecting Office 365 (Outlook 365) email accounts.

Modern Authentication combines authentication and authorization protocols to securely verify users and grant access between clients and servers. It includes:

• Authentication methods: Multi-Factor Authentication (MFA), smart cards, and client certificates

• Authorization methods: Microsoft’s implementation of OAuth 2.0

• Conditional access: Microsoft Entra ID Conditional Access and Mobile Application Management (MAM)

In short, Modern Authentication redirects the XCALLY client to Microsoft Entra ID for secure user login via username, password, or MFA

Configuration

To enable Modern Authentication for a new Office 365 email account in XCALLY, follow these main steps:

1. Register an application in the Azure Portal

2. Create a new Cloud Provider in XCALLY (Service: Microsoft Azure, Type: Outlook365)

3. Authenticate the Cloud Provider Account

4. Associate the Cloud Provider with the email accounts on XCALLY

Microsoft Entra ID application registration 

To allow XCALLY to use Office 365, you must register an application in Microsoft Entra ID (Azure Portal). This enables authentication and authorization for your XCALLY instance.

App Registration

Follow these steps to create the app registration:

• Sign in to the Azure portal

• If you manage multiple tenants, select the correct one under Directories + Subscriptions 

  

• Go to Microsoft Entra ID → App Registrations → New Registration.

• Enter a Display Name for your app. 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

• Choose Supported account types based on your needs:

  • Single tenant: 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 (Any Microsoft Entra ID tenant - Multitenant). 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 (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)

• Don't enter anything for Redirect URI (optional). You'll configure a redirect URI in the next section

• Click Register

After registration, note your:

• Application (client) ID

• Directory (tenant) ID

You’ll need these later during the XCALLY Cloud Provider configuration.

Authentication - Redirect URI

The Redirect URI tells Microsoft where to send authorization tokens after login.

1. In the Azure Portal, go to Manage → Authentication.

2. Under Platform configurations, select Add a platform → Web.

Open

3. 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

The Client Secret identifies your application when requesting tokens from Microsoft.

1. In Azure Portal, go to Certificates & Secrets → Client secrets → New client secret.

2. Add a description and choose an expiration (max 24 months). Microsoft recommends setting an expiration value of less than 12 months.

3. Click Add and immediately copy the secret value — it won’t be shown again.

The Client secret value will be needed during the Cloud Provider Configuration phase. 

Open

API Permission

Grant your Azure app access to Microsoft Graph API to allow XCALLY to send and receive emails.

1. In Azure Portal, open your app and select API Permissions → Add a permission → Microsoft Graph.

2. Choose Delegated permissions and add the following ones:

• 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 using Shared Mailboxes, also add these Application permissions (admin consent required). You will find Application type permission under Application permissions.

• After adding, click Add Permissions and have an admin approve any required consents.

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. 

Open

Cloud Provider Configuration

To authenticate Email Accounts with Modern Authentication, you need to configure Microsoft Azure as service of the Cloud Provider on XCALLY.

Follow these steps to configure the Cloud Provider:

1. On XCALLY, under Tools, select Cloud Providers (from the left Menu)

2. Click on the plus button and create a New Account

3. Enter the parameters of the application previously created in the Azure Portal: 

   1. Name: Enter a Name 

   2. Service: Select Microsoft Azure

   3. Type: Select Outlook365

   4. Application Id: Insert the Application (client) ID value 

   5. Tenant Id: Insert the Directory (tenant) ID value

   6. Client Secret: Insert the Client secret value

   7. Redirect URI: Insert the Redirect URI

Cloud Provider Account Authentication

The Cloud Provider Account must be authenticated.  

• In XCALLY, open Tools → Cloud Providers.

• Select the Cloud Provider and click Authenticate.

Open

• You’ll be redirected to the Microsoft sign-in page.

• Sign in with the email address linked to the account. In case of Shared Mailboxes you must choose one email linked to the shared mailbox to authenticate. 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.

• Accept the App access authorization

• XCALLY will confirm successful authentication.

Open

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.

1. Go to Email → Email Accounts → + plus button (Add New).

2. Fill out:

   • Name: Email account name

   • Key: Short 5-character identifier, that will be shown on the Agents Tabs

   • Email Address: Sender’s address (shown in the from field). For shared mailboxes, set the “Modern Authentication Email” to the user who authenticated (delegate account). As in the example used before, developers@xcally.com.

   • List: Default contact list where the new email contacts will be saved in the Contacts Manager,

   • Service: select Outlook365

   • Modern Authentication: Enable using:

     • Username: Same as email address. 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 your previously created provider

3. Save the 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 3 dots button

  • From the menu, select Update Client Secret

    Open

    

  • Enter the New Client Secret and then click on Save

    Open

    

Troubleshooting

Finding the logs

• Logs are written in the log files email-combined.log and email-error.log

Enable debugging

• Change in the .env file the setting XC_DEBUG_LEVEL

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.

Check if SMTP AUTH is enabled for the mailbox you want to send emails from.
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.

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

Open