`XOAUTH2` / `OAUTHBEARER` support

[polarathene]

I heard about Nylas recently and I can see that AI assisted dev appears to be leveraged quite a bit (this made the docs experience a bit less pleasant personally and tends to add skepticism/trust concerns for adopting such projects for me, but I am also aware of the perks).

Feature to support - Bearer token authentication via XOAUTH2 / OAUTHBEARER (authentication through SMTP/POP/IMAP protocols)

Presently I'm quite fond of swaks for the usage I have, but it's development has stalled (as it had for some time before a slight return of activity before becoming inactive again around 2 years ago). In particular I really wanted to see this feature PR land (support for auth via OAUTHBEARER / XOAUTH2).

Instead, for a test suite that requires verifying this support via CLI commands, I am using curl as a workaround (additional information for test environment), which looks like this:

• IMAP - Via Dovecot (which verifies the bearer token against a configured identify provider) with authentication on port 143 (aka IMAP using StartTLS):

  curl --silent \
    --login-options "AUTH=${AUTH_METHOD}" --oauth2-bearer "${ACCESS_TOKEN}" --user "${USER_ACCOUNT}" \
    --url 'imap://localhost:143' -X 'LOGOUT'

• SMTP - Via Postfix (auth delegated to the Dovecot SASL provider) with authentication on port 587 (aka submission port using StartTLS):

  curl --silent \
    --login-options "AUTH=${AUTH_METHOD}" --oauth2-bearer "${ACCESS_TOKEN}" --user "${USER_ACCOUNT}" \
    --url 'smtp://localhost:587' --mail-from "${USER_ACCOUNT}" --mail-rcpt "${USER_ACCOUNT}" --upload-file - <<< 'RFC 5322 content - not important'

Any mail client that has support for either AUTH_METHOD set for either command above (XOAUTH2 / OAUTHBEARER) would be compatible with authenticating this way to the Dovecot IMAP service.

