Issue 53534: Support Microsoft's Graph Protocol API for authentication via OAuth2 token by labkey-bpatel · Pull Request #7381 · LabKey/platform

labkey-bpatel · 2026-02-03T06:02:26Z

Rationale

Microsoft plans to retire SMTP Basic Authentication in March 2026. In response, one of our clients’ IT department has requested a shift to OAuth-based authentication

Since SMTP Oauth 2.0 client credential flow with non-interactive sign-in (for email notifications) is not supported we’ll need to use Microsoft’s Graph API instead of SMTP protocol

This PR adds a Graph transport method as an alternative to SMTP, which enables mail delivery via OAuth2 authentication method.

Spec

Related Pull Requests

Changes

Add EmailTransportProvider interface.
Extract SMTP logic from MailHelper to its own provider class.
Add GraphTransportProvider that implements Graph API email transport using Microsoft SDK, handles attachments >3MB via upload sessions to accommodate Graph API's 4MB request limit.
Update MailHelper to manage multiple transport providers and detect configuration conflict (if both SMTP and Graph are configured)
Add EmailTestWithAttachmentAction in AdminController to test Graph API with HTML content, large attachments and data URI images.
Update emailTest.jsp to display success feedback after email send attempts and add Graph-specific test button for HTML and attachment workflow (button only visible when Graph is the active provider).
Add unit test to mock Microsoft Graph SDK to verify API interactions without real credentials.

Tasks 📍

Manual Testing
Unit test
Verify Fix

… a provider-based abstraction for email transport. Refactor the existing SMTP logic into its own provider. Manage OAuth2 token caching. Enforce that only one transport method can be configured.

…via_graph

…o fb_mail_transport_via_graph

…via_graph

…test, update emailTest.jsp to manually test Graph credentials, add an action to test uploads >= 4MB.

github-actions · 2026-02-03T06:02:40Z

WARNING: This PR appears to have the default title generated by GitHub. Please use something more descriptive.

…date testing. Add comments.

labkey-bpatel · 2026-02-04T18:03:09Z

core/src/org/labkey/core/admin/AdminController.java

+     */
+    @AdminConsoleAction
+    @RequiresPermission(AdminOperationsPermission.class)
+    public class EmailTestWithAttachmentAction extends FormHandlerAction<EmailTestForm>


I created this test action to test HTML content, attachments, and data URI images - scenarios that could hit Graph's size constraints. Should this remain separate for clarity, or would it be better to repurpose/extend EmailTestAction to test HTML/attachments for both transports?

I don't have a strong opinion. If left as Graph API-specific, I would change the name to specify that.

Name changed.

api/src/org/labkey/api/util/GraphTransportProvider.java

…via_graph

…h external URL images and data URI images.

…via_graph

api/src/org/labkey/api/util/GraphTransportProvider.java

…via_graph

…test around this change. Other minor updates.

…via_graph

…method.

labkey-adam

Code looks good, generally speaking. No required changes, but please review my questions & comments.

My biggest concern is the fact that this adds 70MB of JAR files to API. This is an extraordinary amount of new code for a single feature that will be used rarely. Were there any other options that would reduce the dependencies? Can any dependencies be excluded? If we can't slim it down, we may need to consider pushing the Graph API transport and dependencies into a separate module.

labkey-adam · 2026-02-23T18:39:54Z

api/src/org/labkey/api/util/MailHelper.java

+            _configurationConflict = true;
+            String names = configured.stream()
+                .map(EmailTransportProvider::getName)
+                .collect(Collectors.joining(" and "));


Not critical, but using StringUtils.joinWithConjunction() would possibly scale this better in the future. There are only two providers right now, but it's theoretically possible that we'd have > 2.

Good point, now changed to use StringUtils.joinWithConjunction()

api/src/org/labkey/api/util/MailHelper.java

labkey-adam · 2026-02-23T18:57:39Z

api/src/org/labkey/api/util/MailHelper.java

-        else
-        {
-            _session = DEFAULT_SESSION;
+            _activeProvider = _smtpProvider;


Why does calling this set _activeProvider? Only one provider can be configured, so either SMTP is already active or you'd be switching to an unconfigured provider. I could understand if this threw if SMTP is not active. This is also a concurrency risk since _activeProvider is not volatile. Ideally it would be final, set statically, and never changed.

It shouldn't, now removed.

labkey-adam · 2026-02-23T19:14:12Z

core/src/org/labkey/core/admin/AdminController.java

+                    "<p>Sent via " + MailHelper.getActiveProvider().getName() + ".</p>" +
+                    "</td></tr>" +
+                    "</table>" +
+                    "</body></html>");


