Tracking Client Information

For auditing and tracking purposes, Event Detail Records (EDRs) can include security information included in SubMan API requests or information can be derived from the client making the request.

SubMan API requests can be made to RS Gateway from MATRIXX Backoffice Customer Tool or another client. Client information can be passed in the request header or it can be derived by the server. Information includes:
  • The client IP address.
  • The client session ID.
  • The client user name.
If the caller sets the following optional HTTP headers, they are added to the ApiEventSecurityInfo MDC and are sent to MATRIXX Engine.
  • MtxHeaderClientIpAddress
  • MtxHeaderClientUserName
  • MtxHeaderClientSessionId

This same information can be included in the ApiEventSecurityInfo field of MtxPrimaryEvent EDRs.

Configuration

You can control how MATRIXX Backoffice Customer Tool and RS Gateway set security information in the following files:
  • matrixxbct.yaml — The configuration file for MATRIXX Backoffice Customer Tool.
  • rsgateway-site.yaml — The configuration file for RS Gateway.
Figure 1 shows MATRIXX Backoffice Customer Tool and a client communicating with RS Gateway that sends a request to MATRIXX Engine by way of the Gateway Proxy.
Figure 1. Security Information Layers
MATRIXX Backoffice Customer Tool and an anonymous client communicate with RS Gateway.
In each configuration file, you can configure one of following security modes:
  • disabled — All ApiEventSecurityInfo HTTP headers are ignored and any values passed in this field in the HTTP payload are removed.
  • server_only — All ApiEventSecurityInfo HTTP headers are ignored and ApiEventSecurityInfo field values are determined by the server, overwriting any values passed in those fields.
  • client_or_server — Any ApiEventSecurityInfo HTTP headers, and any values passed in the payload, are preserved. If this information does not exist, then the server determines values based on the connection making the request.
  • client_only — Any ApiEventSecurityInfo HTTP headers, or any values in the payload passed into the call, are used to populate the ApiEventSecurityInfo field sent to the engine. The server does not construct any values for these fields if they are missing.

The default value for MATRIXX Backoffice Customer Tool and RS Gateway is server_only.

For example, to set ApiEventSecurityInfo values if they exist in the HTTP header sent from a client, add the following to rsgateway-site.yaml:
apiEventSecurityInfo:
    mode: client_only

If ApiEventSecurityInfo.mode is set to server_only the ApiEventSecurityInfo field is populated using values determined by the server.

If ApiEventSecurityInfo.mode is set to client_or_server, information passed in the payload and in HTTP headers is used. When nothing is passed in either of those ApiEventSecurityInfo field is populated using values determined by the server. These are the values of the client connection to the application (MATRIXX Backoffice Customer Tool or RS Gateway) and these values are not guaranteed to be the values of the end client who initiated the call.

For MATRIXX Backoffice Customer Tool, this is the information about the user who is logged into MATRIXX Backoffice Customer Tool making the call. For RS Gateway, this is the information about the system connected to RS Gateway making the call. If the call is made through MATRIXX Backoffice Customer Tool to RS Gateway, the information is the MATRIXX Backoffice Customer Tool connection to RS Gateway and not the user logged into MATRIXX Backoffice Customer Tool.

The username is prefixed with the context when setting the value on the server side to help identify the application the user is logged in to. The ClientUserName value is in this pattern: application:user name. If there is a valid ClientSessionId and an anonymous user session is detected, the ClientUserName is application:ANONYMOUS_USER. If there is a valid ClientSessionId that is not an anonymous user and there is no user name associated with it, the ClientUserName is application:NO_USERNAME_AVAILABLE. For example:
"ClientIpAddress": "122.166.155.55",
"ClientSessionId": "49BA9B0AE5D112C2F33D495213953ECE",
"ClientUserName": "matrixxbct:NO_USERNAME_AVAILABLE"

HTTP Request Header Example

The following example shows an HTTP request with the headers set:
Request URL: http://localhost:8081/matrixxbct/api/subscription/0-1-5-1
Request Method: GET
Status Code: 200
Remote Address: [::1]:8081
Referrer Policy: strict-origin-when-cross-origin
Cache-Control: no-store, no-cache, must-revalidate, max-age=0, post-check=0, pre-check=0
Connection: keep-alive
Content-Length: 637
Content-Type: application/json;charset=ISO-8859-1
Date: Tue, 15 Feb 2022 03:12:53 GMT
Expires: Tue, 03 Jul 2001 06:00:00 GMT
Keep-Alive: timeout=60
Last-Modified: Tue, 15 Feb 2022 03:12:53 GMT
Pragma: no-cache
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
GET /matrixxbct/api/subscription/0-1-5-1 HTTP/1.1
Host: localhost:8081
Connection: keep-alive
Cache-Control: max-age=0
sec-ch-ua: " Not A;Brand";v="99", "Chromium";v="96", "Google Chrome";v="96"
sec-ch-ua-mobile: ?0
sec-ch-ua-platform: "Linux"
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.45 Safari/537.36
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
Sec-Fetch-Site: none
Sec-Fetch-Mode: navigate
Sec-Fetch-User: ?1
Sec-Fetch-Dest: document
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.9
Cookie: JSESSIONID=49BA9B0AE5D112C2F33D495213953ECE
MtxHeaderClientSessionId: 49BA9B0AE5D112C2F33D495213953ECE
MtxHeaderClientUserName: jdoe
MtxHeaderClientIpAddress: 192.0.2.1

EDR Example

The following partial purchase event shows client information included in the header. The user jdoe used MATRIXX Backoffice Customer Tool to purchase a catalog item.
"EventDetails": {
     "$": "MtxPurchaseEvent",
     "ApiEventSecurityInfo": {
         "$": "MtxApiEventSecurityInfo",
         "ClientIpAddress": "192.0.2.1",
         "ClientSessionId": "49BA9B0AE5D112C2F33D495213953ECE",
         "ClientUserName": "matrixxbct:jdoe"
     },
     "AssociatedEventIdList": [
         "HEW0:1:52:411"
     ],
     "EventId": "HEW0:1:52:410",
     "EventTime": "2020-01-14T08:01:00.000000Z",
     "EventTypeArray": [
         4
     ],
     "Flags": 0,
     "InitiatorExternalId": "subscriberTest1",
     "InitiatorId": "0-1-5-41",
     "InitiatorPrimaryUserId": "0-1-5-43",
     "InitiatorType": "subscription",
     "OfferInfoArray": [
         {
             "$": "PurchaseEventOfferInfo",
             "CatalogItemExternalId": "Offer-1",
             "CatalogItemId": 1,
             ...