OAuth2 Gateway

OAuth2 Gateway

The OAuth2 Gateway is a special purpose version of the HTTP Gateway. It is able to perform HTTP requests to resource servers that are protected with OAuth2 op OpenID Connect (OIDC).

The OAuth2 Gateway supports the OAuth2 "Client Credentials" grant type. This grant type allows backend application to request access tokens from authorization servers. It requires a client ID, client secret and token URI.

A client should be registered with the OAuth2 authorization server before using the OAuth2 Gateway and granted permission to acquire access tokens via the client credentials grant type. After registering a client with the authorization server, you should have a client ID and client secret.

The token URI is a global property of your authorization server. Consult your administrator or the authorization server's documentation to discover its value. This URI is used by clients to request access tokens.

Please note that the OAuth2 Gateway does not support the "Authorization Code" grant type. The ConnectAgent is intended be run as a backend application and as such cannot support this grant type which requires a user to be present at times to log in.

Multipart/form-data upload

The gateway also supports uploading ConnectMessages as multipart/form-data. You will need to Enable Multipart Upload to use this feature.

A ConnectMessage can consist of multiple message parts. The Multipart Specification TypeMultipart List and Multipart List attributes determine which of these parts are included in the resulting multipart/form-data upload.

Each part in a multipart/form-data request has its own Content-Type header. The default Content-Type value depends on the type of ConnectMessagePart that is included:

ConnectMessagePart type Multipart/form-data part Content-Type
TEXT text/plain; charset=utf-8
DOCUMENT (XML) application/xml; charset=utf-8
BYTE_ARRAY application/octet-stream
OBJECT application/octet-stream
FILE application/octet-stream

The default Content-Type can be overridden by adding a header multipart.content-type to the ConnectMessagePart with the desired value. Note that in the case of TEXT or DOCUMENT parts if the new Content-Type includes a charset attribute, this charset is used to convert the payload to the desired character encoding.

Besides a Content-Type header each part in the multipart/form-data payload will also have a Content-Disposition header with the value form-data. The Content-Disposition header value has a mandatory name attribute. By default this name attribute gets the name of the ConnectMessagePart. There is also an optional filename attribute that by default is not set. The name and filename attributes can be explicitly defined by adding a multipart.name and multipart.filename header to the ConnectMessagePart.

In the table below, you will find an explanation of these properties. All attributes with a ‘*’ are mandatory.

Attribute Description
Name* By default, we fill this out with the technical ‘tag’, followed by a serial number. Changing the name is optional.
Enabled Set this value to true, if you want this service to be enabled at startup
MessagePart In Specify the name of the MessagePart, which will be used as input. The value of this MessagePart becomes the POST data in a POST request or is used as the URL, depending on the definition of the URL parameter.
MessagePart Out Specify the name of the MessagePart, which will be used as output for the service method. The response of the HTTP request is put on this MessagePart.
URL SPecification Type

Choose the URL specification type. This attribute can have the following values:

  • FIXED
  • FROM_HEADER
  • FROM_SPEL_EXPRESSION
URL The URL location where the HTTP request has to go.
URL Header

Note thad this attribute is only visible when the attribute URL Specification Type has value FIXED.

The URL location where the HTTP request has to go.

URL SpEL Expression

Note that this attribute is only visible when the attribute URL Specification Type has value FROM_SPEL_EXPRESSION.

The Spring Expression Language (SpEL) expression to evaluate the URL.

HTTP Method Specification Type

Choose the HTTP Method specification type. This attribute can have the following values:

  • FIXED
  • FROM_HEADER
  • FROM_SPEL_EXPRESSION
HTTP Method Choose the HTTP Method.
HTTP Method Header

Note that this attribute is only visible when the attribute HTTP Method Specification Type has value FROM_HEADER.

The ConnectMessage header name where the HTTP Method is located.

HTTP Method SpEL Expression

Note that this attribute is only visible when the attribute HTTP Method Specification Type has value FROM_HEADER.

The ConnectMessage header name where the HTTP Method is located.

Encode URI Switch to enable or disable the encoding of URLs. The default is true.
Timeout Maximum time in milliseconds to wait on a single request. Default is '0' which means indefinitely.
Mapped Request Headers A comma separated list of headers to be mapped from the ConnectMessage to the HTTP request.
Mapped Response Headers A comma separated list of headers to be mapped from HTTP response to the ConnectMessage.
Content Type Specify the value of the Content-Type header.
Token URI* The authorization server's token endpoint used to request new access tokens.
Client ID* The client ID used for OAuth 2.0.
Client Secret* The client secret used for OAuth 2.0.
Username

Note that this attribute is only visible when the attribute OAuth2 Grant Type has value RESOURCE_OWNER_PASSWORD_CREDENTIALS.

The username of the resource owner.

Password

Note that this attribute is only visible when the attribute OAuth2 Grant Type has value RESOURCE_OWNER_PASSWORD_CREDENTIALS.

The password of the resource owner.

Refresh Token

Note that this attribute is only visible when the attribute OAuth2 Grant Type has value REFRESH_TOKEN

The refresh token.

OAuth2 Scopes An optional comma separated list of OAuth2 scopes.
Resources

An optional comma-separated list of resources that will be included in the access token request. See RFC8707 for more information.

Client Authentication Method

If applicable, the manner in which client credentials are offered to the token endpoint. This attribute can have the following values:

BASIC
POST
Use Form URL Encoded Switch to enable or disable use application/x-www-form-urlencoded.
Expected Response Type Class to specify return type. The default is a 'java.lang.String'.
Enable Multipart Upload

Enables uploading ConnectMessageParts as multipart/form-data. Note that this overwrites the Content Type and the MessagePart In attributes.

Multipart Specification Type

Only available if Enable Multipart Upload is set to true.

The manner in which to define which ConnectMessageParts are to be included.

ALL - Include all part.

LIST - Include only the parts that are mentioned in a list of part names.

REGEX - Include only the parts that match a regex.

Multipart List

Only available if Multipart Specification Type is set to LIST.

A list of ConnectMessageParts that should be included in the multipart upload.

Multipart Regex

Only available if Multipart Specification Type is set to REGEX.

If the name of a ConnectMessagePart matches this regex, this part is included in the multipart upload.

Expected Response Type Class to specify return type. The default is a 'java.lang.String'.
Enable Request/Response Logging Enable request/response logging. WARNING: this includes a complete hexdump of the request and response, which will greatly increase the size of log files.
Codec Buffer Size

Note that this attribute is only visible when advanced mode is enabled.

The size of the codec buffer in MB.

Description

Description of the specific service. This is for documentation purposes.