Author: Ahmed Saleh
About Ahmed I am a Senior Kubernetes & IDAM Engineer at Midships with 20+ years of hands-on delivery experience supporting cloud transformation. For any feedback, queries or other topics of interest, feel free to contact me at ahmed.saleh@midships.io
This article will describe how to configure ForgeRock IAM products to send logs to STDOUT. The assumptions here are:
The ForgeRock stack is to be deployed on a Kubernetes cluster (e.g. AKS, EKS, OCP, GKE)
There is a requirement to centralise ForgeRock events by sending them to STDOUT and using a cluster-level logging approach to pull events from the STDOUT.
Access Manager
In this section, I will elaborate on STDOUT debug logging and audit logging for AM. We assume that Apache Tomcat is the web container and hence it requires setting tomcat variable to direct its logs to STDOUT:
CATALINA_OUT=”/dev/stdout”The variable needs to be exported as an environment variable before starting Tomcat in your start-up script for AM.
Debug Logging Configuration
AM services proved lots of information within debug logs which are unstructured records. They contain a variety of types of useful information for troubleshooting AM, including stack traces.
AM uses Logback as the handler for debug logging where you can configure the level of debug log record, format, Appender, e.g., Console (STDOUT) or file. Moreover, AM lets you enable the debug log level for specific classes in the AM code base. This can be useful when you turn on debug logging to avoid excessive logging but must gather events to reproduce a problem.
A logback.xml configuration file is added to AM K8s configmap and retrieved during deployment of AM then copied to $TOMCAT_HOME/webapps/${AM_URI}/WEB-INF/classes/logback.xml
Notice that pretty-printing is turned off in the above configuration to save white spaces size.
You may use the following snippet in your script:
echo "-> Updating CATALINA_OUT"
export CATALINA_OUT="/dev/stdout"
echo "-> Updating logback.xml"
tmp_path="$TOMCAT_HOME/webapps/${AM_URI}/WEB-INF/classes/logback.xml"
echo "${file_logbackxml}" > ${tmp_path} # Updating logback.xml
${TOMCAT_HOME}/bin/catalina.sh run –security${file_logbackxml} is the above Logback xml configuration retrieved from your K8s configmap
${TOMCAT_HOME} is your tomcat home
Audit Logging Configuration
ForgeRock Access Manager (AM) provides a detailed audit logging service that captures operational events occurring within AM. Examples of some types of events that are logged include users (including administrators) activities, authentication, configuration updates, errors, etc.
Audit Logging STDOUT Configuration
You need to remove the default file handler from the global configuration and replace it with audit log STDOUT. Audit logging handler is created using REST APIs, high level steps are:
1. Authenticate to AM and retrieve authentication Cookie
2. Delete default Global JSON Handler
3. Create new STDOUT handler
You may use the following CURL commands in your deployment script:
${path_amCookieFile} is path to store authentication cookie in a file
${amAdminPwd} is AM admin password
${amServerUrl} is your AM URL e.g., https://openam.example.com:8443
‘auditlogstdout’ is the name of the newly created handler, you can choose your own name
Key categories of Audit logs provided by ForgeRock AM:
Access Log:
This is captures who, what, when, and output for every access request made to AM. The log filename is in the format access.audit.json. E.g.
Activity Log:
Captures state changes to objects that have been created, updated, or deleted by end users (that is, non-administrators). Session, user profile, and device profile changes are captured in the logs. The log filename is in the format activity.audit.json. E.g.
Authentication Log:
Captures when and how a subject is authenticated and related events. The log filename is in the format authentication.audit.json E.g.
Configuration Log:
Captures configuration changes to the product with a timestamp and by whom. The log filename is in the format config.audit.json. E.g.
DS-Based Components
Directory Server has nine file loggers, and these can be viewed using “dsconfig” command. We recommend you delete these and another three STDOUT loggers will be created.
Two out of the newly created three STDOUT loggers support JSON format, however, the third one (Console Error Logger) doesn’t support JSON format as part of its configuration properties.
Any LDAP or HTTP access logs will be published through the two JSON loggers, the rest of the logs will be published through the plain Console logger with three severities enabled: error, warning, and notice, the other two severities: debug and info are not enabled as they are very verbose, you can opt to enable them but be careful as that will affect your log analysis application’s storage and search performance. The high-level steps for the configuration are:
Trust transaction IDs from publishers
Delete file based loggers
Create Audit handlers’ configurations files
Create new STDOUT handlers
${DS_APP} is DS installation path
${svcURL} is Kubernetes service URL for the pod
${adminConnectorPort} is administration port number
${rootUserDN} is bind DN username
${path_bindPasswordFile} is Path to text file with bind DN user's password
We hope you enjoyed this blog.