Introduction

One of logs written by Ubisecure SSO is the diag log. Diag logs are divided into multiple types and contain diagnostic information about configuration, initialization or some runtime events. The logs are written to files that are usually named according to the convention uas_diag3.[data].log (where [date] is formatted as YYYY-MM-DD). Log file names may be altered by configuration settings.

General format

The log consists of fields separated by spaces. Each line represents one log entry and starts with a timestamp in ISO 8601 format. The next value represents the type of log entry. The last field is the message.

General log entry format:

...

There are currently thirteen possible log entry types: init, environment, protocol, login, method, mapper, acl, authz, ui, session, identity, inboundmapping and tech.

 Each of these will be detailed with example content for each field in the listing below. 

Init

An init entry entry is generated during system startup and initialization. Contains information about initialized components, crucial parameters, possible warnings and errors.

Logger: diag.init

Example:

...

Introduction

All Ubisecure SSO applications deployed to SSO Tomcat print diagnostic information to the shared SSO diagnostic log. In the default installation the file is named sso_diag.YYYY-MM-DD.log and it resides in the ubilogin/logs folder.

See Understanding SSO logger configuration about the technical details.

General format

Each line in the diagnostic log file represents one log entry with a set of fields separated by a space.

General log entry format:

Each log entry starts with a timestamp in the following format: YYYY-MM-DD hh:mm:ss,SSS.

The next field contains the name of the application printing the events the first field after the timestamp. The application name is the same as the webapp folder in the installation:

• uas
• ubilogin
• logviewer
• search
• sso-api
• totp
• password
• password-reset
• cdc
• otpserver

The type of log entry is either one of the predefined Entry type or a fully qualified class name.The predefined Entry types are especially in use by the SSO Authentication server (uas) and are explained later in this document.

Log level is one of the well-known logging levels: TRACE, DEBUG, INFO, WARN, or ERROR. The default levels to log are: INFO, WARN and ERROR. You may configure the desired level to log based on the type of the log entry. How to modify the log levels is described in the end of this document.

The last field is the log message. In case of SSO API (sso-api) the log message is preceded by two additional fields: IP address and the authenticated user name (sub).

In case of an exception the log entry is followed by the exception stack trace only if DEBUG level is set for the type of this log entry. This rule applies only to the Ubisecure developed code and is meant for preserving disk space.

Entry types

There are currently thirteen possible log entry types: init, environment, protocol, login, method, mapper, acl, authz, ui, session, identity, inboundmapping and tech.

Each of these will be detailed with example content for each field in the listing below. 

Init

An init entry is generated during system startup, initialization, and stopping. Contains information about initialized components, crucial parameters, possible warnings and errors.

Logger: diag.init

Examples:

2022-10-03 07:05:48,929 ubilogin init INFO Ubilogin Server Management 9.1.0 started

2022-10-03 07:05:50,742 logviewer init INFO Ubilogin Log Viewer 9.1.0 started

2022-10-03 07:05:53,211 search init INFO Ubilogin Search 9.1.0 started

2022-10-03 07:05:57,851 uas init INFO UbiloginKeyService: Updates to server keys detected at 2022-10-03T07:05:57.461Z 
2022-10-03 07:05:57,851 uas init INFO UbiloginKeyService: Found 1 key(s):
[enabled] [valid] CN=key-initial,OU=ServerKeyContainer,OU=System,CN=Ubilogin,DC=localhost (defaultKeyId="9cuYOsuS6RD0-VnCAmLgj8NobJ0") 
2022-10-03 07:05:57,851 uas init INFO UbiloginKeyService: Signing key: CN=key-initial,OU=ServerKeyContainer,OU=System,CN=Ubilogin,DC=localhost 
2022-10-03 07:05:57,851 uas init INFO UbiloginKeyService: Decryption key(s) (1): [CN=key-initial,OU=ServerKeyContainer,OU=System,CN=Ubilogin,DC=localhost] 
2022-10-03 07:05:57,851 uas init INFO UbiloginKeyService: Published signature validation key(s) (1): [CN=key-initial,OU=ServerKeyContainer,OU=System,CN=Ubilogin,DC=localhost] 
2022-10-03 07:05:57,851 uas init INFO UbiloginKeyService: Published encryption key: CN=key-initial,OU=ServerKeyContainer,OU=System,CN=Ubilogin,DC=localhost 
2022-10-03 07:05:58,179 uas init INFO MessageQueueSender initialised with connection to Accounting Service broker URL: tcp://localhost:36161?connectionTimeout=10 
2022-10-03 07:05:58,179 uas init INFO UbiloginFactory: started 

