Introduction
------------

This is a logback (http:https://logback.qos.ch/) appender for writing "SAML F-TICKS"
to syslog based on Shibboleth (http:https://shibboleth.internet2.edu) Audit Logs. 

This is an "uggly hack" (TM) that transforms the Audit Log format into the 
F-TICKS format. The purpose of this appender is to produce a privacy-preserving 
stream of audit data which can be used to produce federation-wide usage statistics.


Log format
----------

The F-TICKS format implemented by this log appender is a generalization of the
eduroam F-TICKS format:

'F-TICKS/' federationIdentifier '/' version *('#' attribute '=' value ) '#'

In eduroam federationIdentifier is 'eduroam' and version is '1.0'. This 
implementation allows these values to be defined. The eduroam pattern SHOULD 
NOT be reused, instead consider using something that identifies the federation.

The attributes exposed are:

TS: the login time stamp
RP: the relying party entityID
AP: the asserting party entityID (typcially the IdP)
PN: a sha256-hash of the local principal name and a unique key
AM: the authentication method URN

The unique key is stored in a key file and is automatically generated if 
missing. If this key is lost or reset then all local principal names will 
appear to have changed to analysis tools so avoid this!

Configuration
-------------

Configuration is done in logging.xml: 

1) Add an appender definition:

<appender name="IDP_FTICKS" class="net.nordu.logback.FTicksAppender">
   <syslogHost>syslog.example.org</syslogHost>
   <federationIdentifier>swamid</federationIdentifier>
   <version>1.0</version>
   <keyFile>/opt/shibboleth-idp/conf/fticks-key.txt</keyFile>
   <blacklist>^test-.*$$|^monitor$$</blacklist>
</appender>

Change the keyFile to point to where you want to store your random key for
protecting local principal names. 

NOTE!!!! 

   Do not loose this file once you've started to generate logs 

The blacklist is a regular expression, referer to the java documentation on
regular expressions:

  http:https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html#sum
  
Any log event where the local username matches this regexp are excluded from
the log. Typically this is used to disable f-ticks for test or monitor
accounts. Note that Java regexps imply *full* match so be sure to provide ^ and
$ at the beginning and end of the string or your regexps probably won't match.
$ must be doubled as $$ in logging.xml.

NOTE!!!!

The other options should be self-explanatory.


2) Add the appender to the Shibboleth-Audit logger by changing

<logger name="Shibboleth-Audit" level="ALL">
   <appender-ref ref="IDP_AUDIT" />
</logger>

to

<logger name="Shibboleth-Audit" level="ALL">
   <appender-ref ref="IDP_AUDIT" />
   <appender-ref ref="IDP_FTICKS" />
</logger>

This assumes that you haven't changed logging.xml from the default.

3) Build:

# git clone git:https://github.com/leifj/ndn-shib-fticks.git
# cd ndn-shib-fticks
# mvn 
... build finishes ...

The target directory should contain a jar-file. This is what you need for
the next step.

4) Copy the jar-file to shibboleth-identity-provider-2.2.x/lib and re-run the 
install.sh script to build and deploy the shibboleth war-file. You may need to
restart your entire application container (tomcat) for this to take effekt. 

If everything works you should start seeing F-TICKS lines on your syslog server!

Comments are most welcome to leifj at sunet.se