Zhmdff.Auth 3.7.1

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. 
dotnet add package Zhmdff.Auth --version 3.7.1
                    


                    

                
NuGet\Install-Package Zhmdff.Auth -Version 3.7.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Zhmdff.Auth" Version="3.7.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Zhmdff.Auth" Version="3.7.1" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Zhmdff.Auth" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Zhmdff.Auth --version 3.7.1
                    


                    

                
#r "nuget: Zhmdff.Auth, 3.7.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Zhmdff.Auth@3.7.1
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Zhmdff.Auth&version=3.7.1
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Zhmdff.Auth&version=3.7.1
                    


                            Install as a Cake Tool

📦 Zhmdff.Auth — Master Documentation

Version: 3.5.0 | Target Runtime: .NET 8 | License: MIT

Comprehensive authentication and identity management package for ASP.NET Core. Designed for high-performance, modularity, and seamless integration with modern frontend frameworks.

🏗 Architecture & Data Flow

Component Map

Namespace Responsibility
Zhmdff.Auth Minimal API Endpoints, Middleware, Service Registration.
Zhmdff.Auth.Core Entities, DTOs, Interfaces, Domain Logic, Options.
Zhmdff.Auth.Infrastructure EF Core Context, Repositories, Service Implementations, Social Providers.

Dependency Graph

graph TD
    Client[Web/Mobile Client] -->|HTTP Request| Middleware[Auth Middleware]
    Middleware -->|Route Matching| Endpoints[Minimal API Endpoints]
    Endpoints -->|Invoke| Facade[IAuthService / IAdminService]
    Facade -->|Logic| Services[Account/Token/Mfa/Reset Services]
    Services -->|Data Access| Repos[Repositories]
    Repos -->|EF Core| DB[(SQL Server / PostgreSQL)]

DI Lifetimes & Scope Rules

Service Lifetime Purpose
IAuthService<TUser> Scoped Primary facade for all auth operations.
IAdminService Scoped Administrative user/role/permission management.
IUnitOfWork<TUser> Scoped Transactional boundary for database operations.
ITokenGenerator Scoped JWT and Refresh Token generation logic.
IPasswordHasher Scoped BCrypt-based secure password hashing.
AuthPackageOptions Singleton Centralized configuration state.
TokenCleanupService Hosted Background worker for expired token pruning.

🌐 Global Rules & Conventions

Category Rule Implementation
Error Format Consistent JSON response { "Success": false, "ErrorMessage": "...", "Errors": { "Field": ["Error"] } }
Auth Flow JWT + Refresh Tokens Short-lived JWT (Header), Long-lived Refresh Token (Cookie/Body).
CORS & Cookies Secure Defaults HttpOnly, Secure, SameSite=Lax (Env dependent).
Naming PascalCase Enforced JSON serialization for compatibility across ecosystems.
Audit Automatic Logging All sensitive actions (login, password change, admin ops) are audited.

⚙️ Configuration Reference

Configuration Tree & Environment Mapping

The package supports hierarchical appsettings.json, flat keys, and Environment Variables.

AppSettings Key Environment Variable Default Description
Auth:Preset AUTH_PRESET Public Public, Restricted, or Solo.
Auth:Jwt:SecretKey AUTH_JWT_SECRET Required Symmetric key for signing JWTs.
Auth:Jwt:ExpiryMinutes AUTH_JWT_EXP_MINUTES 60 JWT validity duration.
Auth:RefreshToken:ExpiryDays AUTH_REFRESH_TOKEN_EXP_DAYS 7 Refresh token validity.
Auth:Database:Provider AUTH_DB_PROVIDER mssql mssql, postgres, or sqlite.
Auth:Database:ConnectionString AUTH_DB_CONNECTION_STRING Required Connection string for EF Core.
Auth:ProjectId AUTH_PROJECT_ID Required Unique ID embedded in JWT claims.
Auth:EnvSecret AUTH_ENV_SECRET Required Internal secret for environment validation.
Auth:EmergencyAccess:Enabled AUTH_EMERGENCY_ACCESS_ENABLED false Enable/Disable break-glass login.
Auth:OAuth:Enabled AUTH_OAUTH_ENABLED false Master toggle for Social Logins.

