# bekirozturk/symfony-oauth2-bundle architecture

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

- Interactive diagram: https://gitdiagram.com/bekirozturk/symfony-oauth2-bundle
- Repository: https://github.com/bekirozturk/symfony-oauth2-bundle

## Overview

##### Project Type and Purpose
- This is a Symfony bundle specifically built for handling OAuth2 authentication flows in a Symfony application.
- Its primary purpose is to simplify the integration of SSO (Single Sign-On) based on OAuth2, providing endpoints, an authentication controller, and service methods to manage OAuth2 logic.

##### File Structure
- The project follows standard Symfony bundle architecture with key directories:
- src/Controller: Contains controller classes such as AuthController and a customizable OAuth2 controller (SymfonyOauth2Controller) which handles routes like /oauth2/authorize, /oauth2/check, and /oauth2/success.
- src/Service: Houses the OAuth2Service that encapsulates functionality for generating OAuth2 URLs, handling token requests, and retrieving user info.
- src/DependencyInjection: Configurations that allow the bundle to be integrated and configured via Symfony’s Dependency Injection component.
- src/Resources/config: Contains YAML configuration files for routing and service definitions.
- src/Resources/skeleton: Provides skeleton templates (for controllers, etc.) that developers might use to extend or customize behavior.
- composer.json and SymfonyOAuth2Bundle.php form the bundle's entry point and provide metadata for autoloading/integration.
- Deployment or configuration files (e.g., .gitignore) are also present but the main focus is on application-specific components.

##### Key Insights Gleaned from the README
- The README clearly explains installation, configuration (.env variables with OAuth2 endpoints and credentials), Docker configuration for local development, usage, available routes, and customization.
- It also details how the OAuth2Service is used by controllers to facilitate the OAuth2 flow.
- The documentation shows usage examples in both PHP and Twig, emphasizing that the core logic is handled through defined services and routing.

a. Main Components:
- Frontend Entry: While not a full front-end, the client (browser) will interact with defined routes (/oauth2/authorize, /oauth2/check, /oauth2/success).
- Controllers:
- AuthController – initiates OAuth2 redirection.
- SymfonyOauth2Controller – handles post-authentication (e.g., success page).
- OAuth2Service: Central service to manage generation of the OAuth2 authorization URL, token exchange via requestAccessToken(), and fetching user details via getUserInfo().
- Dependency Injection & Bundle Bootstrapping:
- DependencyInjection classes and configuration files under src/Resources/config which enable Symfony Flex integration (registration in bundles.php) and allow user customization.
- External OAuth2 Provider: Represents the SSO server endpoints that the bundle connects to (authorize, token, and userinfo URLs defined in the .env).

b. Relationships and Interactions:
- The client initiates authentication by invoking a route provided by AuthController.
- AuthController calls OAuth2Service to generate the authorization URL using parameters like state and code verifier (using PKCE).
- The user is then redirected to an external OAuth2 provider.
- Following the OAuth2 flow, the external provider redirects back to the defined callback endpoint (/oauth2/check) which is then managed by one of the controllers.
- On successful authentication, control passes to the SymfonyOauth2Controller’s success method where custom logic (user lookup, creation, or login) happens.
- Underlying service calls (OAuth2Service) manage the secure token exchange and data fetching.
- Dependency injection ensures these components (controller and service) are wired properly within Symfony.

c. Architectural Patterns & Design Principles:
- Use of the Symfony bundle pattern, promoting reusability and modularity.
- Separation of concerns: Controllers handle routing and HTTP logic, while the service layer encapsulates OAuth2 business logic.
- Dependency Injection is used extensively to facilitate testing and maintainability.
- Configuration-driven design: YAML and environment variables provide a highly customizable integration with external systems.

d. Technologies, Frameworks, and Libraries:
- Symfony Framework: The bundle integrates deeply with Symfony’s routing, DI container, and controller structure.
- Composer: For dependency management and autoloading the bundle.
- YAML Configuration: Used for routes and service definitions.
- PHP (including PHP attributes for routing in Symfony 5.2+).
- OAuth2 Concepts: Utilizes OAuth2, including PKCE (S256) for secure token exchange.

##### Final Assembly
- Finally, incorporate external systems (OAuth2 Provider endpoints) with clearly marked connections and data flows.

