This connection authenticates with OAuth2 authentication systems.

Properties

Option	Type	Default	Description

Option	Type	Default	Description
`id`	string		ID of the connection.
`url`	string		Base URL of the connection. A full path must be provided (e.g.: https://...).
`headers`	java.util.Map		Custom headers.
`certificateName`	string		Name of the certificate.
`authUrl`	string		Endpoint used for authentication purposes. This is often a separate endpoint which provides token for further calls. A full path must be provided (e.g.: https://https://login.salesforce.com/services/oauth2/token).
`authRequestHeaderBearer`	string	Bearer	Prefix used in the authentication request header. Usually, the value is 'Bearer' in this kind of authentication.
`authRequestHeader`	string	Authentication	Header used for authentication.
`authRequestContentType`	string		Content type of the authentication request. This should adhere to the server requirements. Usually, 'application/x-www-form-urlencoded' is used for OAuth2-based authentications, whereas 'application/json' is used for JWT-based authentications.
`authResponseTokenKey`	string		Defines a key from which token is parsed. E.g. if auth response is {'token': ‘aaa', 'expires':'155555'}, the actual token is in the 'token' key, thus the value of the field is 'token’.
`authResponseExpirationKey`	string		Token validity is often limited. If the response returns the token expiration, the key will be parsed and re-authentication will be automatically made once the token expires. E.g. if auth response is {'token': 'aaa', 'expires':'155555'}, the actual token is in the 'expires' key, thus the value of the field is 'expires'. The token will be automatically refreshed in 155 555 milliseconds.
`authResponseExpirationKeyLocation`	string		Defines location of the field 'expires_in' (or other selected) when it is returned. Options are: body_json, body_plaintext, header_json, header_plaintext. E.g., body_json means that 'expires' is located in the JSON response body. Possible values are: body_json, body_property_based, header_json, header_plaintext.
`reAuthOnCodes`	string		When a list of values separated by a comma is defined, whenever a certain code from list is returned from any request, the authorization is called again. This occurs for example in Salesforce. Example value: 400,401,404.
`authExpirationMultiplier`	string		Token expiration is handled in milliseconds by default. Specify a multiplier if the unit is different (1=ms, 1000=s, ...).
`username`	string		Username used for authentication. Not always required in OAuth2 authentication – it depends on the system.
`password`	string		Password used for authentication. Not always required in OAuth2 authentication – it depends on the system.
`clientId`	string		Client ID used for authentication. Not always required in OAuth2 authentication – it depends on the system.
`clientSecret`	string		Client secret used for authentication. Not always required in OAuth2 authentication – it depends on the system.
`scope`	string		Scope of the authentication request.
`authRequestTemplate`	string		Describes an authentication template. Useful when the target system has different auth params needed. Example value: `{\"grant_type\": \"password\",\"client_id\": \"::clientId\",\"client_secret\": \"::clientSecret\",\"username\": \"::username\",\"password\":\"::password\"}`
`authRequestContentType`	string		Content type of the authentication request. This should adhere to the server requirements. Usually, 'application/x-www-form-urlencoded' is used for OAuth2-based authentications, whereas 'application/json' is used for JWT-based authentications.

Examples

Define a new connection:

<bean id="oauth2Conn" class="net.pricefx.integration.component.rest.domain.connection.OAuth2Connection">
    <property name="url" value="https://thecompany.com"/>
    <property name="authUrl" value="https://thecompany.com/auth"/>
    <property name="scope" value="admin_view"/>
    <property name="clientId" value="123"/>
    <property name="clientSecret" value="aaqqxx"/>
    <property name="authRequestTemplate" value="{"grant_type": "password","client_id": "::clientId","client_secret": "::clientSecret"}"/>
</bean>

Use it in a route:

<route id="opendata2-create">
  <from uri="direct:create"/>
  <to uri="pfx-rest:post?uri=/A_SalesOrder&amp;connection=oauth2Conn"/>
  <to uri="mock:create"/>
</route>

Results:

Request to https://thecompany.com/auth is done, auth response is parsed according to the properties definition. The token is extracted, expiration is extracted.
Request to https://thecompany.com/A_SalesOrder was done with the header PartitionX and value Pricefx xxx(xxx is retrieved token).
Data are returned.

Custom OAuth2 API Setup Example

Let's assume that a target endpoint has the OAuth2 protection but the token endpoint accepts the XML structure, such as:

Example input

<?xml version="1.0" encoding="UTF-8"?>
<content>
	<clientId></clientId>
	<clientSecret></clientSecret>
	<username></username>
	<password></password>
	<grantType></grantType>
</content>

And a response with JSON:

Example input

We then provide a connection named conn123 configured like this:

Example input

And perform:

Example input

This will result in a response with data.

Accesing OAuth2 Resource with Different Auth Structure

It is possible to change the default authentication template to comply with requirements of the specified resource. You must use placeholders to properly bind parameters from the connection.

Let's assume that the resource requires application/x-www-form-urlencoded request with the following body:

Example input

This can be achieved by specifying the OAuth2 connection via XML DSL:

Example input

Several things to observe:

authRequestTemplate is defined as JSON – this is required because otherwise it cannot be converted to x-www-form-urlencoded which is the default (and the only one acceptable) in OAuth2.
We use placeholders ::clientId and ::clientSecret which are defined in the properties.
We do not specify username and password since they are not required.

Re-authentication

When an access token expires, the next request needs to be authenticated again. After a successful authentication call, token expiration time is set based on the following parameters:

reAuthOnCodes – When this parameter is set, token expiration is set to one year.
If reAuthOnCodes is empty, token expiration time is fetched from a field with a name defined in the authResponseExpirationKey parameter. Time is in milliseconds by default, but can be adjusted by authExpirationMultiplier parameter (1=ms, 1000=s, ...). Only time units are supported, OAuth2 connection does not support absolute dates. The default value of authResponseExpirationKey is "expires_in" and it is taken from the authentication response body. Sample authentication response:
In this example, expiration time is 3600000, so the token will be valid for 1 hour.
If reAuthOnCodes is empty and the authResponseExpirationKeyLocation parameter is set, then token expiration time (in milliseconds) is fetched from a field with a name defined in the authResponseExpirationKey parameter, but it will not be taken from the authentication response body, but from the place defined in the authResponseExpirationKeyLocation parameter.

The following are valid authResponseExpirationKeyLocation parameter values:
body_json – Token expiration value will be taken from a field from the authentication response body which is in JSON format.
body_property_based – Token expiration value will be taken from a field from the authentication response body which is in the following format "a=b,c=d,x=f,...".
header_plaintext – Token expiration value will be taken from the authentication response header which is plain text.
header_json – Token expiration value will be taken from the authentication response header which is in JSON format.

Additionally, when the parameter reAuthOnCodes is set, whenever any request returns a response with code contained in that list, the token expiration is set to -1, effectively making it expired, and forcing authentication before the next call.

IntegrationManager Documentation

OAuth2 Connection

Properties

Examples

Custom OAuth2 API Setup Example

Accesing OAuth2 Resource with Different Auth Structure

Re-authentication