.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "sasl-xoauth2.conf" "5" "" "" "File Formats Manual"
.hy
.SH NAME
.PP
/etc/sasl-xoauth2.conf - configuration file for sasl-xoauth2
.SH DESCRIPTION
.PP
This file contains static, administrator-defined information needed for
XOAUTH2 SASL authentication.
.PP
It uses a JSON format to define variables needed to complete XOAUTH2
configuration.
.PP
A minimal configuration file looks like:
.IP
.nf
\f[C]
{
  \[dq]client_id\[dq]: \[dq]CLIENT_ID_GOES_HERE\[dq],
  \[dq]client_secret\[dq]: \[dq]CLIENT_SECRET_GOES_HERE\[dq]
}
\f[R]
.fi
.PP
See the full README for guidance on initial configuration:
https://github.com/tarickb/sasl-xoauth2
.SH OPTIONS
.PP
The top-level JSON object can contain the following keys:
.TP
\f[V]client_id\f[R]
identifies this client for OAuth 2 token requests
.TP
\f[V]client_secret\f[R]
authenticates this client for OAuth 2 token requests; world-readable by
default (but see below to place this in token files instead)
.TP
\f[V]log_to_syslog_on_failure\f[R]
log to syslog if XOAUTH2 flow fails (defaults to \[lq]yes\[rq])
.TP
\f[V]log_full_trace_on_failure\f[R]
log a full trace to syslog if XOAUTH2 flow fails; may contain
tokens/secrets (defaults to \[lq]no\[rq])
.TP
\f[V]token_endpoint\f[R]
URL to use when requesting tokens; defaults to Google, must be
overridden for use with Microsoft/Outlook.
.TP
\f[V]proxy\f[R]
if set, HTTP requests will be proxied through this server
.TP
\f[V]ca_bundle_file\f[R]
if set, overrides CURL\[cq]s default certificate-authority bundle file
.TP
\f[V]ca_certs_dir\f[R]
if set, overrides CURL\[cq]s default certificate-authority directory
.SH TOKEN FILE
.PP
In addition to this file, \f[V]sasl-xoauth2\f[R] relies on a \[lq]token
file\[rq] which it updates independently.
The token file is also JSON-formatted.
The contents of this token file MAY contain values for the keys
described above (except for the logging-related keys).
If they do, the value in the token file overrides the value in the main
configuration file.
.PP
This makes it possible to use the same installation of
\f[V]sasl-xoauth2\f[R] to connect to two different providers
simultaneously.
This also has the benefit of providing storage for client secrets that
is not world-readable.
.SH BUGS
.PP
Please report improvements in this documentation upstream at
https://github.com/tarickb/sasl-xoauth2/issues
.SH SEE ALSO
.PP
sasl-xoauth2-tool(1)