# mgernand/aspnetcore.authorization.permissions architecture

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

- Interactive diagram: https://gitdiagram.com/mgernand/aspnetcore.authorization.permissions
- Repository: https://github.com/mgernand/aspnetcore.authorization.permissions

## Overview

##### Project type and purpose
- This is an open-source .NET 6+ library (AspNetCore.Authorization.Permissions) plus a set of sample ASP.NET Core Razor-Pages applications.
- Purpose: provide a dynamic, permission-based authorization framework for ASP.NET Core, with extensible storage (EF Core, MongoDB) and optional multi-tenant support.

##### File structure
- Top-level “src” folder holds library projects:
- Abstractions (interfaces, extensions)
- Core authorization implementation
- ASP.NET Core Identity integration (core, EF Core store, MongoDB store)
- Shared extensions and stores
- “samples” folder has four Razor-Pages web apps showing EF Core (“SamplePermissions”, “SampleTenant”) and MongoDB (“MongoSamplePermissions”, “MongoSampleTenant”) usage.
- “tests” contains unit tests for core and integration tests for EF Core and MongoDB implementations.

##### Key README insights
- Library is split into two major parts:
a. Base definitions, extension methods, policy handlers (ClaimsPrincipal extensions, RequirePermissionAttribute).
b. Storage/provider implementations for ASP.NET Core Identity (EF Core and MongoDB).
- Optional multi-tenant: tenants contribute extra role permissions and tenant claims.

##### Main components & their interactions
a. Web Host / Sample Application
- Razor Pages controllers and Minimal API endpoints.
- References: AspNetCore.Authorization.Permissions library + Identity + EF Core or MongoDB packages.
b. ASP.NET Core Pipeline
1. HTTP Request → Authentication middleware (ASP.NET Identity cookies or JWT)
2. PermissionsAuthorization middleware (AddPermissionsAuthorization)
3. Policy evaluation via AuthorizationPolicyProvider
4. RequirePermissionAttribute / Minimal API RequirePermission handlers
c. Permissions Core
- IClaimsProvider & IUserPermissionsService interfaces (in Abstractions).
- PermissionEndpointConventionBuilderExtensions, PermissionPolicyHandler, PermissionRequirement.
- ClaimsPrincipalExtensions → HasPermission()
d. Identity Integration
- Extensions.Identity.Permissions.Core: generic managers, stores interfaces, DI setup.
- AspNetCore.Identity.Permissions.EntityFrameworkCore: EF Core model configurations, DbContextExtensions.
- AspNetCore.Identity.Permissions.MongoDB: Schema ensure scripts, MongoDB stores.
e. Data Stores
- InvoicesContext (EF Core) backed by SQLite/SQL Server.
- MongoDB database for tenants and permissions.
f. Multi-tenant components
- ITenantProvider adds tenant claim
- TenantStore & TenantManager load tenant roles and permissions

##### Architectural patterns & design principles
- Layered architecture: Abstractions → Core services → Implementations
- Plugin/Provider pattern: IClaimsProvider, ITenantProvider, IPermissionStore allow swapping persistence.
- Policy/Strategy pattern for authorization policies
- Dependency Injection for all extension points

