Using OAuth2 with Client Credentials in QIE
QIE has made the process of retrieving, caching and managing of bearer tokens easy. In fact, once configured, this process becomes automatic.
QIE has added OAuth2 with Client Credentials support in version 4.0.48. It is configured as part of the WS Connections in the Authentication Protocol section. Below is an example configuration:
Testing OAuth2 in QIE
When configuring a new OAuth2 endpoint, it is helpful to save the configuration and test the OAuth process. Once the Web Service Connection is saved, you can use the Test OAuth button to perform a roundtrip of obtaining a bearer token. Depending on the refresh options, QIE can also attempt a second roundtrip to test the refresh token as well. The results are displayed in a test log dialog. Use the View menu -> Extract & Format Code to easily format and view the response payload.
Note: Using the Test OAuth button will help you identify the appropriate nodePaths in the configuration.
OAuth2 Field Descriptions in QIE:
Authentication: "OAuth2 with Credentials" is the new option.
Method: Some authentication endpoints require POST and others require GET to obtain a token. You have both options.
For consistency with the other QIE Webservice configurations, we used the traditional Username/Password field labels to represent Client Credentials. Your client credentials are often referred to by different names depending on the endpoint. Here are some examples of the different labels we have seen:
- Username/Password
- Client ID/Client Secret
- API Key/Source Secret
Credentials are given to you as you register for your web service access.
Username: This is your Username or Client ID or API Key that was given by the web service.
Password: This is the second have of your credentials. It is your Password, or Client Secret, or Source Secret.
Include Basic Authentication in Header?: Some endpoints require the credentials formatted in the traditional Basic Authentication Header. This is generally needed if the Method field above is GET. If unchecked, the credentials will need to be included in the payload submitted.
Auth URL: This is the URL to send the authorization request. This is provided by the web service.
Content-Type: When using the POST Method, the Content-Type of the payload must be specified. This is generally either application/x-www-form-urlencoded or application/json.
Payload: This is the payload to send to the authorization endpoint.
To make it easy to use the credentials in the context of the payload, the following node tags can be used:
{ws-user:self} - Uses the username for the current webservice.
{ws-pass:self} - Uses the password for the current webservice.
For application/json, remember to add the proper escaping:
/*{ws-user:self}*/ - JSON escaped node tage for username
/*{ws-pass:self}*/ - JSON escaped node tage for password
Token Path: This is the json nodePath to the bearer token or sometimes called access token. This is part of the JSON response from the authentication endpoint. This value is often /access_token or /accessToken.
Token Refresh: This tells QIE how to manage and refresh the bearer token. These will offer some additional Refresh Token Configurations. The options are:
- Refresh upon token failure - A new token will be obtained after an HTTP 401 Unauthorized error occurs. (This behavior will also occur for all of these options.)
- Refresh after fixed time - A new token will be obtained after a fixed time.
- Refresh when the token expires - A new token will be obtained based on the expired field in the response payload.
- Refresh based on token - A new token will be obtained based on the expired field in the response payload. There are additional fields to define the refresh token requirements without using the original client credentials.
Refresh Token after: If the Refresh after fixed time option is used, specify the number of seconds between refreshes. There is no prescribed lifetime of a token. The creator or of the BearerToken decides. BearerTokens can expire in a minute, an hour, or sometimes a week. It just depends on the web service.
Expire Path: If the Refresh when token expires or the Refresh based on token options are used, specify a JSON nodePath for the expiration of the token. This will be part of the JSON response from the authentication endpoint. This value is often /expires or /expires_in.
Refresh Token: If the Refresh based on token option is used, specify the JSON nodePath for the refresh token. This is part of the JSON response from the authentication endpoint. Note: the bearer token and refresh token are not the same thing. The bearer token grants access to the webservice. The refresh token is used only during the refresh process. This value is often /refresh_token or /refreshToken.
Refresh URL: If the Refresh based on token option is used, specify the refresh URL provided by the web service.
Refresh Payload: If the Refresh based on token option is used, configure the refresh payload provided by for the web service. The previously described {ws-user:self} and {ws-pass:self} node tags can be included in this context as well. In addition the following tag is also available in this context for referencing the refresh token:
{ws-refresh-token:self} - Node tage for using the existing refresh token.
/*{ws-refresh-token:self}*/ - JSON escaped node tag for using the existing refresh token.
