Enricher

Introduction

Enricher is a component that can be used for calling web services and returning their response or a part of it. This JSON can be returned as it is or "enriched" into another JSON. It is built into Audit, but can also be used as a separate component in another systems.

Web service requirements

In order to be called by enricher the web service should match the following requirements:

  • HTTP Web service
  • Should return JSON as a response in the HTTP response Body
  • Should accept the parameters if any in the following way:
    • GET
      • URL parameters specified as a query argument i.e. /api/resource?parameter=value
      • URL parameters specified as a part of the URL path i.e. /api/resource/parametervalue
    • POST - should support a JSON request body e.g.
{
    "parameter": "value"
}

it is not recommended by RESTful specifications to use POST for data retrieval, but it can be done in some circumstances

  • The web service should be protected in one of the following way:
    • with a static Bearer token that should be passed in "Authorization" Header of the request
    • with a Bearer token that should be retrieved from an authorization service using OAuth 2.0 authorization protocol. In this case Authorization Server Url, CertificateThumbprint, ClientId and Required Scopes must be specified
    • with a Bearer token that should be retrieved from an authorization service using OAuth 2.0 authorization protocol. In this case Authorization Server Url, ClientId, ClientSecret and Required Scopes must be specified.

Examples

Below are a few examples of enricher configurations with different parameters.

HTTP GET with static token authorization

{
  "name": "weather",
  "type": "http",
  "url": "https://weather.nu/external_api",
  "httpMethod": "GET",
  "bearerToken": "b09e2254-6ade-4e44-9c98-25eefed5599a",
  "input": {
    "parameters": [
      {
        "name": "country",
        "type": "selector",
        "value": "$.address.country"
      },
      {
        "name": "date",
        "type": "selector",
        "value": "$.date"
      }
    ]
  },
  "output": {
    "resultSelector": "",
    "injectAs": "$.weather"
  }
}

HTTP GET with OAuth 2.0 authorization using Authorization server and certificate

{
  "name": "weather",
  "type": "http",
  "url": "https://weather.nu/external_api",
  "httpMethod": "GET",
  "authorizationServerUrl": "https://oauth.weather.nu",
  "oAuth2CertificateThumbprint": "1d4b45e90df21fce012c9a804a5b7c166326c6cf",
  "oAuth2ClientId": "some_id",
  "requiredScopes": [
    "weather:read"
  ],
  "input": {
    "parameters": [
      {
        "name": "country",
        "type": "selector",
        "value": "$.address.country"
      },
      {
        "name": "date",
        "type": "selector",
        "value": "$.date"
      }
    ]
  },
  "output": {
    "resultSelector": "",
    "injectAs": "$.weather"
  }
}

HTTP GET with OAuth 2.0 authorization using Authorization server and client credentials flow

{
  "name": "weather",
  "type": "http",
  "url": "https://weather.nu/external_api",
  "httpMethod": "GET",
  "authorizationServerUrl": "https://oauth.weather.nu",
  "oAuth2ClientId": "weather-client",
  "oAuth2ClientSecret": "RAcmIxj0Tsn3_-GZjp6OomL-xRxoae9kZHvx81zLNj8",
  "requiredScopes": [
    "weather:read"
  ],
  "input": {
    "parameters": [
      {
        "name": "country",
        "type": "selector",
        "value": "$.address.country"
      },
      {
        "name": "date",
        "type": "selector",
        "value": "$.date"
      }
    ]
  },
  "output": {
    "resultSelector": "",
    "injectAs": "$.weather"
  }
}