Calendar integration - Moving to Microsoft Graph (November release)

IRIS Cascade currently uses EWS for Exchange Online for our Outlook Integration module. This method (EWS) is being removed and replaced with Microsoft Graph from October 2026 onwards and it'll be fully removed by 2027.

Please read the Microsoft Exchange Team Blog for more up to date info. It has details on what IT admins might be able to do to enable EWS for specific applications using an 'allow list'.

IRIS Cascade are currently working on changes to our software to allow these new details to be added and we are looking at a November release on the evening of the 4th.

The changes will appear in Admin > Calendar integration providers > Microsoft Outlook.

We will be adding a new field for Microsoft Graph Scopes and the ability to connect using Graph.

The below section is aimed at your IT team to help with the move. Please send them to this page to review.

Customer guidance - new Entra application registration

Register the application

  1. Sign in to the Microsoft Entra admin center as a user with permission to register applications (e.g. Application Administrator or Global Administrator).

  2. Go to Identity > Applications > App registrations and select New registration.

  3. Enter a name (e.g. Cascade HR Calendar Integration).

  4. Under Supported account types, select Accounts in this organizational directory only (single tenant), unless your deployment requires otherwise.

  5. Leave Redirect URI blank — Cascade uses the client credentials flow and does not require a redirect URL.

  6. Select Register and note the Application (client) ID and Directory (tenant) ID.

Create a client secret

  1. Open the app registration and go to Certificates & secrets.

  2. Under Client secrets, select New client secret.

  3. Enter a description and expiry period, then select Add.

  4. Copy the Value immediately — it is only shown once. This is the Client Secret entered in Cascade.

Add API permissions

  1. Go to API permissions and select Add a permission.

  2. Choose Microsoft Graph.

  3. Select Application permissions (not Delegated).

  4. Add:

    1. Calendars.ReadWrite

    2. MailboxSettings.Read

  5. Select Grant admin consent for [your organisation] and confirm.

Both permissions should show a green tick under Status for admin consent granted.

Configure Cascade

Enter the Tenant ID, Application ID and Client Secret in Admin > Calendar Integration Providers > Microsoft Outlook.

Verify

Run a calendar sync for a test employee and confirm that absence or holiday events appear in their Outlook calendar. Check the Cascade scheduler / web service logs if events are not created.

Customer guidance - existing Entra application (EWS permissions)

Use this when you already have an Entra app registration configured for Cascade Outlook integration using Modern authentication with EWS (OAuth). Many customers will already have this:

  • The same Tenant ID, Application ID, and Client Secret in Cascade

  • Office 365 Exchange Online application permission full_access_as_app (or equivalent EWS app-only access)

  • EWS scope {https://outlook.office365.com/.default} stored in the database from the previous integration

You can reuse the existing app registration — you do not need to create a new one. Add Microsoft Graph permissions alongside the existing EWS permissions.

Locate your existing app registration

  1. Sign in to the Microsoft Entra admin center.

  2. Go to Identity > Applications > App registrations and find the app whose Application (client) ID matches the value configured in Cascade.

  3. Confirm the Directory (tenant) ID matches your Cascade Tenant ID setting.

Add Microsoft Graph permissions

  1. Open the app and go to API permissions.

  2. Select Add a permission > Microsoft Graph > Application permissions.

  3. Add

    1. Calendar.ReadWrite

    2. MailboxSettings.Read

  4. Select Grant admin consent for [your organisation].

Your permission list will now include both Exchange Online (EWS) and Microsoft Graph entries. This is expected during migration.

Note: You may remove the EWS full_access_as_app permission after you have verified Graph integration is working correctly, provided no other systems use this app registration for EWS access. Keeping EWS permissions temporarily allows rollback by reverting to an earlier Cascade version if needed.

Update Cascade configuration

  1. In Administration > Calendar Integration Providers > Microsoft Outlook, confirm Authentication Method is Modern (Microsoft365).

  2. Leave Tenant ID, Application ID, and Client Secret unchanged unless you are rotating the secret.

  3. Set Microsoft Graph Scopes to: {https://graph.microsoft.com/.default}. This field is required for Graph authentication. It replaces the EWS scope ({https://outlook.office365.com/.default}) for calendar operations when running a Cascade version that uses Microsoft Graph.

  4. Save the configuration.

Understand what changes at runtime

Setting Before (EWS) After (Graph)
Authentication method Modern (Microsoft365) Modern (Microsoft365) — unchanged
API used for calendar sync EWS (outlook.office365.com) Microsoft Graph (graph.microsoft.com)
OAuth scope for calendar https://outlook.office365.com/.default https://graph.microsoft.com/.default
App registration Same Entra app

Same Entra app (with additional Graph permissions)

Cascade's scheduler and web services continue to iterate per server and database; per-tenant settings are read from system properties as before.

Verify and plan for event migration

  1. Run a calendar sync after upgrading and configuring Graph scopes.

  2. Expect existing synced events to be re-created on first update if Graph cannot find the old EWS event ID (handled automatically).

  3. Monitor logs for authentication or permission errors. Common causes:

    1. Admin consent not granted for new Graph permissions

    2. Incorrect or expired client secret

    3. Missing Calendars.ReadWrite or MailboxSettings.Read application permissions

Troubleshooting

Sympton Likely cause Action
Calendar sync fails with authentication errors Invalid tenant ID, app ID, or secret Verify values in Entra and Cascade match; rotate secret if expired
403 Forbidden or permission errors in logs Graph permissions missing or consent not granted Confirm Calendars.ReadWrite and MailboxSettings.Read are application permissions with admin consent
Events not updating; new duplicates appear Expected during EWS/Graph migration Allow one sync cycle; Cascade recreates events when Graph returns 404 for stale IDs
Basic auth customers affected Should not occur Graph changes apply only when authentication method is Modern; Basic auth still uses EWS

On-prem exchange customers

For on-premises Exchange customers, continue to use Basic authentication. Microsoft Graph calendar integration applies to Modern (Microsoft365) authentication only.