Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Email delivery

Python IMAP OAuth login to a shared mailbox in Microsoft 365 fails

ErrorA01 NO AUTHENTICATE failed.

Short answer

Exchange Online accepts an OAuth token for IMAP only if the SASL user name is right and the token's identity has access to that mailbox. Check three things: the shared mailbox address in the XOAUTH2 string, the Exchange service principal with FullAccess, and the .default scope.

  • Applies to Exchange Online, Python 3.13 imaplib, MSAL for Python
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Decode the access token and note whether it was issued for a signed-in user or for the app itself. The fix depends on that.

    python -c "import jwt,sys; c=jwt.decode(sys.argv[1], options={'verify_signature': False}, algorithms=['RS256']); print(c.get('scp'), c.get('roles'))" "$TOKEN"
  2. 2Match what you see, then jump to its fix

    1. 1The sign-in succeeds in the browser, but imaplib says AUTHENTICATE failedThe XOAUTH2 string names the wrong mailboxFix
    2. 2You use client credentials (a daemon), the token has roles IMAP.AccessAsApp, and login is still refusedThe app-only service principal has no access to the mailboxFix
    3. 3New-ServicePrincipal ran without error, but authentication still failsThe wrong Object ID was used for the service principalFix
    4. 4The token's audience or roles do not match IMAP for Exchange OnlineThe token was requested with the wrong scopeFix

What does the error look like?

  • A01 NO AUTHENTICATE failed.
  • imaplib.IMAP4.error: AUTHENTICATE failed.

Cause 1 of 4

The XOAUTH2 string names the wrong mailbox

1Check

For a shared mailbox with a user token, Microsoft says to get the token on behalf of a user but put the shared mailbox's email address in the userName field of the XOAUTH2 string.

grep -rn "user=" mail_client.py

2Fix

Build the string with the shared mailbox address. The control character 0x01 separates the parts.

import imaplib

def xoauth2(mailbox, token):
    return f"user={mailbox}\x01auth=Bearer {token}\x01\x01".encode()

imap = imaplib.IMAP4_SSL("outlook.office365.com")
imap.authenticate("XOAUTH2", lambda _: xoauth2("shared@contoso.com", token))

3Verify

List the folders of the shared mailbox.

python imap_login_test.py

Confirmed by learn.microsoft.com

Did this fix it?

Cause 2 of 4

The app-only service principal has no access to the mailbox

1Check

With client credentials, an Exchange admin must register the service principal in Exchange with New-ServicePrincipal, then grant FullAccess with Add-MailboxPermission. Check the service principal exists, and ask the admin whether FullAccess was granted to it on this mailbox.

Get-ServicePrincipal | fl

2Fix

Register the service principal and grant it FullAccess on the mailbox.

New-ServicePrincipal -AppId <APPLICATION_ID> -ObjectId <OBJECT_ID>
Add-MailboxPermission -Identity "shared@contoso.com" -User <SERVICE_PRINCIPAL_ID> -AccessRights FullAccess

3Verify

Fetch a fresh token and authenticate again.

python imap_login_test.py

Confirmed by learn.microsoft.com

Did this fix it?

Cause 3 of 4

The wrong Object ID was used for the service principal

1Check

The OBJECT_ID must come from the Overview page of the Enterprise Application, not from the App Registration page. Microsoft states the wrong one causes an authentication failure.

Get-ServicePrincipal | fl

2Fix

Copy the Object ID from Enterprise applications in the Microsoft Entra admin center and register again.

New-ServicePrincipal -AppId <APPLICATION_ID> -ObjectId <ENTERPRISE_APP_OBJECT_ID>

3Verify

Authenticate again with a new token.

python imap_login_test.py

Confirmed by learn.microsoft.com

Did this fix it?

Cause 4 of 4

The token was requested with the wrong scope

1Check

Delegated tokens need the full scope https://outlook.office.com/IMAP.AccessAsUser.All. For client credentials, the token request must use https://outlook.office365.com/.default.

grep -rn "scope" auth.py

2Fix

Request the scope that matches your flow.

# delegated (signed-in user)
scopes = ["https://outlook.office.com/IMAP.AccessAsUser.All"]

# client credentials (daemon)
scopes = ["https://outlook.office365.com/.default"]

3Verify

Decode the new token and confirm scp or roles shows the IMAP permission, then log in.

python imap_login_test.py

Confirmed by learn.microsoft.com

Did this fix it?

How do I stop it coming back?

  • Test the login with one normal mailbox before moving to a shared one.
  • Record the Enterprise application Object ID next to the app registration notes.
  • Refresh tokens before they expire; do not reuse an access token for hours.

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.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Email

Django send_mail fails or hangs with an SSL error

smtplib.SMTPException raised from send_mail()

Django has two secure modes that must not be mixed: EMAIL_USE_TLS for explicit TLS (STARTTLS, usually port 587) and EMAIL_USE_SSL for implicit TLS (usually port 465).

4 causes, each with a fix

Next step

Want this handled for good?

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