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: [DownloadThe 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 {{InstallationPrior 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 Block | : |
---|
| = | } |
apt-get install python-pip python-ldap python-dev libffi-dev
python setup.py install
{code}
h3. Centos 6 and 7
{code:language=bash} |
Centos 6 and 7 Code Block |
---|
|
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 {{ |
Configuration and useOnce the package is installed, the individual modules must be explicitly enabled and configured to use their functionalities. IDP moduleEnabling the moduleTo do so, just create a soft link of the module into FR_CONFIG_PATH/mods-enabled }}.
{ Code Block | : |
---|
| = | } |
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 Block | : |
---|
| = | } |
# 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 {{ |
Configuring the moduleOnce 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:
* {{}} the {{<Issuer/>}} SAML element in the generated SAML assertion. Default: {{- the
<Issuer/> SAML element in the generated SAML assertion. Default: "https://abfab_idp" }}.
* {{}} {{}}.
* {{}} {{}}.
* {{}} {{}}.
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: {{Attribute sourcesAttribute 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" }}.
* {{}} {{"cn=admin,dc=whatever,dc=whatever" }}.
* {{}} {{}}.
* {{}} {{"dc=users,dc=whatever,dc=whatever" }}.
* {{}} {{}} {{}} {{}}.
* {{}} {{}}
The {{sqlite }} attribute source retrieves user attributes from a SQLite3 database. It defines the following configuration elements:
* {{}} {{}} {{}}
{:=} |
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 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:
* {{}} {{}}.
* {{}} {{"urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" }}.
* {{}} {{}}.
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}Attribute filtersAttribute 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}" .
A complete example of IDP configuration Code Block |
---|
|
{
"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
* |
RPP moduleNOTE: 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 {{Enabling the moduleTo do so, just create a soft link of the module into FR_CONFIG_PATH/mods-enabled }}.
{ Code Block | : |
---|
| = | } |
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:
* {{}} {{}}.
* {{}} {{}}.
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}Authorization rulesAuthorization 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: ".*" .
A complete example of RPP configuration Code Block |
---|
|
{
"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}
|
|