Skip to content

Bug 1888604 - Support OAuth2 (XOAUTH2) for outbound SMTP - #199

Open
topunix wants to merge 2 commits into
bugzilla:mainfrom
topunix:bug-1888604
Open

topunix wants to merge 2 commits into
bugzilla:mainfrom
topunix:bug-1888604

Conversation

@topunix

@topunix topunix commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

Two commits.

  1. Restore smtp_ssl as a none/starttls/ssl select

    • Mailer.pm passed smtp_ssl to Email::Sender, but the param was not
      defined, so mail_delivery_method=SMTP died on the transport's Str check.
    • New select param (default none); none maps to 0 for Email::Sender.
    • SMTP transport construction moved into _smtp_transport so it can be
      tested without sending.
    • update_params converts a 5.x boolean: 1 -> ssl, 0/empty -> none.
    • Docs: On -> ssl in the install guides; parameter description updated.
  2. Support OAuth2 (XOAUTH2) for outbound SMTP

    • New params: smtp_auth_method (password, oauth2), smtp_oauth2_token_url
      (https only), smtp_oauth2_client_id, smtp_oauth2_client_secret,
      smtp_oauth2_refresh_token. smtp_username is the XOAUTH2 user.
    • Access token fetched with the refresh token, cached per process (never in
      memcached or the DB; see the smtp_debug note), refreshed with under 5 minutes left, not
      cached without expires_in, dropped on SMTP AUTH failure. No fallback to
      the password. Token errors show only the HTTP status and OAuth2 error code.
    • Password path unchanged.
    • New optional feature smtp_oauth2 (Authen::SASL 2.1800, which provides
      XOAUTH2); Email::Sender 2.600 -> 2.601 for sasl_authenticator.
    • Docs: parameter descriptions, a Gmail setup section, and a smtp_debug
      warning (the debug log of the SMTP session includes the base64-encoded
      access token).

Note: smtp_oauth2_client_secret and smtp_oauth2_refresh_token should be
added to PARAMETERS_SECRET in whichever of this PR or #193 lands second.

Overlaps: Makefile.PL with #192; docs/en/rst/administering/parameters.rst with
#190 and #191. Will rebase whichever lands later.

Testing

  • prove -r t/ in the dev container: all pass except
    t/bmo/bounced-emails.t (fails the same on main).
  • docker/run-tests-in-docker.sh option 2 (mysql/BMO): pass.
  • New t/smtp-ssl.t: transport builds with defaults, ssl value mapping,
    update_params migration (via Bugzilla::Test::MockParams), including reruns.
  • New t/smtp-oauth2.t: password path, token request and cache, param change
    invalidation, no expires_in, token errors (no secrets in messages), no
    password fallback, cache cleared on AUTH failure, param checkers. The
    XOAUTH2 transport subtest needs Authen::SASL >= 2.1800 and skips without
    it; everything else runs in CI.
  • Local only: Authen::SASL 2.1800 installed with cpanm in the dev container
    (not part of the image) to run the XOAUTH2 subtest and the end-to-end test.
  • End to end against Gmail (smtp.gmail.com:587, starttls, oauth2): two
    messages delivered with one token request; bad refresh token gives
    "SMTP OAuth2 token request failed: 400 Bad Request (invalid_grant)" with
    no secrets; empty smtp_username is rejected by Gmail at AUTH and the
    cached token is dropped.

Mailer.pm passed Bugzilla->params->{smtp_ssl} to Email::Sender, but no
such param was defined, so the undef value failed the transport's Str
check and mail_delivery_method=SMTP died.

Add smtp_ssl as a select (none, starttls, ssl; default none) and map
none to 0 for Email::Sender. Move SMTP transport construction into
_smtp_transport so it can be tested without sending. update_params
converts a 5.x boolean value: 1 becomes ssl, 0 or empty becomes none.
Providers such as Gmail and Microsoft are dropping password logins for
SMTP. Add smtp_auth_method (password, oauth2). With oauth2, Bugzilla
gets an access token from smtp_oauth2_token_url using the configured
client ID, client secret and refresh token, and logs in with the
XOAUTH2 SASL mechanism as smtp_username. There is no fallback to
smtp_password.

The access token is cached per process, keyed on the token URL, client
ID, refresh token and username, and refreshed when less than five
minutes remain. It is not cached when the provider gives no expires_in,
and it is dropped when the server rejects the login. Token errors
report only the HTTP status and the OAuth2 error code. The password
path is unchanged.

oauth2 needs the new optional smtp_oauth2 feature (Authen::SASL 2.1800,
which provides XOAUTH2). Email::Sender 2.601 is required for its
sasl_authenticator option.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant