OAUTH2 over IMAP

Summary

Using Oauth2 over IMAP is a great way to allow Cypht to access your E-mail accounts without having to supply a password. Unfortunately there are only 2 providers I know of that support this feature: Gmail and Outlook.com. Setting up Oauth2 requires some additional configuration over a basic install. I would recommend first making sure you have a functional Cypht site before setting this up to simplify troubleshooting.

Create the app with the E-mail provider

The first step is to create an "app" at Gmail or Outlook.com. This provides you with the client secret and client id you need to establish the Oauth2 process. For Gmail this can be done here:

https://console.developers.google.com/project

and for Outlook.com here:

https://account.live.com/developers/applications/

You will need to supply a "redirect URI" during this process. This should be the URL of your Cypht installation followed by with ?page=home. For example https://example.com/?page=home

One app can connect multiple accounts of the same provider by using the user's authorization to request unique access tokens for each account during the OAuth2 flow. Each token corresponds to a specific user's permissions and account data.

Edit and move the oauth2.ini file

Next you need to edit the modules/imap/oauth2.ini file, and move it to the "app_data_dir" as defined in your hm3.ini file. Enter the client id and secret you got from the first step, and make sure the redirect_uri exactly matches what you entered when setting up your app.

Now re-run the config_gen.php script which will find your oauth2.ini file and combine it into the site settings.

Add an Oauth2 account

Login to Cypht and navigate to Settings -> Servers. Use the "Add an E-mail account" dialog at the top to select your provider and enter your E-mail address (note that this section requires the nux module set to be enabled, which is the default in the hm3.ini file).

If everything is working correctly, you should be prompted to Enable access and should see the following:

This provider supports Oauth2 access to your account. This is the most secure way to access your E-mail. Click "Enable" to be redirected to the provider site to allow access.

Clicking "Enable" will redirect your browser to the E-mail providers Oauth2 page where you must allow Cypht access. After doing so, you will be redirected back to Cypht (to the redirect URI) and both the IMAP and SMTP server should be added for that account. Don't forget to save your settings at Settings -> Save if you want the account to persist between logins.