Customizing Identity provider Logs

The Identity Provider uses the Logback logging system. The Logback manual provides an exhaustive set of directions and available options that may be configured. This document does not attempt to replicate this information but instead provides Shibboleth specific information, as it pertains to logging, and instructions for performing simple, common, tasks.

Do not configure paths with brackets in them (for instance c:\Program File (x86)\Idp\Logs ) The logback package currently has an error which will fail all logging silently

Logging Configuration

The logging configuration for the IdP is located at $IDP_HOME/conf/logging.xml. This file is checked for changes every 5 minutes and is reloaded if changes have been made. This means a deployer can keep the logging level at WARN until a problem occurs and then change the logging to DEBUG to get more information if the problem persists, all without restarting the IdP.

Log Files

By default Shibboleth 2.0 Identity Providers write to three log files.

idp-access.log contains a log entry for each time the IdP is accessed, whether information was ever sent back or not. These messages include request time, remote host making the request, server host name and port, and the request path. This log is written in the machine parsable format requestTime|remoteHost|serverHost|serverPort|requestPath|.

idp-audit.log contains a log entry for each time the IdP sends data to a relying party. These messages include the audit event time, IdP and relying party IDs, request and response binding, communication profile ID, request and response ID, principal name, authentication method, and released attribute of the current user. This log is written in the machine parsable format auditEventTime|requestBinding|requestId|relyingPartyId|messageProfileId|assertingPartyId|responseBinding|responseId|principalName|authNMethod|releasedAttributeId1,releasedAttributeId2,|nameIdentifier|assertion1ID,assertion2ID,|
Note the name identifier and assertion IDs were add in Shibboleth 2.1.

idp-process.log contains messages logged during the normal operation of the IdP. This log is meant to be human readable and contains messages that indicate what the IdP is currently doing, encountered errors, warning messages that may indicate potential problems, etc.

All logging messages are "rolled over" at midnight each night.

Useful Loggers

The following, coarse grained, loggers provide useful information in most situations:

Category

Description

Shibboleth-Access

The logger to which shibboleth access messages (think HTTP access logs) are written

Shibboleth-Audit

The logger to which shibboleth audit messages are written

PROTOCOL_MESSAGE

The logger to which incoming and outgoing XML protocols messages are logged

org.opensaml

Messages related only to receiving, parsing, evaluating security of, producing, and encoding SAML messages.

edu.internet2.middleware.shibboleth

Messages related to all the non-SAML message parsing/encoding work; profile handling, authentication, attribute resolution and filtering

edu.internet2.middleware.shibboleth.idp.authn

IdP messages related only to authentication

edu.internet2.middleware.shibboleth.common.relyingparty

IdP messages related to relying party configuration in use

edu.internet2.middleware.shibboleth.common.attribute

IdP messages related only to attribute resolution and filtering

Logging Levels

The logback system defines 5 logging levels (TRACE, DEBUG, INFO, WARN, ERROR). As you progress from the highest level (ERROR) to the lowest level (TRACE) the amount of information logged increases (dramatically so on the DEBUG and TRACE levels). Each level also logs all messages of the levels above it. For example, INFO also logs WARN and ERROR messages.

Mapped Diagnostic Context

Logback, the default logging service used in the IdP, supports a functionality 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 by using the format %mdc{KEY}. Currently the IdP makes the following information available via the MDC:

MDC KEY

Description

idpSessionId

Unique identifier for the user's IdP session. This information is available once a session has been created.

<Pattern>%date{HH:mm:ss.SSS} - %level [%logger:%line] - [%mdc{idpSessionID}] - %msg%n</Pattern>