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.
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.
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 toRepeats
Repeat Count
set to-1
(repeat indefinitely)Repeat Interval
set to30000
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
- 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 |
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",
}