What is SAML SSO? 

SAML (Security Assertion Markup Language) is an open standard for exchanging authentication and authorization data between parties, specifically between an Identity Provider (IdP) and a Service Provider (SP).

Single Sign-On (SSO) allows users to authenticate once with an Identity Provider and then access multiple applications without re-entering credentials.

Extension Features 

The Netresearch SAML Auth extension provides:

• Frontend Authentication: SAML-based login for frontend users
• Backend Authentication: SAML-based login for backend users
• Auto-Discovery: Automatic SAML configuration detection based on domain
• User Provisioning: Automatic creation of TYPO3 users from SAML attributes
• Deep Link Support: Redirect users to their original destination after login
• PSR-14 Events: Modern event system for customization

Requirements 

Support 

For issues and feature requests, please use the GitHub issue tracker.

Composer Installation 

Install the extension using Composer:

composer require netresearch/nr-saml-auth

After installation, activate the extension in the Extension Manager or via CLI:

vendor/bin/typo3 extension:setup

Initial Setup 

After installation, you need to:

1. Create a SAML Auth Settings record on the root page (PID 0) in the TYPO3 backend under List > Create new record > SAML Auth Settings
2. Configure the Service Provider (SP) settings (your TYPO3 installation)
3. Configure the Identity Provider (IdP) settings (your SSO server)
4. Select the user folder and default user groups for new users

See the Configuration section for detailed setup instructions.

Verification 

To verify the installation:

1. Access the Admin Tools > SAML Auth backend module
2. Check that your SAML metadata is correctly generated
3. Share the SP metadata with your Identity Provider administrator

Creating a Settings Record 

1. Go to List module on the root page (PID 0)
2. Click Create new record
3. Select SAML Auth Settings

Service Provider (SP) Configuration 

The Service Provider represents your TYPO3 installation.

https://your-domain.tld

https://your-domain.tld/?logintype=login

Identity Provider (IdP) Configuration 

The Identity Provider is your SSO server (e.g., Azure AD, Okta, SimpleSAMLphp).

User Configuration 

sso-

Auto-Discovery 

The extension supports automatic configuration discovery based on the request domain. When a user attempts to login, the extension matches the current domain against configured sp_entity_id values to find the appropriate SAML configuration.

This allows multiple SAML configurations for different domains within the same TYPO3 installation.

SAML Settings Record Fields 

Example Configuration 

# Service Provider Settings
Entity ID: https://your-domain.tld
Customer Service URL: https://your-domain.tld/?logintype=login
Customer Service Binding: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
Name ID Format: urn:oasis:names:tc:SAML:2.0:nameid-format:transient

# Identity Provider Settings
Entity ID: urn:example:idp
SSO URL: https://idp.example.com/sso
Binding: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
Certificate: [IDP Certificate]

# User Settings
Username Prefix: sso-
User Folder: [Select frontend user folder]
User Groups: [Select default frontend user groups]

Architecture Overview 

The extension uses the following key components:

Dependency Injection 

All services are registered in the DI container and can be injected into your own classes:

use Netresearch\NrSamlAuth\Service\SamlService;

class MyController
{
    public function __construct(
        private readonly SamlService $samlService
    ) {}
}

Extending User Creation 

To customize user creation, listen to the PSR-14 events documented in the Events section.

Example: Adding custom user attributes from SAML response:

use Netresearch\NrSamlAuth\Event\BeforeUserCreationEvent;

class CustomUserAttributeListener
{
    public function __invoke(BeforeUserCreationEvent $event): void
    {
        $attributes = $event->getSamlAttributes();
        $userData = $event->getUserData();

        // Add custom attribute mapping
        $userData['custom_field'] = $attributes['customAttribute'][0] ?? '';

        $event->setUserData($userData);
    }
}

Available Events 

namespace Netresearch\NrSamlAuth\Event;

final class BeforeUserCreationEvent
{
    public function getSamlAttributes(): array;
    public function getUserData(): array;
    public function setUserData(array $userData): void;
    public function getSettings(): Settings;
}

namespace Netresearch\NrSamlAuth\Event;

final class AfterUserCreationEvent
{
    public function getUser(): array;
    public function getSamlAttributes(): array;
    public function getSettings(): Settings;
}

namespace Netresearch\NrSamlAuth\Event;

final class BeforeAuthenticationEvent
{
    public function getSamlResponse(): Response;
    public function getSettings(): Settings;
    public function setSkipAuthentication(bool $skip): void;
}

Registering Event Listeners 

Register your event listeners in your extension's Services.yaml:

# Configuration/Services.yaml
services:
  Vendor\MyExtension\EventListener\CustomUserCreationListener:
    tags:
      - name: event.listener
        identifier: 'myextension/custom-user-creation'
        event: Netresearch\NrSamlAuth\Event\BeforeUserCreationEvent

Example Implementation 

Custom attribute mapping:

namespace Vendor\MyExtension\EventListener;

use Netresearch\NrSamlAuth\Event\BeforeUserCreationEvent;

final class CustomUserCreationListener
{
    public function __invoke(BeforeUserCreationEvent $event): void
    {
        $attributes = $event->getSamlAttributes();
        $userData = $event->getUserData();

        // Map department to custom field
        if (isset($attributes['department'][0])) {
            $userData['tx_myext_department'] = $attributes['department'][0];
        }

        // Map employee ID
        if (isset($attributes['employeeId'][0])) {
            $userData['tx_myext_employee_id'] = $attributes['employeeId'][0];
        }

        $event->setUserData($userData);
    }
}

Upgrading from 10.x to 12.x 

Version 12.x includes breaking changes for TYPO3 12.4/13.4 compatibility.

// OLD: Legacy hook (removed)
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['nr_saml_auth']['beforeUserCreation']

// NEW: PSR-14 event
Netresearch\NrSamlAuth\Event\BeforeUserCreationEvent

// OLD: Direct instantiation (deprecated)
$service = new \Netresearch\NrSamlAuth\Service\SamlService();

// NEW: Dependency injection
public function __construct(
    private readonly SamlService $samlService
) {}

Backward Compatibility 

The extension maintains backward compatibility for:

• SAML Settings record structure
• Database schema
• SAML response handling

The following are NOT backward compatible:

• PHP 7.x support (requires 8.1+)
• TYPO3 10.4/11.5 support (requires 12.4+)
• Legacy hook system (use PSR-14 events)

Version 12.0.0 

Released: (not yet released)

Version 10.0.10 

Released: 2024

Version 10.0.x 

• TYPO3 10.4 and 11.5 LTS support
• PHP 7.4 - 8.1 support
• Initial SAML SSO implementation