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 how to setup Scheduling SetOAuth2Token component below.

Configuration

This component has the following configuration options:

• Authorization URL
• Token URL
• Client Id
• Client Secret
• Scope
• Refresh Token Delay
• Header name - Global variable
• Redirect URL and Authorize

Authorization URL

Description

The URL used for first contact with and authorization on the authorization server.

Remarks

• The Authorization URL is specified in the (API) documentation of the application you require access to.

Token URL

Description

The URL used for getting and refreshing the access token from the authorization server.

Remarks

• The Token URL is specified in the (API) documentation of the application you require access to.

Client Id

Description

Public key called 'Client Id' used to identify the application you want to connect to.

Remarks

• The Client Id is created in the application you require access to.

Client Secret

Description

Secret key called 'Client Secret' used to authenticate on the authorization server.

Remarks

• The Client Secret is created in the application you require access to.

Scope

Description

Specify the permissions that are granted to an access token.

Remarks

• The Scope settings are specified in the (API) documentation of the application you require access to.

Refresh Token Delay

Description

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

Header name - Global variable

Description

The name of the header and global variable for setting / storing the access token.

Redirect URL and Authorize

Description

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 and optionally consent to the required permissions.

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 can be refreshed. The refresh window is the time between (expire_date minus Refresh Token Delay) and the expire_date.

For example, if your access token is valid for 60 minutes and the Refresh Token Delay is set to 1 minute:

• The refresh window is between 59 and 60 minutes.
  (Technically you can refresh after the expire_date, but you won't have a valid access token from 60+ minutes onwards until the access token is refreshed.)
• Your Scheduler has to trigger within this refresh window and therefore its Repeat Interval has to be lower than the Refresh Token Delay time.
• Set Scheduler Repeat Count to -1 so it repeats indefinitely.

OAuth2 Global variables

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

Global variable name	Description
oauth2_<component_guid>_access_token	The access token
oauth2_<component_guid>_client_id	The Client Id
oauth2_<component_guid>_client_secret	The Client Secret
oauth2_<component_guid>_expire_date	The unix timestamp of the expiration date & time
oauth2_<component_guid>_redirect_uri	The Redirect URL
oauth2_<component_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_<component_guid>_refresh_token	The refresh token
oauth2_<component_guid>_scope	The Scope
oauth2_<component_guid>_uri_authorize	The Authorization URL
oauth2_<component_guid>_uri_token	The Token URL

Important! Editing any of these Global variables can break the process of refreshing of tokens.

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.