Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Document allowRA and denyRA, but behind a cut to avoid confusing people.

By default eduTEAMS DSX Discovery Service lists all eduGAIN IdPs for user to select from. This , which is a list of several thousand IdPs. Showing all IdPs often is not always desirable and eduTEAMS . The DSX Discovery Service offers possibility allows to filter out IdPs so that only the relevant IdPs are shown in the list. This allows an SP admin to craft create a list (or several lists) specifically targeting the user base of the his SP. If for nothing else, the filtering should be used to hide IdPs not meant to be shown for 'normal' end user i.e. IdPs having entity category http://refeds.org/category/hide-from-discovery.

Creating the filter

...

using the DSX DS Filter Generator

The filter is generated using eduTEAMS is a base64 encoded JSON object that defines the rules for including or excluding IdPs. The easiest way to generate this is by using DSX Filter Generator.

Info
iconfalse
titleeduTEAMS DSX Filter Generator

https://discoverydsx.eduteamsedugain.org/filter.php

The Generator is able to filter generator can create two types of filters, you may filter entities based on their SAML entity categories or based on entity idsIdP entityID values (or both).

Allow and Deny lists of

...

Entity Categories

You may create both, allow and deny, lists of entity categories.

  • If an "allow" list is defined, all only IdPs not matching atleast at least one of the categories on it are filtered outare visible, all others are hidden.
  • If a "deny" list is defined, all IdPs matching any of the categories on it are filtered out and thus are hidden.

Allow or Deny list of IdPs

You may create allow or deny list of IdPs.

  • If an "allow" list is defined, all IdPs that are not on it this list are filtered out .and thus are hidden
  • If a "deny" list is defined, all IdPs on it are filtered out .and thus are hidden
Expand
titleExample: Show all IdPs except those marked as hidden, Deny list of categories

This example shows how to list all IdPs not tagged as hidden. This is the main use case to setup list of all eduGAIN IdPs.

Navigate to filter generator , on https://discoverydsx.eduteamsedugain.org/filter.php.

Click open the 'select entity categories' - accordion. You should now see all the possible entity categories to choose from in a grey box.

Move http://refeds.org/category/hide-from-discovery to red box.


At the bottom of the page you should see the resulting filter and it's its plaintext version.

Info
iconfalse
titleOutcome

Show all IdPs not belonging to category http://refeds.org/category/hide-from-discovery.



Expand
titleExample: Research and Scholarship, Allow list of entity categories

This example shows how to list only IdPs tagged with Research and Scholarship entity category.

Navigate to filter generator , on https://discoverydsx.eduteamsedugain.org/filter.php.

Click open the 'select entity categories' - accordion. You should now see all the possible entity categories to choose from in a grey box.

Move http://refeds.org/category/research-and-scholarship to green box. Move also http://id.incommon.org/category/research-and-scholarship.

At the bottom of the page you should see the resulting filter and it's its plaintext version.


Info
iconfalse
titleOutcome

Show only IdPs having atleast one of the categories http://refeds.org/category/research-and-scholarship and http://id.incommon.org/category/research-and-scholarship.


...

Expand
titleExample: Allow list of IdPs

This example shows how to list a specific set of IdPs.

Navigate to filter generator , on https://discoverydsx.eduteamsedugain.org/filter.php.

Click open the 'select individual IdPs' - accordion. You should now see all the possible IdPs to select from.

Make sure that the radio - button 'Selected IdPs will be visible' is checked. Select the entities you want the user to pick the IdP from.

At the bottom of the page you should see the resulting filter and it's its plaintext version. Note that by picking individual IdPs you will easily end up with a large filter and you need to set it by reference.

Info
iconfalse
titleOutcome

Show only IdPs https://idp.aalto.fi/idp/shibboleth, https://birk.wayf.dk/birk.php/wayf.au.dk and https://shibboleth.aber.ac.uk/shibboleth-TST.


Merging

...

Two Filter Types

When both entity categories and idp IdP list filters are used together, the list shown comprises of IdPs not filtered out by categories filter with possible additions of IdP allow list or possible deductions of IdP deny list. The assumption is that SP creates the base of the rules using categories filtering and then possible exceptions to those rules by Allow/Deny lists of IdPs.

...

Expand
titleExample: Select entities by category and then some

This example shows how to list all IdPs tagged with Research and Scholarship entity category and a specific set of IdPs.

Navigate to filter generator, https://discoverydsx.eduteamsedugain.org/filter.php.

Click open the 'select entity categories' - accordion. You should now see all the possible entity categories to choose from in a grey box.

Move http://refeds.org/category/research-and-scholarship to green box. Move also http://id.incommon.org/category/research-and-scholarship.

Click open the 'select individual IdPs' - accordion. You should now see all the possible IdPs to select from.

Make sure that the radio - button 'Selected IdPs will be visible' is checked. Select the "Aalto" entity (not belonging to mentioned categories at the time of the writing).

