Skip to content

Gmail OAuth2 login for PQ email retrieval #697

Description

@AgreeDK

Problem Statement

#443 implements PQ-from-email using generic IMAP + app-password, which
already works for Gmail (2FA + app-password). However, app-passwords are
an extra manual setup step for users, and some users may not want to
enable 2FA just to generate one.

Proposed Solution

Add Gmail as an OAuth2 login option alongside the generic IMAP path from
#443, so Gmail users can just click "Connect with Google" instead of
generating an app-password.

  • Use google-auth / google-api-python-client (official SDKs) rather
    than hand-rolled OAuth, to stay on the maintained side of any future
    protocol changes
  • Local loopback browser flow (opens system browser, listens on
    localhost callback) — standard pattern for desktop OAuth apps
  • Request the minimal scope needed: gmail.readonly
  • Token storage/refresh via keyring, same credential store as Get PQ from e-mail account #443
  • Implements the shared EmailProvider interface from Get PQ from e-mail account #443
    (GmailOAuthProvider), so it plugs into the same fetch/parse/DB-match
    pipeline without changes there

Notes / constraints

  • gmail.readonly is a restricted Google OAuth scope, requiring
    Google's app verification process before general release. Since
    OpenSAK is a pure desktop app with no backend server, we should be
    exempt from the costly annual security assessment — but standard
    verification (brand review + scope review) still applies and can take
    from a few days to a few weeks. Start this process early, in
    parallel with development
    — it's an external dependency, not dev
    time, and shouldn't block the rest of the implementation.
  • Until verification completes, users will see Google's "unverified
    app" warning on first login — worth a short note in the UI/user guide
    so it doesn't look like a bug or a security problem with OpenSAK.
  • Expect roughly one maintenance session per year as Google updates
    OAuth/API requirements (this has happened before and will again) —
    a standing cost of third-party OAuth integration.
  • This is a convenience layer, not a functional requirement — Get PQ from e-mail account #443's
    IMAP+app-password path already covers Gmail if this gets deprioritized.

Depends on

Expected Benefits

Smoother login UX for Gmail users — no manual app-password setup.

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureon holdthe issue is on hold for now

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions