Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Numbered Headings
start-numbering-ath2
Wiki Markup
This package provides two different FreeRadius modules, intended to be used in ABFAB/Moonshot environments. They extend the functionality of an ABFAB IDP and ABFAB RPP by adding advanced SAML assertion handling capabilities, including dynamic generation of SAML assertions (on the IDP), manipulation of SAML attributes (on both the IDP and RPP), and authorization based on SAML attributes (on the RPP).

h2. Download

The code is available from the git repository: [https://bitbucket.org/umujisc/abfab_idp_module|https://bitbucket.org/umujisc/abfab_idp_module]

h2. Installation

Prior installing this package the target system must have a valid FreeRadius installation. This guide assumes {{FR_CONFIG_PATH}} is the path where FreeRadius's config files are located (typically {{/etc/freeradius}}, {{/etc/raddb}}, etc.).

The installation process installs the required Python library, the {{abfab_idp}} and {{abfab_rpp}} files into {{FR_CONFIG_PATH/mods-available}} and a couple of example configuration files under {{/usr/share/abfab_idp/examples}}.

In the following subsections you can find more specific installation instructions for a set of supported Linux distributions. Other distributions might work following similar instructions.

h3. Debian 7 and 8

{code:language=bash}
apt-get install python-pip python-ldap python-dev libffi-dev
python setup.py install
{code}

h3. Centos 6 and 7

{code:language=bash}
yum install epel-release
yum install python-pip python-ldap python-devel libffi-devel openssl-devel gcc
python setup.py install
{code}

h2. Configuration and use

Once the package is installed, the individual modules must be explicitly enabled and configured to use their functionalities.

h3. IDP module

h4. Enabling the module

To do so, just create a soft link of the module into {{FR_CONFIG_PATH/mods-enabled}}.

{code:language=bash}
ln -s FR_CONFIG_PATH/mods-available/abfab_idp FR_CONFIG_PATH/mods-enabled
{code}

Once the module has been enabled, FreeRadius needs to know where to use it. This is done by adding its name to the {{post-auth}} section of the {{FR_CONFIG_PATH/sites-enabled/inner_tunnel}} file.

Since the module needs to have access to the {{GSS-Acceptor-*}} RADIUS attributes from the {{Access-Request}} message in order to know who the RP is, it is required to set the {{copy_request_to_tunnel=yes}} option in the {{ttls}} and {{peap}} sections of the {{FR_CONFIG_PATH/mods-enabled/eap}} file. 

Similarly, the module generates {{SAML-AAA-Assertion}} RADIUS attributes that need to be included in the final {{Access-Accept}} RADIUS message. The easiest way of enabling this is by looking for the following stanza in the {{FR_CONFIG_PATH/sites-enabled/inner_tunnel}} file and making sure that {{if (1)}} is set.

{code:language=bash}
    #  Instead of "use_tunneled_reply", change this "if (0)" to an
    #  "if (1)".
    #
    if (1) {
{code}

h4. Configuring the module

Once the module is installed and enabled, you can tune up its behaviour in the {{/etc/abfab_idp.conf}} file. This file is required and contains a single JSON object with the following elements:

* {{assertion_issuer}}. Value to be used for the {{<Issuer/>}} SAML element in the generated SAML assertion. Default: {{"https://abfab_idp"}}.
* {{assertion_lifetime}}. The module will use this value to calculate the expiration time of the SAML assertion. The lifetime is expressed in minutes. Default: {{60}}. 
* {{attribute_sources}}. A list of attribute sources (see below) from where end user attributes will be retrieved. Default: {{[]}}.
* {{attribute_filters}}. A list of attribute filters (see below) to be applied to the retrieved attributes before building the SAML Assertion. Default: {{[]}}.

h5. Attribute sources

Attribute sources are defined as JSON objects, where the {{type}} element defines its type (one of {{ldap}}, {{sqlite}}, or {{static}}). 

The {{ldap}} attribute source retrieves user attributes from a LDAP server. It defines the following additional configuration elements: 

* {{ldap_uri}}. URI of the LDAP server. Example: {{"ldap://ldap.exaple.org:389"}}.
* {{ldap_login}}. LDAP login string. Optional. Example: {{"cn=admin,dc=whatever,dc=whatever"}}.
* {{ldap_password}}. LDAP password string. Optional. Example: {{"supersecretkey"}}.
* {{ldap_basedn}}. LDAP base DN for the queries. Example: {{"dc=users,dc=whatever,dc=whatever"}}.
* {{ldap_mapping}}. Mapping to determine how RADIUS {{User-Name}} attribute (denoted as {{%u}}) is used to retrieve the LDAP information. Example: {{"(mail=%u)"}}.
* {{ldap_timeout}}. Maximum time to wait for a response, expressed in seconds. Default: {{2}}.

The {{sqlite}} attribute source retrieves user attributes from a SQLite3 database. It defines the following configuration elements:

* {{sqlite_db}}. Location of the SQLite3 attribute database. Example: {{attributes.sqlite}}. This database must have a table called {{attributes}} with the following schema:
{code:language=sql}
CREATE TABLE attributes ('username' TEXT NOT NULL,
                         'name' TEXT NOT NULL,
                         'name_format' TEXT NOT NULL,
                         'value' TEXT NOT NULL,
                         PRIMARY KEY('username', 'name'));
{code}

The {{static}} attribute source always produce the same attribute for all the queries. Its main purpose is to enforce a specific attribute that makes sense at an organization level (e.g. organization name). It defines the following configuration elements:

* {{static_name}}: Attribute name. Example: {{"organization-name"}}.
* {{static_name_format}}: Attribute name format. Default: {{"urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"}}.
* {{static_value}}. Attribute value. Example: {{"Hogwarts"}}.

h5. Attribute filters

Attribute filters allow performing basic transformations to the list of attributes. They are defined as JSON objects, where the {{type}} element defines its type (one of {{blacklist}}, {{template}}, or {{combine}}). They also share the following configuration elements:

* {{rp_name}}. The filter will only be applied if the textual name of the RP (as in {{service@hostname}}) matches this regular expression. Default: {{".\*"}}.
* {{idp_name}}. The filter will only be applied if the realm name of the IDP matches this regular expression. Default: {{".\*"}}.

The {{blacklist}} attribute filter allows removing undesired attributes. It defines the following configuration elements:

* {{exclude}}. A list of regular expressions. Attributes whose name match any of these will be excluded from the list. Default: {{[]}}.
* {{include}}. A list of regular expressions. Attributes whose name match any of these will not be excluded even if they match the {{exclude}} list. Default: {{[]}}.

The {{template}} attribute filter allows creating a new attribute based on parts of the value of another attribute. It defines the following configuration elements:

* {{source}}. Name of the source attribute. Example: {{"full-name"}}.
* {{destination}}. Name of the new attribute to be created. Default: {{"new_template_attribute"}}.
* {{re}}. Regular expression to match parts of the attribute value. Example: {{"^(.\*) (.\*)$"}}
* {{template}}. Template (as in Python string templates) to build the new attribute. Example: {{"Surname: \{1\}. Name: \{0\}"}}.

The {{combine}} attribute filter allows creating a new attribute based on the values of several attributes. It defines the following configuration elements:

* {{sources}}. List of source attribute names. Example: {{\["surname", "name"\]}}.
* {{destination}}. Name of the new attribute to be created. Default: {{"new_combined_attribute"}}.
* {{template}}. Template (as in Python string templates) to build the new attribute. Example: {{"Name: \{1\}. Surname: \{0\}"}}.

h4. A complete example of IDP configuration

{code:language=bash}
{
    "assertion_issuer": "https://testidp.org/",
    "attribute_sources": [
        {
            "type": "ldap",
            "ldap_uri": "ldap://ldap.um.es:389",
            "ldap_basedn": "dc=usuarios,dc=um,dc=es",
            "ldap_mapping": "(mail=%u)"
        },
        {
            "type": "static",
            "static_name": "organization",
            "static_value": "University of Murcia"
        }
    ],
    "attribute_filters": [
        {
            "rp_name": ".*@server.org",
            "type": "blacklist",
            "exclude": [".*"],
            "include": ["organization"]
        }
    ]
}
{code}

h3. RPP module
*NOTE: This module only works with FreeRADIUS versions >= 3.0.16*

h4. Enabling the module

To do so, just create a soft link of the module into {{FR_CONFIG_PATH/mods-enabled}}.

{code:language=bash}
ln -s FR_CONFIG_PATH/mods-available/abfab_rpp FR_CONFIG_PATH/mods-enabled
{code}

Once the module has been enabled, FreeRadius needs to know where to use it. This is done by adding its name to the {{post-auth}} section of the {{FR_CONFIG_PATH/sites-enabled/abfab-tr_-idp}} file.

h4. Configuring the module

Once the module is installed and enabled, you can tune up its behaviour in the {{/etc/abfab_rpp.conf}} file. This file is required and contains a single JSON object with the following elements:

* {{attribute_filters}}. A list of attribute filters (as described for the IDP module) to be applied to the SAML Assertion before proxying it. Default: {{[]}}.
* {{authorization_rules}}. A list of authorization rules (see below) that the SAML Assertion must comply in order to grant access to the RP. Default: {{[]}}.

h5. Authorization rules

Authorization rules allow defining a set of attributes and their corresponding values that MUST be present on the SAML Assertion in order to grant the user access to the RP. In case all rules are not satisfied, the {{Access-Accept}} RADIUS message is replaced with an {{Access-Reject}} one.

Authorization rules are defined as JSON objects, with the following configuration elements:

* {{name}}. Regular expression that must match attribute name. Default: {{".\*"}}.
* {{nameformat}}. Regular expression that must match attribute name format. Default: {{".\*"}}.
* {{value}}. Regular expression that must match attribute value. Default: {{".\*"}}.

h4. A complete example of RPP configuration

{code:language=bash}
{
    "attribute_filters": [
        {
            "type": "combine",
            "sources": ["name", "surname"],
            "template": "{0} {1}",
            "destination": "fullname"
        },
        {
            "idp_name": "idp.*",
            "type": "template",
            "source": "fullname",
            "re": "^(\\S)* (.*)$",
            "template": "{1}",
            "destination": "surname_v2"
        },
        {
            "type": "blacklist",
            "exclude": [
                "undesired_attr_1",
                "undesired_prefix_1.*"
            ],
            "include": ["undesired_prefix_1_2"]
        }
    ],
    "authorization_rules": [
        {
            "name": "surname",
            "value": "PEREZ.*"
        },
        {
            "name": "entitlement",
            "value": "professor"
        }
    ]
}
{code}