📡 Complete API Endpoint Registry

Authentication Endpoints (/auth)

Method Route Auth Request Response (200)
POST /auth/register Optional RegisterRequest AuthResult
POST /auth/login None LoginRequest AuthResult
POST /auth/refresh Cookie None AuthResult
POST /auth/logout Cookie None void
POST /auth/mfa/setup JWT None TwoFactorSetupResult
POST /auth/mfa/verify None MfaVerifyRequest AuthResult
POST /auth/forgot-password None ForgotPasswordRequest AuthResult
POST /auth/reset-password None ResetPasswordRequest AuthResult

Administration Endpoints (/admin)

All endpoints require Admin or SuperAdmin role.

Method Route Request Summary
GET /admin/users Query: page, pageSize, search List users with pagination.
PATCH /admin/users/{id}/status SetUserStatusRequest Activate/Deactivate user.
DELETE /admin/users/{id} None Soft delete a user.
PATCH /admin/users/{id}/roles UserRolesRequest Assign/Remove roles.
GET /admin/roles None List all available roles.
GET /admin/audit AuditLogQuery Advanced audit trail filtering.

🧩 Extension Points & Customization

1. Custom User Entity

Inherit from BaseAuthUser to add custom properties:

public class MyUser : BaseAuthUser
{
    public string CompanyName { get; set; }
}

2. Service Overrides

Replace default implementations by registering them after AddAuthPackage:

services.AddScoped<IPasswordHasher, Argon2PasswordHasher>();

3. Permission Resolver

Customize how permissions are mapped to roles by implementing IPermissionResolver.

Setup Guide

1. Middleware Order

ASP.NET Core middleware is execution-order dependent. Incorrect placement will cause CORS or Authentication failures.

  • Rule: UseCors() must come before UseAuthentication() and UseAuthorization().
var app = builder.Build();

app.UseCors(); // Must be before Auth
app.UseAuthentication();
app.UseAuthorization();
2. EF Core Migrations (.NET 8)

Ensure you use the matching major version for the design package to avoid compatibility errors.

dotnet add package Microsoft.EntityFrameworkCore.Design --version 8.0.0

🚀 Setup Guide

ASP.NET Core Integration

var builder = WebApplication.CreateBuilder(args);

// 1. Register Auth Services
builder.Services.AddAuthPackage<MyUser>(builder.Configuration);

var app = builder.Build();

// 2. Map Endpoints
app.MapAuthEndpoints<MyUser>();
app.MapAdminEndpoints<MyUser>();

app.Run();

⚠️ Audit Notes

  • Security: Always set Auth:Cookie:Secure to true in production.
  • Performance: Enable Auth:Role:EnablePermissionCaching for systems with high permission granularity.
  • Database: Ensure MigrationsAssembly is set if running migrations from a separate CLI project.
Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.7.1 278 8/17/2026
3.7.0 105 8/17/2026
3.6.7 112 8/14/2026
3.6.6 303 7/22/2026
3.6.5 130 7/22/2026
3.6.4 126 7/21/2026
3.6.3 257 7/6/2026
3.6.2 199 6/22/2026
3.6.1 122 6/20/2026
3.6.0 116 6/20/2026
3.5.3 117 6/10/2026
3.5.2 127 6/3/2026
3.5.1 124 6/2/2026
3.4.1 115 5/16/2026
3.4.0 112 5/15/2026
3.3.2 113 5/10/2026
3.3.0 125 4/7/2026
3.2.4 109 4/6/2026
3.2.3 113 4/6/2026
3.2.2 114 4/6/2026
Loading failed