[Users] Setting Up OAuth 2.0 for Microsoft

[Dustin Miller]

I recently used the instructions on the OAuth2 FAQ page
(https://www.claws-mail.org/faq/index.php/Oauth2) to set up a Microsoft
Exchange account with OAuth2 in Claws. Based on my experience, I've
submitted some edits to the FAQ page, which are currently pending
approval. I've pasted below this email my proposed version of the
relevant section, in case it is helpful for anyone to reference in the
short-term, with the caveat that it has not yet been endorsed by the
Claws Mail development team.

(I should note that I have not yet been able to receive a definitive
confirmation that this process has worked for me on my system, since I
am currently waiting to see if my email administrator will approve my
request to be given permission to give Claws Mail the access it needs
(see the final note in the FAQ section below for details). However, I
don't currently have any reason to think that things will not work as
expected if/when I get this approval from my email admin.)

Cheers,
Dustin

---------------------------------------------------
=== Setting up OAuth 2.0 for Microsoft - for Outlook or Exchange ===

Sign in to Microsoft account

Go to Azure Active Directory > App registrations

Direct link:
https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps

Choose "New Registration"

* Display name: Anything you choose
* Supported account types - set to "Accounts in any organizational
  directory… and personal Microsoft accounts…" (Note: This will be
  shown on the app’s ‘Authentication’ page.) (It will also be
  represented on the app's ‘Overview’ page as "All Microsoft account
  users".)
* Select a platform: "Public client/native..."
* Redirect URI:
  https://login.microsoftonline.com/common/oauth2/nativeclient

Once you've adjusted settings as desired, click on the 'Register'
button.

(Note: Creating a new registration will result in the auto-generation
of an application (client) ID, an object ID, and a directory (tenant)
ID, all of which will then be visible on the app’s ‘Overview’ page.)

Once app is registered you can configure it:

Quickstart page - Leave alone

Integration assistant page - Leave alone

Branding page - any entries you like

Authentication page - Confirm that the ‘redirect URI’ you set during
registration has its box checked. You can also add/delete redirect
URI’s on this page, as necessary.

Certificates & secrets page - No entries needed

Token configuration page - No entries needed

API permissions page - Add these:

Microsoft Graph:
  - IMAP.AccessAsUser.All
  - Mail.ReadWrite
  - Mail.Send
  - offline_access
  - POP.AccessAsUser.All
  - SMTP.Send

Expose an API page - No entries needed

Owners page - No entries needed

Manifest page - Leave at defaults

Once the app is configured, the Client ID (also called Application ID)
can be copied over to Claws Mail's custom Client ID field. (The Client
ID is shown on the app's 'Overview' page in Azure.) No Client Secret is
needed - leave that entry blank in Claws Mail's custom Client Secret
box.

Note: If you are using an email account managed by a third-party
organization using Microsoft’s email systems, then when you attempt to
get an authorization code you may see a screen that says something like
‘Approval Required’  //  ‘This app requires your admin’s approval...’.
This is likely because Claws Mail is not ‘published’ by a ‘verified
publisher’ or because for some other reason the organization has
decided to limit the apps to which users can give permissions. There
may be a field where you can enter justification for requesting this
app, after which you can click on ‘Request approval’. Then you may see
a notice that says the request has been sent to your ‘admin’ and that
you’ll receive an email in regards to whether it’s been approved or
not. You may want to reach out to your email administrator to see if
they got the request, to let them know it is a legitimate request from
you, and perhaps provide a link to the Claws Mail website and/or other
information about the ‘app’ for which you are wanting them to give you
consent permissions. (The above details may be different depending on
how the organization has configured their 'user consent' settings.)
Ultimately it will be up to the organization (rather than Microsoft or
yourself) as to whether you will be able to give Claws the access it
needs.
------------------------------------------------------------