Identity Manager Server Logging

Identity Manager Server Logging
This page contains the following topics:
Identity Manager uses the underlying Application Server logging support for Apache log4j.
An administrator troubleshoots errors by checking logs in the
server.log
file. By default, the log levels are set to WARN (Warning) in the
server.log
file. That is, only the warning messages are logged in the
server.log
file.
You can change the log levels from WARN (default) to any one of the following log levels:
  • DEBUG
  • INFO
  • ERROR
  • FATAL
  • ALL
  • OFF
Starting with version 14.4, the loggers have been updated to support log4j2. This version changes some of the configuration for the loggers. Log4j versus log4j2 configuration differences are noted in the following text.
Identity Manager supports changing logging levels using either the Logging Admin Tool, or using the log4j/log4j2 configuration file. Logging levels changed using the Logging Admin Tool are not persisted and are lost upon server restart. Logging levels that are changed in the log4j/log4j2 configuration file are maintained across server restarts.
Setting Log4j and Log4j2 Log levels Using a Configuration File
Using this approach means that loggers can log output at the desired levels across server restarts. This method can be useful for a number of reasons:
  • Produce log output from loggers that produce output early in the boot stage
  • Permanently reduce verbose Application Server loggers, such as deployers or service components, by setting log levels to ERROR or OFF.
Using the Log4j Configuration File
The log configuration file is located in the following Identity Manager Server deployment folder:
iam_im.ear/config/com/netegrity/config/log4j_< APP_SERVER >.xml
<APP_SERVER> 
has one of the following values
:
  • “jboss”  (also applies for WildFly)
  • “weblogic”
  • “websphere”
The log4 XML files contain
Appenders
and
Loggers
elements.
Appenders
are log output constructs, such as console or file-based logs.
Loggers
are the components that perform logging and can be set to use a given Appender and a logging level.
In the example below, the IMS.DEFAULT logger’s level has been changed from WARN to DEBUG for detailed logging output.
<LOGGERS> <ROOT ADDITIVITY="FALSE" LEVEL="WARN"> <APPENDERREF REF="ROLLINGLOGGER"/> <APPENDERREF REF="CONSOLE" /> </ROOT> <!-- TELEMETRY LOGS--> <LOGGER ADDITIVITY="FALSE" LEVEL="INFO" NAME="IMS.TELEMETRYJOB"> <APPENDERREF REF="TELEMETRYROLLING"/> </LOGGER> <!-- IM LOGS--> <LOGGER ADDITIVITY="FALSE" LEVEL="WARN" NAME="IMS.UI"> <APPENDERREF REF="ROLLINGLOGGER"/> <APPENDERREF REF="CONSOLE" /> </LOGGER> <LOGGER ADDITIVITY="FALSE" LEVEL="DEBUG" NAME="IMS.DEFAULT"> <APPENDERREF REF="ROLLINGLOGGER"/> <APPENDERREF REF="CONSOLE" /> </LOGGER> <LOGGER ADDITIVITY="FALSE" LEVEL="INFO" NAME="IMS.SSOINTEGRATION"> <APPENDERREF REF="ROLLINGLOGGER"/> <APPENDERREF REF="CONSOLE" /> </LOGGER> <LOGGER ADDITIVITY="FALSE" LEVEL="INFO" NAME="IMS.MAIN"> <APPENDERREF REF="ROLLINGLOGGER"/> <APPENDERREF REF="CONSOLE" /> </LOGGER> </LOGGERS>
Special Configuration for Older log4j Loggers
WorkPoint and Commons loggers have not been upgraded to log4j2; theses loggers still use log4j. A future release may upgrade these components to log4j2. Log4j versus log4j2 configuration differences are noted in the following sections. If other Application Server or third-party log4j loggers that are not deployed by Identity Manager are defined, the same steps following would apply to those loggers.
Commons Logger on WebLogic and WebSphere Configurations
For Weblogic and WebSphere, setting up logger levels statically has changed from Identity Manager versions prior to 14.4.  Before starting Identity Manager on Weblogic or Websphere, the following steps can set up log levels for the Commons components.
Follow these steps:
  1. Create a log4j.properties file located here:
    <iam_im.ear>/config/com/netegrity/config/log4j.properties
    with the following contents to log messages in the console:
    log4j.appender.Console=org.apache.log4j.ConsoleAppender log4j.appender.Console.layout=org.apache.log4j.PatternLayout log4j.appender.Console.layout.ConversionPattern=%d{HH:mm:ss,SSS} %-5p [%c] (%t) %m%n log4j.rootCategory=WARN, Console
  2. Add logging levels in log4j.properties. For example:
    log4j.category.com.ca.commons=INFO
  3. Add JVM options.
    Weblogic
    • For
      Windows
      , add the following line to
      <im_domain>/setDomainEnv.bat
      at the proper location:
      set JAVA_OPTIONS=%JAVA_OPTIONS% -Dlog4j.configuration=/com/netegrity/config/log4j.properties
    • For
      Linux
      , add the following line to
      <im_domain>/setDomainEnv.sh
      at the proper location:
      JAVA_OPTIONS="${JAVA_OPTIONS} -Dlog4j.configuration=/com/netegrity/config/log4j.properties"
    Websphere
    1. In the admin console, select
      Servers
      ,
      Server Types
      ,
      WebSphere Application Servers
      .
    2. Select the application server.
    3. Under Server Infrastructure, select
      Java and Process Management
      ,
      Process Definition
      ,
      Java Virtual Machine
      , and then add the following two custom properties:
      log4j.configuration=/com/netegrity/config/log4j.properties com.ca.commons.logging.nolog4j=false
