Difference between revisions of "Oauth2"

From Claws Mail FAQ
Jump to navigationJump to search
m (Added section on OAuth2-related account settings in Claws. Revised trouble-shooting tip about dismissing Google's warning about giving Claws access to a Gmail account.)
m
 
(13 intermediate revisions by 6 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:
Line 12: Line 12:
  
  
=== Setting up OAuth 2.0 for Gmail ===  
+
== Setting up OAuth 2.0 for Gmail ==  
  
 
'''Follow the instructions here:'''
 
'''Follow the instructions here:'''
 
https://support.google.com/googleapi/answer/6158849
 
https://support.google.com/googleapi/answer/6158849
  
Note: Before starting, make sure that you are not logged in (via webmail) to any Gmail account, or that you are logged in to only the relevant account.
+
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:
 
When setting up the project use these settings:
 
<pre>  Project name: Anything of your choice
 
<pre>  Project name: Anything of your choice
  
   Publishing status (of project): 'Testing' (initial default)
+
   Publishing status (of project): 'In Production'
  
 
   User type: External
 
   User type: External
Line 32: Line 32:
 
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).
 
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", there isn't an option to choose this when you are creating a new project. It seems that the status will be considered as 'Testing' unless/until you have clicked on 'Publish App' in the 'Publishing status' section of the 'OAuth Consent Screen'; then it will be considered as being 'In Production'. (However, 'publishing' the app may require that it be submitted to Google for verification, which requires a variety of submissions that seem more relevant to the developers of an app for 'everyone' rather than for a user who is trying to set something up for themselves.) It is possible to get it working by using the 'Testing' status if you add the relevant 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). However, authorization with this status may only last for seven days. (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)
  
  
Line 59: Line 59:
 
   Click on 'Save and Continue'.
 
   Click on 'Save and Continue'.
 
</pre>
 
</pre>
'''Getting the ClientID'''
+
'''Getting the Client ID'''
 
<pre>
 
<pre>
 
   APIs and Services on the left menu, then Credentials entry
 
   APIs and Services on the left menu, then Credentials entry
  
   Copy the ClientID to the custom entry box on Claws Mail Oauth2 account preferences screen.
+
   Copy the Client ID to the corresponding field on Claws Mail's account settings' 'Oauth2' page.
  
   Select "Edit Oauth Credentials" (pencil icon), then copy the Client Secret to the entry in
+
   Select "Edit OAuth Credentials", then copy the Client Secret to the corresponding field on Claws Mail's account settings' 'Oauth2' page.
  Claws Mail Oauth2 account preferences screen.
 
 
</pre>
 
</pre>
 
'''Troubleshooting:'''
 
'''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.
+
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 ===
 
  
Sign in to microsoft account
+
== Setting up OAuth 2.0 for Microsoft - for Outlook or Exchange ==
  
Go to Azure Active Directory > App registrations
+
===== Step 1: Log in to Azure (Microsoft's cloud service) =====
  
Direct link: 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)
  
Choose "New Registration"
+
You can use the [https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps direct link] as well.
  
  Display name: Anything you choose
+
===== Step 2: Register Claws Mail as a new app =====
  Application (client) ID - will be auto generated
 
  Object ID - will be auto generated
 
  Directory (tenant) ID - will be auto generated
 
  Supported account types - set to "All Microsoft account users"
 
  
Once app is registered you can configure it:
+
* click <code>New registration</code> (in the top bar)
 +
* enter <code>Name</code> (e.g. <q>Claws Mail</q>)
 +
* 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)
  
Branding tab - any entries you like
+
===== Step 3: Configure the app =====
  
Authentication tab -
+
* click on <code>Authentication</code> (in the side menu)
  Redirect URI: https://login.microsoftonline.com/common/oauth2/nativeclient
+
* make sure the ''<q><nowiki>https://login.microsoftonline.com/common/oauth2/nativeclient</nowiki></q>'' is checked, and that the redirect URI is there
  Supported account types: "Accounts in any organizational directory (Any
+
* click on <code>API permissions</code> (in the side menu)
  Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)"
+
* 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
  
Certificates & secrets tab - No entries needed
+
* once all permissions are selected, click <code>Add permissions</code> button (at the bottom)
  
Token configuration - No entries needed
+
===== Step 4: Configure OAuth2 in Claws Mail =====
  
API permissions tab - Add these:
+
* 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
  
Microsoft Graph:
 
  - IMAP.AccessAsUser.All
 
  - Mail.ReadWrite
 
  - Mail.Send
 
  - offline_access
 
  - POP.AccessAsUser.All
 
  - SMTP.Send
 
  
Expose an API tab - No entries needed
+
===== Admin approval =====
  
Owners tab - No entries needed
+
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.
  
Manifest tab - Leave at defaults
+
===== References =====
  
Quickstart tab - Leave alone
+
[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
 
 
Integration assistant - Leave alone
 
 
 
Once configured the ClientID (also called Application ID) can be copied over to Claws Mail custom ClientID box. No Client Secret is needed - leave that entry blank in Claws Mail's custom Client Secret box.
 

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