Add Refresh Token (delegated OAuth) authentication to the Microsoft Outbound Connector (Microsoft 365 Mail element template)

[crobbins215]

Add Refresh Token (delegated OAuth) authentication to the Microsoft Outbound Connector (Microsoft 365 Mail element template)

Is your feature request related to a problem? Please describe.

The Microsoft 365 (Mail) outbound connector is currently delivered as a protocol connector implemented via an element template on top of the HTTP JSON connector (io.camunda:http-json:1). In its current form, it only offers:

• Bearer token authentication, and
• OAuth 2.0 client credentials flow (application permissions).

This blocks adoption in many enterprise Microsoft tenants that disallow application permissions for Microsoft Graph (tenant-wide access concerns) and instead require delegated permissions. Delegated access typically relies on a refresh token based flow so the integration can run continuously without manual token rotation.

Camunda already supports a Refresh Token authentication type for the Microsoft Teams connector, so users reasonably expect parity across Microsoft connectors.

Describe the solution you'd like

Add a Refresh Token (delegated OAuth) authentication option to the Microsoft 365 (Mail) outbound connector experience, aligned with the Microsoft Teams connector pattern, while keeping the connector architecture clean.

Because this “connector” is currently an element template, there are two viable implementation paths:

Option A (preferred): Extend the HTTP/REST connector OAuth capabilities, then update the element template

1. Extend the underlying HTTP connector auth implementation to support a new authentication mode, for example:
   • oauth-refresh-token (grant_type=refresh_token)
2. Ensure the token request is compatible with Microsoft’s token endpoint requirements (form-encoded token requests).
3. Update the Microsoft 365 Mail element template to add a new authentication choice:
   • Refresh Token
   • Fields aligned with Teams connector UX where possible:
     • Tenant ID
     • Client ID
     • Secret (stored as Camunda secret)
     • Refresh token (stored as Camunda secret)
     • (Optional) scopes / resource
4. Runtime behaviour:
   • Exchange refresh token for access token automatically
   • Support refresh token rotation (store/expect updated refresh token where applicable)
   • Clear error messages for invalid_grant / interaction_required with guidance to re-authorise
5. Documentation:
   • Add a section to Microsoft 365 connector docs mirroring the Teams “Refresh Token type authentication” guidance, including how to obtain a refresh token and operational expectations.

Option B: Build a full Microsoft 365 Mail connector (SDK-based) rather than an element template

If extending the HTTP connector is not desirable, implement Microsoft 365 Mail as a first-class outbound connector (Connector SDK) that:

• Handles delegated OAuth end-to-end (including token refresh)
• Keeps Graph-specific behaviour encapsulated
• Ships with its own element template(s) and a consistent connection UX

Describe alternatives you've considered

• Continue with client credentials only (application permissions) and recommend Exchange application access policies to limit mailbox scope.
  • Still fails for tenants with “delegated-only” security posture.
• Use Bearer token auth.
  • Not viable for long-running/repetitive processes due to short access token TTL and manual rotation overhead.
• Ask customers to implement delegated OAuth outside Camunda (token broker / Azure Function) and call Graph from HTTP connector.
  • Adds repeated custom work, operational burden, and undermines the value of an out-of-the-box connector.

Additional context

• Microsoft Teams connector already documents and supports a Refresh Token connection type (Tenant ID, Client ID, Secret ID, Refresh token). This is a strong precedent for how delegated auth should look and behave in Camunda.
• The Microsoft 365 (Mail) connector docs currently document only Bearer token and OAuth2 client credentials, and the element template reflects those same options.
• Microsoft’s token endpoint expects application/x-www-form-urlencoded for token requests, which affects both “workaround via HTTP connector” and any native implementation that needs to exchange/refresh tokens.

[ztefanie]

In the grooming we decided to go with option A

[crobbins215]

@KerstinHebel merging #6535 with this issue already open, thanks for flagging. When we have a fix it would be helpful if we could come back to you and test

[crobbins215]

Ticket info #6535

Describe the Bug

the MS connector requires to have API acces as APP for several permissions, this creates security and compliance issues.
With these permissions the integration has access to all user emails in the tenant (high possibilty to expose confidentials content), same for Calendar, the app has access to all calendars within the tenant and to ALL information in the calendars, even the onces marked as private from the User. (same risk as for the emails)

Steps to Reproduce

See documentation (https://docs.camunda.io/docs/components/connectors/out-of-the-box-connectors/microsoft-o365-mail/#oauth2-client-credentials-flow-authentication) required app level permissions

Expected Behavior

Support to have delegated permissions only, and have a setup for user authentication. This is the normal way apps are integrating and interacting with M365 (eg, Zoom, Calendly and so far)

Environment

Camunda 8.8 SaaS

Example for proper permissions:

[KerstinHebel]

Hi Calvin,
I just read what you described above, For Option B, using client credentials with Exchange application access policies/RBAC doesn’t actually fix the sensitive‑information problem. Those policies only limit which mailboxes the app can access, not what it can see inside those mailboxes. Once an app has application permissions like Mail.Read or Calendars.Read, it can read full message bodies and calendar events (including items marked as private) for every mailbox in its scope. So basically what is used now, cant be used at all.... Also I dont know an app which integrates with App level permissions for Mail and Calendar Access with M365.

[crobbins215]

Hi Calvin, I just read what you described above, For Option B, using client credentials with Exchange application access policies/RBAC doesn’t actually fix the sensitive‑information problem. Those policies only limit which mailboxes the app can access, not what it can see inside those mailboxes. Once an app has application permissions like Mail.Read or Calendars.Read, it can read full message bodies and calendar events (including items marked as private) for every mailbox in its scope. So basically what is used now, cant be used at all.... Also I dont know an app which integrates with App level permissions for Mail and Calendar Access with M365.

Great feedback, thanks @KerstinHebel

[MaxTru]

@crobbins215 for Option a

Documentation:
Add a section to Microsoft 365 connector docs mirroring the Teams “Refresh Token type authentication” guidance, including > how to obtain a refresh token and operational expectations.

Would this cover the delegate access pattern that Kerstin described as best practice?

[crobbins215]

From my Microsoft understanding, yes

Yes “refresh token” authentication is effectively the delegated OAuth pattern (user context), and it’s the right way to cover the “delegate access” best-practice Kerstin described when the API requires delegated permissions.

In Microsoft Graph, delegated permissions are a scenario in which an app acts on behalf of a signed-in user.
(https://learn.microsoft.com/en-us/graph/permissions-overview?)

@sbuettner, when we do this, we need to make sure, Outlook Inbound and MS Teams are all in sync.

[crobbins215]

Being able to test it with @KerstinHebel will be a big help so we can make sure we get it right.