OAuth2 Connections

Short Description

OAuth2 connection allows you to obtain OAuth2 access token which can by used for authorization with API of external services. The connection can be used together with HTTPConnector component or it can provide tokens in CTL2 language.

OAuth2 connections support only Authorization Code flow. Other OAuth2 flows are not supported, such as Client Credentials flow.

Creating OAuth2 Connection

To use OAuth2, you first need to register an application in the service where you want to connect. Providers (Google/Azure/other) usually offer free app registrations in their cloud console UI. The registered app will have its Client ID, Client Secret and it will let you register a Redirect URL. For details on what Redirect URL to register, see its section below.

To create a OAuth2 connection, right click Connections in Outline and choose Connections > Create OAuth2 connection.

OAuth2 connection is always an external connection so as a first step you have to specify a file into which configuration of a new connection will be saved.

In Create OAuth2 connection dialog, fill in Connection name, select Provider and authorize the connection. Only an authorized connection can provide OAuth2 access token.

Click on Finish saves connection configuration.

Basic

Connection properties on the Basic tab are mandatory. Some are Provider dependent and may not be displayed when you change the Provider.

Connection name

A name for this connection.
Connection name is used to reference the connection in CTL2 function getOAuth2Token.

Provider

Provider is external provider of OAuth2 authorization service. Selecting a specific provider changes default URLs needed to use authorization service and enables behavior specific for that provider (if any).

Client ID

Client ID defined in application registration. This ID specifies application registered with authorization service Provider.

Client secret

Client secret defined in application registration. This secret protects access to the application registered with authorization service Provider. Use Secure parameters to encrypt Client secret property (see Secure Graph Parameters).

Scopes

Scopes are permissions of the connection. Their values depend on the application provider. If you have more than one scope, separate individual scopes by spaces.

Tenant ID

Only applies for Azure provider. Tenant ID is identifier of Azure Subscription.

Advanced

Connection properties on the Advanced tab have default values generated based on selected Provider and Data Shaper server/runtime to which the designer project is connected.

Authorization endpoint

An URL used for sending authorization request.

Token endpoint

An URL used for obtaining OAuth2 access token.

Redirect URL

An URL registered together with client application. After successful authorization the user is redirected to this URL. Default value is generated based on project setup and is used when the property is left empty. Unless you use a specific setup like proxy or load balancer for your server, you can leave this value empty and use the default.
Note that the redirect URL registered in provider must match to this URL. Most providers allow differences in ports on localhost URLs. For local projects, registering redirect URL http://localhost/clover/oauth2 should suffice. Some providers require exact match even with localhost URLs, in those cases you must register the exact URL you see in the connection dialog.
For server projects, register hostname of your server followed by /oauth2. Note that OAuth2 protocol requires using HTTPS for non-localhost URLs. An example of full URL: https://some-server.com:8083/clover/oauth2.

Authorize connection

To use connection in graphs, the connection has to be authorized. Authorization is a manual interactive process in which user gives the connection access to their resources. This access is limited by the OAuth2 scopes.

The connection can be authorized using the Authorize button. You may decide whether you want to use embedded web browser or an external browser. When using external browser, the browser set as default system browser in your OS is used.

During authorization you may be asked to fill in user credentials and confirm client access permissions. After successful authorization the dialog is made read-only and connection is ready to use in graphs. You may unlock the connection editing by using the Re-authorize button. Connection can be re-authorized as many times as you need.

Authorized connections keep their OAuth2 tokens in a special .tokens file in the same directory as connection’s .cfg file. You may transfer both of these files between environments to keep the connection authorized. As long as master password is the same, the connection will stay authorized.

Details

OAuth2 access tokens are usually short-lived. The expiration time depends on the provider and ranges anywhere between 15 minutes and several months. OAuth2 connection in Data Shaper handles refreshing of tokens automatically, if provider supports it. The connection always provides a non-expired access token.

If provider doesn’t support refreshing of access tokens, the connection dialog displays date and time when will the current access token expire. User has to manually re-authorize OAuth2 connection using the connection dialog.