Email Authentication changes

Note: These changes only impact IRIS Cascade customers who have moved away from the standard Cascade authentication (SendGrid) method to use another provider.

Microsoft 365 SMTP OAuth setup for Cascade HR

This guide explains how to configure Cascade HR to send email using SMTP with OAuth 2.0 against Microsoft 365 (Exchange Online).

This page is intended for customers IT administrators and implementation teams. Please show this page to your IT team.

If required, you can also give them access to the Admin > Email service area in Cascade by creating a new role and assigning it to the IT team member(s) so they can enter the details themselves when ready.

Overview

Microsoft is deprecating basic authentication (username and password) for SMTP. Cascade HR now supports (from September release):

  • SMTP AUTH Basic — existing username/password SMTP (default; unchanged behaviour)

  • SMTP AUTH with OAuth — app-only authentication for Microsoft 365 via smtp.office365.com

Cascade continues to queue emails internally. Only the send mechanism changes; no change is required to workflows, payslip email, password reset, or other features that queues mails.

Prerequisites

  • Microsoft 365 tenant with Exchange Online

  • Entra ID (Azure AD) Global Administrator or Application Administrator rights

  • Exchange Online Administrator rights (for mailbox permissions)

  • A dedicated service mailbox to send system email (shared mailbox or user mailbox)

  • Outbound access from the Cascade application server to smtp.office365.com on port 587 (TLS)

  • Cascade role permission Email service (ADMINISTER_EMAIL_SERVICE)

Part 1 — Entra ID app registration

  1. Sign in to the Microsoft Entra admin center.

  2. Go to Identity → Applications → App registrations → New registration.

  3. Enter a name (e.g. Cascade HR SMTP).

  4. Choose Accounts in this organizational directory only.

  5. Register the application and note the Application (client) ID and Directory (tenant) ID.

  6. Go to Certificates & secrets → New client secret. Copy the secret value immediately (it is shown only once).

  7. Go to API permissions → Add a permission → APIs my organization uses → search Office 365 Exchange Online.

  8. Add the Application permission SMTP.SendAsApp (or Mail.Send if your tenant policy requires it).

  9. Click Grant admin consent for the organisation.

Security: Store the client secret securely. Rotate it on a schedule and update Cascade email service settings when rotated.

Part 2 — Exchange Online configuration

Grant the registered application permission to send as the service mailbox.

  1. Connect to Exchange Online PowerShell.

  2. Register the service principal (replace {client-id} with your app registration client ID):

  3. powershell

  4. New-ServicePrincipal -AppId "{client-id}" -ServiceId

  5. Grant send permission on the mailbox (replace addresses as appropriate):

  6. powershell

  7. Add-MailboxPermission -Identity "cascade-mail@yourdomain.com" -User "{client-id}" -AccessRights FullAccess

  8. Ensure SMTP AUTH is enabled for the mailbox if your tenant restricts it:

  9. powershell

  10. Set-CASMailbox -Identity "cascade-mail@yourdomain.com" -SmtpClientAuthenticationDisabled $false

  11. Confirm tenant SMTP AUTH policy allows the mailbox (if using per-mailbox policies).

Refer to Microsoft documentation on SMTP AUTH with OAuth for the latest cmdlet names and policy guidance.

Part 3 — Cascade Email service settings

In Cascade, go to Admin > Email service. Users will need the Email service administration permission.

Field Value
Authentication Method SMTP AUTH with OAuth
Server name/URL smtp.office365.com
Port 587
Server requires SSL Ticked
Application ID Application (client) ID from Entra ID
Tenant ID Directory (tenant) ID
Client Secret Client secret (enter via Cascade; stored encrypted)

Leave Authentication Method as SMTP AUTH Basic until Entra ID and Exchange steps are complete, then switch to SMTP AUTH with OAuth.

Recommended configuration for OAuth

For OAuth SMTP, the recommended setup is to send all email from a single service mailbox. This keeps Microsoft 365 configuration simple: the registered application only needs send-as permission on one mailbox.

On the Email service page, under the advanced settings:

  1. Check Override from addresses.

  2. Set Show 'from email address' as to your service mailbox address (e.g. cascade-mail@yourdomain.com). This address must match the mailbox granted permissions in Exchange Online (Part 2).

  3. Optionally set Show 'from name' as to the display name you want recipients to see (e.g. Cascade HR).