At the bottom of the page you should see the resulting filter and it's plaintext version.

Info
iconfalse
titleOutcome

Show https://idp.aalto.fi/idp/shibboleth and any IdP having atleast at least one of the categories http://refeds.org/category/research-and-scholarship and http://id.incommon.org/category/research-and-scholarship.


Applying the

...

Filter in the Discovery Request

The filter generated with the tool is set as query string appended as an HTTP GET parameter to the discovery request.  It can be set either by value or by reference. The maximum length for discovery request query parameters by some browsers is 512 bytes. If the filter is large exceeding that this value you one should set the filter by reference.

Filter by value - filter

Code Block
https://discoverydsx.eduteamsedugain.org/wayf.php?filter=eyJhbGxvd0hvc3RlbCI6dHJ1ZSwiYWxsb3dIb3N0ZWxSZWciOnRydWV9Cg==

...

Expand
titleExample: Shibboleth SP


Code Block
title/etc/shibboleth/shibboleth2.xml
<SSO
    discoveryProtocol="SAMLDS"
    discoveryURL="https://discoverydsx.eduteamsedugain.org/wayf.php?filter=eyJhbGxvd0hvc3RlbCI6dHJ1ZSwiYWxsb3dIb3N0ZWxSZWciOnRydWV9Cg==">
    SAML2 SAML1
</SSO>


...

Expand
titleExample: SimpleSAMLphp


Code Block
titleauthsources.php
'default-sp' => array(
    'saml:SP',
    'entityID' => 'https://sp.example.com/simplesaml/',
    'idp' => NULL,
    'discoURL' => 'https://discoverydsx.eduteamsedugain.org/wayf.php?filter=eyJhbGxvd0hvc3RlbCI6dHJ1ZSwiYWxsb3dIb3N0ZWxSZWciOnRydWV9Cg==',
    'privatekey' => 'example.key'
),


Filter by reference - efilter

Code Block
https://discoverydsx.eduteamsedugain.org/wayf.php?efilter=www.example.com/filter

where contents of www.example.com/filter would be a plain text document containing the filter, for example:

Code Block
eyJhbGxvd0hvc3RlbCI6dHJ1ZSwiYWxsb3dIb3N0ZWxSZWciOnRydWV9Cg==

...

Expand
titleExample: Shibboleth SP


Code Block
title/etc/shibboleth/shibboleth2.xml
<SSO
    discoveryProtocol="SAMLDS"
    discoveryURL="https://discoverydsx.eduteamsedugain.org/wayf.php?efilter=www.example.com/filter">
    SAML2 SAML1
</SSO>


...

Expand
titleExample: SimpleSAMLphp


Code Block
titleauthsources.php
'default-sp' => array(
    'saml:SP',
    'entityID' => 'https://sp.example.com/simplesaml/',
    'idp' => NULL,
    'discoURL' => 'https://discoverydsx.eduteamsedugain.org/wayf.php?efilter=www.example.com/filter',
    'privatekey' => 'example.key'
),


More complex filters

The filter language supports scenarios that are not currently covered by the filter generator, but that can be manually constructed. Similarly, it is possible to programmatically generate your own filters by referencing a script hosted at the efilter  location.  In both cases, you create a filter by generating an appropriate JSON object and then base64 encoding it.

A good starting point is to get the filter as close as possible to your needs using the filter generator at https://dsx.edugain.org/filter (e.g. honouring hide-from-discovery). You can then take the resulting JSON object show as the "Human readable form of filter" and further customise it further to your needs.


Expand
titleExample: Registration Authority

It is possible to filter IdPs by their registration authority (the federation that they come from). This may be useful when you want to list only the IdPs from a specific subset of eduGAIN that are not already identified by an entity category (for instance, only from certain countries).

The registration authority is usually specified as a URL identifying the federation operator. You can determine the correct one either from the federation's entry on the eduGAIN technical site or by examining metadata for the <mdrpi:RegistrationInfo registrationAuthority=""> element.

For instance, the South African Identity Federation uses a registration authority of https://safire.ac.za. To list only IdPs from this federation, you'd need to generate a JSON filter object like this:

Code Block
{"ver":"2","allowFeeds":{"eduGAIN":{"allowRA":["https://safire.ac.za"],"denyEC":["http://refeds.org/category/hide-from-discovery"]}}}

which would then be base64 encoded to produce a filter:

Code Block
eyJ2ZXIiOiIyIiwiYWxsb3dGZWVkcyI6eyJlZHVHQUlOIjp7ImFsbG93UkEiOlsiaHR0cHM6Ly9zYWZpcmUuYWMuemEiXSwiZGVueUVDIjpbImh0dHA6Ly9yZWZlZHMub3JnL2NhdGVnb3J5L2hpZGUtZnJvbS1kaXNjb3ZlcnkiXX19fQ==


You can also remove IdPs from a specific federation in a similar way, by using the denyRA keyword.