How can we help?

AxEmail.OAuth2

Introduction

Skip to properties and methods

OAuth2 or ‘Modern Authentication’ as it’s called by Microsoft is a modular approach to authentication. With OAuth2 the different parties involved are clearly separated from each other.

The Auron E-mail OAuth2 component focuses on desktop software authentication flows.

A high-level overview

Consider the case of accessing a GMail account. OAuth2 knows these parties:

  • The resource owner – e.g. You
  • The resource – e.g. Your mailbox
  • The authorizing party – e.g. Google
  • The application that needs access – e.g. Your e-mail application

Using OAuth2 your application:

  1. Directs the users to the google login page
  2. Google uses your ‘client id’ and ‘client secret’ to show information about your application to the user
  3. Your application waits for the user to sign-in and confirm the permissions you request
  4. Google sends a bearer token to your application
  5. Your application uses the bearer token to log into the e-mail
  6. If the bearer token expires your application can use the refresh token to refresh the bearer token

OAuth2 knows multiple authorization flows. The Auron E-mail Component implements two of them:

  • Authorization Code Flow: The user logs in with name and password.
  • Device Code Flow: The user types in a user-code it has received from your application.

You can find detailed descriptions on how to setup client IDs for
Google and Microsoft services in the FAQ section of our knowledgebase.

Authorization code flow – Example

With the authorization code flow you can login with the authorizing party immediately.

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' Component info
WScript.Echo "Auron Email Component " & objOAuth2.Version
WScript.Echo "Build: " & objOAuth2.Build & vbCrLf & "Module: " & objOAuth2.Module
WScript.Echo "License Status: " & objOAuth2.LicenseStatus & vbCrLf _
  & "License Key: " & objOAuth2.LicenseKey & vbCrLf

' Set Logfile
objOAuth2.LogFile = "OAuth2.log"

' Set OAuth parameters
objOAuth2.Flow = objConstants.OAUTH2_FLOW_AUTHCODE
objOAuth2.ClientID = "" ' TODO: Enter your client id
objOAuth2.ClientSecret = "" ' TODO: Enter your client secret
objOAuth2.RedirectUrl = "http://localhost:7999/oauth2test/"
objOAuth2.Scope = "https://mail.google.com/"
objOAuth2.AuthCodeUrl = "https://accounts.google.com/o/oauth2/v2/auth"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

' Collect device and usercode and show the login page
objOAuth2.Login
WScript.Echo "Login result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Wait for the user to login
objOAuth2.WaitForTokens(90000)
WScript.Echo "WaitForTokens result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Display the bearer and refresh tokens. 
' The bearer token needs to be passed to the SMTP, IMAP or POP object.
WScript.Echo
WScript.Echo "Bearer token: " & objOAuth2.BearerToken
WScript.Echo "Refresh token: " & objOAuth2.RefreshToken
WScript.Echo "Bearer timeout: " & objOAuth2.BearerExpInSeconds & " seconds"
How to run this example

Device code flow – Example

This flow uses a ‘User Code’ that the user needs to enter instead of logging in directly.

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' Component info
WScript.Echo "Auron Email Component " & objOAuth2.Version
WScript.Echo "Build: " & objOAuth2.Build & vbCrLf & "Module: " & objOAuth2.Module
WScript.Echo "License Status: " & objOAuth2.LicenseStatus & vbCrLf _ 
  & "License Key: " & objOAuth2.LicenseKey & vbCrLf

' Set Logfile
objOAuth2.LogFile = "OAuth2.log"

' Set OAuth2 parameters
objOAuth2.Flow = objConstants.OAUTH2_FLOW_DEVICECODE
objOAuth2.ClientID = "" ' TODO: Enter your client id
objOAuth2.ClientSecret = "" ' TODO: Leave empty when using Microsoft device code flow
objOAuth2.Scope = "offline_access https://outlook.office.com/IMAP.AccessAsUser.All"
objOAuth2.DeviceCodeUrl = "https://login.microsoftonline.com/common/oauth2/v2.0/devicecode"
objOAuth2.TokenExchangeUrl = "https://login.microsoftonline.com/common/oauth2/v2.0/token"

