How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I add logging to server-side scripts in AM 6.x?

Last updated Jan 12, 2023

The purpose of this article is to provide information on adding logging to server-side scripts in AM. You may want to add logging to troubleshoot a script that is not behaving as expected or desired.


1 reader recommends this article
Note

This article does not apply to AM 7 and later because AM 7 uses Logback for configuring debug logging. See To Temporarily Enable Debug Logging with Logback.jsp for further information.

Background information

The Scripting API in AM uses the logger object to log debug messages from scripts to the AM debug logs. Debug logging in scripts is not enabled by default; you must enable it by setting the debug log level for the amScript service.

Debug log messages from scripts are logged to the following AM debug logs depending on the type of script:

Script type Log file
Authentication Authentication
Policy Condition Entitlement
OIDC claims OAuth2Provider
OAuth 2.0 Access Tokens (AM 6.5.x) OAuth2Provider

The available logger methods that can be used are detailed in: Debug Logging.

Logging in scripts (authentication nodes)

This example shows how you would output a message level debug error in the logs for a scripted decision node. The log level selected and the log level specified in the script should match, else a message will not be output.

  1. Update your decision node script to include the required logger code. You can do this via the Console or the REST API depending on how you manage your scripts. For example, you could add the following to the script you want to debug: logger.message("Test error message logged for Authentication");
  2. Set the required debug level for the amScript service by navigating to the Debug.jsp page, for example: https://am.example.com:8443/am/Debug.jsp and setting the following fields:
    1. Select the script from the Debug instances field. The script name will be in the format: scripts.AUTHENTICATION_TREE_DECISION_NODE.<_id>, for example: scripts.AUTHENTICATION_TREE_DECISION_NODE.01e1a3c0-038b-4c16-956a-6c9d89328cff
    2. Select Message from the Level field (this must match the log level specified in your script in step 1).
  3. Click Submit to change the debug level.

This message will output to a debug file with the same name as the script you selected in step 2a.

Logging in scripts (authentication modules)

This example shows how you would output an error message in the Authentication log for a scripted authentication module. The log level selected and the log level specified in the script should match, else a message will not be output.

  1. Set the required debug level for the amScript service by navigating to the Debug.jsp page, for example: https://am.example.com:8443/am/Debug.jsp and setting the following fields:
    • Select the Authentication debug file from the Category field.
    • Select Scripting from the Debug instances field.
    • Select Error from the Level field (this must match the log level specified in your script in step 3).
  2. Click Submit to change the debug level.
  3. Update your authentication module script to include the required logger code. You can do this via the Console or the REST API depending on how you manage your scripts. For example, you could add the following to the script you want to debug: logger.error("Test error message logged for Authentication"); This message will output to the Authentication log when the script is run.

See Also

How do I create a script in AM (All versions) using Amster?

Scripting API Functionality

Getting Started with Scripting

Related Training

N/A

Related Issue Tracker IDs

N/A


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