# novactive/almaviacxibexasamlbundle architecture

> Architecture diagram of the GitHub repository novactive/almaviacxibexasamlbundle, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/novactive/almaviacxibexasamlbundle
- Repository: https://github.com/novactive/almaviacxibexasamlbundle

## Overview

##### Project Type and Purpose
- This is a Symfony-based bundle (a plugin/module) that adds SAML authentication support to Ibexa.
- The bundle handles SAML configuration, dependency injection, view customization, and authentication logic by connecting with an external SAML Identity Provider (IdP).

##### File Structure
- Top-level files (LICENSE, README.md, composer.json, ci-config.yaml) indicate this is a well-packaged, deployable library.
- The “src” directory is split into two main sections:
- The “bundle” folder encapsulates the Symfony bundle itself. It contains:
▪ The main bundle PHP class (AlmaviaCXIbexaSamlBundle.php).
▪ A DependencyInjection subdirectory with extension classes (e.g., AlmaviaCXIbexaSamlExtension.php) and a Compiler folder (LazySaml2Auth.php). These facilitate service registration and custom compilation passes.
▪ A Resources directory for configuration (YAML files such as default_settings.yaml, services.yaml), translations, and Twig view templates for the admin login interface.
- The “lib” folder holds the core business logic under Security/Saml:
▪ SamlAuthFactory, SamlUserFactory, SamlUserProvider, and related classes handling low-level SAML operations, error handling (SamlException, SamlExceptionLogger), and user creation/mapping.

##### Key Components
- SAML Bundle – Represents the high-level integration into the Ibexa project.
- Integration into Symfony’s Dependency Injection container (via the Extension and Compiler classes).
- How YAML configuration files (default_settings.yaml, services.yaml, monolog.yaml, etc.) are processed.
- SAML Library – The “lib” directory with classes handling:
- Authentication factory (SamlAuthFactory)
- User provider and factory for creating or loading users based on SAML assertions.
- Exception handling and logging specific to SAML operations.
- SAML IdP configuration (entityId, login/logout URLs, bindings, X509 Certificate, email attribute).
- SAML Service Provider (SP) settings.
- External SAML Identity Provider (IdP) – Represent the external SAML service that the bundle communicates with.
- Ibexa Application / Security Layer – Show the integration where the bundle’s configuration modifies the security firewall and routes (like /saml/login, /saml/acs, /saml/logout) in the Ibexa application.

##### Relationships and Interactions
- Data flow: From the configuration files/environment variables into the Dependency Injection process.
- The SAML Bundle’s registration of services via DependencyInjection and Compiler passes.
- How SAML authentication requests and responses are handled by the SamlAuthFactory and routed controllers.
- The SAML User Provider’s role in mapping SAML attributes to Ibexa users.
- Communication between the Ibexa application’s UI (admin login page utilizing the Twig template) and the SAML endpoints.
- The flow of authentication data between the SAML Service Provider (your bundle) and the external IdP.