' Collect device and usercode and show the login page
objOAuth2.Login
WScript.Echo "Login result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

WScript.Echo "Please enter user code: [" & objOAuth2.UserCode & "]"
WScript.Echo

' Wait for the user to enter the usercode.
objOAuth2.WaitForTokens(objOAuth2.UserCodeExpInSeconds * 1000)
WScript.Echo "WaitForTokens result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Display the bearer and refresh tokens. The bearer token needs to be passed to the 
' SMTP, IMAP or POP object.
WScript.Echo
WScript.Echo "Bearer token: " & objOAuth2.BearerToken
WScript.Echo "Refresh token: " & objOAuth2.RefreshToken
WScript.Echo "Bearer timeout: " & objOAuth2.BearerExpInSeconds & " seconds"
How to run this example

Properties and Methods

Property Type Read/Write Description
Version String Read Version number of the Auron Email Component
Build String Read Build number of the Auron Email Component
Module String Read Module name of the Auron Email Component
LicenseStatus String Read License Status
LicenseKey String Read/Write License Key
LastError Number Read Result of the last called method
LogFile String Read/Write The path to a logfile which can be used for troubleshooting
Flow Integer Read/Write The authorization flow
AuthCodeUrl String Read/Write Authorization code URL
DeviceCodeUrl String Read/Write The device code URL
TokenExchangeUrl String Read/Write The token exchange URL
RedirectUrl String Read/Write The redirect URL
VerificationUrl String Read/Write The verification URL
ClientID String Read/Write Your client ID
ClientSecret String Read/Write Your client secret
Scope String Read/Write Resource scope to access
SuccessHtml String Read/Write Show when Authorization code flow was successful
ErrorHtml String Read/Write Show when Authorization code flow failed
AutoOpenBrowser Boolean Read/Write Automatically open the browser
LoginUrl String Read Resulting login URL
DeviceCode String Read Device code
UserCode String Read User code
UserCodeMessage String Read User code message
BearerToken String Read Bearer token
RefreshToken String Read Refresh token
BearerTokenExpInSeconds Number Read Bearer token expiration timeout in seconds
UserCodeExpInSeconds Number Read User code expiration time in seconds
PollIntervalInSeconds Number Read Poll interval in seconds
ResultScope String Read Resulting scope
LastResponse String Read Last HTTP response
ResultError String Read Last response error
ResultErrorDescription String Read Last response error description
ProxyServer String Read/Write ProxyServer URL if required
ProxyAccount String Read/Write Proxy login account if required
ProxyPassword String Read/Write Proxy password if required

Method Description
Clear Reset all properties to their default values
SaveLicenseKey Save the License Key in the registry
GetErrorDescription Get the description of the given error
Sleep Sleep for the specified number of milliseconds
Login Start OAuth2 authorization
WaitForTokens Continue OAuth2 authorization
RefreshBearerToken Exchange the refresh token for a new bearer token

Version property

Return the version number of the Auron Email Component

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Wscript.Echo "Auron Email Component Version"  & objOAuth2.Version & "; Build"  & _
  objOAuth2.Build & "; Module"  & objOAuth2.Module
WScript.Echo "License Status:"  & objOAuth2.LicenseStatus & vbCrLf
...

Build property

Return the build number of the Auron Email Component.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Wscript.Echo "Auron Email Component Version"  & objOAuth2.Version & "; Build"  & _
  objOAuth2.Build & "; Module"  & objOAuth2.Module
WScript.Echo "License Status:"  & objOAuth2.LicenseStatus & vbCrLf
...

Module property

Return the module name of the Auron Email Component.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Wscript.Echo "Auron Email Component Version"  & objOAuth2.Version & "; Build"  & _
  objOAuth2.Build & "; Module"  & objOAuth2.Module
WScript.Echo "License Status:"  & objOAuth2.LicenseStatus & vbCrLf
...

LicenseStatus property

