SetOAuth2Token component

The SetOAuth2Token component is used to handle the process of retrieving and refreshing Access and Refresh tokens as specified in the OAuth2 protocol. Access tokens are used to authorize calls to endpoints / applications, i.e. email or a cloud platform. An access token is sent along as part of requests to these applications, often as an 'Authorization' header.

important

To trigger the process of continuously refreshing tokens in order to have a valid access token available at all times this component needs to be combined with a Scheduler component. Read more about Scheduling the SetOAuth2Token component below.

The tokens generated with this component are stored in the Tenant variables and can be used throughout your tenant.

tip

Read more about using variables in Dovetail on this reference page.

Configuration

The SetOAuth2Token component has the following configuration options:

Credentials Type

The type of credentials you want to create. The options are:

• Custom to generate tokens for any endpoint. This gives you all the configuration options.
• Google Drive to generate tokens for the Inbound or Outbound Google Drive component.

Authorization URL

The URL used for first contact with and authorization on the authorization server. It is specified in the (API) documentation of the application you require access to.

Token URL

The URL used for getting and refreshing the access token from the authorization server. It is specified in the (API) documentation of the application you require access to.

Client Id

Public key called 'Client Id' used to identify the application you want to connect to. It is created in the application you require access to.

Client Secret

Secret key called 'Client Secret' used to authenticate on the authorization server. It is created in the application you require access to.

Scope

Specify the permissions that are granted to an access token. It is specified in the (API) documentation of the application you require access to.

Refresh Token Delay

Defines how many seconds before the expire_date an access token is allowed to be refreshed, default is 25 seconds.

Header name - Tenant variable

The name of the header and tenant variable for setting / storing the access token. Read more about Using Variables.

Redirect URL and Authorize

On the bottom of the settings you see the redirect URL for the test and production environment. Paste the applicable redirect URL into the settings of the application you require access to (you can use the copy button).

Click the Authorize button after you've completely set up the component and settings in the application you require access to. A popup appears prompting you to fill in the user credentials of the application (optionally you have to agree to the terms).

When the OAuth2 token received with success! message appears you've succesfully retrieved the first set of access and refresh tokens.

Scheduling SetOAuth2Token component

The SetOAuth2Token component has to be combined with a Scheduler component in order to periodically check if the access token is ready to be refreshed. The refresh window is the time between (expire_date minus Refresh Token Delay) and the expire_date of the token.

Imagine your access token is valid for 60 minutes and you receive a set of new tokens at 12h00. If the Refresh Token Delay is set to 1 minute, the refresh window is between 12h59 and 13h00. (Technically you can refresh after 13h00 as long as your refresh token is still valid, but then you won't have a valid access token from 13h00 until it is refreshed.)

The Scheduler has to trigger the SetOAuth2Token component within this refresh window. A good Repeat Interval value for the Scheduler is the Refresh Token Delay time divided by 2.

Scheduler settings for the example above:

• Method set to Repeats
• Repeat Count set to -1 (repeat indefinitely)
• Repeat Interval set to 30000 milliseconds (30 seconds)

Scheduling for Google Drive

Use the Scheduler settings below for the Google Drive Credentials Type:

• Method : Repeats
• Repeat Count : -1
• Repeat Interval : 15000 milliseconds

Remarks

note

• This component uses The OAuth 2.0 Autorization Framework.
• How long access & refresh tokens are valid, Client Id, Client Secret, Token URL, Authorization URL and Scope are defined by the application you require access to. Please refer to your application (API) documentation.

OAuth2 Tenant variables

After succesfully setting up the component the following tenant variables will be set:

Tenant variable name	Description
oauth2_<guid>_access_token	The access token
oauth2_<guid>_client_id	The Client Id
oauth2_<guid>_client_secret	The Client Secret
oauth2_<guid>_credentials_type	The type of access token
oauth2_<guid>_expire_date	The Unix timestamp representing the expiration date and time. It is calculated by adding the expires_in value from the JSON token response to the Unix timestamp recorded at the time of receiving the response
oauth2_<guid>_redirect_uri	The Redirect URL
oauth2_<guid>_refresh_flag	Flag for refreshing status: 1 => token is being refreshed (other processes will not be allowed to refresh this token simultaneously) 0 => token is not being refreshed (a process is allowed to start refreshing the token)
oauth2_<guid>_refresh_token	The refresh token
oauth2_<guid>_scope	The Scope
oauth2_<guid>_uri_authorize	The Authorization URL
oauth2_<guid>_uri_token	The Token URL

caution

Editing any of these tenant variables can break the process of refreshing of tokens.

Example JSON token response

{
  "access_token":"2NDE1ZTZjNGZmZjI3...MTQ0NjJkZmQ5OTM",
  "token_type":"Bearer",
  "expires_in":3600,
  "refresh_token":"TQ5MGE3YmNmMDFkNTVk...IwOGYzYTlmM2YxO",
}

Last update on Nov 18, 2024