WorkPoint Logger Configuration
The WorkPoint Server that is deployed in the Identity Manager Server EAR contains its own log4 configuration files. There are two log4j configuration property files: a general WP server configuration and the Queue Monitor configuration:
  • <app_server_deployment folder>/iam_im.ear/config/wp-server.properties
  • <app_server_deployment folder>/iam_im.ear/config/wpqmonitor.log4j.properties
These property files define the same Appenders and Loggers configuration constructs found in the Identity Manager log4j XML files in a property format.
Setup Log4j and Log4j2 Log Levels Using the Logging Admin Tool
Identity Manager supports dynamic configuration of Logger levels using a logging Admin Tool provided by the Identity Manager Server Admin Tools component (an optional installer component). Starting with Identity Manager 14.4, there are now two logging JSP files as part of the logging Admin Tool:
  • <Install_DIR>/IAM Suite
    /Identity Manager/tools/samples/Admin/user_console.war/logging.jsp
  • <Install_DIR>/IAM Suite
    <IAM Suite>/IdentityManager/tools/samples/Admin/user_console.war/logging_v2.jsp
Older log4j components are configured using logging.jsp, and the newer log4j2 components are configured in logging_v2.jsp.
Most loggers have been updated to log4j2. Workpoint and Commons are two loggers that must be managed in logging.jsp.
By default, the logging Admin Tool is not activated.
To activate the tool and change the log levels, follow these steps:
  1. Navigate to
    <Install_DIR>/IAM Suite/Identity Manager/tools/samples/Admin/user_console.war
    , and copy the sample
    logging.jsp and logging_v2.jsp
    files.
  2. Navigate to
    <App_server_deployment folder>/iam_im.ear/user_console.war
    and replace the existing
    logging.jsp and logging_v2.jsp
    files with the sample JSP files that you copied in step 1.
  3. Restart the Identity Manager Server
Configuration Requirements for Log4j2 Loggers
The following additional steps are required for managing log levels in 14.4 in JBoss/WildFly, and WebSphere:
For JBoss/WildFly Windows:
Add the following line to
<JBoss_bin>/standalone.conf.bat
:
set "JAVA_OPTS=%JAVA_OPTS% -DLog4jContextSelector=org.apache.logging.log4j.core.selector.BasicContextSelector"
For JBoss/WildFly Linux:
Add the following line to
<JBoss_bin>/standalone.conf.sh
:
JAVA_OPTS="$JAVA_OPTS -DLog4jContextSelector=org.apache.logging.log4j.core.selector.BasicContextSelector"
For WebSphere
  1. In the admin console, select
    Servers
    ,
    Server Types
    ,
    WebSphere Application Servers
    .
  2. Select the application server.
  3. Under
    Server Infrastructure
    , select
    Java and Process Management
    ,
    Process Definition
    ,
    Java Virtual Machine
    , and then add the following two custom properties:
    log4j.configurationFile=/com/netegrity/config/log4j_websphere.xml Log4jContextSelector=org.apache.logging.log4j.core.selector.BasicContextSelector
