New functionality has been added to pasUnity that provides a means to authorize and authenticate with SMTP and POP3 mail servers using the OAuth 2.0 standard.

What is OAuth 2.0?

OAuth 2.0 is a protocol that is used to authorize a client application with secure delegated access to a resource (the mail account) through the use of revocable access tokens as opposed to through the use of using personal credentials. The access tokens themselves have a short lifespan, typically within a few minutes to a couple hours of issuance. The OAuth 2.0 server may implement several different grants, or process flows, that can be utilized to authorize and authenticate a client. Initial authorization of the application typically must be done interactively as a one-time setup. The one-time setup allows pasUnity to acquire a refresh token from the server. If a refresh token is successfully obtained from the server, pasUnity can continue to refresh the access token until either the refresh token is revoked or it expires.

OAuth 2.0 Pre-Configuration

In order to use OAuth 2.0, your mail server must support the OAuth 2.0 standard and allow one of the grant types that pasUnity has implemented. The mail server will require configuration such as generation of a client ID, optional client secrets, redirect URLs, and various other settings specific to the server. The steps to configure a client vary depending on the product, but we will demonstrate the process for Exchange 365.

To begin, navigate to the your organization's Azure portal at https://portal.azure.com, and use the menu to navigate to the Azure Active Directory overview page. In the overview section, click Add and then click the App Registration button.



Specify a name for the application, the accounts that are allowed to use this application, and an optional redirect URI. We intend to use the Device Authorization grant type, so we will leave the redirect URI empty.



Review and create the new app registration and you will be sent to the web page displaying the overview of the app registration. The Client ID is specified under the display name, and clicking the Endpoints button will display the OAuth 2.0 registered endpoints.



Next we need to create a mode for authentication. Use the menu to navigate to the Authentication tab, add a new platform, and choose Mobile and desktop applications. A custom redirect URI must be provided, but it will not be necessary for the Device Authorization grant type. For this case, we will use http://localhost, however any other URL specified must use the HTTPS scheme.



After configuring the platform, scroll to the bottom of the authentication page and check the advanced setting Allow public client flows. This is necessary to enable the Device Code flow. Save the settings.



Once the application is created, configured with a platform, and public client flows are enabled, the Device Authorization grant type can be used with Exchange 365 accounts and pre-configuration is complete.

OAuth 2.0 Access Token

At the most basic level, you can enter a static access token that has already been retrieved into the text box and not choose a grant type. Doing so will allow pasUnity to send and receive email for the duration the access token is valid. If the token expires, it must be refreshed manually. This is not typically recommended because the access token usually has a short lifespan. If you do wish to specify an access token manually, the field is macro resolvable so you may still access key value pairs and other various macro commands that are not Job specific.



OAuth 2.0 Grant Types

Alternatively, if you do not specify a static access token, pasUnity can manage the refreshing of access tokens by configuring one of the supported grant types. Once the grant type is configured, a one-time manual authorization will be required where you must authorize pasUnity to access the email account. Once authorized, pasUnity can re-authorize itself with the use of a refresh token. Refresh tokens also have expiration dates, but they are typically configurable and can often last as long as two years before needing to be reset.

Authorization Code Grant Type

The Authorization Code Grant Type defines a flow in which the client must first authorize with an authorization server in a web browser through the application before requesting an access token. Enter the Authorization URI, Access Token URI, Redirection URI, Client ID, Client Secret (if applicable for the mail server), and the Scope of the delegated permissions that will be requested from the authorization and token servers. In this example, the Scope of https://outlook.office.com/SMTP.Send and offline_access are requested from the server. These scopes are defined by the server, and in this case indicate that we want the ability to send mail over SMTP and to be able to manage the token refreshing through a refresh token.



Once complete, press the Authorize OAuth Client button to begin the interactive flow. You will be directed to the authorization URI inside a web browser in pasUnity. Log in with your credentials and authorize pasUnity to access the resources. Upon successful authentication, the server will redirect the web browser to the redirect URI that contains an authorization code. The authorization code is then sent to the access token URI to retrieve the access token and a refresh token, which can be used to refresh the access token from the token server.

Device Authorization Grant Type

The Device Authorization Grant Type defines a flow in which the user must navigate to a URL on any device and enter a user code to authorize the client before requesting an access token. Enter the Device Authorization URI, Access Token URI, Client ID, and the Scope of the delegated permissions that will be requested from the authorization and token servers.

Since we previously configured an app registration in Exchange 365 in the pre-configuration section, we can fill the form out with the values from the app registration. The app registration overview page will display vital information for filling out this form, such as the Application (Client) ID, and the Directory (Tenant) ID. In Exchange 365, each URI is generated from a pattern containing the Tenant ID and the action to take against the server.

For example, if our Tenant ID is 00000000-0000-0000-0000-000000000001, we can infer that our device authorization URI will be :
https://login.microsoftonline.com/00000000-0000-0000-0000-000000000001/oauth2/v2.0/deviceCode

and the access token URI will be:
https://login.microsoftonline.com/00000000-0000-0000-0000-000000000001/oauth2/v2.0/token.

The scopes we must request are defined by the Exchange 365 server. To be able to receive mail over POP3 we need to request the scope https://outlook.office.com/POP.AccessAsUser.All, and to be able to refresh the access token, we need to request the scope offline_access. If this app registration was used to send mail over SMTP, we could also request the scope https://outlook.office.com/SMTP.Send.



Once complete, press the Authorize OAuth Client button to begin the interactive flow. The device authorization server will provide a URL you must navigate to and a user code you must enter at the at the URL. These values will be displayed inside of a popup dialog. You can navigate to the URL manually, or have a web browser opened automatically and the user code copied to the clipboard for you to paste.



After navigating to the URL and submitting the user code, you will be asked to log in using your credentials. Once the application is authorized, you may close the browser and press OK on the window in pasUnity. Web requests will be sent for 2 minutes at the interval specified by the authorization server until it is detected that the authorization flow is complete. A successful authorization will return an access token and a refresh token, which can be used to refresh the access token from the token server.

OAuth 2.0 Key Value Pairs

Once an access token and a refresh token are obtained from a token server, they are stored in system-managed key value pairs for the account. The keys stored are AccessToken, AccessTokenExpirationDate, and RefreshToken, prefixed by the protocol used for the account. For example, configuring OAuth 2.0 for sending mail with SMTP will result in the keys SMTPAccessToken, SMTPAccessTokenExpirationDate, and SMTPRefreshToken.



Every time mail is sent or received from this account, the access token and the access token expiration date will be evaluated. If the access token has expired at the time of use, a new token will be requested from the token server using the refresh token. If the refresh token is valid and a new access token can be obtained from the access token server, the key value pairs will be updated for the account to match the new values. Altering any of these values manually can have the impact of breaking the authorization for pasUnity.

Summary

In addition to the added layer of complexity added by the OAuth 2.0 configuration authorization process, the user who owns the resource (in this case, the account), must be present to manually authorize the application for one-time configuration. For these reasons, OAuth 2.0 may not be the best option. While OAuth 2.0 is not required or even available for most mail servers, Exchange 365 will be removing user name and password authentication in the near future for POP3 clients. If you have an Exchange 365 account and you need to collect mail over POP3, we recommend the Device Authorization Flow and the steps described above can be used to configure OAuth 2.0. Contrary to Exchange 365, Exchange Server does not support OAuth 2.0. It's OK if User name and password authentication is used, but we do recommend a strong password to keep your account safe. OAuth 2.0 authentication has been extensively tested on Exchange 365 and Gmail servers, but other servers have not undergone the same testing.