README

A SimpleSAMLphp module for advanced attribute filtering based on Service Provider entityIDs. This module allows you to define different attribute release policies for different SPs, filtering attributes based on pattern matching against attribute values.

Features

Define a default filter policy for all Service Providers
Override policies for specific Service Providers by entityID
Filter attributes completely (remove them) or filter specific values using pattern matching
Performance optimization through configuration caching
Strict attribute name validation against standard SAML attribute maps

Versioning and compatibility

This repository maintains multiple branches to support different versions of SimpleSAMLphp:

master: The active development branch containing the latest features and updates. This is the development version and may be unstable.
release-1: Maintains compatibility with SimpleSAMLphp 1.x (legacy support, up to version ~1.19).
- Tested with PHP 7.4
release-2: Supports SimpleSAMLphp 2.x and newer versions.
- Tested with PHP 8.1-8.4

Please select the branch corresponding to the SimpleSAMLphp version you are using. By using Composer the correct version will be installed automatically.

Installation

Using Composer

composer require arnesaai/simplesamlphp-module-attributevaluefilter

Manual Installation

Download or clone this repository
Place it in the modules directory of your SimpleSAMLphp installation
Enable the module by creating an empty file named default-enable in the module's root directory

Configuration

Create a file named config-avf.ph in the SimpleSAMLphp config directory. A config template is provided in the config-template directory that you can copy and modify:

cp modules/attributevaluefilter/config-template/config-avf.php config/

Below is an example configuration:

<?php

$config = [
    'default' => [
        'eduPersonEntitlement' => 'NULL',  // Remove completely
        'schacPersonalUniqueID' => 'NULL', // Remove completely
        'mail' => 'NULL'                   // Remove completely
    ],
    'https://sp.example.org/sp' => [
        'schacPersonalUniqueID' => [
            'urn:schac:personalUniqueID:EMŠO',  // Only keep values containing this pattern
            'urn:schac:personalUniqueID:SI'     // Or this pattern
        ],
        'mail' => [
            'example.org'  // Only keep email addresses containing this domain
        ]
    ],
    'research.org/portal' => [
        'eduPersonEntitlement' => [
            'urn:mace:example.org:researcher',
            'urn:mace:example.org:member'
        ]
    ]
];

Configuration Structure

default: Required section that defines the default filtering rules for all SPs
SP-specific sections (identified by entityID): Override the default rules for specific SPs

Filter Values

'NULL': Removes the attribute completely
Array of patterns: Keeps only values that contain at least one of the specified patterns

Filter Ordering

⚠️ IMPORTANT: This filter must be placed before the consent module in your authentication processing chain. Specifically:

Place it immediately after expireDate filter (if used)
Always place it before the consent module

If you don't follow this order, the consent page will show unfiltered attributes to the user, even though they will be filtered before being sent to the SP!

Example authproc configuration in saml20-idp-hosted.php:

'authproc' => [
    10 => 'core:AttributeMap',
    20 => 'core:ExpireDate',
    // AttributeValueFilter should come right after ExpireDate
    30 => 'attributevaluefilter:AttributeValueFilter',
    // Other filters...
    90 => 'consent:Consent',  // Consent must come after AttributeValueFilter
],

Examples

Example 1: Limiting Email Domains

'https://webmail.example.org' => [
    'mail' => [
        '@example.org',  // Only allow example.org email addresses
    ]
],

Example 2: Filtering Entitlements

'https://admin.example.org' => [
    'eduPersonEntitlement' => [
        ':admin',  // Only keep entitlements containing ":admin"
    ],
    'eduPersonAffiliation' => [
        'staff',   // Only keep "staff" affiliation
    ]
],

Example 3: Personal IDs

'https://service.gov.example' => [
    'schacPersonalUniqueID' => [
        'urn:schac:personalUniqueCode:int:esi:GOV',
        'urn:example:personalID:',
    ],
],

Validation

The module validates all attribute names against standard SimpleSAMLphp attribute maps, ensuring that only recognized attributes are configured. When an unrecognized attribute is found, the module will log an error and throw an exception to prevent misconfiguration.

Performance Optimization

AttributeValueFilter includes a caching mechanism to improve performance:

Filters are parsed and processed on first use, then cached
The cache is automatically invalidated when the configuration changes
Cache files are stored in the module's /cache directory

Error Handling

The module implements strict error handling:

Configuration errors throw exceptions to prevent misconfigurations from silently failing
Invalid attribute names are detected and reported
Detailed error messages help identify configuration problems
All errors are logged for troubleshooting

Logging

The module provides detailed debug logs of its operation, showing which attributes are kept and which are filtered. Debug logs also show:

Cache status and invalidation
Filter initialization
Attribute value matching against patterns
Configuration validation

License

This module is released under the LGPL-2.1-or-later license.

Support

For issues and feature requests: https://xdev.arnes.si/open/aai/simplesamlphp-module-attributevaluefilter/-/issues.

arnesaai / simplesamlphp-module-attributevaluefilter

Maintainers

Details