Accessing the Admin Tool Logger Configuration Pages
To manage logging level for log4j2 loggers, start Identity Manager and browse to the following URL:
<IM_SERVER:PORT>/iam/im/logging_v2.jsp
To manage logging level for log4j loggers, start Identity Manager, and browse to the following URL:
<IM_SERVER:PORT>/iam/im/logging.jsp
Additional Steps to Secure Logging Admin Tool
By default, the logging Admin Tool that is deployed to the Identity Manager EAR as shown above are not protected. The following steps describe how to protect the tool. This is highly recommend process to ensure the security of the Identity Manager Server.
Enabling Security on JBoss/WildFly
Follow these steps:
  1. Open
    <JBOSS/WILDFLY_HOME>/standalone/deployments/iam_im.ear/user_console.war/WEB-INF\web.xml
    file for editing
  2. Add the following text after the last taglib tag. This text secures the admin toolkit.
    <security-constraint> <web-resource-collection> <web-resource-name>IAMSecureAdminTooles</web-resource-name> <description>Security constraint for IAM Admin Tools</description> <url-pattern>/logging.jsp</url-pattern> <http-method>POST</http-method> <http-method>GET</http-method> </web-resource-collection> <auth-constraint> <description>only let the admin users use secured admin tools</description> <role-name>IAMAdmin</role-name> </auth-constraint> <user-data-constraint> <description>SSL not required</description> <transport-guarantee>NONE</transport-guarantee> </user-data-constraint> </security-constraint> <login-config> <auth-method>BASIC</auth-method> <realm-name>IAM Realm</realm-name> </login-config> <security-role> <description>The IAM Secure Admin Role</description> <role-name>IAMAdmin</role-name> </security-role>
Enabling Security on WebLogic
If you are using WebLogic,
follow these steps
:
  1. Navigate to
    <WebLogic_HOME>/user_projects/domains/<DOMAIN>/applications/iam_im_ear/user_console.war/WEB-INF
    and open
    weblogic.xml
    for editing.
  2. Add the following text after the <weblogic-web-app> element:
    <security-role-assignment> <role-name>IAMAdmin</role-name> <global-role/> </security-role-assignment>
  3. Delete the following text under
    <WebLogic_HOME>/user_projects/domains/<DOMAIN>/iam_im_WarJSPPages/jsp_servlet
    _app/__adapterblthtest.class _app/__adapterblthtest.java _app/__objecttest.class _app/__objecttest.java _app/__ping.class _app/__ping.java _app/__plugintest.class _app/__plugintest.java _ui/__ping.class _ui/__ping.java __logging$1.class __logging.class __logging.java __ping.class __ping.java
  4. Restart Identity Manager server to re-generate JSP pages.
Enabling Security on WebSphere
If you are using WebSphere, perform the following steps:
  1. Navigate to
    <WebSphere_HOME>/profiles/<Profile_Name>/installedApps/<cell_Name>/iam_im.ear/ /META-INF
    , and open
    application.xml
    for editing.
  2. At the end of the XML document, before the
    </application>
    element, enter the following text:
    <security-role id="SecurityRole_IAMAdmin"> <role-name>IAAdmin</role-name> </security-role>
  3. From the same directory (mentioned in step 1), open
    ibm-application-bnd.xmi
    for editing.
  4. Replace the existing text with the following text:
    <codeblock><codeph>example code</codeph></codeblock> <?xml version="1.0" encoding="UTF-8"?> <applicationbnd:ApplicationBinding xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:applicationbnd="applicationbnd.xmi"> <authorizationTable> <authorizations> <specialSubjects xmi:type="applicationbnd:AllAuthenticatedUsers" name="AllAuthenticatedUsers"/> <role href="META-INF/application.xml#SecurityRole_IAMAdmin"/> </authorizations> </authorizationTable> <application href="META-INF/application.xml#Application_ID"/> </applicationbnd:ApplicationBinding>
If administrative and application security is enabled, the role can be mapped through the link Enterprise Applications, <application-name>, Configuration, Security role to user/group mapping in the WebSphere administration console.
Defining a Role and Authorized User for the Logging Admin Tool
JBoss/WildFly
Identity Manager supports the
logging.jsp
file which controls the logging of configuration logs during the run time. The file is available at /iam/im/logging.jsp. By default, the logging.jsp file cannot be accessed by any user. To access this file, you must configure a JBoss/WildFly user as a member of the
IAMAdmin
application group. By default, the application does not have any users.You can control access to the logging.jsp file by adding a user to the
IAMAdmin
application group.
Follow these steps:
  1. Create a JBoss/WildFly application user by running
    add-user.bat
    for Windows or
    add-user.sh
    for Linux. For example:
    C:\wildfly-8.2.1.Final\bin>add-user.bat
  2. Select option "b" (Application User) for the following question:
    What type of user do you wish to add?
  3. Enter the
    Username
    and
    Password
    of the new user when asked to "Enter the details of the new user to add". For example:
    Username: imuser Password: **********
  4. Type
    IAMAdmin
    for the following question:
    What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[]:
  5. Type
    Yes
    for the following question:
    About to add user 'imuser' for realm 'ApplicationRealm' Is this correct yes/no?
  6. Type
    No
    for the following question:
    Is this new user going to be used for one AS process to connect to another AS process? e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server EJB calls.
  7. Browse to logging.jsp at http://<FQDN>:<8080>/iam/im/logging.jsp. User the credentials from step 3 to securely log in to the page.
WebLogic:
WebSphere: