README

This project has reached end of life, which means no new features will be added. Security patches and important bug fixes will end as of 2024. Check out RCIAM METRICS instead.

Description

Module for simpleSAMLphp which shows Proxy IdP/SP statistics

Contribution

This repository uses Conventional Commits.

Any change that significantly changes behavior in a backward-incompatible way or requires a configuration change must be marked as BREAKING CHANGE.

Available scopes:

• design
• Auth Process filters:
  • statistics
• ...

Instalation

Once you have installed SimpleSAMLphp, installing this module is very simple. First of all, you will need to download Composer if you haven't already. After installing Composer, just execute the following command in the root of your SimpleSAMLphp installation:

php composer.phar require cesnet/simplesamlphp-module-proxystatistics

Configuration

1. Install MySQL Database and create database for statistics and user.
2. For this database run script to create tables. Script is available in config-templates/tables.sql.
3. Copy config-templates/module_proxystatistics.php to your config folder and fill it.
4. Configure, according to mode

• PROXY - collects data about number of logins from each identity provider and accessed services; for PROXY mode, configure IdPAttribute filter from Perun module to get sourceIdPName from IdP metadata:

    50 => [
        'class' => 'perun:IdPAttribute',
        'attrMap' => [
            'name:en' => 'sourceIdPName',
        ],
    ],
    // where 50 is priority (for example, must not be used for other modules)

• IDP - collects data about accessed services through given identity provider; for IDP mode, configure entity ID and name in module_proxystatistics.php

    'IDP' => [
        'id' => '',
        'name' => '',
    ],

• SP - collects data about identity providers used for access to given service; for SP mode, configure entity ID and name in module_proxystatistics.php

    'SP' => [
        'id' => '',
        'name' => '',
    ],

• MULTI_IDP - similar to IDP mode, stores more identity providers in one database; for MULTI_IDP mode, configure entity ID and name in each module_proxystatistics.php we want to get statistics from

    'IDP' => [
        'id' => '',
        'name' => '',
    ],

1. Configure proxystatistics filter

    50 => [
        'class' => 'proxystatistics:Statistics',
    ],
    // where 50 is priority (for example, must not be used for other modules)

1. Add to config.php:

'instance_name' => 'Instance name',

Writing via API

Authproc filter: writing login events to external APIs

Use proxystatistics:ApiStatistics in your authproc pipeline and configure one or both API targets.

    60 => [
        'class' => 'proxystatistics:ApiStatistics',
        'usernameAttribute' => 'uid',
        'idpIdentifierAttribute' => 'sourceIdPEntityID',
        'idpNameAttribute' => 'sourceIdPName',

        // Legacy endpoint (Basic auth)
        'oldApi' => [
            'apiUrl' => 'https://proxy.com/proxy/module.php/proxystatistics/writeLoginApi.php',
            'apiUsername' => 'api_writer',
            'apiPassword' => 'ap1Wr1T3rP@S$',
        ],

        // New endpoint (API key)
        'newApi' => [
            'apiUrl' => 'http://app.url/api/events/signin',
            'apiKey' => 'your-secret-write-key',
        ],
    ],

Behavior:

• If oldApi is configured (apiUrl, apiUsername, apiPassword), login events are sent to the old endpoint.
• If newApi is configured (apiUrl, apiKey), login events are sent to the new endpoint.
• If both are configured, the filter writes to both endpoints.
• If none is fully configured, no API write is performed.

Configuration

Add the following (and adjust the credentials) to enable writing via the API (example request following). Methods supported are POST,PUT.

  'apiWriteEnabled' => true,
  'apiWriteUsername' => 'api_writer',
  'apiWritePasswordHash' => password_hash('ap1Wr1T3rP@S$'),

Example request

curl --request POST \
  --url https://proxy.com/proxy/module.php/proxystatistics/writeLoginApi.php \
  --header 'Authorization: Basic encodedCredentials' \
  --header 'Content-Type: application/json' \
  --data '{
	"userId": "user@somewhere.edu",
	"serviceIdentifier": "https://service.com/shibboleth",
	"serviceName": "TEST_SERVICE",
	"idpIdentifier": "https://idp.org/simplesamlphp",
	"idpName": "TEST_IDP"
}'

New external statistics API example request

curl -X POST http://{app.url}/api/events/signin \
    -H "Content-Type: application/json" \
    -H "X-API-Key: your-secret-write-key" \
    -d '{
        "userId": "user123",
        "serviceId": "service-abc",
        "serviceName": "My Application",
        "idpId": "idp-xyz",
        "idpName": "SAML Identity Provider",
        "signinTime": "2026-03-02T10:15:30Z"
    }'