##### Specific Architectural Patterns / Principles
- Dependency Injection – Evident from the DI directory and compiler passes.
- Configuration-Driven Behavior – YAML configuration and environment variables drive the behavior of the authentication logic.
- Separation of Concerns – The division between the “bundle” (integration with Symfony and Ibexa) and “lib” (pure SAML logic/security services) is an important architectural separation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Configuration & Environment Variables
    ConfigEnv["Configuration & Environment Variables"]:::config

    %% Layer 2: YAML Configuration Files
    subgraph "YAML Config Files"
        Y1["Default Settings"]:::config
        Y2["Service Definitions"]:::config
        Y3["SAML Prepend Config"]:::config
        Y4["Monolog Config"]:::config
    end

    %% Admin Login Twig Template (View Layer)
    AdminTwig["Admin Login Twig Template"]:::view

    %% Layer 3: SAML Bundle (Integration Layer) with Dependency Injection components
    subgraph "SAML Bundle (Integration Layer)"
        DI_Ext["Dependency Injection Extension"]:::bundle
        Compiler["Compiler Pass for Lazy Authentication"]:::bundle
        S_Bundle["SAML Bundle"]:::bundle
    end

    %% Layer 4: SAML Library (Security Logic)
    subgraph "SAML Library (Security Logic)"
        AuthFactory["SamlAuthFactory"]:::lib
        Exception["SamlException"]:::lib
        ExceptionLogger["SamlExceptionLogger"]:::lib
        UserFactory["SamlUserFactory"]:::lib
        UserProvider["SamlUserProvider"]:::lib
    end

    %% Layer 5: Ibexa Security & Routing and External SAML IdP
    Ibexa["Ibexa Security & Routing"]:::routing
    ExternalIdP["External SAML IdP"]:::external

    %% Connections from Configuration to YAML Files
    ConfigEnv -->|feeds| Y1
    ConfigEnv -->|feeds| Y2
    ConfigEnv -->|feeds| Y3
    ConfigEnv -->|feeds| Y4

    %% Connection from one of the YAML files to Dependency Injection Extension as representative of config flow
    Y2 -->|configures| DI_Ext

    %% Within SAML Bundle subgraph: DI and Compiler feed into main Bundle
    DI_Ext -->|registers| S_Bundle
    Compiler -->|compiles| S_Bundle

    %% SAML Bundle triggers view and library logic
    S_Bundle -->|renders| AdminTwig
    S_Bundle -->|initiates| AuthFactory
    S_Bundle -->|communicates| ExternalIdP
    S_Bundle -->|integrates with| Ibexa

    %% SAML Library internal flow
    AuthFactory -->|creates| UserFactory
    UserFactory -->|provides user to| UserProvider
    AuthFactory -->|error| Exception
    Exception -->|logged by| ExceptionLogger

    %% SAML Library provides user mapping to Ibexa Security
    UserProvider -->|maps attributes| Ibexa

    %% Additionally, Admin Twig view connects to Ibexa Security for UI integration
    AdminTwig -->|displays login| Ibexa

    %% Click Events
    click S_Bundle "https://github.com/novactive/almaviacxibexasamlbundle/blob/master/src/bundle/AlmaviaCXIbexaSamlBundle.php"
    click DI_Ext "https://github.com/novactive/almaviacxibexasamlbundle/blob/master/src/bundle/DependencyInjection/AlmaviaCXIbexaSamlExtension.php"
    click Compiler "https://github.com/novactive/almaviacxibexasamlbundle/blob/master/src/bundle/DependencyInjection/Compiler/LazySaml2Auth.php"
    click Y1 "https://github.com/novactive/almaviacxibexasamlbundle/blob/master/src/bundle/Resources/config/default_settings.yaml"
    click Y2 "https://github.com/novactive/almaviacxibexasamlbundle/blob/master/src/bundle/Resources/config/services.yaml"
    click Y3 "https://github.com/novactive/almaviacxibexasamlbundle/blob/master/src/bundle/Resources/config/prepend/hslavich_onelogin_saml.yaml"
    click Y4 "https://github.com/novactive/almaviacxibexasamlbundle/blob/master/src/bundle/Resources/config/prepend/monolog.yaml"
    click AdminTwig "https://github.com/novactive/almaviacxibexasamlbundle/blob/master/src/bundle/Resources/views/themes/admin/account/login/saml_login.html.twig"
    click AuthFactory "https://github.com/novactive/almaviacxibexasamlbundle/blob/master/src/lib/Security/Saml/SamlAuthFactory.php"
    click Exception "https://github.com/novactive/almaviacxibexasamlbundle/blob/master/src/lib/Security/Saml/SamlException.php"
    click ExceptionLogger "https://github.com/novactive/almaviacxibexasamlbundle/blob/master/src/lib/Security/Saml/SamlExceptionLogger.php"
    click UserFactory "https://github.com/novactive/almaviacxibexasamlbundle/blob/master/src/lib/Security/Saml/SamlUserFactory.php"
    click UserProvider "https://github.com/novactive/almaviacxibexasamlbundle/blob/master/src/lib/Security/Saml/SamlUserProvider.php"

    %% Styles
    classDef config fill:#f9e79f,stroke:#d4ac0d,stroke-width:2px;
    classDef bundle fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef lib fill:#a3e4d7,stroke:#16a085,stroke-width:2px;
    classDef routing fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef external fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;
    classDef view fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
```