The status of your license. In case you have not licensed the product, the property holds the trial expiration date.
For details, see Product Activation.

Example:

Set objOAuth2 = CreateObject("AxEmail.OAuth2")                 ' Create new instance
WScript.Echo "License Status:"  & objOAuth2.LicenseStatus
WScript.Echo "License Key:"  & objOAuth2.LicenseKey

LicenseKey property

A license key is required to unlock this component after the trial period has expired. Assign the LicenseKey property every time a new instance of this component is created (see code below). Alternatively, the LicenseKey property can be set automatically. This requires the license key to be stored in the registry. For details, see Product Activation.

Example:

Set objOAuth2 = CreateObject("AxEmail.OAuth2")                 ' Create new instance
objOAuth2.LicenseKey = "XXXXX-XXXXX-XXXXX"                ' Assign your license key 
WScript.Echo "LicenseKey:"  & objOAuth2.LicenseKey

LastError property

Completion code of the last called function. To find the error description of a given error code, go to the online error codes page.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
...  
' Refresh bearer tokens
objOAuth2.RefreshBearerToken
If objOAuth2.LastError <> 0 Then
  WScript.Echo "Error:"  & objOAuth2.GetErrorDescription(objOAuth2.LastError)    
End If
...

LogFile property

By default, LogFile holds an empty string and nothing is logged. If a valid file name is assigned to it, the Auron Email Component will write debug information to this file. Output data is written at the end of the file, the file is not cleared.

By default the log file uses the UTF16LE character encoding. To use UTF8 please prefix the log file name with the text: ‘UTF8:’ (e.g.: ‘UTF8:logfile.txt’).

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
objOAuth2.LogFile = "C:\temp\log.txt"
objOAuth2.Connect "smtp.example.com", "me@example.com", "password"
...

Flow property

This is the authorization flow. Please use one of these constants.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' ...

objOAuth2.Flow = objConstants.OAUTH2_FLOW_AUTHCODE
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.RedirectUrl = "http://localhost:7999/oauth2test/"
objOAuth2.Scope = "https://mail.google.com/"
objOAuth2.AuthCodeUrl = "https://accounts.google.com/o/oauth2/v2/auth"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

' ...

AuthCodeUrl property

The base URL to direct the user to the login URL and obtain an authorization code.

This URL only applies when using the ‘Authorization code flow’.

Find this URL in the documentation of the authorization service. Don’t include URL parameters.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' ...

objOAuth2.Flow = objConstants.OAUTH2_FLOW_AUTHCODE
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.RedirectUrl = "http://localhost:7999/oauth2test/"
objOAuth2.Scope = "https://mail.google.com/"
objOAuth2.AuthCodeUrl = "https://accounts.google.com/o/oauth2/v2/auth"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

' ...

DeviceCodeUrl property

The base URL to receive a user code and device code from.

This URL only applies when using the ‘Device code flow’.

Find this URL in the documentation of the authorization service. Don’t include URL parameters.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' ...

objOAuth2.Flow = objConstants.OAUTH2_FLOW_DEVICECODE
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.Scope = "https://mail.google.com/"
objOAuth2.DeviceCodeUrl = "https://oauth2.googleapis.com/device/code"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

' ...

TokenExchangeUrl property

The base URL for token exchange. The OAuth component will use this URL to exchange an authorization code for the bearer and refresh tokens.

Find this URL in the documentation of the authorization service. Don’t include URL parameters.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' ...

objOAuth2.Flow = objConstants.OAUTH2_FLOW_AUTHCODE
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.RedirectUrl = "http://localhost:7999/oauth2test/"
objOAuth2.Scope = "https://mail.google.com/"
objOAuth2.AuthCodeUrl = "https://accounts.google.com/o/oauth2/v2/auth"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

' ...

RedirectUrl property

This is the local URL that the login page should redirect to.

This only applies when using the authorization code flow.

Please make sure this URL is registered with your authentication service.

Either use a localhost URL with a port number > 1024 or make sure that the URL is properly configured using the ‘NetSh http’ command.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' ...

