OAuth 2.0 Configuration

Scope:

OAuth 2.0 Authorization applies only to the configuration of an email server for the purpose of sending alarm notifications or reports.

OAuth stands for Open Authorization (not authentication). "2.0" refers to the second (and current) generation. This is a protocol used to allow defined access between web or desktop applications. It is an open standard, used by Microsoft, Google and many other companies. OAuth 2.0 is related to, but distinct from, OpenID Connect. A complete set of terms and definitions is provided in OAuth 2.0 Definitions and Process

For an example of how to configure VTScada to work with each of two common OAuth 2.0 providers, see:Google Workspace Configuration for OAuth 2.0 and Microsoft 365 Configuration for OAuth 2.0.

If using OAuth 2.0 ensure that all servers are using VTScada version 12.1 or version 12.0. OAuth tokens will not be handled properly if your servers run a mix of these two versions.

Preparation

Before configuring OAuth 2.0 within VTScada, you will need all of the following:

An OAuth 2.0 provider

A provider looks after user authentication and provides authorization for the service (email) that you want to access from VTScada. Examples include Google Workspace® (formerly G-Suite®), Microsoft MS 365® (formerly Office 365®), and others.

You must obtain all of the following from your selected OAuth 2.0 provider before proceeding to configure VTScada.

Authorization Endpoint URL

A publicly available REST endpoint offered by the OAuth 2.0 provider. Used to confirm the resource owner's credentials during an access request by a third-party application.

Token Endpoint URL

A publicly available REST endpoint offered by the OAuth 2.0 provider. This is where a third-party application such as VTScada can get the tokens needed to access the resource owner’s protected resources.

Revocation Endpoint URL

Optional. Not supported by all providers. A publicly available REST endpoint offered by the OAuth 2 provider. This allows clients to indicate to the authorization server that an access token is no longer needed. Used to enable a "sign out" feature in clients, allowing the authorization server to clean up any security credentials associated with the authorization.

Client ID

An identifier for your application. This will be generated for you as part of the provider configuration.

Client Secret

Similar to a password, this is known only to your application and your provider. You must copy this to a secure location after it is created during the provider configuration process.

A certificate for your VTScada server(s)

Commonly (but incorrectly) referred to as an SSL certificate. Every provider will have its own set of restrictions on what it will accept as the redirect URIClosed The URL identifying a server registered as a potential system to receive the single use code during the OAuth 2 consent flow.. The VTScada OAuth server(s) need not be exposed to the public Internet by being included in a VTScada Thin Client server list, but must be capable of making a connection to the public OAuth servers.

The certificate may be self-signed so long as it is trusted by the user-agent (browser).

An email account with your selected provider.

For example, a Workspace account if using Google as a provider. An MS 365 account if using Azure.
Create an account for VTScada. Do not use your personal email account.

A server list specifying at least one OAuth 2.0 server

Referring to client / server configuration, not a Thin Client Server. This is not strictly necessary but is recommended even if your application runs on only a single server.

Your application must be secured and you must be signed in with an account that has the Administrator privilege

The Redirect URI must be resolvable on your internal network.

 

Assuming that these items are in place, proceed as follows:

Part 1: Enable OAuth 2.0 configuration in VTScada.

  1. Open the security Options dialog (Administrative Settings)
  2. Select the option, Enable OAuth 2.0, found within the Advanced section.
  3. Select OK to save your changes.

OAuth 2.0 enabled in the security Administrative Settings dialog.

  1. Close the Administrative Settings dialog.
    The OAuth 2.0 Settings dialog option is now enabled.

 

Part 2: Configure VTScada to use OAuth 2.0 authorization.

  1. Open the Edit Server Lists page of the Application Configuration dialog.
  2. Select the server(s) that will respond to OAuth grant requests.
    In the case of an application that runs on only a single server, this step is not required, but it is recommended.
  3. Open the OAuth 2.0 settings dialog.
    Available from either the drop-down security menu in the screen or the Security page of the Application Configuration dialog.