With this configuration, IRIS Cascade uses that single address for OAuth authentication and as the visible sender, regardless of the original from address on individual queued emails. You do not need to grant the application send-as access to every mailbox that might appear as a sender in IRIS Cascade.

If Override from addresses is not enabled, Cascade falls back to other configured addresses when determining the OAuth send-as mailbox, which may require broader mailbox permissions in Microsoft 365.

Migration checklist

  1. Complete Entra ID app registration and admin consent.

  2. Configure Exchange mailbox permissions and SMTP AUTH for your service mailbox.

  3. On the Email service page, set Server name/URL to smtp.office365.com, Port to 587, and enable Server requires SSL.

  4. Enter Application ID, Tenant ID, and Client Secret (keep Authentication Method as SMTP AUTH Basic until the above steps are complete).

  5. Apply the recommended OAuth configuration (Override from addresses and Show 'from email address' as).

  6. Set Authentication Method to SMTP AUTH with OAuth.

  7. Decommission basic-auth credentials when satisfied (optional; remove or rotate the Password under SMTP AUTH Basic settings).

Rollback

Set Authentication Method back to SMTP AUTH Basic and restore previous Username and Password. No code deployment rollback is required.

Verification

  1. Trigger a representative email from Cascade (for example submit a holiday request, a workflow notification or scheduled job such as payslip distribution).

  2. Check the email queue in Administration for success status.

  3. Confirm receipt in the target mailbox and that the sender address matches Show 'from email address' as when Override from addresses is enabled.

  4. For scheduled mail, confirm the Cascade Scheduler queue job completes without errors in the intranet error log.

Troubleshooting

Symptom Likely cause Action

Authentication failed

Wrong client secret or tenant ID

Verify Entra ID values; re-enter Client Secret

535 / auth error

 Admin consent not granted Grant admin consent for SMTP.SendAsApp
Mailbox access denied App not authorised for mailbox Run Add-MailboxPermission / service principal setup for the address in Show 'from email address' as
SMTP AUTH disabled Tenant or mailbox policy Enable SMTP AUTH for the service mailbox
Connection timeout Firewall Allow outbound TCP 587 to smtp.office365.com
4.3.1 storage error Message too large

Reduce attachment size; queue will not retry

Secret expired

 Client secret rotation Create new secret in Entra ID and update Client Secret in Cascade
Wrong sender address Override from addresses not configured Enable Override from addresses and set Show 'from email address' as to the authorised service mailbox

FAQ

Can we reuse the Outlook calendar integration app?

You can use the same app registration if permissions include SMTP.SendAsApp. Calendar and SMTP OAuth use separate configuration in IRIS Cascade.

Do we need to change firewall rules?

Yes, if outbound SMTP is restricted. Allow TLS to smtp.office365.com:587 from the Cascade web and scheduler servers.

What happens to emails already in the queue?

Queued emails are unaffected. They send using the authentication method configured at send time.

Is delegated (per-user) OAuth supported?

This release uses app-only (client credentials) authentication, suitable for system-generated emails.

Per-user delegated SMTP is not configured by default.

Can we stay on basic authentication?

Yes. Leave Authentication Method as SMTP AUTH Basic. IRIS Cascade will continue to use SendGrid.

OAuth is opt-in per environment. You can choose to use this if needed.

Where did the email settings go in System Properties?

Email-related system properties are now managed on the dedicated Email service administration page. They have been removed from the main System Properties list.

Why use Override from addresses with OAuth?

It ensures all outbound mail is sent via one authorised mailbox, so you only need to configure SMTP.SendAsApp (or equivalent) permissions once in Microsoft 365.

Support information

When contacting the service desk with any issues, please provide:

  • Authentication Method setting (SMTP AUTH Basic or SMTP AUTH with OAuth)

  • Whether failures occur for all queued emails or only specific message types

  • Relevant queue error message (from Administration > Email queue or intranet error log)

  • Confirmation that Entra ID admin consent and Exchange mailbox permissions are in place for the mailbox in Show 'from email address' as