I know this is "just" test HTML, but using DOM is preferred. I don't love that concatenated strings aren't HTML encoded here, even though it's just for testing. DOM would handle this automatically.

Absolutely - I was focused on getting things working and missed adding the DOM layer for encoding. Now updated.

labkey-adam · 2026-02-23T19:16:34Z

core/src/org/labkey/core/admin/AdminController.java

+     */
+    @AdminConsoleAction
+    @RequiresPermission(AdminOperationsPermission.class)
+    public class EmailTestWithAttachmentAction extends FormHandlerAction<EmailTestForm>


I don't have a strong opinion. If left as Graph API-specific, I would change the name to specify that.

labkey-adam · 2026-02-23T19:24:42Z

api/src/org/labkey/api/util/MailHelper.java

+    }

-        return session;
+    public static void init()


Have you tried getting rid of init()? Seems unnecessary. The first caller who touches MailHelper should force the initialization to occur. I don't see any benefit of doing this proactively in ApiModule.doStartup().

Since this initial code review, the design has changed. Removing init() may longer be necessary, please review the new changes.

labkey-bpatel · 2026-02-24T17:46:01Z

Code looks good, generally speaking. No required changes, but please review my questions & comments.

My biggest concern is the fact that this adds 70MB of JAR files to API. This is an extraordinary amount of new code for a single feature that will be used rarely. Were there any other options that would reduce the dependencies? Can any dependencies be excluded? If we can't slim it down, we may need to consider pushing the Graph API transport and dependencies into a separate module.

We could trim ~10MB by cutting azure-identity, but that would require us to handle token management - not a significant saving. I am leaning toward pushing these changes to a standalone module for now, then we can revisit moving it into premiumModules down the road. Thoughts?

…via_graph

…er class to a new module in premiumModules. Rename test action to 'GraphEmailTestWithAttachmentAction'. Remove setting activeProvider in setSession. Use StringUtilsLabKey.joinWithConjunction()

…via_graph

labkey-adam

Please see a few suggestions and questions. I'm approving and no further review is needed at this stage.

I do think we should consider some refactoring to make key classes less tied to SMTP and Jakarta Mail. MailHelper special cases SMTP in a few places, making some of the methods applicable to SMTP only. It's now odd that ViewMessage and MultipartMessage extend Jakarta Mail classes and hold an SMTP session, even when used with Graph. Ideally, MailHelper and the message classes would be completely generic to the provider. Dumbster could construct & configure an SmtpTransportProvider, and set that as MailHelper's active provider. However, I don't think any of this is required right now. I'd prefer to get this tested and merged, and get the client to test it. Then circle back with some improvements as a follow-on.

labkey-adam · 2026-02-27T19:17:39Z

api/src/org/labkey/api/util/MailHelper.java

-        {
-            _session = DEFAULT_SESSION;
-        }
+        return _smtpProvider.getSession();


Should this return null if _smtpProvider is not configured?

labkey-adam · 2026-02-27T19:18:25Z

api/src/org/labkey/api/util/MailHelper.java