This level of detail ensures that every crucial aspect of the project’s architecture is captured, from user requests hitting the bundle’s endpoints to secure token management and user authentication logic—all integrated within the Symfony ecosystem.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actor
    Client["Client (Browser)"]:::external

    %% Authentication Flow
    subgraph "Authentication Flow"
        Auth["AuthController"]:::controller
        OAuthService["OAuth2Service"]:::service
        Callback["Callback Endpoint (/oauth2/check)"]:::endpoint
        OAuthController["SymfonyOauth2Controller"]:::controller
        Provider["External OAuth2 Provider"]:::external
    end

    %% Configuration Components
    subgraph "Configuration"
        DI1["Configuration.php"]:::config
        DI2["SymfonyOAuth2Extension.php"]:::config
        YAML1["routes.yaml"]:::config
        YAML2["services.yaml"]:::config
        YAML3["symfony_oauth2.yaml"]:::config
    end

    %% Bundle Integration & Metadata
    subgraph "Bundle Integration"
        Bundle["SymfonyOAuth2Bundle.php"]:::bundle
        Composer["composer.json"]:::bundle
    end

    %% Authentication Flow Connections
    Client -->|"initiate_auth"| Auth
    Auth -->|"generate_URL"| OAuthService
    OAuthService -->|"request_token"| Provider
    Provider -->|"redirect(oauth2/callback)"| Callback
    Callback -->|"finalize_auth"| OAuthController

    %% Configuration to Internal Components
    DI1 ---|"configures"| Auth
    DI1 ---|"configures"| OAuthService
    DI1 ---|"configures"| OAuthController
    DI2 ---|"configures"| Auth
    DI2 ---|"configures"| OAuthService
    DI2 ---|"configures"| OAuthController
    YAML1 ---|"routing_defines"| Auth
    YAML1 ---|"routing_defines"| OAuthController
    YAML2 ---|"service_defines"| OAuthService
    YAML3 ---|"oauth2_config"| OAuthService

    %% Bundle Integration Connections
    Bundle -->|"bootstraps"| DI1
    Bundle -->|"bootstraps"| DI2
    Bundle -->|"includes"| YAML1
    Bundle -->|"includes"| YAML2
    Bundle -->|"includes"| YAML3
    Composer -->|"manages"| Bundle

    %% Click Events for Component Mapping
    click Auth "https://github.com/bekirozturk/symfony-oauth2-bundle/blob/main/src/Controller/AuthController.php"
    click OAuthController "https://github.com/bekirozturk/symfony-oauth2-bundle/blob/main/src/Resources/skeleton/controller/SymfonyOAuth2Controller.php"
    click OAuthService "https://github.com/bekirozturk/symfony-oauth2-bundle/blob/main/src/Service/OAuth2Service.php"
    click DI1 "https://github.com/bekirozturk/symfony-oauth2-bundle/blob/main/src/DependencyInjection/Configuration.php"
    click DI2 "https://github.com/bekirozturk/symfony-oauth2-bundle/blob/main/src/DependencyInjection/SymfonyOAuth2Extension.php"
    click YAML1 "https://github.com/bekirozturk/symfony-oauth2-bundle/blob/main/src/Resources/config/routes.yaml"
    click YAML2 "https://github.com/bekirozturk/symfony-oauth2-bundle/blob/main/src/Resources/config/services.yaml"
    click YAML3 "https://github.com/bekirozturk/symfony-oauth2-bundle/blob/main/src/Resources/config/symfony_oauth2.yaml"
    click Bundle "https://github.com/bekirozturk/symfony-oauth2-bundle/blob/main/src/SymfonyOAuth2Bundle.php"
    click Composer "https://github.com/bekirozturk/symfony-oauth2-bundle/blob/main/composer.json"

    %% Styles
    classDef external fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef controller fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef service fill:#e6ffe6,stroke:#009900,stroke-width:2px;
    classDef config fill:#fff2cc,stroke:#ffcc00,stroke-width:2px;
    classDef bundle fill:#d1cce0,stroke:#6f42c1,stroke-width:2px;
    classDef endpoint fill:#ffd966,stroke:#ff9900,stroke-width:2px;
```
