Difference between revisions of "Oauth2"

From Claws Mail FAQ
Jump to navigationJump to search
m
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
__FORCETOC__
 
__FORCETOC__
 
  
 
== Claws Mail Account Settings for OAuth 2.0 ==
 
== Claws Mail Account Settings for OAuth 2.0 ==
  
 
When setting up an account with OAuth2, besides correctly filling out the 'OAuth2' page, you also need to make sure you have the correct settings on the 'Receive' and 'Send' pages:
 
When setting up an account with OAuth2, besides correctly filling out the 'OAuth2' page, you also need to make sure you have the correct settings on the 'Receive' and 'Send' pages:
<pre>
+
<pre>  'Receive' page (POP): Authenticate before POP connection: Authentication method = 'OAuth2'.
  'Receive' page (POP): Authenticate before POP connection: Authentication method = 'OAuth2'.
 
  
'Receive' page (IMAP): Authentication method = 'OAuth2'.
+
  'Receive' page (IMAP): Authentication method = 'OAuth2'.
  
'Send' page (POP / IMAP): SMTP Authentication: Authentication method = 'OAuth2'.
+
  'Send' page (POP / IMAP): SMTP Authentication: Authentication method = 'OAuth2'.
 
</pre>
 
</pre>
  
  
== Setting up OAuth 2.0 for Gmail ==
+
== Setting up OAuth 2.0 for Gmail ==  
  
'''There are some instructions here:'''https://support.google.com/googleapi/answer/6158849''' but the instructions below may be more helpful.'''
+
'''Follow the instructions here:'''
 +
https://support.google.com/googleapi/answer/6158849
  
 +
Note: If you use more than one Google/Gmail account, make sure you are signed in to Google Cloud Platform with the desired account before creating a project or changing any settings. (It is possible to be signed into multiple accounts; just make sure the browser tab/window you are working in is controlled by the correct account.)
  
=== Preamble ===
+
When setting up the project use these settings:
In order to use Gmail in Claws, you have to obtain OAuth2 credentials from Google.
+
<pre>  Project name: Anything of your choice
  
Getting these can appear quite complicated for the regular non-technical end user, but provided you follow the workflow carefully, it shouldn't take too long.
+
  Publishing status (of project): 'In Production'
  
Almost everything has to be done in the Google Cloud console, which is designed for software developers to use, so it can appear confusing to a non-technical end-user, and it can be easy to get lost in the multitude of screens and menus.
+
  User type: External
 
+
</pre>
 
+
'''Notes related to the above:'''
Google also have an unfortunate habit of rejigging their interfaces so that today's workflow might not be tomorrow's.
 
 
 
However the outline below worked in June 2022.
 
 
 
The critical thing is to follow the order of activities exactly. Trying to skip ahead or doing something incompletely & hoping to return later can cause problems.
 
 
 
 
 
The sequence of operations is:
 
 
 
# Setup Google Cloud Project
 
# Obtain credentials for your project
 
# Enter credentials into ClawsMail
 
# Authorise ClawsMail with Google
 
 
 
 
 
This sequence will have to be followed for '''each''' Gmail account that you want to use with ClawsMail.
 
 
 
=== Setting up your Google Cloud Project ===
 
 
 
You need to get into the Google Cloud Console, so go to '''https://console.cloud.google.com/projectselector2/apis/dashboard?supportedpurview=project'''
 
 
 
If you are already signed into the Google (Gmail) account that you want to set up OAuth2 for, you won't need to sign in.
 
 
 
If you aren't, sign in with the Google (Gmail) account for which you want to set up OAuth2.
 
 
 
Once signed in, you need to create a "Project" so that you can generate credentials.
 
 
 
So, click on "Create Project" on the right hand side of the screen.
 
 
 