2022-10-03 07:06:00,633 uas init INFO Ubilogin Authentication Server 9.1.0 started

Environment

This type of entry is also generated on startup and contains information related to the runtime environment and configuration. Data may be written in many rows and the structure of the data is indicated by the row indentation.

Logger: diag.init.environment

Example:

20212022-0810-0306 1607:3829:5219,241097 uas environment INFO Java Cryptography Extension (JCE) Unlimited Strength Providerinstalled: SunJGSSYes
20212022-0810-0306 1607:3829:5219,241097 uas environment INFO Security Providers and Services:
20212022-0810-0306 1607:3829:5219,241097 uas environment INFO   GssApiMechanism.1.2.840.113554.1.2.2 = sun.security.jgss.krb5.Krb5MechFactory (max strengh)
2021-08-03 16:38:52,241 environment    GssApiMechanism.1.3.6.1.5.5.2Provider: SUN
2022-10-06 07:29:19,097 uas environment INFO   Services:
2022-10-06 07:29:19,097 uas environment INFO    MessageDigest.SHA3-224 = sun.security.jgssprovider.spnego.SpNegoMechFactorySHA3$SHA224 (max strengh)
20212022-0810-0306 1607:3829:5219,241097 uas environment INFO  Properties:
2021-08-03 16:38:52,241 environment    GssApiMechanism.1.2.840.113554.1.2.2  Signature.NONEwithDSA = sun.security.jgss.krb5.Krb5MechFactory
2021-08-03 16:38:52,241 environment    GssApiMechanism.1.3.6.1.5.5.2 = sun.security.jgss.spnego.SpNegoMechFactoryprovider.DSA$RawDSA (max strengh)

Protocol

Protocol entries are generated for diagnostics of protocols, usually connected with runtime errors.

For some exceptions of type TicketProtocolException and its subtypes, such as TicketProtocolOAuth2Exception and TicketProtocolSAML2Exception, the issuer of the request (which is the client_id or entityId of the application) is shown in square brackets.

Logger: diag.protocol

Example:

20212022-10-06-16 0709:4204:0128,812145 uas protocol TokenServlet: protocol.oauth2.TicketProtocolOAuth2Exception:ERROR AuthorizationServlet [oauth2-application-clientid] Invalid ticket request: code_verifierchallenge: protocol.oauth2.TicketProtocolOAuth2Exception: [oauth2-application] Invalid ticket request: code_challenge

Login

The login entry is generated at runtime to diagnose ubilogin SSO authentication mapping issues.  Happy-case entries are seen only if DEBUG level is specified for this type.

Logger: diag.login

Example:

20212022-0810-0306 1607:3829:5319,619097 uas login DEBUG Locator.findUbiloginAuthMapping(testlogin): (&(objectClass=ubiloginAuthMethod)(cn={0})(ubiloginAuthMapping={1})): names.size()=1

...

This type of entry is used for runtime diagnostic of runtime errors of authentication authentication methods.

Logger: diag.method

Example:

20212022-0610-1607 0108:4304:2628,253694 uas method com.ubisecure.ubilogin.sso. INFO ubilogin.authorizer.MethodMenuFilterMethodPolicyFilter:UbiloginAgent[cnCN=CustomerID APIUbilogin,ouOU=eIDM ServicesSystem,cnCN=Ubilogin,dcDC=examplelocalhost]:[MethodStatus[password.21,true]]

Mapper

Mapper entries are used when mapping users to groups. They are created for runtime diagnostic.

