| Table of Contents |
|---|
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:
...
2021-08-03 16:38:53,619 init SingleLogoutProtocol: started
2021-08-03 16:38:53,629 init SessionFactoryLDAP: root=cn=ServerSession,ou=System,cn=Ubilogin,dc=test dynamicObjectSessionStore=false
2021-08-03 16:38:53,629 init SessionFactoryLDAP: 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
| Table of Contents |
|---|
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:
| Timestamp | Type | Message | |
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 entry is generated during system startup and initialization. Contains information about initialized components, crucial parameters, possible warnings and errors.
Logger: diag.init
Example:
2021-08-03 16:38:5253,241619 environmentinit ProviderSingleLogoutProtocol: SunJGSSstarted |
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:
2021-08-03 16:38:52,241 environment Provider: SunJGSS |
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:
...
2021-06-16 07:42:01,812 protocol TokenServlet: protocol.oauth2.TicketProtocolOAuth2Exception: [application-clientid] Invalid ticket request: code_verifierLogin
The login entry is generated at runtime to diagnose ubilogin authentication mapping issues.
Logger: diag.login
Example:
...
2021-08-03 16:38:53,619 login DEBUG Locator.findUbiloginAuthMapping(testlogin): (&(objectClass=ubiloginAuthMethod)(cn={0})(ubiloginAuthMapping={1})): names.size()=1Method
This type of entry is used for diagnostic of runtime errors of authentication methods
Logger: diag.method
Example:
...
2021-06-16 01:43:26,253 method com.ubisecure.ubilogin.sso.ubilogin.authorizer.MethodMenuFilter:UbiloginAgent[cn=CustomerID API,ou=eIDM Services,cn=Ubilogin,dc=example]:[MethodStatus[password.2,true]]Mapper
Mapper entries are used when mapping users to groups. They are created for runtime diagnostic.
...
(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:
2021-06-16 07:42:01,812 protocol TokenServlet: protocol.oauth2.TicketProtocolOAuth2Exception: [application-clientid] Invalid ticket request: code_verifier |
Login
The login entry is generated at runtime to diagnose ubilogin authentication mapping issues.
Logger: diag.login
Example:
2021-08-03 16:38:53,619 login DEBUG Locator.findUbiloginAuthMapping(testlogin): (&(objectClass=ubiloginAuthMethod)(cn={0})(ubiloginAuthMapping={1})): names.size()=1 |
Method
This type of entry is used for diagnostic of runtime errors of authentication methods
Logger: diag.method
Example:
2021-06-16 01:43:26,258253 mappermethod com.ubisecure.ubilogin.sso.mapperubilogin.authorizer.RegisteredMapperMethodMenuFilter: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:///UbiloginAgent[cn=CustomerID API,ou=eIDM Services,cn=Ubilogin,dc=example">cn=d3857c0f-bf12-4de8-80cd-60ab2abaeeb3,ou=Users,ou=eIDM Users,cn=Ubilogin,dc=example</saml:NameID>]:[UbiloginGroup[cn=eIDMUser,ou=eIDM,ou=eIDM Users,cn=Ubilogin,dc=example], UbiloginGroup[cn=Password Users,ou=Password,ou=System,]:[MethodStatus[password.2,true]] |
Mapper
Mapper entries are used when mapping users to groups. They are created for runtime diagnostic.
Logger: diag.mapper
Example:
2021-06-16 01:43:26,258 mapper ubilogin.mapper.RegisteredMapper: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=example], ">cn=d3857c0f-bf12-4de8-80cd-60ab2abaeeb3,ou=Users,ou=eIDM Users,cn=Ubilogin,dc=example</saml:NameID>]:[UbiloginGroup[cn=CustomerID API Users=eIDMUser,ou=eIDM,ou=eIDM ServicesUsers,cn=Ubilogin,dc=example], UbiloginGroup[cn=AuthenticatedPassword Users,ou=Password,ou=System,cn=Ubilogin,dc=example], UbiloginGroup[cn=eIDMUserCustomerID API Users,ou=eIDM GroupsServices,cn=Ubilogin,dc=example], UbiloginGroup[cn=Authenticated Users,ou=System,cn=Ubilogin,dc=example], UbiloginGroup[cn=eIDMUser,ou=eIDM Groups,cn=Ubilogin,dc=example]] |
Acl
Another type of runtime diagnostic entry is access control, named acl.
...
2021-06-16 00:27:12,111 tech ping: the system is alive |
Configuration
...
ping: the system is alive |
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 and newer)
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:
| Code Block |
|---|
<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 withdiag - the case.insensitive default level is one of these:
trace,debug,info,warn,error,offand 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:
| Code Block |
|---|
<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:
| Code 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:
| Code Block |
|---|
<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
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.appender.Diag = com.ubisecure.log4j.DailyFileAppender |
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.
...