KrakenD

Moesif KrakenD plugin is available only on KrakenD Enterprise.

Since KrakenD 2.5, Moesif has native integration with KrakenD Enterprise. This means you only need add the necessary configuration in krakend.json file to start using Moesif.

Enabling the Moesif plugin in KrakenD

Since the Moesif plugin is available in KrakenD Enterprise by default, the only thing required to enable Moesif in KrakenD is to add a telemetry/moesif entry into the krakend.json configuration file. To push data to your Moesif account, you must add your Moesif Application ID to this config.

In order to track Users and Companies in Moesif, you must add few additional settings that are covered further down on the page.

Below is an example of a krakend.json file that includes the extra_config section to use Moesif with KrakenD. The application_id field is the only value that is required.

{
  "version": 3,
  "extra_config": {
    "telemetry/moesif": {
      "@comment": "Push user activity to Moesif based on the information contained in JWT, every second, in batches of 1000 events",
      "application_id": "Sign in to get your Moesif Application Id",
      "debug": false,
      "log_body": false,
      "event_queue_size": 1000000,
      "batch_size": 1000,
      "timer_wake_up_seconds": 1
    }
  }
}

See additional documentation from KrakenD for more details.

Tracking Users

To allow Moesif to track API calls by a user ID, you can identify the user that made the call through the JWT they use. To do this, you’ll need to set the user_id_headers parameter within the configuration. Additionally, if using a JWT you’ll need to also set the user_id_jwt_claim parameter.

Setting the user_id_headers

In the Moesif configuration, you will need to add the user_id_headers field. This field defines the list of possible headers that can identify a user uniquely. When the header is Authorization and the auth type is Basic, KrakenD will automatically extract the username with no additional configuration.

If tokens are used and passed as an Authorization: Bearer header, KrakenD will extract the user ID from the JWT claim based on what is configured in the corresponding user_id_jwt_claim field (covered below).

In the case where multiple headers may contain the user information, an array of options can be passed. Below is an example of an array with multiple headers.

"user_id_headers": [
  "X-User-Id",
  "Authorization"
],

Of the list that is passed, all entries are tested in the given order. The first header to match in the list is used to extract the user ID (successfully or not).

Setting the user_id_jwt_claim

When using JWT tokens, the user_id_jwt_claim defines which claim in the JWT contains the user ID. The field must be a string. By default, KrakenD will use the value that is stored in the JWT’s sub claim. Below is an example of how to set up KrakenD to use a JWT to extract a user ID.

"user_id_jwt_claim": "sub",
"identify_company": {
  "jwt_claim": "company_id"
},

Tracking Companies

Identifying the company to which an API call (and user) belongs can be done in 3 different ways: through a JWT claim, header value, or query string. It’s important to note that only one of these methods can be used at a time.

Via JWT Claim

To identify a company through a value in the JWT claim, you’ll want to specify which field in the JWT claim should be used. If your JWT payload looks similar to this:

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "company_id": "123myCompany"
}

you can add the following to your krakend.json Moesif configuration:

"identify_company": {
  "jwt_claim": "company_id"
},

Note: the value where company_id is can be the name of whatever field you’d like to extract from the JWT.

Via Request Header

To extract the company ID from a header, you will need to use the header option and specify which header to retrieve the value from. For instance, if there is a header in the request called X-Company-Id, it could be extracted by using the following entry in your config.

"identify_company": {
  "header": "X-Company-Id"
},

Via Query String

To extract the value from a query parameter, you can use the query_string option and specify which query string the value should be extracted from. For instance, if a request contains a ?company_id=123mycompany query string, the company ID could be extracted using the following entry in your config:

"identify_company": {
  "query_string": "company_id"
},

Parameters

Below is a list of all the parameters that can be added to the krakend.json configuration file within the Moesif configuration object (telemetry/moesif).

Key	Title	Description	Type	Default	Examples
application_id	Collector Application ID	The Collector Application ID is used to send events, actions, users, and companies to Moesif’s Collector API. Moesif provides it under the ‘API Keys’ section.	string
debug	Enable debug	Set to true when configuring Moesif for the first time while in development, to see the activity in the logs. Set to false in production.	boolean	false
log_body	Send the body	Send the body of all endpoints and requests to Moesif.	boolean	true
event_queue_size	Event Queue Size	Sends the number of events you can hold in-memory to send them asynchronously to Moesif. If the throughput of your API generates more events than the size of the queue, the exceeding events will be discarded and not reported.	integer	1000000
batch_size	Batch Size	Number of events you will send on every batch reporting asynchronously to Moesif. For high throughput you will need to increase this value.	integer	200
timer_wake_up_seconds	Timer Wake Up	Specifies how often a background thread runs to send events to Moesif. Value in seconds.	integer	2
request_header_masks	Request header masks	The list of request headers that you want to mask their values before sending them to Moesif.	array		[“Authorization”]
response_header_masks	Response header masks	The list of response headers that you want to mask their values before sending them to Moesif.	array		[“Cookie”]
request_body_masks	Request body masks	The list of fields in the request body that you want to mask before sending them to Moesif. You can set log_body to false to prevent any body being sent.	array		[“password”, “credit_card”]
response_body_masks	Response body masks	The list of fields in the response body that you want to mask before sending them to Moesif. You can set log_body to false to prevent any body being sent.	array		[“password”, “credit_card”]
user_id_headers	User ID headers	Defines the list of possible headers that can identify a user uniquely.	array		[“X-User-ID”, “Authorization”]
user_id_jwt_claim	User ID JWT claim	When using JWT tokens, it defines which claim contains the user ID. The field must be a string.	string	“sub”
identify_company	Identify company	It sets which strategy you want to use to identify the company. Identifying the company helps you efficiently govern your API. Choose the system you wish to apply (declare only one property).	object		jwt_claim, header, query_string

Example Config

Here is an example of a krakend.json that includes the elements required to track users and companies.

{
  "version": 3,
  "extra_config": {
    "telemetry/moesif": {
      "@comment": "Push user activity to Moesif based on the information contained in JWT, every second, in batches of 1000 events",
      "application_id": "yourapplicationid",
      "user_id_headers": [
        "Authorization"
      ],
      "user_id_jwt_claim": "sub",
      "identify_company": {
        "jwt_claim": "company_id"
      },
      "debug": false,
      "log_body": false,
      "event_queue_size": 1000000,
      "batch_size": 1000,
      "timer_wake_up_seconds": 1
    }
  }
}