FAQ ICS Email and OAuth2

From Overbyte
Jump to navigation Jump to search

In June 2022 Google stopped accepting traditional authentication methods for it's SMTP and POP3 email servers, instead requiring OAuth2, and I believe Microsoft is doing the same from October 2022.

The main different with OAuth2 is the application does not store the account password so is unable to share it. Instead the user is directed to a sign-in web page from Google or Microsoft where the account details are entered and the application receives limited life tokens that are used instead of the password. For this to work, the developer needs an application account at Google or Microsoft to obtain a application client ID and secret, which need to saved securely and sent as part of the OAuth2 sign-in. In theory, Google and Microsoft need to approve applications using the account client details, and will give warnings during sign-in after a grace period.

If sign-in works, the application receives an access token usually with a life of a few hours, and a refresh token that may be stored securely like a password and may have a life of several months and which may be used to obtain a new access token without a new sign-in. Note the refresh token may be cancelled at any time requiring a new sign-in. The refresh token may also be shared between different applications using the same client details and email account, for instance with servers where interaction is not possible.

ICS added support for OAuth2 with version V8.65 in November 2020 to the TSslSmtpCli, TSslPop3Cli and TIcsMailQueue email components, by adding the TIcsRestEmail component to projects with some extra code, as illustrated in the samples OverbyteIcsMailQuTst, OverbyteIcsSslMailSnd and OverbyteIcsSslMailRcv.

But the ICS server samples using email were not updated at the time, so have now been done for the forthcoming V8.70 release which is available from SVN and the overnight zip, OverbyteIcsSslMultiWebServ, OverbyteIcsDDWebService and OverbyteIcsSslMultiFtpServ.

Since other developers may similarly need to add OAuth2 support for email applications, this is a quick guide.

  1. For the TSslSmtpCli, TSslPop3Cli or TIcsMailQueue component, add an onOATokenEvent handler.
  2. Drop a TIcsRestEmail component named IcsRestEmail and add onEmailNewTokenEvent and onEmailProgEvent handlers. The LoginTimeout property defines how long the component will wait for an interactive browser OAuth2 login, if necessary, defaulting to 30 seconds. If this happens the onEmailNewTokenEvent is called allowing the application to save the new refresh token to avoid further interaction.
  3. In the onOATokenEvent event, call the IcsRestEmail.GetNewToken method and set the handler properties Token, TokExpireDT and TokAccount, see any of the samples.
  4. Set the IcsRestEmail component properties RestEmailType, ClientId, ClientSecret, and RefrToken, there is a function IcsLoadRestEmailFromIni that does this from an INI file for the server samples (without encryption).
  5. Set SMTP AuthType to smtpAuthXOAuth2 or POP3 AuthType to popAuthXOAuth2 with the appropriate host. This causes onOATokenEvent to be called when an access token is needed.