The OAuth 2.0 Settings dialog. All fields are disabled until you begin configuration of a provider.
Note that Providers and Grants can both be deleted using the trashcan buttons below the respective lists.

Grant Scopes and Redirect URI entries can be edited by double-clicking. Editing may require you to grant consent again.

  1. Create a new Provider by clicking the button under the providers list.
    This enables the data entry fields.
  2. Create a Provider Name as desired.
    Create an easily recognized name to identify the purpose of the registration and the resource provider
  3. Enter the Authorization Endpoint URL for your chosen OAuth 2.0 provider.
  4. Enter the Token Endpoint URL for your chosen OAuth 2.0 provider.
  5. Enter the Revocation Endpoint URL for your chosen OAuth 2.0 provider, if one exists.
  6. Set the Client ID and Client secret to the values created when configuring your OAuth 2.0 provider.
  7. Set the Refresh Token Lifetime to as appropriate.
    This field is measured in seconds and must match the token lifetime used by your provider. This value refers to the time between uses of the refresh token, and not the overall lifetime of the token.
    For reference, standard values from two commonly-used providers are:

    • Google: 6 months of inactivity (15552000 seconds )

    • Microsoft: 2 weeks of inactivity (1209600 seconds )

  1. Select Pen icon next to the Provider Scopes field to open the Scope Editor.

Scope Editor

Example showing the scope if configuring for GSuite authentication.

  1. Enter the URI for the provider scope.
    The scope is the service for which you are authorizing access.
  2. Select the pen beside the Redirect URIs field to open the Redirect URIs editor.

Your OAuth 2.0 server(s) need not be visible to the Internet, but must be secured.

  1. Set the OAuth Redirect URIs as given when configuring your OAuth 2.0 provider.
    These will be the FQDNClosed Fully Qualified Domain Name's of your VTScada OAuth servers, along with the VTScada OAuth path which is "/vtscada/oauth/return".
    Do not include any realm name for your application. Do not include the port number unless it is non-standard.
  2. Create a new Grant by clicking the button under the Grants List.
  3. Create a name for the grant.
    This is used to identify the service to which you are granting authorization. Naming the grant to match your provider's email service might be appropriate.
  4. In the Grant Bearer field, enter the identification of the user who will be running the consent operation. Typically, this will be an email address.
    This must be an email account registered with your provider.
  5. Select the pen beside the Requested (Grant) Scopes field to open the Grant Scopes editor.

Example showing selection of a GSuite email scope.

  1. Select the relevant email scope then click OK to close the dialog.
    Scopes are the set of access permissions to be requested for the bearer. This must be a subset of those configured for the OAuth 2.0 provider registration.

This completes configuration. An example is shown following these steps.

  1. Select the Apply button.
  2. Select the Grant button to grant authority for VTScada to access the designated email account.
    You need not grant consent immediately, but must do so before using the service. See the following notes under Granting Consent

Sample OAuth 2 Settings dialog, as configured for GSuite.

Grant Selection

If you configure more than one OAuth 2.0 grant, then you will have a selection of which to use within the Alarms tab of the Edit Properties / Application Configuration dialog. Outgoing and Incoming Alarm Email Acknowledgments will each have a Grant Selection.

To use:

  1. Select the appropriate grant.

  2. Initiate the consent operation for that grant.

  3. Optionally, you can use this to revoke consent for a grant.

Granting Consent

Do not use your personal email to send and receive alarm notifications. VTScada will erase all messages in the Inbox after retrieval. Always use an account that is dedicated for VTScada's use.

Your default browser is open, waiting for you to complete the operation there.

You must grant consent for VTScada to use an email account through your provider. The dialogs will vary according to your selected provider, but the process will be similar. First you must confirm the account to use. Then confirm that access is granted. Note that this operation will always happen within your default browser, not within VTScada.

The Security Admin who configures the provider and grant may not be the one with the credentials to actually give consent, therefore, grant consumers (alarm emails) are able to grant consent.

 

Revoking Consent

You may revoke consent for a grant at any time. Use the Revoke button and confirm that you wish to proceed.