-    public static Session getSession()
-    {
-        return _session;
+        return new MultipartMessage(getSession());


What happens here if getSession() returns null?

labkey-adam · 2026-02-28T23:14:19Z

api/src/org/labkey/api/util/MailHelper.java

-        return session;
+    public static void setSession(Session session)
+    {
+        _smtpProvider.setSession(session);


Should this throw if called when Graph transport is active?

labkey-adam · 2026-02-28T23:20:51Z

api/src/org/labkey/api/util/MailHelper.java

+    }

-        return session;
+    public static void setSession(Session session)


Clarify method name? setSmtpSession()

labkey-adam · 2026-02-28T23:21:29Z

api/src/org/labkey/api/util/MailHelper.java

+     * Returns the SMTP session for creating messages
+     */
+    @Nullable
+    public static Session getSession()


Clarify? getSmtpSession()

labkey-bpatel added 11 commits January 20, 2026 15:12

Implement email transport using the Microsoft Graph API and introduce…

c778ac9

… a provider-based abstraction for email transport. Refactor the existing SMTP logic into its own provider. Manage OAuth2 token caching. Enforce that only one transport method can be configured.

Merge remote-tracking branch 'origin/develop' into fb_mail_transport_…

f054865

…via_graph

Add dependencies. Updates for testing.

e855f46

Create getters for the URLs.

0e69360

Remove unused dependencies.

f10f466

Merge remote-tracking branch 'origin/fb_mail_transport_via_graph' int…

2aa8590

…o fb_mail_transport_via_graph

Add confirmation that an email was sent successfully.

34ef547

Merge remote-tracking branch 'origin/develop' into fb_mail_transport_…

8400794

…via_graph

Dependencies and versions

e481448

Add a helper for adding a file attachment

69bec71

Use Microsoft SDK to send messages and upload attachments, add junit …

565d551

…test, update emailTest.jsp to manually test Graph credentials, add an action to test uploads >= 4MB.

labkey-bpatel changed the title ~~Fb mail transport via graph~~ Issue 53534: Support Microsoft's Graph Protocol API for authentication via OAuth2 token Feb 3, 2026

labkey-bpatel added 3 commits February 3, 2026 12:47

add comments

f075819

add comment

1459fe2

Handle data URIs in HTML to comply with Graph's 4MB request limit. Up…

35bbddc

…date testing. Add comments.

labkey-bpatel mentioned this pull request Feb 4, 2026

Issue 53534: Support Microsoft's Graph Protocol API for authentication via OAuth2 token LabKey/server#1276

Open

labkey-bpatel requested review from labkey-adam and labkey-tchad February 4, 2026 07:08

labkey-bpatel commented Feb 4, 2026

View reviewed changes

labkey-tchad reviewed Feb 4, 2026

View reviewed changes

api/src/org/labkey/api/util/GraphTransportProvider.java Outdated Show resolved Hide resolved

Merge remote-tracking branch 'origin/develop' into fb_mail_transport_…

a697223

…via_graph

labkey-bpatel marked this pull request as ready for review February 5, 2026 00:46

labkey-bpatel added 6 commits February 4, 2026 22:20

Remove mockito

ce46a1a

Updates with JMock

9606396

Use DataHandler to get the correct content type. Update test with bot…

5757b1b

…h external URL images and data URI images.

Exclude dependency on msal4j-persistence-extension

4998a7b

Merge remote-tracking branch 'origin/develop' into fb_mail_transport_…

0351964

…via_graph

Revert "exclude group" approach used for resolving dependency conflict

eb9973e

labkey-bpatel requested a review from labkey-tchad February 9, 2026 18:57

labkey-tchad approved these changes Feb 9, 2026

View reviewed changes

api/src/org/labkey/api/util/GraphTransportProvider.java Outdated Show resolved Hide resolved

labkey-bpatel mentioned this pull request Feb 10, 2026

Issue 53534: Support Microsoft's Graph Protocol API for authentication via OAuth2 token LabKey/testAutomation#2881

Open

labkey-bpatel added 6 commits February 10, 2026 20:58

Handle CC/BCC mapping in buildGraphMessage()

2e2b18c

Merge remote-tracking branch 'origin/develop' into fb_mail_transport_…

6cd0dc4

…via_graph

Merge remote-tracking branch 'origin/develop' into fb_mail_transport_…

5c73b1b

…via_graph

Treat CID inline parts without filenames as attachments. Update unit …

d558483

…test around this change. Other minor updates.

Merge remote-tracking branch 'origin/develop' into fb_mail_transport_…

e42999d

…via_graph

Code review change - move some of the common setup code to the setup …

50d30b7

…method.

labkey-adam reviewed Feb 23, 2026

View reviewed changes

labkey-bpatel added 4 commits February 25, 2026 22:09

Merge remote-tracking branch 'origin/develop' into fb_mail_transport_…

01949cf

…via_graph

Code review changes: Code refactor around moving GraphTransportProvid…

27d230c

…er class to a new module in premiumModules. Rename test action to 'GraphEmailTestWithAttachmentAction'. Remove setting activeProvider in setSession. Use StringUtilsLabKey.joinWithConjunction()

cleanup, code review change

b84ce8c

revert unintended change

f8d0d9c

labkey-bpatel requested a review from labkey-adam February 27, 2026 04:01

Merge remote-tracking branch 'origin/develop' into fb_mail_transport_…

a6df92e

…via_graph

labkey-adam approved these changes Feb 28, 2026

View reviewed changes

Conversation

labkey-bpatel commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rationale

Related Pull Requests

Changes

Tasks 📍

Uh oh!

github-actions bot commented Feb 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

labkey-adam left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

labkey-bpatel Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

labkey-bpatel commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

labkey-adam left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

labkey-bpatel commented Feb 3, 2026 •

edited

Loading

labkey-bpatel Feb 26, 2026 •

edited

Loading

labkey-bpatel commented Feb 24, 2026 •

edited

Loading