App registration | Email & SSO | Microsoft 365

Overview

CasEngine sends and reads email through Microsoft 365 (Microsoft Graph), signed in with an app registration in your Microsoft Entra ID. Basic SMTP sign-in with a username and password no longer works, because Microsoft now requires multi-factor authentication.

This article shows your IT administrator how to:

1. Create the app registration and give it the permissions CasEngine needs.
2. Create a client secret and send the app details to your CasEngine contact.
3. Connect Microsoft 365 in CasEngine and turn on Email Send and Email Read.

You need the Global Administrator or Privileged Role Administrator role in Entra ID to grant admin consent.

What changed from the previous version of this article: the app now also needs Organization.Read.All (CasEngine uses it to confirm the connection), a redirect URI, and the connection is made from Settings → App Settings → Integrations instead of Email configuration.

Step 1: Create the app registration

1. Sign in to the Microsoft Entra admin center and go to Identity → Applications → App registrations → New registration.
   
   

2. 

3. Name: CasEngine-Email (or a name your team will recognise).
4. Supported account types: Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant). CasEngine signs in through Microsoft's shared sign-in address, which does not accept single-tenant apps (error AADSTS50194). Only users and mailboxes in your own organization are used.
5. Redirect URI: platform Web, value https://<your CasEngine address>/api/integration/microsoft/callback, for example https://casengine.yourfirm.com/api/integration/microsoft/callback.
6. Click Register.

If you also use Sign in with Microsoft for CasEngine, see Single sign-on below for the second redirect URI and how to restrict the app to your own organization.

Step 2: Add the permissions

Go to API permissions → Add a permission → Microsoft Graph → Application permissions (not Delegated) and add:

Mail.Read is not needed when Mail.ReadWrite is added.

Click Grant admin consent for <your organization>. Every row must show Granted for <your organization> in the Status column.

Step 3: Create a client secret

1. Go to Certificates & secrets → Client secrets → New client secret.
2. Description: CasEngine; Expires: 24 months (the longest your policy allows).
3. Copy the secret Value straight away. It is shown only once. (The Secret ID is not the secret.)
4. Add a reminder to renew it before the expiry date. When it expires, CasEngine email stops.

Step 4: Send the details to CasEngine

From the app's Overview page, collect:

Send them to your CasEngine contact through a secure channel (a password manager share or encrypted message, never plain email).

On-premises installations: these values are not entered in CasEngine Settings. They are stored as environment variables on the CasEngine API app pools in IIS (CE_api_onprem, and CE_api_staging_onprem if you have staging), where the secret is kept out of the database and configuration files:

The CasEngine team sets these during installation, or your administrator sets them with the installation runbook. The app pools are recycled afterwards so the new values take effect. When the client secret is renewed, only CloudProviders__Microsoft__ClientSecret needs updating.

Step 5: Connect Microsoft 365 in CasEngine

Once CasEngine confirms the app details are in place:

1. Sign in to CasEngine as an administrator and go to Settings → App Settings → Integrations → Microsoft Outlook.
2. Click Connect. Microsoft opens a consent page: check that the app name is your app (for example CasEngine-Email), sign in as a Global Administrator, and click Accept.
3. You return to CasEngine and Microsoft Outlook shows Connected.
4. Turn on each service you need. Enter the mailbox, then click Approve in Microsoft & enable:

Use a shared or dedicated mailbox for Email Read, not a person's working inbox.

Single sign-on (Sign in with Microsoft)

CasEngine's Sign in with Microsoft uses the same app registration: no second app and no extra secret. It needs a second redirect URI and the app restricted to your own organization.

1. Add the sign-in redirect URI. In the app: Authentication → Web → Redirect URIs → Add URI:

https://<your CasEngine address>/api/v1.0/Auth/SSOCallback

It must match exactly: https://, your CasEngine address (with the port if it is not 443), and /api/v1.0/Auth/SSOCallback. Click Save.

2. Keep the app multitenant, but allow only your organization. CasEngine signs users in through Microsoft's shared sign-in address, so the app must be multitenant (Step 1.3). Restrict it to your own tenant so no other organization's accounts can use it:

1. Authentication → Supported account types: Accounts in any organizational directory (Multitenant).
2. Under the multitenant option, choose Allow only certain tenants and add your Directory (tenant) ID. Click Save.

If that option is not shown in your portal yet (it is a newer Entra feature), set it with Microsoft Graph Explorer, signed in as an administrator:

PATCH https://graph.microsoft.com/beta/applications/<app Object ID>
Content-Type: application/json

{
  "signInAudience": "AzureADMultipleOrgs",
  "signInAudienceRestrictions": {
    "@odata.type": "#microsoft.graph.allowedTenantsAudience",
    "allowedTenantIds": [ "<your Directory (tenant) ID>" ]
  }
}

Use the app's Object ID from its Overview page, not the Application (client) ID.

3. Choose who may sign in (recommended). Go to Enterprise applications → your app → Properties → Assignment required? = Yes, then under Users and groups add the group of CasEngine users.

4. Turn on single sign-on in CasEngine. Ask your CasEngine contact to enable Microsoft sign-in for your firm. Each user signs in with the Microsoft account whose email matches their CasEngine user email exactly; accounts without a matching active CasEngine user are refused.

Test: open CasEngine, click Sign in with Microsoft, and sign in. If Microsoft shows an error, the code (for example AADSTS50011) is listed under Troubleshooting below.

Limit access to specific mailboxes (recommended)

Application permissions allow access to every mailbox in your organization. To limit CasEngine to the mailboxes above, follow How to restrict CasEngine's access to specific mailboxes in Microsoft 365. It uses Exchange Online RBAC for Applications.

Troubleshooting

For Microsoft's background on why basic SMTP sign-in stopped working, see Authenticated client SMTP submission.