Add XOAuth2 support for GMail

[imartinezortiz]

This PR, uses https://github.com/tarickb/sasl-xoauth2 to add support for the XOAuth2 authentication method that is usually required / recommend for some providers like GMail. Currently this library it is specifically designed for GMail, but seems that there is a discussion to provide support for other providers like Office365 (there is an active PR).

More precisely, this PR does:

• Changes the Dockerfile to add a multi-stage build to build the SASL XOAuth2 library and then copy the result to the actual image. This build stage is configurable using docker build args.
• Define and document RELAYHOST_TLS_LEVEL, XOAUTH2_CLIENT_ID, XOAUTH2_SECRET, XOAUTH2_INITIAL_ACCESS_TOKEN, XOAUTH2_INITIAL_REFRESH_TOKEN environment variables to configure the XOAuth2 authentication.
• Modify entrypoint scripts to enable this feature if it is configured RELAYHOST and RELAYHOST_USERNAME too.
• Add a support function (file_env) to allow to pass sensitive values using a file instead of through environment variables. In addition to adhere to good practices, this allows to use Docker secrets or k8s secrets.
• Add extra step in the main entrypoint script to remove from the env variables that contains sensitive values.

Related to #41

[bokysan]

This was mighty fast pull request. I'm impressed. :)

I've gone through the code and don't see any issues. I would, however, suggest to try to create some tests for the new code, if possible:

• The unit-tests folder (and corresponding ./unit-tests.sh) contains BATS tests which can execute your bash functions and see if they work. We should at least have these.
• The integration-tests (and corresponding ./integration-tests.sh) will spin up postfix and try to send an email. Most of these tests send the email to oblivion, so I'm not quite sure how we could test if XAuth2 works or not. Any ideas?

On a side note -- I see that RELAYHOST_TLS_LEVEL and RELAYHOST are not used for anything else other than directly setting postfix settings, so I'll probably deprecate them in the next version in favor of POSTFIX_relayhost and POSTFIX_smtp_tls_security_level.

[imartinezortiz]

Hi @bokysan, just had the work done :D. I've updated the PR to add unit-tests. Regarding the two other points:

• integration-tests whenever there are some errors regarding xoauth2 config there is some output in the docker log, so I guess that is posible to grep the docker log to check if there is o there is not a specific output. The only downside I see, is that you need to create a GMail account and follow the documented setup to perform the integration tests.
• I just use RELAYHOST and RELAYHOST_USERNAME to check that they are available before doing the xoauth2 config. I do not see any issue, once you decide to use POSTFIX_relayhost you will need to search-and-replace in common-run.sh and the replacement should also work with the xoauth2 code.

[imartinezortiz]

Hi again, I added a new commit to modify the integration-tests to allow to test the XOAuth2 feature. I could run all the integration tests locally including the tests regarding the XOAuth2 tests.

I didn't figured out an easy way to get access to the docker container logs, particularly postfix logs that are the ones I need to parse for XOAuth2 tests.

Requirements to run the XOAuth2 tests:

• Must be run with as root or at least using sudo.
• In both xoauth2 and xoauth2-error integration tests folder it is required to have a .env that contains the required parameters to run the integration tests.

integration-tests/xoauth/.env sample content:

FROM=your.gmail.account@gmail.com
TO=your.destination.account@yourprovider.example.com
RELAYHOST_USERNAME=your.gmail.account@gmail.com
XOAUTH2_CLIENT_ID=your_client_id.apps.googleusercontent.com
XOAUTH2_SECRET=your_secret
XOAUTH2_INITIAL_ACCESS_TOKEN=your_access_token
XOAUTH2_INITIAL_REFRESH_TOKEN=your_refresh_token

To test an XOAuth2 error, just provide a fake RELAYHOST_USERNAME value in integration-tests/xoauth-error/.env:

FROM=your.gmail.account@gmail.com
TO=your.destination.account@yourprovider.example.com
RELAYHOST_USERNAME=not.your.gmail.account@gmail.com
XOAUTH2_CLIENT_ID=your_client_id.apps.googleusercontent.com
XOAUTH2_SECRET=your_secret
XOAUTH2_INITIAL_ACCESS_TOKEN=your_access_token
XOAUTH2_INITIAL_REFRESH_TOKEN=your_refresh_token

Just separated the commits to facilitate the review.

[bokysan]

Thanks for the commit.

I've left you some review notes. As soon as we resolved them I'll be merging the commit.

[bokysan]

I'll need to run this code myself. There must be a simpler way of doing this. Maybe leave it to run the tests and then analyze the log file as explained in #35, without capturing the docker output?

(This can be resolved later on though, I will not block the commit because of this.)

[imartinezortiz]

Following #35 (comment) gave me the clues to send logs to a shared volume.

[bokysan]

Side note: I might create a "testing" gmail account and add its credentials to build secrets, as the tests are now failing at GitHub.

[bokysan]

I'm gonna go ahead an merge this into master and see if I can set up the tests to use the GitHub secrets.

Thanks for the great work!