How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Jan 11, 2023

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


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.

If IG generates its own transaction ID, it will be logged under transactionId in the access.audit.json (not in the headers section). The x-forgerock-transactionid header is only logged in the headers section of the access.audit.json log if the original incoming request included this header. 

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.

You will still need to configure other ForgeRock products to trust incoming transaction IDs. See the following links for further assistance:

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 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

Auditing Your Deployment

Related Training


Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.