Authentication Processing Filters in SimpleSAMLphp

In SimpleSAMLphp, there is an API where you can do stuff at the IdP after authentication is complete, and just before you are sent back to the SP. The same API is available on the SP, after you have received a successful Authentication Response from the IdP and before you are sent back to the SP application.

Authentication processing filters postprocess authentication information received from authentication sources. It is possible to use this for additional authentication checks, requesting the user's consent before delivering attributes about the user, modifying the user's attributes, and other things which should be performed before returning the user to the service provider they came from.

Examples of neat things to do using Authentication Processing Filters:

How to configure Auth Proc Filters

Auth Proc Filters can be set globally, or to be specific for only one SP or one IdP. That means there are five locations where you can configure Auth Proc Filters :

Note : An Auth Proc Filter will not work in the "Test authentication sources" option in the web UI of a SimpleSAMLphp IdP. It will only be triggered in conjunction with an actual SP. So you need to set up an IdP and and SP when testing your filter.

The configuration of Auth Proc Filters is a list of filters with priority as index . Here is an example of Auth Proc Filters configured in config.php :

'authproc.idp' => [
    10 => [
        'class' => 'core:AttributeMap',
        'addurnprefix'
    ],
    20 => 'core:TargetedID',
    50 => 'core:AttributeLimit',
    90 => [
        'class' => 'consent:Consent',
        'store' => 'consent:Cookie',
        'focus' => 'yes',
        'checked' => true
    ],
],

This configuration will execute Auth Proc Filters one by one, with the priority value in increasing order. When Auth Proc Filters is configured in multiple places, in example both globally, in the hosted IdP and remote SP metadata, then the list is interleaved sorted by priority.

The most important parameter of each item on the list is the class of the Auth Proc Filter . The syntax of the class is modulename:classname . As an example the class definition core:AttributeLimit will be expanded to look for the class \SimpleSAML\Module\core\Auth\Process\AttributeLimit . The location of this class file must then be: modules/core/src/Auth/Process/AttributeLimit.php .

You will see that a bunch of useful filters is included in the core and saml modules, but there are many others published as [SimpleSAMLphp modules)[https://simplesamlphp.org/modules/] you can install. Beyond that, you are encouraged to create your own filters and share with the community. If you have created a cool Auth Proc Filter that does something useful, let us know, and we may add it on the Modules overview.

When you know the class definition of a filter, and the priority, the simple way to configure the filter is:

20 => 'core:TargetedID',

This is analogous to:

20 => [
    'class' => 'core:TargetedID'
],

Some Auth Proc Filters have optional or required parameters . To send parameters to Auth Proc Filters , you need to choose the second of the two alternatives above. Here is an example of provided parameters to the consent module:

90 => [
    'class' => 'consent:Consent',
    'store' => 'consent:Cookie',
    'focus' => 'yes',
    'checked' => true,
],

Filters in config.php

Global Auth Proc Filters are configured in the config.php file. You will see that the config template already includes an example configuration.

There are two config parameters:

The filters in authproc.idp will be executed at the IdP side regardless of which IdP and SP entity that is involved.

The filters in authproc.sp will be executed at the SP side regardless of which SP and IdP entity that is involved.

Filters in metadata

Filters can be added both in hosted and remote metadata. Here is an example of a filter added in a metadata file:

$metadata['https://example.org/saml-idp'] = [
    'host' => '__DEFAULT_',
    'privatekey' => 'example.org.pem',
    'certificate' => 'example.org.crt',
    'auth' => 'feide',
    'authproc' => [
        40 => 'core:TargetedID',
    ],
]

The example above is in saml20-idp-hosted .

Preconditional filters

Any filter can be configured with a precondition that will determine whether or not a filter should run. The condition is represented as a string that will be evaluated, similar to the core:PHP filter. It also has the $attributes and $state variable available for use. The code must return either true to run the filter, or false to skip it.

'authproc' => [
    40 => 'core:TargetedID',
    '%precondition' => 'return $attributes["displayName"] === "John Doe";',
],

Auth Proc Filters included in the SimpleSAMLphp distribution

The following filters are included in the SimpleSAMLphp distribution:

See the Third-party modules page on the SimpleSAMLphp website for externally hosted modules that may provide a processing filter.

Writing your own Auth Proc Filter

Look at the included Auth Proc Filters as examples. Copy the classes into your own module and start playing around.

Authentication processing filters are created by creating a class under Auth/Process/ in a module. This class is expected to subclass \SimpleSAML\Auth\ProcessingFilter . A filter must implement at least one function - the process(&$request) -function. This function can access the $request -array to add, delete and modify attributes, and can also do more advanced processing based on the SP/IdP metadata (which is also included in the $request -array). When this function returns, it is assumed that the filter has finished processing.

If a filter for some reason needs to redirect the user, for example to show a web page, it should save the current request. Upon completion it should retrieve the request, update it with the changes it is going to make, and call \SimpleSAML\Auth\ProcessingChain::resumeProcessing . This function will continue processing the next configured filter.

Requirements for authentication processing filters:

Don't hestitate to ask on the SimpleSAMLphp mailinglist if you have problems or questions, or want to share your Auth Proc Filter with others.