• It'd be nice if Nylas were capable of it too (seems to be lacking from the comparison page).
• OAUTHBEARER is the more modern standard FWIW (standardized in 2015), with XOAUTH2 (Google's earlier method) still having adoption AFAIK but otherwise deemed legacy/deprecated.

Additional References:

• Since you already have provider support with Microsoft Outlook, it might be worth noting they have Office 365 related docs on SASL XOAUTH2 support (also details usage with IMAP, POP, and SMTP protocols).
• A real world setup shared by a user (in late 2025) using a variety of OSS software (which presumably Nylas could simplify). I've also setup Roundcube (Webmail client) to authenticate through Dovecot and an OIDC login flow.

---

Nylas documents a fixed set of OAuth2 providers, but one is listed as "IMAP". The associated docs page is rather sparse on this front (and that recommended guides section is massive in comparison despite being largely irrelevant to the page itself). I'm assuming this concern is due to either the docs being generated and/or the age of the Nylas which seems fairly young.

I would assume that the IMAP auth provider was more than just standard username + password credentials, given this page states:

Nylas CLI

A modern, open-source CLI (MIT licensed) that connects to Gmail, Outlook, Exchange, Yahoo, iCloud, and any IMAP provider through OAuth.

Somewhat misleading there?

---

I've not yet felt compelled to try Nylas out locally to better verify, a quick search over this repo for the IMAP provider and XOAUTH2 / OAUTHBEARER keywords suggests there is no support in place.

Consulting Gemini also suggests no support (not sure why it's deemed SMTP and IMAP protocols as "legacy" though):

No, Nylas does not support XOAUTH2 or OAUTHBEARER in the way you are thinking.

Because XOAUTH2 and OAUTHBEARER are SASL mechanisms explicitly designed to pass OAuth2 tokens over legacy TCP protocols like SMTP and IMAP, they don't apply to Nylas.

[nbarraclough]

Hey @polarathene what email providers are you using that support OAuth tokens for IMAP? It's supported for Yahoo & they are called out as a named provider, but for other IMAP connections you're right we bundle them as 'IMAP'.

For those examples you linked we'd usually recommend authing an account through Nylas & the Graph API or EWS rather than OAuth for IMAP? It seems unnecessary, but I'm keen to be convinced otherwise.

[polarathene]

Support in the wild

what email providers are you using that support OAuth tokens for IMAP?

As per the linked PR comment (at jetmore/swaks, an alternative to Nylas CLI), in my previous comment that would be a self-hosted Dovecot (which has it's own configuration to an OAuth or OIDC provider to verify the access token) and Postfix (delegated auth through SASL to Dovecot to authenticate).

I also noted in the prior comment supported service examples of:

• Roundcube webmail (supports configuring OIDC login and passing that access token to Dovecot to verify on it's side).
  • An example of configuring this is covered in DMS OAuth2 support docs
  • Refer to this example for adding a basic Roundcube container to compose.yaml, or this example for a more complete setup. I'm pretty sure I had an example somewhere with an actual IdP service included too 😅
• Microsoft Office 365 docs for XOAUTH2 (see this example of someone attempting to connect this way with swaks).

Another example is Stalwart (modern rust mailserver) which has this SASL support covered in their OAuth implementation too (they also note that popular mail client apps tend to lack support, but that doesn't mean it's not useful elsewhere).

---

Additional context

Some services (not specifically mail clients) have limited OAuth2 support, since IIRC that doesn't have a standardized/generic flow, so a client implements provider-specific support (or delegates to a library/API that has done that work instead). IdP's with OIDC support however can be generic, allowing any compliant provider to be integrated by the user/admin. This is how Dovecot and Roundcube get broader compatibility, while mail clients like Thunderbird have only a fixed set of supported OAuth2 providers IIRC. Regardless of OAuth2 or OIDC, an access token that authorizes that users session is sent to the service like Dovecot which then verifies against the IdP that it's valid to authenticate successfully.

XOAUTH2 (legacy) / OAUTHBEARER (modern and official standard) are auth mechanisms for SASL that support OAuth2/OIDC authentication via the access token (or JWT ID token), which protocols like SMTP/IMAP/POP support and mail clients tend to implement, while services like Dovecot implement the other side of it (configuring what auth mechanisms are supported and enabled to negotiate a compatible one).

I maintain docker-mailserver (aka DMS, one of the most popular dockerized mailserver images), where we've had users interested in OAuth login support, so that instead of direct credentials configured in Dovecot, it can be configured to integrate with an external OIDC provider of their choice. The users may also use mail clients like Roundcube or have automated headless clients that are compatible with the requested auth mechanism support.

---

Implementation guidance / reference

If you are interested, as previously mentioned I demonstrate a compose.yaml setup that allows you to fully offline/locally deploy DMS with a minimal mocked OIDC service for verifying a client is compatible.

In the commands section, expand the collapsed section to see basic shell commands for both XOAUTH2 + OAUTHBEARER formats.

• These document fairly well what you'd need to implement on your actual client, the OAuth2 auth token is encoded as a password credential effectively, and the auth mechanism communicated over the protocol.
• Alternatively see my test suite Caddyfile and associated compose.yaml (with API call examples)
  • This way is a little more convenient than the shell commands for deriving the AUTHENTICATE value to send via IMAP.
  • I found this Caddyfile approach simpler than the original PR to DMS which contributed a mock server in Python.

I then show a swaks command (that would work if that PR were to actually be merged), and an equivalent command to doing the same with curl (NOTE: that was broken during some curl releases, such as those packaged by Debian 12).

Reference - Raw IMAP transactions

For reference, from the DMS test suite we also have the following raw IMAP transactions to test these mechanisms (piping the lines through netcat direct to the IMAP port):

XOAUTH2:

a0 NOOP See test/config/oauth2/Caddyfile to generate the below XOAUTH2 string
a1 AUTHENTICATE XOAUTH2 dXNlcj11c2VyMUBsb2NhbGhvc3QubG9jYWxkb21haW4BYXV0aD1CZWFyZXIgRE1TX1lXTmpaWE56WDNSdmEyVnUBAQ==
a2 EXAMINE INBOX
a3 LOGOUT

OAUTHBEARER:

a0 NOOP See test/config/oauth2/Caddyfile to generate the below OAUTHBEARER string
a1 AUTHENTICATE OAUTHBEARER bixhPXVzZXIxQGxvY2FsaG9zdC5sb2NhbGRvbWFpbiwBaG9zdD1sb2NhbGhvc3QBcG9ydD0xNDMBYXV0aD1CZWFyZXIgRE1TX1lXTmpaWE56WDNSdmEyVnUBAQ==
a2 EXAMINE INBOX
a3 LOGOUT

As opposed to plain login credentials:

a1 LOGIN john.doe@example.test secret
a3 EXAMINE INBOX
a4 FETCH 1 BODY[]
a5 LOGOUT

Similar can be done for SMTP and POP protocols. View the linked PR comment I provided earlier, it links to the relevant RFCs for further reference.

Reference - Dovecot OIDC config

Not likely to be that useful to you as this is server-side implementation of it, but if interested in how Dovecot is setup for OAuth support in DMS, read on.

DMS is mostly providing a convenience layer (the container image integrates various services and simplifies a standard config with ENV/CLI for further changes as necessary), so for this related feature config we just support ENV that map to relevant settings in Dovecot (replacing fixed settings with related ENV values) and basic enablement.

Support in DMS could be better, but as explained it's quite basic that users can just supply their own config, like this user request for introspection with credentials that can be supported without extra changes to DMS:

services:
  dms:
    configs:
      - source: oauth2
        target: /etc/dovecot/dovecot-oauth2.conf.ext

configs:
  oauth2:
    content: |
      client_id = dms-dovecot
      client_secret = hunter2
      introspection_mode = post
      introspection_url = https://auth.example.com/admin/oauth2/introspect

[polarathene]

It seems unnecessary, but I'm keen to be convinced otherwise.

My perspective is from the OSS side of self-hosting a mail server and the community around that.

Many are happy with basic username + password credentials, but those with more elaborate setups have OIDC (self-hosted or remote) for SSO (DMS can leverage this as noted above for authentication, but until we land SCIM support, accounts still need to be provisioned for actually having a mailbox to receive mail, OIDC integration alone isn't sufficient in our case but SCIM is an unrelated concern for Nylas CLI so nevermind that).

Presently it seems Nylas CLI would only be compatible with plain login mechanism (username + password). Implementing client support for what has been requested above should be fairly simple for the XOAUTH2 / OAUTHBEARER mechanisms when connecting via IMAP?

If Nylas only has the fixed OAuth2 support and not OIDC, I can understand if that is a larger point of friction to implement/support? (nylas auth login would presumably take care of that, although sadly it seems to only support the browser flow, making it less useful non-interactively but in my test suite and the swaks example the access token is provided explicitly which may be acceptable for Nylas CLI too?)

Reference: I shared in my original issue description a link to a blog where a user used Claude to vibe code a solution for them to connect to Microsoft Office 365 SMTP/IMAP via XOAUTH2 with SASL. They link to their source for that here is the python script to acquire a token and format for the appropriate protocol, that supports interactive auth flows (although my interest is personally more towards automation for CI).