Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Logback has been chosen as the logging framework because it supports all the functionality that had been implemented in the SSO proprietary logging system.

...

The logback.xml files reside in these location locations for each web application in the default installation (<webapp> is the name of the web application like uas, logviewer, sso-api etc.):

  • Linux: /usr/local/ubisecure/ubilogin-sso/ubilogin/webapps/<webapp>/WEB-INF/classes from where it is copied to /usr/local/ubisecure/ubilogin-sso/tomcat/webapps/<webapp>/WEB-INF/classes during the installation process

  • Windows: C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\webapps\<webapp>\WEB-INF\classes from where it is copied to C:\Program Files\Ubisecure\ubilogin-sso\tomcat\webapps\<webapp>\WEB-INF\classes during the installation process

There is no need to customise these files.

Expand
titleThe contents of the logback.xml file (uas web application, Windows installation)with explanations

Windows installation C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\webapps\uas\WEB-INF\classes\logback.xml:

Code Block
<?xml version="1.0" encoding="UTF-8"?>
<configuration debug="true" scan="false" scanPeriod="30 seconds">
	<property name="LOG_CONTEXT" scope="context" value="uas" />
	
  <include file="C:\Program Files\Ubisecure\ubilogin-sso\ubilogin/custom/logging/include-logback.xml"/>    
</configuration>

Notes:

  • The attribute debug="true" in the configuration element facilitates troubleshooting for logging configuration

    • When set to true, logback will print status information to the console as it processes the configuration

    • In Windows installations, see the note about Windows console log in the end of this page

    • All other web applications except uas has this setting as false in order not to repeat the status information many times

  • The attribute scan="false" in the configuration element disables scanning of changes in the logger configuration files (logback.xml and include-logback.xml)

    • If set to true, logback will reload the logger configuration if either of the files have been changed

    • Interval to scan for file changes is defined by scanPeriod

    • All web application has this setting as false by default

  • The LOG_CONTEXT property is individual for each web application, it is the same as the folder name of that application

Shared include-logback.xml file

The include-logback.xml file reside in this location in the default installation and it is meant for some customisation:

  • Linux: /usr/local/ubisecure/ubilogin-sso/ubilogin/custom/logging

  • Windows: C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\custom\logging

Expand
titleThe contents of the include-logback.xml file with explanations

Windows installation: C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\custom\logging\include-logback.xml

Each section of this file is explained below.

Code Block
  <!-- (1) Default levels for Diagnostic logs entry types -->
  <turboFilter class="com.ubisecure.common.logging.MarkerBasedLogFilter">
    <DefaultLevels>audit=info;tech=info;diag.*=info</DefaultLevels>
  </turboFilter>
  • SSO diagnostic log levels especially for the uas application can be set by entry types, see Diag log description

  • DefaultLevels element specifies the default levels for each entry type

  • Without this definition the default level is off

  • Default level can be overridden here or the level in use can be set via the management UI

  • Audit log is enabled by default

  • In order to enable Statistics log, DefaultLevels element values need to be modified

Code Block
  <!-- (2) Limit the amount of rotated files to be preserved. 
       Uncomment property and set the appropriate value if you desire this feature -->
  <!-- <property name="LOG_FILE_MAX_HISTORY" value="10" />  -->
  <!-- <property name="AUDIT_LOG_FILE_MAX_HISTORY" value="400" /> -->
  <!-- <property name="PASSWORD_AUDIT_LOG_FILE_MAX_HISTORY" value="400" /> -->

  • By default, log files are rotated on a daily basis and the old files are never deleted

  • By removing comment signs from these properties and specifying the amount of days you need to preserve, you can make logback to deleted the old files automatically

  • Property LOG_FILE_MAX_HISTORY applies to SSO diagnostics log (sso_diag.<YYYY-MM-DD>.log)

  • Property AUDIT_LOG_FILE_MAX_HISTORY applies to uas and SSO management (ubilogin) audit logs and statistics log (uas3_audit.<YYYY-MM-DD>.log, uas3_statistics.<YYYY-MM-DD>.log, management_audit.<YYYY-MM-DD>.log)

  • Property PASSWORD_AUDIT_LOG_FILE_MAX_HISTORY applies to password and password-reset audit log (password_audit.<YYYY-MM-DD>.log)

Code Block
  <!-- (3) SSO log format settings START -->
  
  <conversionRule conversionWord="diagex" converterClass="com.ubisecure.common.logging.LogExceptionConverter" />
  <conversionRule conversionWord="diagmarker" converterClass="com.ubisecure.common.logging.MarkerConverter" />

  <conversionRule conversionWord="diagex" converterClass="com.ubisecure.common.logging.LogExceptionConverter" />
  <conversionRule conversionWord="diagmarker" converterClass="com.ubisecure.common.logging.MarkerConverter" />

  <if condition='property("LOG_CONTEXT").equalsIgnoreCase("sso-api")'>
    <then>
      <property name="DIAG_LOG_PATTERN" value="%d{'yyyy-MM-dd HH:mm:ss,SSS'} %property{LOG_CONTEXT} %diagmarker %level %X{remote-addr} %X{sub} %msg %diagex%nopex%n" />
    </then>
    <else>
      <property name="DIAG_LOG_PATTERN" value="%d{'yyyy-MM-dd HH:mm:ss,SSS'} %property{LOG_CONTEXT} %diagmarker %level %msg %diagex%nopex%n" />
    </else>
  </if>
  <property name="CONSOLE_LOG_PATTERN" value="${DIAG_LOG_PATTERN}" />
  <property name="FILE_LOG_PATTERN" value="${DIAG_LOG_PATTERN}" />
  <property name="AUDIT_FILE_LOG_PATTERN" value="&#34;%d{'yyyy-MM-dd HH:mm:ss,SSS'}&#34;,%msg%n" />
  <property name="MANAGEMENT_AUDIT_LOG_PATTERN" value="%d{'yyyy-MM-dd HH:mm:ss,SSS'} %msg %diagex%nopex%n" />
  <property name="PASSWORD_AUDIT_LOG_PATTERN" value="%msg %diagex%nopex%n" />
  
  <!-- (3) SSO log format settings END -->

  • Log format is specified for each logback appender with pattern properties

  • The format for file

