dev/core#2141 - Allow OAuth2 services to define mail setup routine
authorTim Otten <totten@civicrm.org>
Fri, 30 Oct 2020 08:39:58 +0000 (01:39 -0700)
committerTim Otten <totten@civicrm.org>
Tue, 3 Nov 2020 12:32:48 +0000 (04:32 -0800)
commit7be4bff1c08120f2c42b2c26912710de938cd1e0
treee74a1f0e04299c97a4554ac4e1951a362beb1343
parent0214a8bee0f2735a9f71f0878f38dee07e0e30a6
dev/core#2141 - Allow OAuth2 services to define mail setup routine

Overview
--------

For certain types of mail accounts -- such as Google Mail and Microsoft
Exchange Online -- the setup process may require interaction with a remote
web-service.

If you have OAuth2 enabled for one of these services, then this will create
an option for "Add Mail Account".

Before
------

There is no setup procedure.

After
-----

* Navigate to "Administer => CiviMail => Mail Accounts".
* Below the table, there is a select2 box for "Add Mail Account".
* If "Microsoft Exchange Online" is configured, then it will appear in the dropdown. Choose it.
* It redirects to MS to get authorization from the user (OAuth2 Authorization Code).
* The user comes back.
* We initialize a new mail account (`MailSettings` / `civicrm_mail_settings`)
* We accept the code and save the token (`OAuthSysToken`) with the account.
* We redirect to the account configuration form.

Technical Details
-----------------

The new mail account will have some details, such as `server`, `protocol`,
and `username` pre-filled.  This uses a template -- see e.g.
`providers/ms-exchange.dist.json` (`mailSettingsTemplate`).
ext/oauth-client/CRM/OAuth/MailSetup.php [new file with mode: 0644]
ext/oauth-client/oauth_client.php
ext/oauth-client/tests/phpunit/CRM/OAuth/MailSetupTest.php [new file with mode: 0644]