Logger: diag.mapper

Example:

20212022-0610-1607 0108:4304:2635,258467 uas mapper INFO ubilogin.mapper.RegisteredMapper:Identity[UBILOGIN&password.21&<saml:NameID xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName" NameQualifier="ldap:///cn=Ubilogin,dc=examplelocalhost">cn=d3857c0f-bf12-4de8-80cd-60ab2abaeeb3,ou=Users,ou=eIDM Users,cn=Ubilogin,dc=example<>CN=Administrator,OU=System,CN=Ubilogin,DC=localhost</saml:NameID>]:[UbiloginGroup[cnCN=eIDMUserAccounting Users,ouOU=eIDMAccounting,ouOU=eIDM UsersSystem,cnCN=Ubilogin,dcDC=examplelocalhost], UbiloginGroup[cn=PasswordAuthenticated Users,ou=Password,ou=System,cn=Ubilogin,dc=examplelocalhost], UbiloginGroup[cnCN=CustomerID APIPassword Users,ouOU=eIDM Services,cn=Ubilogin,dc=example], UbiloginGroup[cn=Authenticated Users,ou=System,cnPassword,OU=System,CN=Ubilogin,dcDC=examplelocalhost], UbiloginGroup[cnCN=eIDMUserAdministrators,ouOU=eIDM GroupsSystem,cnCN=Ubilogin,dcDC=examplelocalhost]] 

Acl

Another type of runtime diagnostic entry is access control, named acl.

Logger: diag.acl

Example:

20212022-0610-1607 0108:4304:3135,799471 uas acl INFO ubilogin.authorizer.saml2.SubjectAccessUbiloginAccessControl:Identity[UBILOGIN&password.21&<saml:NameID xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName" NameQualifier="ldap:///cn=Ubilogin,dc=examplelocalhost">cn=d3857c0f-bf12-4de8-80cd-60ab2abaeeb3,ou=Users,ou=eIDM Users,cn=Ubilogin,dc=example<>CN=Administrator,OU=System,CN=Ubilogin,DC=localhost</saml:NameID>]:true 

Authz

Auths entries are related to authorization diagnostic and are created at runtime.

Logger: diag.authz

Example:

20212022-0610-1607 0108:4304:3135,800471 uas authz INFO ubilogin.authorizer.UsernameAuthorizer:Identity[UBILOGIN&password.21&<saml:NameID xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName" NameQualifier="ldap:///cn=Ubilogin,dc=examplelocalhost">cn=d3857c0f-bf12-4de8-80cd-60ab2abaeeb3,ou=Users,ou=eIDM Users,cn=Ubilogin,dc=example<>CN=Administrator,OU=System,CN=Ubilogin,DC=localhost</saml:NameID>]:urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName:password.21.grant_typedn=passwordCN%3DAdministrator%2COU%3DSystem%2CCN%3DUbilogin%2CDC%3Dlocalhost&password.2.dn=cn%3Dd3857c0f-bf12-4de8-80cd-60ab2abaeeb3%2Cou%3DUsers%2Cou%3DeIDM+Users%2Ccn%3DUbilogin%2Cdc%3Dexample&password.2.ldap=ldap%3A%2F%2F%2Fcn%3DUbilogin%2Cdc%3Dexample

UI

...

1.ldap=ldap%3A%2F%2F%2Fcn%3DUbilogin%2Cdc%3Dlocalhost&username=CN%3DAdministrator%2COU%3DSystem%2CCN%3DUbilogin%2CDC%3Dlocalhost 

UI

These entries are used for runtime diagnostic of user interface issues. Created at runtime. Happy-case entries are seen only if DEBUG level is specified for this type.

Logger: diag.ui

20212022-0610-1607 0308:1204:3335,876471 uas ui WARN unmarshalJSON: protocol.oauth2.TicketProtocolOAuth2Exception: The requested application is invalid: javax.json.stream.JsonParsingException: Unexpected char 60 at (line no=1, column no=1, offset=0)

...

Session entries are generated for diagnostics of session handling, usually connected with runtime errors. Happy-case entries are seen only if DEBUG level is specified for this type.

Logger: diag.session

Example:

20212022-0810-0507 1108:04:2835,021589 uas session DEBUG SessionStoreGC.gc(1628168668021)
2021-08-05 12:53:31,370 uas session DEBUG expired SingleSignOnSession _7beddef3b05b8034a3265c455d73e64edfc6fb1b

...

This type of entry is used for runtime diagnostic of runtime errors on identity creation and encoding.

Logger: diag.identity

Example:

20212022-0610-1603 0314:1922:3632,992913 uas identity INFO X509IdentityFactory.createIdentities(): Identity[UBILOGIN&password.2&<saml:NameID xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName" NameQualifier="ldap:///cn=Ubilogin,dc=examplelocalhost">cn>CN=d3857c0f1445dd95-bf12d685-4de84d9b-80cda7ce-60ab2abaeeb382f111545810,ouOU=Users,ouOU=eIDM Users,cnCN=Ubilogin,dcDC=example<localhost</saml:NameID>] 

Inboundmapping

Separate This specific type of entries is inboundmapping. It's used for diagnostics of attributes mapping.

Logger: diag.inboundmapping

Example:

20212022-0810-07 09 14:2804:0835,340232 uas inboundmapping WARN InboundMappingTable: ubiloginAttributeName: cn=1,cn=imt.soso.1,cn=Server,ou=System,cn=Ubilogin,dc=test

...

Tech entries are used for miscellaneous diagnostics messages.

Logger: tech

Example:

2022-

10-03 07:05:57,023 uas tech INFO JLDAP: url=ldap://

localhost/cn=Ubilogin,dc=

localhost,servers=[ldap://

localhost/cn=Ubilogin,dc=

localhost],tls=false,confConnectTimeout=15000,confReadTimeout=15000,confMaxAge=120000,confAuthPool=8,failoverType=multi-master

Configuration

The Diag log may be configured either via configuration file (logback.xml replacing log4j.properties since SSO 9.1) or via SSO UI.

Configuring via logback.xml file (SSO >= 9.1)

The logback.xml file is located in ubilogin customization directory (ubilogin-sso/ubilogin/custom/logging/logback.xml) and contains the configuration of all SSO logging. Learn about Logback configuration file syntax.

The defaults for diag log entry type based logging is configured in these lines:

<turboFilter class="com.ubisecure.common.logging.MarkerBasedLogFilter">
    <DefaultLevels>audit=info;tech=info;diag.*=info</DefaultLevels>
</turboFilter>

The syntax for DefaultLevels is the following:

• the delimiter for individual entry type settings is semicolon (;)
• the entry type key is one among these listed in section Entry Types in lowercase (diag.init, diag.init.environment, tech, etc.); diag.* can be used to specify all entry types starting with diag
• the case.insensitive default level is one of these: trace, debug, info, warn, error, off and is specified after equal sign (=), e.g. tech=info
• the default level if not specified is off

There are custom patterns that have been defined for diag console and file logging:

<conversionRule conversionWord="diagex" converterClass="com.ubisecure.common.logging.LogExceptionConverter" />
<conversionRule conversionWord="diagmarker" converterClass="com.ubisecure.common.logging.MarkerConverter" />
 
<property name="CONSOLE_LOG_PATTERN"
          value="%d{'yyyy-MM-dd HH:mm:ss,SSS'} %diagmarker %level %msg %diagex%nopex%n" />
<property name="FILE_LOG_PATTERN"
          value="%d{'yyyy-MM-dd HH:mm:ss,SSS'} %diagmarker %msg %diagex%nopex%n" />

LogExceptionConverter (diagex) controls when stack trace is printed to the log and MarkerConverter (diagmarker) prints either the entry type or the Java class name based logger category.

The diag log file name and the rotation of it is defined by this block:

    <property name="LOG_FOLDER" value="@logs.dir.esc@" />
    <property name="UAS_LOG_FILE" value="${LOG_FOLDER}/uas3" />
...  
 
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <filter class="ch.qos.logback.core.filter.EvaluatorFilter">
...
        </filter>
        <encoder>
            <pattern>${FILE_LOG_PATTERN}</pattern>
        </encoder>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${UAS_LOG_FILE}_diag.%d{yyyy-MM-dd}.log</fileNamePattern>
...
        </rollingPolicy>
    </appender>

You can also define the log level of any of the SSO or 3rd party libraries based on their category:

<logger name="servlet.LogLevelUpdater" level="DEBUG" />   
<logger name="org.apache.activemq" level="INFO" />

To change any of these settings you need to manually apply the same changes on all nodes. A restart of Tomcat may also be required. It depends if you define scan="true" and scanPeriod in your logback.xml file.

Configuring via log4j.properties file (SSO <= 9.0)

The log4j.properties file is located in web application directory for the UAS module (tomcat/webapps/uas/WEB-INF/log4j.properties) and contains the configuration of all logs for the UAS. By convention the lines responsible for the diag log are set as follows:

log4j.logger.ubilogin.tech = INFO, Diag, C
log4j.logger.ubilogin.diag = INFO, Diag
log4j.logger.ubilogin.diag.init = INFO, C

log4j.appender.Diag = com.ubisecure.log4j.DailyFileAppender
log4j.appender.Diag.File = @logs.dir.esc@/uas3_diag
log4j.appender.Diag.layout = org.apache.log4j.PatternLayout
log4j.appender.Diag.layout.ConversionPattern = %d{ISO8601} %c{1} %m%n

The upper lines are responsible for setting the logging level and assigning logger types to the Diag log. The lower lines define the naming and layout of the files.
These changes are stored locally on each node. To change these settings you need to manually apply the same changes on all nodes, a restart of Tomcat may also be required.

Configuring via UI

...

 
2022-10-03 07:06:00,773 uas tech INFO ping: the system is alive

Logger configuration

The default logger configuration is detailly explained in Understanding SSO logger configuration.

We don't recommend modifications to the default Diagnostic log configuration except tuning the log levels especially when troubleshooting issues.

Configuring log levels for predefined Entry types

The Diagnostic log levels for predefined may be configured either via SSO Management UI or via the configuration file.

Configuring via SSO Management UI

Configuring via SSO Management UI Logging tab is the recommended way as no server restart is required and in a clustered environment the change applies to both nodes.

See Management UI logging configuration for guidelines.

Configuring with Logback configuration files

It is also possible to override the default levels for the Entry types in the logger configuration file which resides in the following location in the default installation:

Windows:

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

Linux: 

/usr/local/ubisecure/ubilogin-sso/ubilogin/custom/logging/include-logback.xml

To change the default levels please modify the DefaultLevels value in this section:

  <!-- (1) Default levels for Diagnostic logs entry types -->
  <turboFilter class="com.ubisecure.common.logging.MarkerBasedLogFilter">
    <DefaultLevels>audit=info;tech=debug;diag.*=info;diag.init.environment=warn</DefaultLevels>
  </turboFilter>

The syntax for DefaultLevels is the following:

• the delimiter for individual entry type settings is semicolon (;)
• the entry type key is one among these listed in section Entry Types in lowercase (diag.init, diag.init.environment, tech, etc.); diag.* can be used to specify all entry types starting with diag
• the case.insensitive default level is one of these: trace, debug, info, warn, error, off and is specified after equal sign (=), e.g. tech=info
• the default level if not specified is off

Configuring log levels for arbitrary classes

The log levels for arbitrary classes may be configured only via configuration file include-logback.xml.

You can specify package name, part of the package name, or a fully qualified class name. You can also define the log level of any of the SSO or 3rd party libraries.

Please add your definitions to the following section in the configuration file:

  <!-- (10) Customise log levels -->
  <!-- Some examples  -->
  <logger name="com.ubisecure.saml2" level="DEBUG" /> 
  <logger name="com.ubisecure.saml2.metadata.URLMetadataLocator" level="INFO" /> 
  <logger name="org.apache.activemq" level="WARN" />