(You can call it whatever you like, but if you're going to create more than one project & set of credentials, it might be helpful to use names that relate uniquely to each email address you are using.)
 
 
 
'''NB''' If you get into trouble or make mistakes that you can't rectify, you can simply delete the project & start again.
 
  
 +
1. If/when you create a new project, if it appears that the process has stalled, look in the top-right corner for a notification icon that you can click on and then select the relevant project. This should then open that project's dashboard so you can continue with the process. (As of 24 Mar 2022.)
  
'''FIRST'''
+
2. Regarding Google's above-linked instructions related to the "Credentials" page: Where it says "Click 'New Credentials'" it should read "Click '+ CREATE CREDENTIALS'" (as of 24 Mar 2022).
  
Select "Oauth Consent Screen"
+
3. Regarding "Publishing status", the initial default is 'Testing'. To change this to 'In Production' click on the 'Publish App' button in the 'Publishing status' section of the 'OAuth Consent Screen', and then click on 'Confirm'. This results in the status changing to ‘In Production’ and a new section ‘Verification Status’ showing with a ‘Needs verification’ status, which can be safely ignored. If this doesn't work for some reason, you can switch back to 'Testing' status on the same 'OAuth Consent Screen' page you used before. For this status to work you need to make sure you've added the desired email address to the 'Test Users' list on the 'Edit App Registration' - 'Test Users' page of the 'OAuth Consent Screen' setup process (or on the main 'OAuth Consent Screen' page). Note that with this status each authorization code will only last for seven days, after which you will be unable to connect and will see authorization errors in the network log. To get a new authorization code, go to the 'OAuth2' page of the Claws Mail settings and repeat the steps for getting an authorization code and completing authorization. (Note that there is no need to get a new client ID or client secret.) (as of 17 Apr 2022)
  
(you won't be able to create any credentials until you have done this step)
 
  
<pre>For "type", select "External" & click "CREATE".
+
'''OAuth consent screen settings:'''
 +
<pre> App name: Anything of your choice
  
You're now in "Edit app registration"
+
  User support email: Your own email
  
For "App name" you can enter whatever you like.
+
  Developer email: Your own email
(Again, it might be helpful to use names related to the email address you're doing this for.)
 
  
Ignore "App domain" fields, they can be left blank.
+
  App domain entries: Leave blank
 
 
In the "User Support Email" and "Developer Contact Email" fields enter the Gmail address for which you want to set up OAuth2 credentials.
 
 
 
Click "Save and Continue"
 
 
</pre>
 
</pre>
 +
'''Scopes settings:'''
 +
<pre>  Click on 'Add or Remove Scopes'.
  
 +
  Select (check the box) this entry: "Gmail API, https://mail.google.com/, Read, compose, send and
 +
      permanently delete all your email from Gmail"
  
'''NEXT'''
+
      (Note that the list is in alphabetical order and you may need to go to a later page to find this entry.
 
+
      Also, if you can't find it in the list, you can enter the URL manually at the bottom of the page to add it to the list.)
Select "add or remove scopes"
 
You need to select "Gmail" from the list (table) that opens on the RHS of the screen, but it might not appear.
 
 
 
<blockquote>
 
If it doesn't appear, you will need to paste
 
"https://mail.google.com/"
 
into the "manually add scopes" box,
 
 
 
then click "update table",
 
  
then click "update".
+
  Click on 'Update'.
</blockquote>
 
  
You should now see "GMAIL Scopes" under "Your restricted scopes"
+
  Confirm that the section 'Your restricted scopes' shows the entry you just added.
 
 
Click "save and continue"
 
 
 
 
 
'''NEXT'''
 
 
 
Click on '''"+ Add users"'''.  If you don't add yourself as a test user at this point the authorisation process that comes later will fail.
 
 
 
Once again, enter the email address that you want to access with Claws Mail.
 
 
 
Then click "back to dashboard", which should take you to the "OAuth Consent screen" page.
 
 
 
On this page you should see a heading of '''"Publishing status"''', under which it should now say '''"Testing"'''.
 
 
 
 
 
'''Do not be tempted to click "Publish App" at this point.'''
 
 
 
 
 
'''NEXT'''
 
 
 
You can now create the credentials you need to authorise ClawsMail to use your Gmail account.
 
 
 
<pre>
 
Click "Credentials", then "create credentials", and then "OAuth client ID".
 
 
 
For "Application Type" select "Desktop app".
 
 
 
You can either accept the default name offered, or, as before, enter something relating to the email account for which you're doing this.
 
 
 
Then click "Create"
 
  
 +
  Click on 'Save and Continue'.
 
</pre>
 
</pre>
 
+
'''Getting the Client ID'''
 
 
A popup box will show you the Client ID & Client Secret.
 
 
 
You need these to enter into ClawsMail, so copy them.
 
 
 
There is also an option to download them as a JSON file.
 
 
 
(This is convenient for the more technically minded user, but perhaps a bit insecure. If you do this, keep it somewhere safe)
 
 
 
 
 
=== Authorising Clawsmail with Google/Gmail ===
 
'''NEARLY FINALLY'''
 
 
 
Now that you have your credentials, you have to enter them into ClawsMail itself for your Gmail account.
 
 
 
Remember that you must also set the "Send" and "Receive" authentication method to "OAuth2" for your account in those screens.
 
 
 
You need to go to Configuration/Edit accounts & select and edit the account for which you've created the credentials.
 
 
 
 
<pre>
 
<pre>
Select "Oauth2".
+
  APIs and Services on the left menu, then Credentials entry
  
From the dropdown "Select OAuth2 Service Email Provider", select "Google/Gmail"
+
  Copy the Client ID to the corresponding field on Claws Mail's account settings' 'Oauth2' page.
  
You now need to copy into the "Client ID" and "Client Secret" boxes the credentials you copied in the previous step.
+
  Select "Edit OAuth Credentials", then copy the Client Secret to the corresponding field on Claws Mail's account settings' 'Oauth2' page.
 
 
Now click "Open default browser with request".
 
 
 
Gmail should launch in your browser, taking you to login screens with multiple warnings about how unsafe what you are doing is.
 
 
 
Don't "go back to safety", because what you're doing is safe.
 
 
 
Eventually you will get a screen offering you an authorisation code.
 
 
 
Copy this.
 
 
</pre>
 
</pre>
 +
'''Troubleshooting:'''
  
 
+
It's possible / probable that Gmail will 'complain' about giving access to an unverified third-party app. If this keeps you from using Claws to access your Gmail, you may need to log in to Gmail's web-mail interface and review / revise your security settings there. This may involve dismissing the warning Google gives about the Project that you set up for Claws to access GMail on your account. If you dismiss a Warning, Google may then ask you why you are dismissing it, providing several options, leaving you free to choose the one which seems most suitable (like trusting the app and its developer, as of 8 Jun 2022).
'''FINAL STEP'''
 
 
 
Now go back to the ClawsMail OAuth2 page that you launched the browser page from.
 
 
 
Paste in the code you copied from the Gmail screen in the previous step into the "Authorisation code" box, then click "Authorise" and "Apply".
 
 
 
 
 
Now see if you can fetch email from Gmail in Clawsmail.
 
 
 
 
 
=== Epilogue ===
 
 
 
Unfortunately, because neither your project nor ClawsMail are verified apps as far as Google is concerned, this is not quite the end of the story.
 
 
 
From now on, every 7 days after the initial authorisation, it will revert to unauthorised & ClawsMail won't be able to access you Gmail account.
 
 
 
Fortunately, you don't have to go through the whole process again, but just the final step:
 
 
 
Go to ClawsMail OAuth2 page, launch browser, get an authorisation code & then paste it back into the Authorisation code box & click authorise.
 
  
  
Line 193: Line 75:
 
== Setting up OAuth 2.0 for Microsoft - for Outlook or Exchange ==
 
== Setting up OAuth 2.0 for Microsoft - for Outlook or Exchange ==
  
'''Step 1: Get into 'Azure', Microsoft's cloud computing service.'''
+
===== Step 1: Log in to Azure (Microsoft's cloud service) =====
  
Go to https://portal.azure.com , making sure you are signed in with the Microsoft account you are wanting to set up. Go to 'Azure Active Directory' (click on the 'View' button under 'Manage Azure Active Directory') and then the 'App registrations' page (via the link in the side-pane). Here is a direct link to this page: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps .
+
* go to https://portal.azure.com and log in
 +
* click on <code>Azure Active Directory</code>
 +
* click on <code>App registrations</code> (in the side menu)
  
 +
You can use the [https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps direct link] as well.
  
'''Step 2: Register Claws Mail as a new app.'''
+
===== Step 2: Register Claws Mail as a new app =====
  
Click on 'New Registration' to get to the 'Register an application page', then adjust the settings as follows:
+
* click <code>New registration</code> (in the top bar)
<pre>
+
* enter <code>Name</code> (e.g. <q>Claws Mail</q>)
  Display name: Anything you choose.
+
* set <code>Supported account types</code> to the most premissive option: ''<q>Accounts in any organizational directory and personal Microsoft accounts</q>''
 +
* set <code>Redirect URI</code> to ''<q>Public client/native</q>'' and ''<q><nowiki>http://127.0.0.1:8888</nowiki></q>''
 +
* click <code>Register</code> button (at the bottom)
  
  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".)
+
===== Step 3: Configure the app =====
  
  Select a platform: "Public client/native..."
+
* click on <code>Authentication</code> (in the side menu)
 +
* make sure the ''<q><nowiki>https://login.microsoftonline.com/common/oauth2/nativeclient</nowiki></q>'' is checked, and that the redirect URI is there
 +
* click on <code>API permissions</code> (in the side menu)
 +
* click on <code>Add a permission -> Microsoft Graph -> Delegated permissions</code> and add the following permissions<br />(use the search box to filter the list, then tick the box next to a permission name to select it):
 +
- offline_access
 +
- SMTP.Send
 +
- IMAP.AccessAsUser.All
 +
- POP.AccessAsUser.All
 +
- Mail.ReadWrite
 +
- Mail.Send
 +
- User.Read
  
  Redirect URI: <nowiki>http://127.0.0.1:8888</nowiki>
+
* once all permissions are selected, click <code>Add permissions</code> button (at the bottom)
</pre>
 
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.)
+
===== Step 4: Configure OAuth2 in Claws Mail =====
  
 +
* choose <code>Service Provider</code> (e.g. <q>MS Exchange</q>) - ''TODO: explain the difference''
 +
* enter <code>Client ID</code> (called <code>Application ID</code> in Azure - shown at app <code>Overview</code> page)
 +
* leave <code>Secret</code> field empty
 +
* click <code>Copy link</code> button and open the request in your browser (you will be asked to authenticate)
 +
* copy the full URL you were redirected to into the <code>Authorisation code</code> field<br>(it will be something like <nowiki>https://login/microsoftonline.com/common/oauth2/nativeclient#code=0.AQIjdkSjkD...&session_state=e7cd...</nowiki> )
 +
* click <code>Authorise</code> button
  
'''Step 3: Configure the Claws Mail app.'''
 
  
The various configuration pages can be accessed via the links in the side-pane. Nothing needs to be changed on the following pages:
+
===== Admin approval =====
<pre>
 
Quickstart
 
Integration assistant
 
Branding
 
Certificates & secrets
 
Token configuration
 
Expose an API
 
Owners
 
Manifest
 
</pre>
 
  
Check/adjust settings on the following pages:
+
If your email account is managed by a third-party organisation, the attempt to get authorization code will likely fail. You need to '''ask your admin''' to approve the usage of the registered app and grant the API permissions in the organisation tenancy. Sometimes you will see a form where you can enter justification for the approval and request it with a simple button click. However, most of the time, you will need to contact your '''IT support''' on your own. In such a situation, provide a link to the registered app and some basic information about Claws Mail.
<pre>
 
'Authentication' - 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.
 
  
'API permissions' - Click on 'Add a permission' > 'Microsoft Graph' > 'Delegated permissions', and add the following permissions. First, select each permission by typing some/all of its name in the search/filter box to narrow the results, expanding categories as needed, and clicking on the box beside the permission so that a check mark shows. Once you've selected all the permissions, click on the 'Add permissions' button to add them all at the same time. Any permissions that have been successfully added will now show up in the 'Configured permissions' list on the 'API permissions' page.
+
===== References =====
  - IMAP.AccessAsUser.All
 
  - Mail.ReadWrite
 
  - Mail.Send
 
  - offline_access
 
  - POP.AccessAsUser.All
 
  - SMTP.Send
 
  - User.Read
 
</pre>
 
Once the Claws Mail app is configured, the Client ID (also called Application ID) can be copied to Claws Mail's corresponding Client ID field. (The Client ID is shown on the app's 'Overview' page in Azure.) No Client Secret is needed, so Claws Mail's Client Secret field should be empty.
 
  
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.
+
[https://docs.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth Authenticate an IMAP, POP or SMTP connection using OAuth] - documentation from Microsoft

Latest revision as of 18:05, 24 July 2022


Claws Mail Account Settings for OAuth 2.0

When setting up an account with OAuth2, besides correctly filling out the 'OAuth2' page, you also need to make sure you have the correct settings on the 'Receive' and 'Send' pages:

  'Receive' page (POP): Authenticate before POP connection: Authentication method = 'OAuth2'.

  'Receive' page (IMAP): Authentication method = 'OAuth2'.

  'Send' page (POP / IMAP): SMTP Authentication: Authentication method = 'OAuth2'.


Setting up OAuth 2.0 for Gmail

Follow the instructions here: https://support.google.com/googleapi/answer/6158849

Note: If you use more than one Google/Gmail account, make sure you are signed in to Google Cloud Platform with the desired account before creating a project or changing any settings. (It is possible to be signed into multiple accounts; just make sure the browser tab/window you are working in is controlled by the correct account.)

When setting up the project use these settings:

  Project name: Anything of your choice

  Publishing status (of project): 'In Production'

  User type: External

Notes related to the above:

1. If/when you create a new project, if it appears that the process has stalled, look in the top-right corner for a notification icon that you can click on and then select the relevant project. This should then open that project's dashboard so you can continue with the process. (As of 24 Mar 2022.)

2. Regarding Google's above-linked instructions related to the "Credentials" page: Where it says "Click 'New Credentials'" it should read "Click '+ CREATE CREDENTIALS'" (as of 24 Mar 2022).

3. Regarding "Publishing status", the initial default is 'Testing'. To change this to 'In Production' click on the 'Publish App' button in the 'Publishing status' section of the 'OAuth Consent Screen', and then click on 'Confirm'. This results in the status changing to ‘In Production’ and a new section ‘Verification Status’ showing with a ‘Needs verification’ status, which can be safely ignored. If this doesn't work for some reason, you can switch back to 'Testing' status on the same 'OAuth Consent Screen' page you used before. For this status to work you need to make sure you've added the desired email address to the 'Test Users' list on the 'Edit App Registration' - 'Test Users' page of the 'OAuth Consent Screen' setup process (or on the main 'OAuth Consent Screen' page). Note that with this status each authorization code will only last for seven days, after which you will be unable to connect and will see authorization errors in the network log. To get a new authorization code, go to the 'OAuth2' page of the Claws Mail settings and repeat the steps for getting an authorization code and completing authorization. (Note that there is no need to get a new client ID or client secret.) (as of 17 Apr 2022)


OAuth consent screen settings:

  App name: Anything of your choice

  User support email: Your own email

  Developer email: Your own email

  App domain entries: Leave blank

Scopes settings:

  Click on 'Add or Remove Scopes'.

  Select (check the box) this entry: "Gmail API, https://mail.google.com/, Read, compose, send and
      permanently delete all your email from Gmail"

      (Note that the list is in alphabetical order and you may need to go to a later page to find this entry.
       Also, if you can't find it in the list, you can enter the URL manually at the bottom of the page to add it to the list.)

  Click on 'Update'.

  Confirm that the section 'Your restricted scopes' shows the entry you just added.

  Click on 'Save and Continue'.

Getting the Client ID

  APIs and Services on the left menu, then Credentials entry

  Copy the Client ID to the corresponding field on Claws Mail's account settings' 'Oauth2' page.

  Select "Edit OAuth Credentials", then copy the Client Secret to the corresponding field on Claws Mail's account settings' 'Oauth2' page.

Troubleshooting:

It's possible / probable that Gmail will 'complain' about giving access to an unverified third-party app. If this keeps you from using Claws to access your Gmail, you may need to log in to Gmail's web-mail interface and review / revise your security settings there. This may involve dismissing the warning Google gives about the Project that you set up for Claws to access GMail on your account. If you dismiss a Warning, Google may then ask you why you are dismissing it, providing several options, leaving you free to choose the one which seems most suitable (like trusting the app and its developer, as of 8 Jun 2022).


Setting up OAuth 2.0 for Microsoft - for Outlook or Exchange

Step 1: Log in to Azure (Microsoft's cloud service)

You can use the direct link as well.

Step 2: Register Claws Mail as a new app
  • click New registration (in the top bar)
  • enter Name (e.g. Claws Mail)
  • set Supported account types to the most premissive option: Accounts in any organizational directory and personal Microsoft accounts
  • set Redirect URI to Public client/native and http://127.0.0.1:8888
  • click Register button (at the bottom)
Step 3: Configure the app
  • click on Authentication (in the side menu)
  • make sure the https://login.microsoftonline.com/common/oauth2/nativeclient is checked, and that the redirect URI is there
  • click on API permissions (in the side menu)
  • click on Add a permission -> Microsoft Graph -> Delegated permissions and add the following permissions
    (use the search box to filter the list, then tick the box next to a permission name to select it):
- offline_access
- SMTP.Send
- IMAP.AccessAsUser.All
- POP.AccessAsUser.All
- Mail.ReadWrite
- Mail.Send
- User.Read
  • once all permissions are selected, click Add permissions button (at the bottom)
Step 4: Configure OAuth2 in Claws Mail
  • choose Service Provider (e.g. MS Exchange) - TODO: explain the difference
  • enter Client ID (called Application ID in Azure - shown at app Overview page)
  • leave Secret field empty
  • click Copy link button and open the request in your browser (you will be asked to authenticate)
  • copy the full URL you were redirected to into the Authorisation code field
    (it will be something like https://login/microsoftonline.com/common/oauth2/nativeclient#code=0.AQIjdkSjkD...&session_state=e7cd... )
  • click Authorise button


Admin approval

If your email account is managed by a third-party organisation, the attempt to get authorization code will likely fail. You need to ask your admin to approve the usage of the registered app and grant the API permissions in the organisation tenancy. Sometimes you will see a form where you can enter justification for the approval and request it with a simple button click. However, most of the time, you will need to contact your IT support on your own. In such a situation, provide a link to the registered app and some basic information about Claws Mail.

References

Authenticate an IMAP, POP or SMTP connection using OAuth - documentation from Microsoft