This module provides all the functionality of an ABFAB IdP into a FreeRADIUS server. Its main purpose is the dynamic generation of SAML assertions containing meaningfull information about the actual user that has been authenticated.
This section describes in detail the different functionalities that this module implements, indicating the configuration possibilities that are present. To see how these functionalities are enabled the configuration possibilities, refer to the Configuration section.
1.1. Generation of the Moonshot Targeted IDs RADIUS attribtes
Moonshot defines a set of RADIUS attributes that are intended to provide pseudonymity. This module is able to generate and distributed them as required.
1.2. Dynamic generation of SAML assertions
This is the most important feature of the module. Upon a user has been authenticated by FreeRADIUS, this module takes the attributes from the configured Attribute Sources and generate a valid SAML assertion to be delivered to the Relying Party.
The module provides two different implementations (so called Assertion builders) for doing this: leveraging the module to use the PySAML library to generate a standard and valid assertion, or using a Jinja2 template to create a custom SAML assertion using a set of variables provided by the module. Let's see them with a little more detail.
1.2.1. PySAML Assertion Builder
The ABFAB IDP implementation can make use of the PySAML library to generate valid and well-formed SAML assertions, using the information obtained from the attribute sources. This is the easiest and more straightforward way of generating a SAML assertion and probably the best fit for most of the users.
1.2.2. Jinja2 Assertion Builder
Jinja2 is a modern and designer-friendly templating language for Python, modelled after Djangoâ€™s templates. It is fast, widely used and secure with the optional sandboxed template execution environment.
Users can provide a Jinja2 template that makes use of the following variables to generate the SAML assertions of their IDP:
- username: name of the end user
- rp_name: name of the RP as the 4-tuple (GSS-Acceptor-Service-Name, GSS-Acceptor-Host-Name, GSS-Acceptor-Realm-Name, Trust-Router-COI)
- targeted_ids: user's targeted IDs as a 3-tuple (Moonshot-Host-TargetedId, Moonshot-Realm-TargetedId, Moonshot-TR-COI-TargetedId)
- issuer: IDP SAML issuer name
- attributes: list of attributes as 3-tuple (name, format, list of values)
- reqid: SAML request ID (or None if not provided)
- now: current date time in "%Y-%m-%dT%H:%M:%SZ" format
- expiration: assertion expiration date time in "%Y-%m-%dT%H:%M:%SZ" format
- random: random string of 256 digits for miscellaneous use
An example Jinja2 template would look like the following:
1.3. Support for a number of different attribute sources
The assertion builders are fed with a number of attributes about the authenticated user. This module provides support for obtaining such attributes form a number of different sources (so called Attribute sources). In particular, it supports LDAP servers, SQLite databases and static definitions. Each IDP might have zero, one or more attribute source of each type. The values of the attributes from different sources that share the name are combined. Each attribute source can define an Attribute Relase Policy (so called Attribute Filter) which of the obtained attributes will be included in the provided SAML assertion.
1.3.1. LDAP Attribute Source
The ABFAB IDP module can obtain user attributes from LDAP servers. This support has been tested with openLDAP and Active Directory, although any other standard LDAP server should work as well. For an LDAP source it must be defined a mapping between the FreeRADIUS user name and the LDAP attribute that will be used as a key value to identify the user (e.g. mail address).
1.3.2. SQLite Attribute Source
It is also possible to create an attribute database where attributes are stored. This attribute source requires a table called attributes to exist, with the following schema:
1.3.3. Static Attribute Source
The ABFAB IDP module also allows an IDP to declare static attribute that will be included in every SAML assertion, regardless who the user is.
1.4. Support for attribute release policies
Sometimes an IDP do not want to include all the user attributes obtained from the Attribute Sources in the SAML assertion. The most typical reason for doing this is privacy protection, although other reasons might also be possible (e.g. optimization).
This module provides two different implementations (so called Attribute Filters) to define such policies.
1.4.1. JSON Attribute Filter
This filter allows the definition of complex filters based on a JSON file that contains a set of filtering rules. Each rule declares a RP name, a whitelist and a blacklist.
If the textual representation of the RP name matches the regular expression defined in the RP name, the rule is applied. Otherwise, the next rule is examined.
If a rule is applied, all the attributes matching any of the regular expressions listed in the blacklist will not be included in the SAML assertion, with the exception to those that match any of the regular expressions listed in the whitelist.
An example policy file be:
Let's imagine we have a user called testuser, which has the following attributes:
If the attributes are being provided to a RP named "email@example.com", it will get only
whereas if the RP is named "firstname.lastname@example.org", it would get
as everything else is being blacklisted.
1.4.2. Simple Attribute Filter
This filter provides a much simpler alternative, where the IDP only declares a list of allowed attribute names, with no requirement of having a separated JSON file. This unique rule is applied to any RP. As a matter of example, the results would be identical to having a JSON filter with the following rule:
1.5. Support for several logging backends
The module emits a number of log messages with the purpose of providing information of what is going on on the IDP. There are three different logging backends (so called Loggers) that can be used to record these messages. They can be used simultaneously if desired.
1.5.1. FreeRADIUS Logger
This is the most basic Logger. It generates FreeRADIUS log messages that are included alog the rest of FreeRADIUS logging messages and recorded according the FreeRADIUS configuration (e.g. console, file, syslog...).
1.5.2. File Logger
This Logger writes the logging messages into a specified file in the filesystem.
1.5.3. Syslog logger
This Logger sends the log messages to the syslog daemon using the /dev/syslog
You can download the code of the ABFAB IdP module from our Bitbucket git repository by:
This module installation requires you to have a python 2 development environment with setuptools and pip installed, in order to satisfy all the dependencies. Following you can find specific instructions for a set of Linux distributions. Other distributions might work following similar instructions.
The installation process installs the "abfab_idp" and "abfab_idp_legacy" files into the FreeRADIUS mods-available folder. The first one is intended to be used with FreeRADIUS > 3.0.10, whereas the second one is intended for older versions of FreeRADIUS.
It also installs an abfab_idp.conf and policies.json example files under /usr/share/abfabidp/examples.
2.1. Debian 7
2.2. Debian 8
2.3. Centos 6 and 7
3.1. Enabling the module in the FreeRADIUS configuration structure
The package installs the "abfab_idp" and "abfab_idp_legacy" files into the FreeRADIUS mods-available folder. The first one is intended to be used with FreeRADIUS >= 3.0.10, whereas the second one is intended for older versions of FreeRADIUS. You must enable one of them by symlinking the chosen one from the mods-enabled folder.
Once the module has been enabled, you must add it into the post-auth section of the inner_tunnel site (under the sites-enabled folder). The IDP module needs to have access to the value of the GSS-Acceptor-* RADIUS attributes, hence you must make sure that they are being passed from the "default" site to the "inner_tunnel" one. The easiest way of doing it is by just setting the "copy_request_to_tunnel=yes" in the ttls and/or peap section of the "eap" module (in the mods-enabled/eap file). Similarly, the IDP module generates SAML-Message attributes that need to be included in the outcome of the "default" site. The easiest way of enabling this is by just setting the "use_tunneled_reply=yes" option in the ttls and/or peap sections.
The use_tunneled_reply option should no longer be used after v3.0.7. Use the outer.session-state list/object instead.
3.2. Configuring the IDP behaviour
The behaviour of the IDP module is defined in the abfab_idp file (using the "unlang" file format). However, FreeRADIUS versions below 3.0.10 lack of Python's module configuration capabilities. For this reason, the abfab_idp_legacy module uses a JSON representation of the same configuration and located in the /etc/abfab_idp.conf file instead.
The following stanza depicts a complete configuration file, including comments with explanations for almost every possible option.
3.3. Configuration examples
This subsection provides different real configuration examples using both configuration languages (unlang and JSON).
3.3.1. Example 1
This IDP is using the freeradius log system for delivering the log events, generating the assertions by means of the internal SAML library, and obtaining the attributes from a LDAP directory and a static source.
3.3.2. Example 2
This IDP is using the two log destinations. On the one hand all the events are being sent to the freeradius log system, whereas the file /var/log/radiusidp/idp.log will record all the events above the "info" level. The SAML assertions are being generated using a Jinja2 template (see section above). Finally, it is gathering attributes from two different LDAP servers. For the first one, a JSON attribute release policy is being used (see above), while for the second all the attributes are being provided to the RP.