GrydAuth Module

GrydAuth is a complete authentication and authorization module for .NET applications. It provides JWT/OAuth2 authentication, role-based access control (RBAC), permission-based authorization, and multi-tenancy support out of the box.

✨ Features

Feature	Description
🔐 JWT Authentication	Complete JWT token lifecycle with access/refresh tokens
👥 User Management	User registration, authentication, password management
🎭 Role-Based Access	Flexible role system with hierarchical permissions
🔑 Permission System	Granular permission-based authorization with policies
🏢 Multi-Tenancy	Built-in support for tenant isolation and federation
🌐 OAuth2/OIDC	Integration with Auth0, Azure AD, and custom providers
📍 Security Features	Rate limiting, audit logging, geo-location tracking
🔄 Token Invalidation	Real-time token blacklisting and version control

📦 Packages

GrydAuth is organized in multiple packages following Clean Architecture:

📦 GrydAuth
├── GrydAuth.Domain           # Entities, Value Objects, Domain Events
├── GrydAuth.Application      # Commands, Queries, Interfaces
├── GrydAuth.Infrastructure   # JWT, Repositories, External Services
├── GrydAuth.API              # Controllers, Middlewares, Filters
└── GrydAuth.Infrastructure.Auth0  # Auth0 integration (optional)

🚀 Quick Start

Installation

.NET CLI

# Install all GrydAuth packages
dotnet add package GrydAuth.API
dotnet add package GrydAuth.Infrastructure

# Optional: Auth0 integration
dotnet add package GrydAuth.Infrastructure.Auth0

Package Manager

Install-Package GrydAuth.API
Install-Package GrydAuth.Infrastructure

Basic Configuration

// Program.cs
using GrydAuth.API.Controllers;
using GrydAuth.Infrastructure;
using Gryd.API.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Add GrydAuth services (reads from appsettings.json)
builder.Services.AddGrydAuth(builder.Configuration);

// Add Controllers (includes GrydAuth API controllers)
builder.Services.AddControllers()
    .AddApplicationPart(typeof(AuthController).Assembly);

// Add Exception Handlers
builder.Services.AddGrydAuthExceptionHandler();
builder.Services.AddCoreExceptionHandler();

var app = builder.Build();

// Exception handling first
app.UseExceptionHandler();

// Authentication middleware
app.UseAuthentication();

// GrydAuth middleware (token blacklist, SmartFederation)
// CRITICAL: AFTER Authentication, BEFORE Authorization
app.UseGrydAuth();

// Authorization middleware
app.UseAuthorization();

app.MapControllers();
app.Run();

Configuration File

// appsettings.json
{
  "JwtSettings": {
    "SecretKey": "your-256-bit-secret-key-here-min-32-chars",
    "Issuer": "gryd-app",
    "Audience": "gryd-app-users",
    "ExpirationMinutes": 60,
    "RefreshTokenExpirationDays": 7
  },
  "GrydAuth": {
    "Cache": {
      "IsEnabled": true,
      "Redis": { "ConnectionString": "localhost:6379" }
    },
    "PasswordPolicy": {
      "MinLength": 8,
      "RequireDigit": true,
      "RequireLowercase": true,
      "RequireUppercase": true,
      "RequireSpecialChar": true
    },
    "Security": {
      "MaxFailedAccessAttempts": 5,
      "LockoutDurationMinutes": 15,
      "EnableSecurityLogging": true
    }
  },
  "MultiTenancy": {
    "IsEnabled": true
  }
}

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                       GrydAuth.API                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │ Controllers │  │ Middlewares │  │ Exception Handlers      │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    GrydAuth.Application                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │  Commands   │  │   Queries   │  │     Interfaces          │ │
│  │  - Login    │  │ - GetUser   │  │ - IAuthService          │ │
│  │  - Register │  │ - GetRoles  │  │ - ITokenService         │ │
│  │  - Refresh  │  │ - GetPerms  │  │ - IPermissionService    │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   GrydAuth.Infrastructure                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │   JWT Svc   │  │ Repositories│  │ Permission Handler      │ │
│  │ - Generate  │  │ - User      │  │ - Policy Provider       │ │
│  │ - Validate  │  │ - Role      │  │ - Auth Handler          │ │
│  │ - Refresh   │  │ - Tenant    │  │ - Claim Builder         │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      GrydAuth.Domain                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │  Entities   │  │Value Objects│  │    Domain Events        │ │
│  │  - User     │  │ - Email     │  │ - UserCreatedEvent      │ │
│  │  - Role     │  │ - Password  │  │ - RoleAssignedEvent     │ │
│  │  - Tenant   │  │ - Token     │  │ - PermissionChanged     │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

📊 Entity Relationship Diagram

The following diagram shows the complete data model for GrydAuth, including all entities and their relationships:

100% 💡 Use Ctrl + Scroll para zoom | Arraste para navegar

Entity Descriptions

Entity	Type	Description
User	Aggregate Root	Global user entity, not tied to specific tenants
Tenant	Aggregate Root	Organization/company in multi-tenancy system
UserTenant	Aggregate Root	User-Tenant relationship with roles and permissions
Role	Aggregate Root	Groups permissions together (tenant-scoped)
Permission	Aggregate Root	Defines actions that can be performed (tenant-scoped)
UserRole	Entity	Links UserTenant to Role
UserPermission	Entity	Direct permission assignment to UserTenant
RolePermission	Entity	Links Role to Permission (tenant-scoped)
UserAppId	Entity	Multi-app support - links User to application IDs
UserPasswordHistory	Entity	Password history for reuse prevention
FailedLoginAttempt	Entity	Security tracking for brute-force protection
PasswordResetToken	Entity	Token for password reset flow

Key Relationships

1. User ↔ Tenant (Many-to-Many via UserTenant)

   • Users exist globally, not tied to tenants
   • UserTenant manages the relationship with roles/permissions per tenant

2. Role ↔ Permission (Many-to-Many via RolePermission)

   • Roles group permissions together
   • Both are tenant-scoped

3. UserTenant ↔ Role/Permission

   • Users can have roles AND direct permissions per tenant
   • Permissions are evaluated from both sources

4. User ↔ AppId (One-to-Many)

   • Users can access multiple applications
   • AppId is validated during login

📖 Documentation Sections

🚀

Getting Started

Step-by-step guide to set up GrydAuth in your application.

🔐

Authentication

JWT tokens, login, registration, and password management.

🔑

Authorization

Roles, permissions, and policy-based access control.

🏢

Multi-Tenancy

Tenant isolation, federation, and cross-tenant access.

🛡️

Security Features

Rate limiting, audit logging, and geo-location.

📚

API Reference

Complete API documentation with endpoints and models.

🔗 Related Links

• Gryd.Core Documentation - Foundation utilities
• Gryd.Domain Documentation - DDD building blocks
• GrydCrud Module - CRUD operations with auth integration