objOAuth2.Flow = objConstants.OAUTH2_FLOW_AUTHCODE
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.RedirectUrl = "http://localhost:7999/oauth2test/"
objOAuth2.Scope = "https://mail.google.com/"
objOAuth2.AuthCodeUrl = "https://accounts.google.com/o/oauth2/v2/auth"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

' ...

VerificationUrl property

This URL is set by the OAuth2 component to the URL that the user should navigate to so they can enter the ‘User Code’.

This only applies to the ‘device code flow’.

If ‘AutoOpenBrowser’ is set then the OAuth2 component will navigate there automatically after calling
‘Login’.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' ...
objOAuth2.Flow = objConstants.OAUTH2_FLOW_DEVICECODE
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.Scope = "https://mail.google.com/"
objOAuth2.DeviceCodeUrl = "https://oauth2.googleapis.com/device/code"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

objOAuth2.Login
If objOAuth2.LastError = 0 Then
  WScript.Echo "Please navigate to: " & objOAuth2.VerificationUrl
  WScript.Echo "Please enter: " & objOAuth2.UserCode
End If

' ...

ClientID property

This is the client ID of your application.

To use OAuth2 your application needs to be registered with the authorizing party (e.g. Microsoft or Google). With registration you’ll receive a Client ID and sometimes a Client Secret.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' ...
objOAuth2.Flow = objConstants.OAUTH2_FLOW_DEVICECODE
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.Scope = "https://mail.google.com/"
objOAuth2.DeviceCodeUrl = "https://oauth2.googleapis.com/device/code"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

objOAuth2.Login
If objOAuth2.LastError = 0 Then
  WScript.Echo "Please navigate to: " & objOAuth2.VerificationUrl
  WScript.Echo "Please enter: " & objOAuth2.UserCode
End If

' ...

ClientSecret property

This is the client secret of your application.

To use OAuth2 your application needs to be registered with the authorizing party (e.g. Microsoft or Google). With registration you’ll receive a Client ID and sometimes a Client Secret.

NOTE: If a third party knows your client secret they can impersonate your application to an end-user. This is why the client-secret needs to be kept a secret.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' ...
objOAuth2.Flow = objConstants.OAUTH2_FLOW_DEVICECODE
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.Scope = "https://mail.google.com/"
objOAuth2.DeviceCodeUrl = "https://oauth2.googleapis.com/device/code"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

objOAuth2.Login
If objOAuth2.LastError = 0 Then
  WScript.Echo "Please navigate to: " & objOAuth2.VerificationUrl
  WScript.Echo "Please enter: " & objOAuth2.UserCode
End If

' ...

Scope property

The property is a space separated list of resources that need to be accessed.

Once login and token exchange is completed find the resulting scope in
ResultScope.

Some common scope values to use:

Scope Authorizing party Description
https://mail.google.com/ Google Access GMail through POP3, SMTP and IMAP; Authorization code flow
email Google Access GMail through POP3, SMTP and IMAP; Device code flow
offline_access https://outlook.office.com/SMTP.Send Microsoft Access MS Exchange through SMTP
offline_access https://outlook.office.com/POP.AccessAsUser.All Microsoft Access MS Exchange through POP3
offline_access https://outlook.office.com/IMAP.AccessAsUser.All Microsoft Access MS Exchange through IMAP

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' ...
objOAuth2.Flow = objConstants.OAUTH2_FLOW_DEVICECODE
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.Scope = "email"
objOAuth2.DeviceCodeUrl = "https://oauth2.googleapis.com/device/code"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

objOAuth2.Login
If objOAuth2.LastError = 0 Then
  WScript.Echo "Please navigate to: " & objOAuth2.VerificationUrl
  WScript.Echo "Please enter: " & objOAuth2.UserCode
End If

' ...

SuccessHtml property

This property is only used with the Authorization code flow.

On success the user is redirected to the RedirectUrl. This property controls the success message.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

objOAuth2.SuccessHtml = "<h1>Success!</h1>"
objOAuth2.ErrorHtml = "<h1>Failed!</h1>"

