OAuth2 endpoint parameters for gateway authentication

The v3.42.0 release added a new GatewayOAuth2EndpointParams configuration option to support customization of Elimity Insights' access token retrieval for gateway authentication. By default, assuming EnableGatewayOAuth2 is true, Elimity Insights will perform a basic OAuth2 client credentials flow. The GatewayOAuth2EndpointParams configuration option allows inclusion of additional parameters in the access token request. It should be a record mapping parameter names to Expr programs that result in the respective parameter's value.

As an example we'll explain how this feature allows us to provide out-of-the-box gateway authentication to our SaaS customers. As detailed in our documentation about gateway-based imports, we want to include base_url, gateway_url and source_id custom claims in the access tokens from our own OAuth2 server. To achieve this, we first need to make sure Elimity Insights provides the additional information in its token requests. For example, a token request from https://example.elimity.com for a gateway at https://gateway.example.com to import into a source with id 42 should look like this:

POST /oauth/token HTTP/1.1
Host: auth.elimity.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=example-client-id&
client_secret=example-client-secret&
audience=gateway&
base_url=https%3A%2F%2Fexample.elimity.com&
gateway_url=https%3A%2F%2Fgateway.example.com&
source_id=42

This corresponds to the following configuration for Elimity Insights:

Configuration option	Value
EnableGatewayOAuth2	true
GatewayOAuth2ClientId	"example-client-id"
GatewayOAuth2ClientSecret	"example-client-secret"
GatewayOAuth2EndpointParams.audience	"'gateway'"
GatewayOAuth2EndpointParams.base_url	"baseURL"
GatewayOAuth2EndpointParams.gateway_url	"gatewayURL"
GatewayOAuth2EndpointParams.source_id	"sourceID"
GatewayOAuth2TokenUrl	"https://auth.elimity.com/oauth/token"

Each value in the GatewayOAuth2EndpointParams record must be a valid Expr program with result type string. Elimity Insights will inject the following variables:

Variable	Type	Description
baseURL	string	Base URL of the Elimity Insights server
gatewayURL	string	URL of the gateway to import data from
sourceID	string	Unique identifier of the source to import data into