Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Security and hardening

JavaMail cannot log in to Office 365 IMAP with an OAuth token

ErrorA01 NO AUTHENTICATE failed.

Short answer

Exchange Online only accepts an OAuth access token over the XOAUTH2 mechanism, and Jakarta Mail has that mechanism switched off by default. After that, the failure is nearly always the token: wrong scope, or for app-only access a missing Exchange service principal and mailbox permission.

  • Applies to Jakarta Mail / Angus Mail 2.x, Exchange Online, Microsoft Entra ID
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Turn on protocol debug output and look at which mechanisms the client tries. If XOAUTH2 never appears in the AUTHENTICATE line, the first cause applies. If it does appear and the server still answers NO, check the token.

    props.put("mail.debug", "true");
  2. 2Match what you see, then jump to its fix

    1. 1The debug output does not show AUTHENTICATE XOAUTH2XOAUTH2 is not enabled in the mail sessionFix
    2. 2The token request succeeds, but the server answers AUTHENTICATE failedThe token was requested with the wrong scopeFix
    3. 3Token has the IMAP.AccessAsApp role but AUTHENTICATE failedApp-only (client credentials) access is missing its Exchange service principalFix

What does the error look like?

  • A01 NO AUTHENTICATE failed.
  • AUTHENTICATE failed

Cause 1 of 3

XOAUTH2 is not enabled in the mail session

1Check

The IMAP provider keeps XOAUTH2 out of its default mechanism list, because the password must be an access token instead of a real password.

grep -rn "auth.mechanisms\|xoauth2" src/ | head

2Fix

Set the mechanism list to XOAUTH2 for the IMAP protocol and pass the access token as the password.

Properties props = new Properties();
props.put("mail.imap.ssl.enable", "true");
props.put("mail.imap.auth.mechanisms", "XOAUTH2");
Session session = Session.getInstance(props);
Store store = session.getStore("imap");
store.connect("outlook.office365.com", 993, "user@contoso.com", accessToken);

3Verify

The debug output now shows AUTHENTICATE XOAUTH2 and the server answers OK.

store.isConnected()

Confirmed by eclipse-ee4j.github.io

Did this fix it?

Cause 2 of 3

The token was requested with the wrong scope

1Check

For a signed-in user, the scope has to be the full Outlook resource URL, not a Graph scope. Decode the token on a test tenant and read its scp claim.

echo "$ACCESS_TOKEN" | cut -d. -f2 | tr '_-' '/+' | base64 -d 2>/dev/null

2Fix

Request https://outlook.office.com/IMAP.AccessAsUser.All (plus offline_access if you want refresh tokens) through the authorization code or device code flow.

scope=https://outlook.office.com/IMAP.AccessAsUser.All offline_access

3Verify

Request a new token and connect again.

store.connect("outlook.office365.com", 993, "user@contoso.com", newAccessToken);

Confirmed by learn.microsoft.com

Did this fix it?

Cause 3 of 3

App-only (client credentials) access is missing its Exchange service principal

1Check

Client credentials needs more than the Entra permission. A tenant admin must grant consent, register the service principal in Exchange, and give it access to each mailbox.

Get-ServicePrincipal | fl

2Fix

Use the Object ID of the Enterprise application, not of the App registration, when you register the service principal, then grant mailbox access. Request the token with the scope https://outlook.office365.com/.default.

Connect-ExchangeOnline -Organization <tenantId>
New-ServicePrincipal -AppId <APPLICATION_ID> -ObjectId <ENTERPRISE_APP_OBJECT_ID>
Add-MailboxPermission -Identity "john.smith@contoso.com" -User <SERVICE_PRINCIPAL_ID> -AccessRights FullAccess

3Verify

List the registered principals, then retry the IMAP login with a freshly issued token.

Get-ServicePrincipal | fl

Confirmed by learn.microsoft.com

Did this fix it?

How do I stop it coming back?

  • Keep the token request and the IMAP login in one small test class, so a scope change is caught straight away.
  • For app-only access, write down the three steps (consent, service principal, mailbox permission) in your runbook.
  • Use the Enterprise application Object ID when registering the service principal.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.