' ...

objOAuth2.Flow = objConstants.OAUTH2_FLOW_AUTHCODE
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.RedirectUrl = "http://localhost:7999/oauth2test/"
objOAuth2.Scope = "https://mail.google.com/"
objOAuth2.AuthCodeUrl = "https://accounts.google.com/o/oauth2/v2/auth"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

' ...

ErrorHtml property

This property is only used with the Authorization code flow.

On failure the user is redirected to the RedirectUrl. This property controls the failure message.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

objOAuth2.SuccessHtml = "<h1>Success!</h1>"
objOAuth2.ErrorHtml = "<h1>Failed!</h1>"

' ...

objOAuth2.Flow = objConstants.OAUTH2_FLOW_AUTHCODE
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.RedirectUrl = "http://localhost:7999/oauth2test/"
objOAuth2.Scope = "https://mail.google.com/"
objOAuth2.AuthCodeUrl = "https://accounts.google.com/o/oauth2/v2/auth"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

' ...

AutoOpenBrowser property

Set this property to true to automatically open the default browser to show a login prompt.

If this property is not set please open the LoginUrl property after calling Login.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

objOAuth2.AutoOpenBrowser = False

' ...

objOAuth2.Login
If objOAuth2.LastError = 0 Then
  WScript.Echo "Please navigate to: " & objOAuth2.VerificationUrl
  WScript.Echo "Please enter: " & objOAuth2.UserCode
End If

WShShell.Run objOAuth2.LoginUrl

' ...

LoginUrl property

Use this property when AutoOpenBrowser is set to False.

This property contains either the URL to authenticate the user or for the user to enter the user code depending on which Authorization Flow is used.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

objOAuth2.AutoOpenBrowser = False

' ...

objOAuth2.Login
If objOAuth2.LastError = 0 Then
  WScript.Echo "Please navigate to: " & objOAuth2.VerificationUrl
  WScript.Echo "Please enter: " & objOAuth2.UserCode
End If

WShShell.Run objOAuth2.LoginUrl

' ...

DeviceCode property

When using the device code Flow this property contains the device code.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' ...

objOAuth2.Login

' ...

WScript.Echo objOAuth2.DeviceCode
WScript.Echo objOAuth2.UserCode
WScript.Echo objOAuth2.UserCodeMessage

' ...

UserCode property

When using the device code Flow this property contains the user code.

The user should enter the user code in the sign-in browser window to start authentication

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' ...

objOAuth2.Login

' ... 

WScript.Echo objOAuth2.DeviceCode
WScript.Echo objOAuth2.UserCode
WScript.Echo objOAuth2.UserCodeMessage

' ...

UserCodeMessage property

When using the device code Flow this property contains the user code message.

The user code message is a friendly message from the authorization server to show to your user which contains the user code.

The user code message may be internationalized according to user settings etc.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' ...

objOAuth2.Login

' ... 

WScript.Echo objOAuth2.DeviceCode
WScript.Echo objOAuth2.UserCode
WScript.Echo objOAuth2.UserCodeMessage

' ...

BearerToken property

This is the bearer token that needs to be set with the
POP3,
SMTP or
IMAP protocol to authenticate on the server.

The bearer token expires after BearerExpInSeconds seconds.

Depending on your authorizing party and their security policies you may be able to silently obtain a new bearer token after the bearer token has expired by calling RefreshBearerToken.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")

' ...

' Wait for the user to login
objOAuth2.WaitForTokens(90000)
WScript.Echo "WaitForTokens result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Display the bearer and refresh tokens. 
' The bearer token needs to be passed to the SMTP, IMAP or POP object.
WScript.Echo
WScript.Echo "Bearer token: " & objOAuth2.BearerToken
WScript.Echo "Refresh token: " & objOAuth2.RefreshToken
WScript.Echo "Bearer timeout: " & objOAuth2.BearerExpInSeconds & " seconds"

RefreshToken property

The refresh token. Use the refresh token to receive a new Bearer token once the bearer token expires.

