Using OAuth for authentication to connect with SMTP, IMAP, and POP3

Requirements: IPWorks

Our SMTP based components (SMTP, FileMailer, HTMLMailer) as well as our IMAP and POP components can use OAuth as a form of Authentication.

Contents

OAuth Authentication

Some environments may require authentication using OAuth when connecting via SMTP, IMAP, or POP. For instance, this is required when connecting to Gmail or Office365. The OAuth component can be used to obtain an authorization string for use with OAuth in SMTP, IMAP, or POP. The current version of the OAuth component implements OAuth 2.0.

Refresh Tokens

Refresh Tokens (sometimes referred to as offline tokens) are used to refresh access tokens to reduce the amount of user interaction. Typically, these refresh tokens are saved after the initial login and are used until the are expired so the user only has to log in the first time. The expiration date and if a new refresh token can be retrieved using a refresh token varies depending on the service provider. For example, Gmail's refresh token only expires if it has not been used for 5 months, if the login information had changed, or if the scopes have changed. On the other hand, Office365's tokens expire after 90 days but a new refresh token is supplied upon each use.

Sometimes, an additional scope will need to be added to the AuthorizationScope property for the RefreshToken property to be populated on the initial authorization request. For example, Office365 requires the additional "offline_access" scope while Google does not. The refresh token value will then need to be saved somewhere safe. Storing the refresh token in an un-secure way can lead to security risks. When the time comes to authenticate then, set the RefreshToken property with the value previously saved before calling GetAuthorization. As a note, in the case of Office365, the RefreshToken property will then be overwritten with the new refresh token.

GMail

Authenticating with IMAP:

//Getting an authorization string
oauth.ClientId = "CLIENT_ID";
oauth.ClientSecret = "CLIENT_SECRET";
oauth.ServerAuthURL = "https://accounts.google.com/o/oauth2/auth";
oauth.ServerTokenURL = "https://accounts.google.com/o/oauth2/token";
oauth.RefreshToken = ""; //Input value from previous run if saved
oauth.AuthorizationScope = "https://mail.google.com/";
string authorization = oauth.GetAuthorization();
string refreshToken = oauth.RefreshToken; //Save for later


//Setting Gmail server settings
imap.MailServer = "imap.gmail.com";
imap.User = "test@email.com";
imap.SSLStartMode = IPWorks.ImapSSLStartModes.sslImplicit;
imap.MailPort = 993;
 
//Authenticating using XOAuth2
imap.AuthMechanism = IPWorks.ImapAuthMechanisms.amXOAUTH2;
imap.Config("AuthorizationIdentity=" + authorization);
imap.Connect();
//Additional code here
imap.Disconnect();

Authenticating with SMTP:

//Getting an authorization string
oauth.ClientId = "CLIENT_ID;
oauth.ClientSecret = "CLIENT_SECRET";
oauth.ServerAuthURL = "https://accounts.google.com/o/oauth2/auth";
oauth.ServerTokenURL = "https://accounts.google.com/o/oauth2/token";
oauth.RefreshToken = ""; //Input value from previous run if saved
oauth.AuthorizationScope = "https://mail.google.com/";
string authorization = oauth.GetAuthorization();
string refreshToken = oauth.RefreshToken; //Save for later
 
//Setting Gmail server settings
smtp.User = "test@email.com";
smtp.From = "test@email.com";
smtp.SendTo = "test@email.com";
smtp.Subject = "Test";
smtp.Message = "Hello, this is a test";
smtp.MailServer = "smtp.gmail.com";
 
//Authenticating using XOAuth2
smtp.AuthMechanism = IPWorks.HtmlmailerAuthMechanisms.amXOAUTH2;
smtp.Config("AuthorizationIdentity=" + authorization);
smtp.Message = "Test Mail";
smtp.Connect();
smtp.Send();
smtp.Disconnect();

Authenticating with POP:

//Getting an authorization string
oauth.ClientId = "CLIENT_ID";
oauth.ClientSecret = "CLIENT_SECRET";
oauth.ServerAuthURL = "https://accounts.google.com/o/oauth2/auth";
oauth.ServerTokenURL = "https://accounts.google.com/o/oauth2/token";
oauth.RefreshToken = ""; //Input value from previous run if saved
oauth.AuthorizationScope = "https://mail.google.com/";
string authorization = oauth.GetAuthorization();
string refreshToken = oauth.RefreshToken; //Save for later

