File(s): conf/logback.xml
Format: Logback
| Table of Contents | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
Overview
All logging is done through an abstract API called SLF4J that allows for a choice of logging implementation at runtime. The software ships and installs with a logging implementation called Logback. We do not at present have any examples of replacing this implementation.
...
The following properties are declared for you:
Variable | Default | Function |
|---|---|---|
idp.logfiles | ${idp.home}/logs | Location of log files |
idp.loghistory | 180 | Number of days of logs to keep |
idp.process.appender | IDP_PROCESS | Appender to use for diagnostic log (set to ASYNC_PROCESS for high volume DEBUG logging) |
idp.loglevel.idp | INFO | Log level for the IdP proper |
idp.loglevel.ldap | WARN | Log level for LDAP events |
idp.loglevel.messages | INFO | Set to DEBUG for protocol message tracing |
idp.loglevel.encryption | INFO | Set to DEBUG to log cleartext versions of encrypted content |
idp.loglevel.opensaml | INFO | Log level for OpenSAML library classes |
idp.loglevel.props | INFO | Set to DEBUG to log runtime properties during startup |
idp.loglevel.spring | ERROR | Log level for Spring Framework (very chatty) |
idp.loglevel.container | ERROR | Log level for Tomcat/Jetty (very chatty) |
idp.loglevel.xmlsec | INFO | Set to DEBUG for low-level XML Signing/Encryption logging |
Log Files
By default there are three classes of log file produced:
...
Some examples of useful categories follow:
Category | Description |
|---|---|
Shibboleth-Audit, Shibboleth-Consent-Audit | Categories to which audit messages are written, allowing them to be captured by additional logging destinations |
Shibboleth-FTICKS | Category for F-TICKS logging messages. |
PROTOCOL_MESSAGE | A logger for incoming and outgoing XML protocol messages, not active by default |
org.opensaml.saml | Messages related only to receiving, parsing, evaluating security of, producing, and encoding SAML messages (this produces a lot of log messages, especially at IdP startup) |
org.opensaml.saml.saml2.encryption.Encrypter | Logs unencrypted SAML content at DEBUG level, not active by default |
org.opensaml.saml.metadata.resolver | Information regarding metadata loading, refresh, and querying |
net.shibboleth.idp | Messages related to all the IdP's functions, profile handling, authentication, attribute resolution and filtering |
net.shibboleth.idp.authn | Messages related only to authentication |
net.shibboleth.idp.attribute | Messages related to attribute resolution and filtering |
org.ldaptive | Messages related to LDAP library processing (applies to both authentication or attribute lookup) |
The default configuration includes additional loggers that are either commented out or are hardwired to particular levels. Adjusting these categories may result in a lot of additional noise, but also may be useful to diagnose very low-level problems (or you might be asked to in order to help diagnose a problem).
...
Logback supports a feature known as the Mapped Diagnostic Context (MDC). Information stored in the MDC is available to every logging message (after the point the information is stored) and can be accessed in an event string with the format %mdc{KEY}. Currently the IdP makes the following information available via the MDC:
There are properties defined to provide some additional control over how this feature works:
idp.logging.MDC.enabled
Can be set to false to turn off the Java filter that populates the MDC if not used.
idp.logging.MDC.createSession
Can be set to false to prevent the Java filter from actually creating a servlet session in accessing the session ID, if it doesn’t already exist. Note that almost all uses of the IdP end up creating that session anyway.
MDC KEY | Description |
|---|---|
idp.version | The IdP version string |
idp.jsessionid | The servlet container's JSESSIONID attribute |
idp.remote_addr | The IP address of the remote user-agent. This is the user's browser for front-channel requests and the SP for back-channel requests. |
idp.server_hostname | The host name of the server to which the current request was sent |
idp.server_port | The port number to which the current request was sent |
Example Logging Pattern using the Container Session ID
| Code Block |
|---|
<Pattern>%date{HH:mm:ss.SSS} - %level [%logger:%line] - [%mdc{idp.jsessionid}] - %msg%n</Pattern> |
V5.1+ also supports extracting arbitrary HTTP request headers into MDC keys using a map defined in a bean named shibboleth.MDCHeaders. The map keys define the MDC keys to create and the values define the header name to read in:
| Code Block |
|---|
<util:map id="shibboleth.MDCHeaders">
<entry key="idp.headers.sec-fetch-site" value="Sec-Fetch-Site" />
</util:map> |
| Note |
|---|
Notably, using the header feature creates some degree of risk from logging content created by the client and thus subject to manipulation. This may be a particularly risky choice when sending logs to external systems or operating on it in some way, so this feature is probably best limited to occasional use while debugging problems. |
Other Examples
Preventing Audit Log Entry Duplication
...