Refresh the bearer token by calling RefreshBearerToken.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")

objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.Scope = "https://mail.google.com/"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

' Refresh Bearer Token
objOAuth2.RefreshBearerToken()
WScript.Echo "RefreshBearerToken result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' The bearer token needs to be passed to the SMTP, IMAP or POP object.
WScript.Echo
WScript.Echo "Bearer token: " & objOAuth2.BearerToken
WScript.Echo "Bearer timeout: " & objOAuth2.BearerExpInSeconds & " seconds"

BearerTokenExpInSeconds property

The is the bearer token expiration timeout in seconds.

This value is set immediately after calling WaitForTokens has completed successfully.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")

' ...

' Wait for the user to login
objOAuth2.WaitForTokens(90000)
WScript.Echo "WaitForTokens result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Display the bearer and refresh tokens. 
' The bearer token needs to be passed to the SMTP, IMAP or POP object.
WScript.Echo
WScript.Echo "Bearer token: " & objOAuth2.BearerToken
WScript.Echo "Refresh token: " & objOAuth2.RefreshToken
WScript.Echo "Bearer timeout: " & objOAuth2.BearerExpInSeconds & " seconds"

UserCodeExpInSeconds property

The is the expiration timeout in seconds for both the UserCode as well as the DeviceCode property.

This only applies to the device code flow.

This value is set immediately after calling Login has completed successfully.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
Set objConstants = CreateObject("AxEmail.Constants")

' ...

objOAuth2.Login
WScript.Echo "Login result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' ... 

WScript.Echo objOAuth2.DeviceCode
WScript.Echo objOAuth2.UserCode
WScript.Echo objOAuth2.UserCodeMessage
WScript.Echo objOAuth2.UserCodeExpInSeconds
WScript.Echo objOAuth2.PollIntervalInSeconds

' ...

PollIntervalInSeconds property

The is the recommended poll interval in seconds for the WaitForTokens method.

This only applies to the device code flow.

This value is set immediately after calling Login has completed successfully.

The OAuth2 component automatically takes this interval into account when using a long timeout value on the WaitForTokens method.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")

' ...

' Wait for the user to login
objOAuth2.WaitForTokens(90000)
WScript.Echo "WaitForTokens result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Display the bearer and refresh tokens. 
' The bearer token needs to be passed to the SMTP, IMAP or POP object.
WScript.Echo
WScript.Echo "Bearer token: " & objOAuth2.BearerToken
WScript.Echo "Refresh token: " & objOAuth2.RefreshToken
WScript.Echo "Bearer timeout: " & objOAuth2.BearerExpInSeconds & " seconds"

ResultScope property

This the resulting scope after authorization.

It’s possible that authorization was successful for only a part of the requested scope.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")

' ...

' Wait for the user to login
objOAuth2.WaitForTokens(90000)
WScript.Echo "WaitForTokens result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Display the bearer and refresh tokens. 
' The bearer token needs to be passed to the SMTP, IMAP or POP object.
WScript.Echo
WScript.Echo "Bearer token: " & objOAuth2.BearerToken
WScript.Echo "Refresh token: " & objOAuth2.RefreshToken
WScript.Echo "Result Scope: " & objOAuth2.ResultScope

LastResponse property

This is the last HTTP response received during the OAuth2 protocol.

This value can be useful while troubleshooting OAuth2 protocol issues.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")

' ...

' Wait for the user to login
objOAuth2.WaitForTokens(90000)
WScript.Echo "WaitForTokens result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Display the bearer and refresh tokens. 
' The bearer token needs to be passed to the SMTP, IMAP or POP object.
WScript.Echo
WScript.Echo "Bearer token: " & objOAuth2.BearerToken
WScript.Echo "Refresh token: " & objOAuth2.RefreshToken
WScript.Echo
WScript.Echo "Last response: " & objOAuth2.LastResponse

ResultError property

If there was an error message from the server this property will contain that error.

This can be useful when troubleshooting

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")

' ...

