OAuth 2.0 Definitions and Process

OAuth 2.0 is a protocol in which a user’s resources with a provider (for example an email account with MS 365) can be accessed by third-party applications without sharing the user’s credentials with those third-party applications. This allows a resource provider and their users control over which applications can access specified protected resources, and for how long access will last. The user is reassured that the third-party application will not access resources not explicitly requested, and can also remove permission for applications to access to their resources without having to change their credentials.

Common definitions

Resource provider

Sources from which a resource is offered. This includes providers such as Google and Microsoft, which offer a variety of resources including things such as email, calendars, file storage, and databases.

Resource owner

The user registration with the resource provider. This is often an account registered with the resource provider to which specific resources are assigned. This includes things such as Google or Microsoft user accounts.

OAuth 2.0 provider

A source that provides security for a resource by providing credentials to applications for accessing that resource. The OAuth 2.0 provider is often the same as the resource provider, and will share information with the resource provider on permissions granted by users to a third-party application for specific resources.

OAuth 2.0 grant

The consent given by a resource owner for a specific set of permissions to be given to a third-party application registered with the OAuth 2.0 provider. This allows accessing the resource without having direct access to the credentials, instead using a token, or a set of tokens, unique to the grant when accessing the resource.

The bearer of an OAuth 2 grant is the account that will be used during normal operation, and requires the scopes you are defining as allowed for use by VTScada. In this case it would be the reply email.

User agent

Often a web browser. Used as a means of confirming the resource owner’s credentials during the OAuth 2.0 consent process. This browser provides a means for the credentials to be sent directly to the OAuth 2.0 provider without passing by the application which is requesting access to the resources. For VTScada, this is the users default web browser.

OAuth 2.0 provider authorization endpoint

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

OAuth 2.0 provider token endpoint

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

Redirect URIs

This is the URL identifying a server registered as a potential system to receive the single use code during the OAuth 2 consent flow. There may be multiple redirect URIs registered for a single third-party application registration. Due to the handling of the communication during a consent operation, the redirect URI needs only be resolvable by the system which is running the user agent.

Access token

A short-lived token that is exchanged by a third-party application when attempting to access a resource owner’s resources.

Refresh token

A longer-lived token that permits the third-party application to acquire a new access token without requiring the user provide consent each time. The permissions given for the new access token are the same as the previous. This token can be invalidated by the resource owner when desired.

 

OAuth 2.0 Consent Flow Description

The OAuth 2.0 consent flow used by VTScada is the Authentication code flow. In this flow, a VTScada server will direct a user agent to the OAuth 2.0 provider authorization endpoint. After the resource owner is successfully authenticated, the OAuth 2.0 provider authorization endpoint will redirect the user agent to the VTScada server with a single use code. This code can then be exchanged by the VTScada server for a pair of tokens by providing it to the OAuth 2.0 provider token endpoint. These tokens can then be used by VTScada to access to the resource for which the resource owner granted consent. Continued use of the resource by VTScada for services such as the alarm email system require a refresh token.

In order to authenticate the user agent with the VTScada server, a VTScada client will first direct the user agent to the server. At this point, the server will establish information required to protect the different elements of the OAuth 2.0 consent flow when communicating with the OAuth 2.0 provider. This is an additional step prior to beginning the general OAuth 2.0 consent flow.

1. VTScada client invokes the user agent.
2. The user agent is directed to the VTScada OAuth 2.0 redirect server to establish common identifying information.
3. The user agent is redirected to the OAuth 2.0 provider’s authorization endpoint.
4. The user agent contacts the authorization endpoint and authenticates the resource owner.
5. The authorization endpoint redirects the user agent to the VTScada OAuth 2.0 redirect server with the single use code.
6. The user agent provides the VTScada OAuth 2.0 redirect server with the code.
7. The VTScada OAuth 2.0 redirect server contacts the OAuth 2.0 provider token endpoint with the single use code.
8. The token endpoint responds with the appropriate tokens.
9. The VTScada OAuth 2.0 redirect server passes the acquired tokens to the primary server for the OAuth 2.0 implementation. This may be the same server as that handling the OAuth 2.0 redirect.