##### Don’t overthink—separate into as many components as makes sense
- How DI brings together Abstractions + Core + chosen Implementation (EF or Mongo)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        SamplePermissions["SamplePermissions"]:::sample
        SampleTenant["SampleTenant"]:::sample
        MongoSamplePermissions["MongoSamplePermissions"]:::sample
        MongoSampleTenant["MongoSampleTenant"]:::sample
    end

    %% ASP.NET Core Pipeline
    subgraph "ASP.NET Core Pipeline"
        direction TB
        AuthMiddleware["Authentication Middleware"]:::pipeline
        PermissionsAuth["PermissionsAuthorization Middleware"]:::pipeline
        PolicyProvider["AuthorizationPolicyProvider"]:::pipeline
        RequirementHandler["RequirePermissionAttribute / Minimal API Handlers"]:::pipeline
    end

    %% Permissions Core
    subgraph "Permissions Core Library"
        direction TB
        Abstractions["Abstractions Layer"]:::core
        CoreLib["Permissions Core Library"]:::core
    end

    %% Identity Integration
    subgraph "Identity Integration Libraries"
        direction TB
        ExtCore["Extensions.Identity.Permissions.Core"]:::integration
        IdentityDefault["AspNetCore.Identity.Permissions"]:::integration
        EFImpl["EF Core Store Implementation"]:::integration
        MongoImpl["MongoDB Store Implementation"]:::integration
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        SQLDB["SQL/SQLite Database"]:::datastore
        MongoDB["MongoDB Database"]:::datastore
    end

    %% Flows
    SamplePermissions -->|"HTTP Request"| AuthMiddleware
    SampleTenant --> AuthMiddleware
    MongoSamplePermissions --> AuthMiddleware
    MongoSampleTenant --> AuthMiddleware

    AuthMiddleware -->|"requests authorization"| PermissionsAuth
    PermissionsAuth -->|"build policy"| PolicyProvider
    PolicyProvider -->|"evaluate requirement"| RequirementHandler
    RequirementHandler -->|"fetch claims"| Abstractions
    Abstractions -->|"IClaimsProvider, IUserPermissionsService"| CoreLib
    CoreLib -->|"uses interfaces"| ExtCore
    ExtCore -->|"Identity stores/managers"| IdentityDefault
    IdentityDefault -->|"EF Store"| EFImpl
    IdentityDefault -->|"Mongo Store"| MongoImpl
    EFImpl -->|"reads/writes"| SQLDB
    MongoImpl -->|"reads/writes"| MongoDB

    %% Click Events
    click Abstractions "https://github.com/mgernand/aspnetcore.authorization.permissions/tree/main/src/AspNetCore.Authorization.Permissions.Abstractions/*"
    click CoreLib "https://github.com/mgernand/aspnetcore.authorization.permissions/tree/main/src/AspNetCore.Authorization.Permissions/*"
    click ExtCore "https://github.com/mgernand/aspnetcore.authorization.permissions/tree/main/src/Extensions.Identity.Permissions.Core/*"
    click IdentityDefault "https://github.com/mgernand/aspnetcore.authorization.permissions/tree/main/src/AspNetCore.Identity.Permissions/*"
    click EFImpl "https://github.com/mgernand/aspnetcore.authorization.permissions/tree/main/src/AspNetCore.Identity.Permissions.EntityFrameworkCore/*"
    click MongoImpl "https://github.com/mgernand/aspnetcore.authorization.permissions/tree/main/src/AspNetCore.Identity.Permissions.MongoDB/*"
    click SamplePermissions "https://github.com/mgernand/aspnetcore.authorization.permissions/tree/main/samples/SamplePermissions/*"
    click SampleTenant "https://github.com/mgernand/aspnetcore.authorization.permissions/tree/main/samples/SampleTenant/*"
    click MongoSamplePermissions "https://github.com/mgernand/aspnetcore.authorization.permissions/tree/main/samples/MongoSamplePermissions/*"
    click MongoSampleTenant "https://github.com/mgernand/aspnetcore.authorization.permissions/tree/main/samples/MongoSampleTenant/*"
    click SQLDB "https://github.com/mgernand/aspnetcore.authorization.permissions/tree/main/src/AspNetCore.Identity.Permissions.EntityFrameworkCore/*"
    click MongoDB "https://github.com/mgernand/aspnetcore.authorization.permissions/tree/main/src/AspNetCore.Identity.Permissions.MongoDB/*"

    %% Styles
    classDef sample fill:#f9f,stroke:#333,stroke-width:1px
    classDef pipeline fill:#fff3cd,stroke:#333,stroke-width:1px,stroke-dasharray: 4 2
    classDef core fill:#cfe2ff,stroke:#333,stroke-width:1px
    classDef integration fill:#d1e7dd,stroke:#333,stroke-width:1px
    classDef datastore fill:#ffe5b4,stroke:#333,stroke-width:1px,shape:cylinder
```