' Wait for the user to login
objOAuth2.WaitForTokens(90000)
WScript.Echo "WaitForTokens result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Display the bearer and refresh tokens. 
' The bearer token needs to be passed to the SMTP, IMAP or POP object.
WScript.Echo
WScript.Echo "Bearer token: " & objOAuth2.BearerToken
WScript.Echo "Refresh token: " & objOAuth2.RefreshToken
WScript.Echo 
WScript.Echo "Result Error: " & objOAuth2.ResultError
WScript.Echo "Result Error Description: " & objOAuth2.ResultErrorDescription

ResultErrorDescription property

If there was an error message from the server this property will contain the description of that error.

This can be useful when troubleshooting

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")

' ...

' Wait for the user to login
objOAuth2.WaitForTokens(90000)
WScript.Echo "WaitForTokens result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Display the bearer and refresh tokens. 
' The bearer token needs to be passed to the SMTP, IMAP or POP object.
WScript.Echo
WScript.Echo "Bearer token: " & objOAuth2.BearerToken
WScript.Echo "Refresh token: " & objOAuth2.RefreshToken
WScript.Echo 
WScript.Echo "Result Error: " & objOAuth2.ResultError
WScript.Echo "Result Error Description: " & objOAuth2.ResultErrorDescription

ProxyServer property

Set the proxy server if this is required.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
          
' Setup HTTP proxy
objOAuth2.ProxyServer = "proxy.domain.com:8080"
objOAuth2.ProxyAccount = "Account"
objOAuth2.ProxyPassword = "Password"

' Set OAuth parameters
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.RefreshToken = "1234567890123456789012345678901234567890"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

' Exchange the bearer token using a refresh token
objOAuth2.RefreshBearerToken
WScript.Echo "RefreshBearerToken result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

...

ProxyAccount property

Set the proxy server login if this is required.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
          
' Setup HTTP proxy
objOAuth2.ProxyServer = "proxy.domain.com:8080"
objOAuth2.ProxyAccount = "Account"
objOAuth2.ProxyPassword = "Password"

' Set OAuth parameters
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.RefreshToken = "1234567890123456789012345678901234567890"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

' Exchange the bearer token using a refresh token
objOAuth2.RefreshBearerToken
WScript.Echo "RefreshBearerToken result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

...

ProxyPassword property

Set the proxy server password if this is required.

Example: 

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
          
' Setup HTTP proxy
objOAuth2.ProxyServer = "proxy.domain.com:8080"
objOAuth2.ProxyAccount = "Account"
objOAuth2.ProxyPassword = "Password"

' Set OAuth parameters
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.RefreshToken = "1234567890123456789012345678901234567890"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

' Exchange the bearer token using a refresh token
objOAuth2.RefreshBearerToken
WScript.Echo "RefreshBearerToken result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

...

Clear method

This function resets all properties to their default values.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objOAuth2 = CreateObject("AxEmail.OAuth2")   
....
objOAuth2.Clear
...

SaveLicenseKey method

Description:

Use SaveLicenseKey to store the license key permanently in the registry. When a license key is saved, it is restored automatically every time a new instance of the object is created. It is not recommended to save the license key if you distribute the component with your own software, because the key can be easily used by others.

Parameters:

  • None.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objOAuth2 = CreateObject("AxEmail.OAuth2")                 ' Create new instance
objOAuth2.LicenseKey = "XXXXX-XXXXX-XXXXX"
objOAuth2.SaveLicenseKey                                     ' Save license key to registry

For more information, see Product Activation.

GetErrorDescription method

GetErrorDescription provides the error description of a given error code.

Parameters:

  • The error code

Return value:

The error string.

Example:

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
...
WScript.Echo "result:"  & objOAuth2.LastError & ","  & _
  objOAuth2.GetErrorDescription(objOAuth2.LastError)

Sleep method

This function suspends the current thread for the specified number of milliseconds.

Parameters:

  • Milliseconds to sleep

Return value:

Always 0.

Example:

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
....
objOAuth2.Sleep 1000
...

Login method

Call this version to start the OAuth2 authorization process.

