Add OAUTH Credential server

The OAUTH credential server allows CMS to ack as an OAUTH broker and
supply bearer tokens to other applications in the system. Currently this
only support SMTP tokens for outbound mail delivery.

A UNIX domain socket is used to communicate between the SMTP agent and CMS.

A simple one line protocol is used to specify the account requested and
CMS returns the plain XAOUTH2 response string. The agent is responsible to
base64 encode it.

This works for GMail and O365 mailboxes.

Signed-off-by: Jason Gunthorpe <jgg@mellanox.com>

2 files changed, 200 insertions, 0 deletions

diff --git a/doc/example-exim4.conf b/doc/example-exim4.conf
new file mode 100644
index 0000000..2f2c906
--- /dev/null
+++ b/doc/example-exim4.conf
@@ -0,0 +1,134 @@
+# Specify local domains HERE, these are names that might appear in email
+domainlist local_domains =
+domainlist relay_to_domains =
+hostlist relay_from_hosts = localhost
+# Create this file HERE
+# It has single lines in the format:
+#  domain.com: host=smtp.office365.com::587 helo=cms user=user@domain.com oauth=/home/XX/mail/.cms/exim/unix
+# oauth= may also be replaced with password= to do basic authentication. The
+# file is searched based on the Envelope From when invoking sendmail
+SMARTFN = /etc/exim4/exim-smart-hosts
+
+# We don't have IPv6, do not even try.
+disable_ipv6=true
+
+# It is also a good idea to edit /etc/default/exim4 and switch to 'queueonly' mode (Debian)
+local_interfaces = <; [127.0.0.1]:25
+
+acl_smtp_rcpt = acl_check_rcpt
+acl_smtp_data = acl_check_data
+
+tls_advertise_hosts =
+
+# Trusted users are allowed to override the sender envelope
+trusted_users = # Add your user name HERE
+
+never_users = root
+
+host_lookup = *
+
+prdr_enable = true
+
+log_selector = +smtp_protocol_error +smtp_syntax_error \
+	+tls_certificate_verified
+
+ignore_bounce_errors_after = 2d
+timeout_frozen_after = 7d
+
+keep_environment =
+add_environment = <; PATH=/bin:/usr/bin
+
+begin acl
+acl_check_rcpt:
+
+  # Standard input
+  accept  hosts = :
+          control = dkim_disable_verify
+
+  deny    message       = Restricted characters in address
+          domains       = +local_domains
+          local_parts   = ^[.] : ^.*[@%!/|]
+
+
+  deny    message       = Restricted characters in address
+          domains       = !+local_domains
+          local_parts   = ^[./|] : ^.*[@%!] : ^.*/\\.\\./
+
+
+  accept  local_parts   = postmaster
+          domains       = +local_domains
+
+
+  require verify        = sender
+
+  accept  hosts         = +relay_from_hosts
+          control       = submission
+          control       = dkim_disable_verify
+
+  accept  authenticated = *
+          control       = submission
+          control       = dkim_disable_verify
+
+  require message = relay not permitted
+          domains = +local_domains : +relay_to_domains
+
+  require verify = recipient
+
+  accept
+
+begin routers
+
+# The router is sensitive to the sender address and will use the correct outgoing server.
+# Use something like:
+#  exim -f 'user@domain.com' -bt user@otherdomain.com
+# To quick test
+smarthost:
+  debug_print = "R: smarthost for $local_part@$domain"
+  driver = manualroute
+  domains = ! +local_domains
+  transport = remote_smtp_smarthost
+  route_data = ${extract{host}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}}
+  no_more
+
+begin transports
+
+remote_smtp_smarthost:
+  debug_print = "T: remote_smtp_smarthost for $local_part@$domain"
+  driver = smtp
+  helo_data = ${extract{helo}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{$value}{wakko.ziepe.ca}}
+  hosts_require_auth = ${extract{user}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{*}{}}
+  hosts_require_tls = *
+  tls_tempfail_tryclear = false
+  tls_verify_certificates = system
+
+begin retry
+
+*                      *           F,2h,15m; G,16h,1h,1.5; F,4d,6h
+
+begin rewrite
+
+# Replace user and domain HERE
+root@+local_domains user@domain.com Ffrs
+user@+local_domains user@domain.com Ffrs
+
+begin authenticators
+
+xoauth2_smart:
+  driver = plaintext
+  client_condition = ${if and {{!eq{$tls_out_cipher}{}} {eq{${extract{oauth}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{}fail}}{}}} }
+  public_name = XOAUTH2
+  client_ignore_invalid_base64 = true
+  client_send = : ${readsocket{${extract{oauth}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{$value}fail}}{SMTP ${extract{user}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{$value}fail}}}
+
+# Plain has fewer round trips, so prefer to use it
+plain_smart:
+  driver = plaintext
+  client_condition = ${if and {{!eq{$tls_out_cipher}{}} {eq{${extract{password}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{}fail}}{}}} }
+  public_name = PLAIN
+  client_send = ^${extract{user}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{$value}fail}^${extract{password}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}}
+
+login_smart:
+  driver = plaintext
+  client_condition = ${if and {{!eq{$tls_out_cipher}{}} {eq{${extract{password}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{}fail}}{}}} }
+  public_name = LOGIN
+  client_send = : ${extract{user}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{$value}fail} : ${extract{password}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}}
diff --git a/doc/smtp.md b/doc/smtp.md
new file mode 100644
index 0000000..48f3d6c
--- /dev/null
+++ b/doc/smtp.md
@@ -0,0 +1,66 @@
+# Outbound mail through SMTP
+
+The cloud services now all support OAUTH2 as an authentication method for
+SMTP, and CMS provides an internal broker service to acquire and expose the
+OAUTH access token needed for SMTP.
+
+This allows the use of several normal SMTP tools without having to revert
+to BASIC authentication.
+
+## CMS Configuration
+
+CMS uses a UNIX domain socket to expose the access token. CMS must be running
+to maintain a fresh token.
+
+This feature is enabled in the configuration file:
+
+```Python
+account = Office365_Account(user="user@domain.com")
+Office365("inbox", account)
+CredentialServer("/var/run/user/XXX/cms.sock",
+                 accounts=[account])
+```
+
+Upon restart CMS will acquire and maintain a OAUTH token with the SMTP scope
+for the specified accounts, and serve token requests on the specified path.
+
+# exim 4
+
+Exim is a long standing UNIX mail system that is fully featured. exim's flexible
+authentication can support the use of OAUTH tokens:
+
+```
+begin authenticators
+
+xoauth2_smart:
+  driver = plaintext
+  client_condition = ${if !eq{$tls_out_cipher}{}}
+  public_name = XOAUTH2
+  client_ignore_invalid_base64 = true
+  client_send = : ${readsocket{/home/XX/mail/.cms/exim/cms.sock}{SMTP user@domain}}
+```
+
+Since exim runs as a system daemon, permissions must be set to allow access to
+the socket:
+
+```sh
+cd /home/XX/mail/.cms
+mkdir exim
+chmod 0750 exim
+sudo chgrp Debian-exim cms
+```
+
+And the CMS configuration must specify a umask:
+
+```Python
+CredentialServer("/home/XX/mail/.cms/exim/cms.sock",
+                 accounts=[account],
+				 umask=0o666)
+```
+
+A fully functional [exim4.conf](example-exim4.conf) is provided. This minimal,
+relay only config can replace the entire configuration from the distro, after
+making the adjustments noted. In this mode /usr/bin/sendmail will be fully
+functional for outbound mail and if multiple accounts are required, it will
+automatically choose the account to send mail through based on the Envelope
+From header.