sasl-xoauth2.conf(5)

💖 sasl-xoauth2.conf(5) — the manual page, but make it make sense 💖

okay bestie, gather round, because we're talking about /etc/sasl-xoauth2.conf, the config file for sasl-xoauth2. yes it's a File Formats Manual situation, no it's not scary, i got you 🫶

---

✨ NAME ✨

/etc/sasl-xoauth2.conf — the configuration file for sasl-xoauth2 💅

---

🌸 DESCRIPTION 🌸

so this file is where the static, administrator-defined stuff lives — the info that XOAUTH2 SASL authentication needs to actually do its thing. it's not vibes-based, it's you-based: you (the admin, the main character 👑) decide what goes in here.

it's written in JSON, because of course it is, and it defines the variables needed to complete your XOAUTH2 configuration. no cap.

a minimal config file looks exactly like this, character for character, don't get creative:

{
  "client_id": "CLIENT_ID_GOES_HERE",
  "client_secret": "CLIENT_SECRET_GOES_HERE"
}

and if you want the full guidance on initial setup, the README is right there: https://github.com/tarickb/sasl-xoauth2

---

🎀 OPTIONS 🎀

the top-level JSON object can contain these keys, and yes, we're going through all of them. sit down, hydrate 🍓

• client_id — identifies this client when it's asking for OAuth 2 tokens. it's basically the username of the operation ✨
• client_secret — authenticates this client for those OAuth 2 token requests. heads up: it's world-readable by default 😭 (but see below, because you can stash this in token files instead — do that, bestie)
• always_log_to_syslog — always writes plugin log messages to syslog, even when the run succeeded. ⚠️ this one may contain tokens/secrets. defaults to "no".
• log_to_syslog_on_failure — logs to syslog if the XOAUTH2 flow fails. defaults to "yes".
• log_full_trace_on_failure — logs a full trace to syslog if the XOAUTH2 flow fails. ⚠️ again: may contain tokens/secrets. defaults to "no".
• token_endpoint — the URL to use when requesting tokens. it defaults to Google, so if you're on Microsoft/Outlook you must override this. no skipping, fr fr.
• proxy — if set, HTTP requests get proxied through this server. it's giving tunnel ✨
• ca_bundle_file — if set, overrides CURL's default certificate-authority bundle file.
• ca_certs_dir — if set, overrides CURL's default certificate-authority directory.
• refresh_window — if set, overrides the default 10 second refresh window with whatever time you give it, in seconds (and it's an integer, don't be cute with it).

---

🦋 TOKEN FILE 🦋

okay so beyond this file, sasl-xoauth2 also leans on a "token file", and it updates that thing independently. the token file is JSON-formatted too, naturally 💅

here's the tea: the contents of the token file MAY contain values for the keys described above — except for the logging-related keys. and if they do? the value in the token file overrides the value in the main configuration file. token file wins, periodt.

why do we love this? because it means:

• you can use the same installation of sasl-xoauth2 to connect to two different providers at the same time 🤯
• you get a place to store client secrets that is not world-readable — which, again, the main config file is by default, so, yeah 🙈

---

💀 BUGS 💀

found an improvement for this documentation? please report it upstream, bestie: https://github.com/tarickb/sasl-xoauth2/issues

---

🌈 SEE ALSO 🌈

• sasl-xoauth2-tool(1)

---

and that's the whole page, you ate it 💖 this was sasl-xoauth2.conf(5) from the File Formats Manual — go forth and authenticate responsibly, ily 🫶✨