OAuth2 Connection

Owned by Ondřej Tesař
Aug 26, 2024
4 min read

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:

  1. reAuthOnCodes – When this parameter is set, token expiration is set to one year.

  2. 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.

  3. 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 version 5.8.0