...

….

...

  • appenders are compatible with e.g. Logviewer

  • Diagnostic log pattern is the same for all web applications except sso-api has even more fields in it, the fields are:

    • date-timestamp

    • web application name e.g. uas, ubilogin, sso-api etc.

    • either the entry type (init, tech, method etc.) or fully qualified class name (e.g. com.ubisecure.saml2.metadata.URLMetadataLocator)

    • log level

    • sso-api only: remote IP address of the caller

    • sso-api only: authenticated user calling the API

    • log message

    • exception message

      • the full stack trace is printed only in case of debug level set to the entry type or fully qualified class name of this log event

  • Audit log patterns are compatible with previous releases

  • We don’t recommend you to modify these settings except CONSOLE_LOG_PATTERN can be altered if desired

Code Block
  <!-- (4) SSO log folder and base file name -->
  <property name="LOG_FOLDER" value="C\:\\Program Files\\Ubisecure\\ubilogin-sso\\ubilogin/logs" />
  <property name="SSO_LOG_FILE_PREFIX" value="${LOG_FOLDER}/sso" />
  <property name="UAS_LOG_FILE_PREFIX" value="${LOG_FOLDER}/uas3" />

  • These settings define the log folder which is set during the installation process (platform specific) and the log file base names

Code Block
  <!-- (5) SSO installation log appenders START -->
  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
...
  </appender>

  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
...
    <!-- <file>${SSO_LOG_FILE_PREFIX}_diag.log</file> -->
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
      <fileNamePattern>${SSO_LOG_FILE_PREFIX}_diag.%d{yyyy-MM-dd}.log</fileNamePattern>
      <if condition='isDefined("LOG_FILE_MAX_HISTORY")'>
        <then>
          <maxHistory>${LOG_FILE_MAX_HISTORY}</maxHistory>
        </then>
      </if>
    </rollingPolicy>
  </appender>
...
  
  <!-- (5) SSO installation log appenders END -->

  • The noteworthy thing with file appenders is that a time based rolling policy on daily basis has been defined

  • Because the file element on top of the rollingPolicy element is commented out, also the current day's file has the date in its name (e.g. sso_diag.2022-11-25.log)

    • In linux systems it is possible to remove the comment signs from the file element and have the current day’s file without date in its name (e.g. sso_diag.log)

    • Only the files with the date in their names are visible in the Logviewer application

  • The maxHistory element is defined only if the respective property is set in the beginning of this configuration file

Code Block
  <!-- (6) SSO management audit log. -->
  <!-- Set the level to INFO if you desire to have SSO Management audit file log -->
  <logger name="com.ubisecure.ubilogin.management" level="OFF">
    <appender-ref ref="MANAGEMENT_AUDIT_FILE" />
  </logger>

Code Block
  <!-- (7) SSO SatuHetu log appender if needed START -->
  ...
  <!-- (7) SSO SatuHetu log appender if needed END -->

  • This part is relevant only for a few customers

Code Block
  <!-- (8) Syslog appenders if needed START -->
...
  <!-- (8) Syslog appenders if needed END -->

  • This part is relevant only for Ubisecure own cloud installation (IDC)

Code Block
  <!-- (9) Configure appenders for logging with default INFO level -->
  <root level="INFO">
    <appender-ref ref="CONSOLE" />
    <appender-ref ref="FILE" />
    <appender-ref ref="AUDIT_FILE" />
    <appender-ref ref="STATISTICS_FILE" />
    <appender-ref ref="PASSWORD_AUDIT_FILE" />
  </root>
...

  • In this section the default level INFO is specified for each appender

  • This means that the default logging level for all Java classes, implemented by Ubisecure or third parties, is INFO

  • If you don’t desire to have console logging, you could remove CONSOLE appender from this list

  • Basically the same applies to file appenders, as even if you have no events for them, these definitions will create empty files for each

  • You should keep at least FILE and AUDIT_FILE appenders here

Code Block
  <!-- (10) Customise log levels -->
  <!-- Some examples  -->
  <logger name="com.ubisecure.saml2.metadata.URLMetadataLocator" level="INFO" />  

  • In this section you can override the default level INFO for any Java package or class

  • You can set a higher level in order to reduce logging

  • You can set a lower level when troubleshooting

Note about Windows console log => TODO:

Links:

...