The exact function depends on the Flow property.
In device code flow this function retrieves the user code, device code and authorization url from the OAuth2 server.
In authorization code flow this function starts listening on the local callback URL and opens the login prompt.

If AutoOpenBrowser is set then calling this method automatically opens the default browser to the authorization URL.
The authorization URL will be set in LoginUrl after calling this function.

Call WaitForTokens to continue authorization by waiting for the bearer and refresh tokens.

On success LastError will be 0 after calling this function.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
....

' Start authorization and show the login page
objOAuth2.Login
WScript.Echo "Login result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Wait for the user to login
objOAuth2.WaitForTokens(90000)
WScript.Echo "WaitForTokens result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Display the bearer and refresh tokens. 
' The bearer token needs to be passed to the SMTP, IMAP or POP object.
WScript.Echo
WScript.Echo "Bearer token: " & objOAuth2.BearerToken
WScript.Echo "Refresh token: " & objOAuth2.RefreshToken
WScript.Echo "Bearer timeout: " & objOAuth2.BearerExpInSeconds & " seconds"

...

WaitForTokens method

Call this function right after a successful call to Login to continue the OAuth2 authorization process.

The exact function depends on the Flow property. In device code flow this function polls the
TokenExchangeUrl until bearer and refresh tokens are returned.
In the authorization code flow this function listens on the RedirectUrl to receive the authorization code and exchanges it using the TokenExchangeUrl for the Bearer and refresh tokens once the user has logged in.

If LastError is 0 after calling this function then the user has logged in and the bearer token and refresh tokens are set.

If LastError is set to 37905 (‘No Tokens Yet’) then this function needs to be called again to continue to wait or poll.

If LastError is set to anything other than 0 or 37905 then this means that the call has failed and no bearer token was received.

On success this function returns immediately when the tokens are received and before the timeout has expired.

Please note that the refresh token can sometimes stay empty. This has to do with the permissions requested in Scope property and / or the permissions granted by the user.

Parameters:

  • Milliseconds to wait

Return value:

Always 0.

Example:

Set objOAuth2 = CreateObject("AxEmail.OAuth2")
....

' Start authorization and show the login page
objOAuth2.Login
WScript.Echo "Login result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Wait for the user to login
objOAuth2.WaitForTokens(90000)
WScript.Echo "WaitForTokens result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Display the bearer and refresh tokens. 
' The bearer token needs to be passed to the SMTP, IMAP or POP object.
WScript.Echo
WScript.Echo "Bearer token: " & objOAuth2.BearerToken
WScript.Echo "Refresh token: " & objOAuth2.RefreshToken
WScript.Echo "Bearer timeout: " & objOAuth2.BearerExpInSeconds & " seconds"

...

RefreshBearerToken method

Call this function to exchange a refresh token for a new bearer token.

This function does not open a browser nor requires any user interaction.

After the bearer token has expired call this function if a refresh token is available to refresh the bearer token.

On success LastError will be 0 after calling this function.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objOAuth2 = CreateObject("AxEmail.OAuth2")

' Set OAuth parameters
objOAuth2.ClientID = "1234567890-12345678901234567890.apps.googleusercontent.com"
objOAuth2.ClientSecret = "GOCSPX-12345678901234567890_1234567890"
objOAuth2.RefreshToken = "1234567890123456789012345678901234567890"
objOAuth2.TokenExchangeUrl = "https://oauth2.googleapis.com/token"

' Exchange the bearer token using a refresh token
objOAuth2.RefreshBearerToken
WScript.Echo "RefreshBearerToken result " & objOAuth2.LastError & _
  ": " & objOAuth2.GetErrorDescription(objOAuth2.LastError)

' Display the bearer and refresh tokens. 
' The bearer token needs to be passed to the SMTP, IMAP or POP object.
WScript.Echo
WScript.Echo "Bearer token: " & objOAuth2.BearerToken
WScript.Echo "Refresh token: " & objOAuth2.RefreshToken
WScript.Echo "Bearer timeout: " & objOAuth2.BearerExpInSeconds & " seconds"

...