Skip to main content

External Authentication

Fenergo supports both mTLS (Mutual Transport Layer Security) and OAuth 2.0 Client Credentials on outbound traffic originating from the following services:

  • Webhooks
  • External Data Adapters
  • Screening Adapters

It is important to note that mTLS and OAuth 2.0 Client Credentials are not mutually exclusive. They can be utilized either in tandem or independently.

mTLS bolsters security through bilateral certificate verification. Unlike traditional TLS, where only the server provides a certificate for verification, mTLS mandates that both the client and server present and authenticate each other's certificates. This process intensifies the trust relationship.

On the other hand, OAuth 2.0 Client Credentials ensure that only authenticated outbound services (as listed above) have the capability to access your protected resource APIs. This mechanism offers a fortified layer of security for server-to-server interactions.

External Authentication as an add-on​

Both mTLS and OAuth 2.0 Client Credentials are set up as add-on services to our outbound services (as mentioned above). Therefore, their settings or configurations are not directly accessible under these existing outbound services. Instead, they can be configured or enabled for these outbound services using the following endpoints:

note

The capability to incorporate mTLS or OAuth 2.0 Client Credentials as an 'add-on' ensures that there's no need to update existing outbound services to enable mTLS.

How It Works​

You can configure the External Authentication service for your specific Client Hosted Endpoints that require either mTLS, OAuth authentication, or both. When a request originates from one of the outbound services (as previously mentioned), it's adjusted based on that particular configuration. In the case of mTLS, the pertinent certificate and validation checks are integrated into the request. For OAuth 2.0 Client Credentials, the designated Client Hosted Authorization Endpoint is called upon to retrieve the access token. This token is subsequently added to the request before it's sent to your Client Hosted Endpoint.

Within the framework of our outbound services (as outlined above), FenX operates as the 'client', while your Client Hosted Endpoint assumes the server role.

Configuration is done per Client Hosted Endpoint​

External Authentication is provided on a 'per URL' basis. This means that each Client Hosted Endpoint that our outbound services access must be individually configured with the appropriate mTLS and/or OAuth 2.0 Client Credential settings using our ExternalAuthentication Command API.

note

For both our External Data and Screening Adapters, multiple configurations need to be set up. Specifically, one configuration for each Client Hosted Endpoint, which will be detailed later in this document.

How to Implement External Authentication​

mTLS​

To implement mTLS, ensure you have the following components in place:

Client Certificate​

Fenergo will provide you with a 'client' certificate. Install this certificate in your server's trust store. By doing so, when our outbound adapters send a request to your Client Hosted Endpoint in real time, your server will be able to validate and authenticate our 'client' certificate, thus fulfilling its part in the mTLS handshake.

Server Certificate​

On the other hand, we need you to supply us with your server's leaf certificate (public key only) in PEM format. This certificate, which is the final certificate in the chain and cannot sign other certificates, will be used to authenticate your server and complete the mTLS handshake. You can submit this leaf certificate via our ExternalAuthentication Command API

Pre-requisites​

Before configuring the External Authentication service, ensure you've completed the following tasks:

  • Install the Fenergo client certificate in client's external infrastructure.
  • Have your server certificate(leaf) in PEM format ready.

Configuration​

Once you've met the prerequisites, you can start configuring your first Client Hosted Endpoint. Navigate to the desired outbound service (mentioned above) and copy its URL (Client Hosted Endpoint). With this URL, you can set up a configuration that enables mTLS specifically for that URL (Client Hosted Endpoint). Configuration is done via the ExternalAuthentication Command API.

note

mTLS Configuration is configured separately from your webhooks, external data and screening adapters. You simply add an 'External Authentication Configuration' using the existing webhook/external data/screening adapter' URLs.

OAuth 2.0 Client Credentials​

To implement the OAuth 2.0 Client Credentials flow for any of your Client Hosted Endpoints, you must have a publicly accessible Client Hosted Authorization Endpoint available. This endpoint should adhere to the OAuth 2.0 Client Credentials flow specification, i.e.:

  • It must accept the client_id and client_secret parameters:
  • Either as part of the authorization header (if basic authentication is enabled)

Sent as part of the header as follows:

HeaderValue
AuthorizationBASIC {Base64({client_id}:{client_secret})}

As part of the request body with the parameters:

  • client_id
  • client_secret

Your publicly accessible Client Hosted Authorization Endpoint must accept a 'grant_type' parameter of 'client_credentials' in the request body, e.g.:

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
  • Parameters that are sent in the request body use the "application/x-www-form-urlencoded" format
  • The response must include an access token and optionally an 'expires_in' parameter as follows:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "expires_in":3600,
}

Before configuring the External Authentication service, ensure the following components are in place:

  • A publicly accessible OAuth 2.0 Client Hosted Authorization Endpoint.
  • Client credentials with the necessary permissions for the Client Hosted Endpoint.
  • Knowledge of whether Basic Authentication is enabled.

Configuration:

Once you've met the prerequisites, you can start configuring your Client Hosted Endpoint. Navigate to the desired outbound service (mentioned above) and copy its URL (Client Hosted Endpoint). With this URL, you can set up a configuration that enables the OAuth 2.0 Client Credentials flow, specifically for that URL (Client Hosted Endpoint). Configuration is done via the ExternalAuthentication Command API.

Custom Headers and Form Values​

You may specify additional custom header and form values that will be sent to your Client Hosted Authorization Endpoint as part of the authorization request.

info

Form values are sent to the Client Hosted Authorization Endpoint using the "application/x-www-form-urlencoded" format as per RFC 6749 specification.

note

OAuth 2.0 Client Credentials Configuration is configured separately from your webhooks, external data and screening adapters. You simply add an 'External Authentication Configuration' using the existing webhook/external data/screening adapter' URLs.

mTLS and OAuth 2.0 Client Credentials​

You can configure a single Client Hosted Endpoint to support both mTLS and OAuth 2.0 Client Credentials. However, it's crucial to note that when enabling OAuth 2.0 Client Credentials, an additional Client Hosted Authorization Endpoint is introduced. You need to decide whether this Token Endpoint should also be mTLS-enabled and if its mTLS configuration matches that of the Client Hosted Endpoint.

note

The useEndpointMtlsConfiguration parameter, which is part of the oAuthConfiguration.clientCredentialsConfig object, determines whether the Client Hosted Authorization Endpoint should use the same mTLS settings as the Client Hosted Endpoint or have its own distinct mTLS configuration.

External Data and Screening Adapters​

For external data and screening adapters, additional External Authentication endpoints need to be configured. This is because both the External Data and Screening adapters make calls to various endpoints. As such, each of these endpoints need to be configured with the relevant mTLS/OAuth 2.0 Client Credential settings via the External Authentication API's.

Below are the specific endpoints that need to be enabled via the External Authentication APIs:

External Data:

  • authurl/adapter/test
  • authurl/adapter/search
  • authurl/adapter/get
  • authurl/adapter/document

Screening:

  • authurl/api/test
  • authurl/api/screen
  • authurl/api/resolvematches
  • authurl/api/ongoingscreening
  • authurl/api/ongoingscreeningupdate
info

Please be aware that the introduction of mTLS and/or OAuth 2.0 Client Credentials does not affect the existing HMAC mechanism on our various adapters, and as such it remains intact and operational as before.

Permissions​

You require the following permissions in order to add an mTLS/OAuth 2.0 Client Credential enabled endpoint (configuration):

  • External Authentication Configuration Access
  • External Authentication Configuration Create
  • External Authentication Configuration Edit
  • External Authentication Configuration Delete