//Setting Gmail server settings
pop.MailServer = "pop.gmail.com";
pop.User = "test@email.com";
pop.SSLStartMode = IPWorks.ImapSSLStartModes.sslImplicit;
pop.MailPort = 993;
 
//Authenticating using XOAuth2
pop.AuthMechanism = IPWorks.ImapAuthMechanisms.amXOAUTH2;
pop.Config("AuthorizationIdentity=" + authorization);
pop.Connect();
//Additional code here
pop.Disconnect();

Office365

Authenticating with IMAP:

//Getting an authorization string
oauth.ClientId = "CLIENT_ID";
oauth.ClientSecret = "CLIENT_SECRET";
oauth.ServerAuthURL = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize";
oauth.ServerTokenURL = "https://login.microsoftonline.com/common/oauth2/v2.0/token";
oauth.RefreshToken = ""; //Input value from previous run if saved
oauth.AuthorizationScope = "https://outlook.office.com/IMAP.AccessAsUser.All offline_access";
string authorization = oauth.GetAuthorization();
string refreshToken = oauth.RefreshToken; //Save for later

//Setting Office365 server settings
imap.MailServer = "outlook.office365.com";
imap.User = "test@email.com";
imap.SSLStartMode = IPWorks.ImapSSLStartModes.sslImplicit;
imap.MailPort = 993;
 
//Authenticating using XOAuth2
imap.AuthMechanism = IPWorks.ImapAuthMechanisms.amXOAUTH2;
imap.Config("AuthorizationIdentity=" + authorization);
imap.Connect();
//Additional code here
imap.Disconnect();

Authenticating with SMTP:

oauth.ClientId = "CLIENT_ID";
oauth.ClientSecret = "CLIENT_SECRET";
oauth.ServerAuthURL = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize";
oauth.ServerTokenURL = "https://login.microsoftonline.com/common/oauth2/v2.0/token";
oauth.RefreshToken = ""; //Input value from previous run if saved
oauth.AuthorizationScope = "https://outlook.office.com/SMTP.Send offline_access";
oauth.GrantType = OauthGrantTypes.ogtAuthorizationCode;
string refreshToken = oauth.RefreshToken; //Save for later

//Setting Office365 server settings
smtp.User = "test@email.com";
smtp.From = "test@email.com";
smtp.SendTo = "test@email.com";
smtp.Subject = "Test";
smtp.Message = "Hello, this is a test";
smtp.MailServer = "smtp.office365.com";
smtp.MailPort = 587;

smtp.AuthMechanism = SmtpAuthMechanisms.amXOAUTH2;
smtp.Config("AuthorizationIdentity=" + oauth.GetAuthorization());           
smtp.SSLStartMode = SmtpSSLStartModes.sslExplicit;

smtp.Connect();
smtp.Send();
smtp.Disconnect();

Authenticating with POP:

//Getting an authorization string
oauth.ClientId = "CLIENT_ID";
oauth.ClientSecret = "CLIENT_SECRET";
oauth.ServerAuthURL = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize";
oauth.ServerTokenURL = "https://login.microsoftonline.com/common/oauth2/v2.0/token";
oauth.RefreshToken = ""; //Input value from previous run if saved
oauth.AuthorizationScope = "https://outlook.office.com/POP.AccessAsUser.All offline_access";
string authorization = oauth.GetAuthorization();
string refreshToken = oauth.RefreshToken; //Save for later

//Setting Office365 server settings
pop.MailServer = "outlook.office365.com";
pop.User = "test@email.com";
pop.SSLStartMode = IPWorks.PopSSLStartModes.sslImplicit;
pop.MailPort = 995;
 
//Authenticating using XOAuth2
pop.AuthMechanism = IPWorks.PopAuthMechanisms.amXOAUTH2;
pop.Config("AuthorizationIdentity=" + authorization);
pop.Connect();
//Additional code here
pop.Disconnect();

We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.