How To

How do I configure IG (All versions) to generate the transaction ID for tracing transactions throughout the ForgeRock stack?

Last updated Aug 10, 2020

The purpose of this article is to provide information on configuring IG to generate the transaction ID for auditing purposes, instead of receiving a transaction ID from a client application. This approach can be used if you don't want client applications to send the X-ForgeRock-TransactionId HTTP header.


2 readers recommend this article

Overview

You can configure IG to generate the transaction ID if you have a client application in front of IG but you do not want it to send the X-ForgeRock-TransactionId HTTP header. For example, in a flow such as the following, you want IG to generate the transaction ID that is then consumed by the other products:

Client Application --> IG --> AM --> DS

This configuration provides an alternative to the solution provided in How do I trace transactions through the audit logs for troubleshooting across ForgeRock products? which uses the HTTP header X-ForgeRock-TransactionId to pass the transaction ID from client applications to ForgeRock products.

You may want IG to generate its own transaction ID for a number of reasons, including:

  • You are concerned about IG accepting transaction IDs from client applications, for example, if they are external.
  • You do not want to (or cannot) make changes to the client application in order to allow it to generate and send transaction IDs.

Configuring IG to generate the transaction ID

There are two options available depending on your use case:

  • If you are using the AmService heap object, ensure amHandler is set to ForgeRockClientHandler (which it is by default). This configuration means the transaction ID is generated by IG and then passed on with any direct communications with AM. See Configuration Reference › AmService for further information.
  • If you are using a different heap object or handler, you can still use ForgeRockClientHandler as the handler in your configuration or alternatively, you can use the TransactionIdOutboundFilter as a filter for a custom handler in a chain, for example:
    "handler" : {
      "type" : "Chain",
      "config" : {
        "handler": "MySecureClientHandler",
        "filters": [ "TransactionIdOutboundFilter" ]
      }
    }
    This filter will insert the transaction ID into the header of the request and because you have not trusted the Transaction Id header, IG will generate the transaction ID.

Downstream applications

If you want the transaction ID to be passed to downstream applications (non-ForgeRock products), you must ensure either ForgeRockClientHandler or TransactionIdOutboundFilter is used on the requests downstream.

For example, if you currently use the ReverseProxyHandler for downstream requests, you could add a new ReverseProxyHandler to the heap that includes the transaction ID header; similar to this:

{
    "heap": [{
        "name": "TxIDReverseProxyHandler",
        "type": "Chain",
        "config": {
            "filters": ["TransactionIdOutboundFilter"],
            "handler": "ReverseProxyHandler"
        }
    }]
}

This definition should be added to the heap after the entry for ReverseProxyHandler.

You could then use TxIDReverseProxyHandler in place of ReverseProxyHandler for all downstream requests and this would ensure the transaction ID header is passed on as expected.

See Also

Troubleshooting IG/OpenIG

Maintenance Guide › Auditing Your Deployment

Related Training

N/A

Related Issue Tracker IDs

N/A



Copyright and TrademarksCopyright © 2020 ForgeRock, all rights reserved.
Loading...