OAuth 2.0 access tokens typically have a very limited lifetime. To enable webMethods.io Integration to refresh a configured access token, you must configure Refresh Access Token to true and Session Management to fixed or auto.
To use the Out-of-Box refresh implementations offered by webMethods.io Integration, configure Refresh URL Request as URL Query String or Body Query String along with appropriate values for the fields Consumer ID, Consumer Secret, Refresh Token, Refresh URL, and Access Token. This option can be used if the API provider adheres to the standard implementation of the Refresh grant type as described by the OAuth 2.0 Authorization Framework specification.
The following example provides you information on how to implement and configure a custom refresh mechanism for Accounts using webMethods.io Integration.
Before you begin
- When using the REST connector, if you are using Google API services, then you need to have a working Google account to log into the Google Cloud console to obtain the access token for OAuth 2.0 authorization.
- You need to have access permission for Google APIs.
- When using the endpoint target (Server URL) to initiate communication with the SaaS provider, for example, Twitter, the endpoint is https://api.twitter.com/1. To get the endpoint, go through the SaaS connector documentation available on the internet.
- When using Custom Connector, every back end provides its own authentication mechanism. Get the authentication details from the backend documentation.
- You need to have a relevant Google connector app in Google Cloud Platform to retrieve its Client ID and Client Secret if using any Google APIs.
Basic Flow
Before you try to configure a refresh token callback for a REST connector, you must have the following configurations (Step 1 - Step 3) completed on the Accounts configuration page:
1.Get the endpoint target (Server URL) for the connection configuration. For example, (https://api.twitter.com/1.1).
- Get the Consumer ID and Consumer Secret issued to the client to identify itself to the authorization server. Consumer Secret is a secret matching to the client identifier.
- Configure the Session Management parameters to determine at what intervals the access token would be considered for a refresh.
The access token is refreshed during the next immediate execution after the determined interval. Session expiration is handled according to the setting of the Session Management property in your configuration. To refresh the ‘Access Token’ automatically, set the Session Management to either fixed or auto. The Timeout value should be based on the back-end settings.
Note: If Session Management is set to none, then the access token will not be refreshed.
- Select Refresh URL Request field as Refresh token callback service to configure a custom refresh implementation. This field is available only if the OAuth v2.0 authentication type is selected.
When you select this option, you must specify the FlowService name in the Refresh token callback service field. This is a service that needs to be implemented by a user. The Refresh token callback service option allows you to create a FlowService, which will be executed when the access token has expired or is not valid. You can view the link of the same FlowService on the REST Connectors page.
- Click the custom callback FlowService name in the REST Connectors page to create a new FlowService.
You must add the implementation for refreshing the access token in the Callback FlowService.
The FlowService adhere to the specification with the input and output parameters shown below:
These are the inputs that would be provided to the Custom callback FlowService implementation by webMethods.io Integration. Values will correspond to the current values of these fields in the account configuration
These are the output expected by webMethods.io Integration. The values returned for these fields will determine the inputs for the subsequent API and refresh execution.
- access_token - The access token issued by the authorization server, applicable for subsequent API and refresh executions.
-
token_type - The type of the token issued. For example,
bearer. - expires_in - The lifetime in seconds of the access token. For example, the value 3600 denotes that the access token will expire in one hour from the time the response was generated. Relevant for auto session management where expiry interval returned by API provider is given precedence.
- refresh_token - The refresh token to be used for subsequent refresh execution.
- scope - (Optional) If identical to the scope requested by the client; else, REQUIRED
- errorResponse - The details of the error in refresh execution.
The newly created FlowService will generate an access token that is mapped to the access token field in the output signature.