ScreamCode.Auth.Core 1.0.6

ScreamCode.Auth

Authentication and user management for ASP.NET Core applications.

Trial: 30 days Professional, free on first install. License: screamcode.com/pricing Docs: screamcode.com/docs/auth

Features

Packages

dotnet add package ScreamCode.Auth.Core --version 1.0.6
dotnet add package ScreamCode.Auth.Infrastructure --version 1.0.6
dotnet add package ScreamCode.Auth.AspNetCore --version 1.0.6
dotnet add package ScreamCode.Auth.Admin --version 1.0.6

⚠️ Always specify versions explicitly. Without a version, NuGet may resolve incompatible versions.

⚠️ Always update all four ScreamCode.Auth packages to the same version together. Mixing versions causes NU1605 dependency errors.

ℹ️ Database provider packages (SQL Server, PostgreSQL, MySQL, SQLite) are automatically included as dependencies of ScreamCode.Auth.Infrastructure. You do not need to install them separately. Installing them separately may cause version conflicts.

Requirements

• .NET 8
• One of: SQL Server, PostgreSQL, or MySQL

ScreamCode.Auth creates its own tables automatically on first run. You do not need to run any migrations manually.

Database configuration

SQL Server

"ScreamAuth": {
  "DatabaseProvider": "SqlServer",
  "ConnectionString": "Server=localhost;Database=MyAppDB;Trusted_Connection=True;TrustServerCertificate=True;"
}

Tables are created in the screamauth schema within your database.

PostgreSQL

"ScreamAuth": {
  "DatabaseProvider": "PostgreSql",
  "ConnectionString": "Host=localhost;Database=MyAppDB;Username=postgres;Password=yourpassword;"
}

Tables are created in the screamauth schema within your database.

MySQL

"ScreamAuth": {
  "DatabaseProvider": "MySql",
  "ConnectionString": "Server=localhost;Database=MyAppDB;Uid=root;Pwd=yourpassword;"
}

ℹ️ MySQL does not support schemas. ScreamCode.Auth handles this automatically — tables are created directly in the specified database.

Full appsettings.json reference

{
  "ConnectionStrings": {
    "Default": "Server=localhost;Database=MyAppDB;Trusted_Connection=True;TrustServerCertificate=True;"
  },
  "ScreamAuth": {
    "ApplicationName": "My App",
    "LicenseKey": "",
    "DatabaseProvider": "SqlServer",
    "ConnectionString": "Server=localhost;Database=MyAppDB;Trusted_Connection=True;TrustServerCertificate=True;",
    "DatabaseSchema": "screamauth",
    "AutoMigrateDatabase": true,
    "DefaultLocale": "en",
    "Token": {
      "Issuer": "https://yourdomain.com",
      "Audience": "https://yourdomain.com",
      "HmacSecret": "YOUR-SECRET-MIN-32-CHARS-CHANGE-IN-PRODUCTION",
      "AccessTokenMinutes": 60,
      "RefreshTokenDays": 30,
      "Algorithm": "HS256"
    },
    "Security": {
      "MfaPolicy": "None",
      "AllowConcurrentSessions": true,
      "MaxFailedAttempts": 5,
      "LockoutDurationMinutes": 15
    },
    "Password": {
      "MinLength": 8,
      "RequireUppercase": true,
      "RequireLowercase": true,
      "RequireDigit": true,
      "RequireSpecialChar": false
    },
    "AuthMethods": {
      "Password": true,
      "EmailOtp": true,
      "SocialLogin": false,
      "MagicLink": false,
      "Passkey": false
    },
    "Smtp": {
      "Host": "smtp.yourprovider.com",
      "Port": 587,
      "UseSsl": true,
      "Username": "",
      "Password": "",
      "FromAddress": "noreply@yourdomain.com",
      "FromName": "My App"
    }
  }
}

Setup by architecture

Blazor Server

New project

dotnet new blazor -f net8.0 --interactivity Server

Program.cs:

using YourApp.Components;
using ScreamCode.Auth.Core.Extensions;
using ScreamCode.Auth.AspNetCore.Extensions;
using ScreamCode.Auth.Admin;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorComponents().AddInteractiveServerComponents();
builder.Services.AddHttpContextAccessor();
builder.Services.AddCascadingAuthenticationState();
builder.Services.AddRazorPages();
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

builder.Services
    .AddScreamAuth(builder.Configuration)
    .AddAspNetCore()
    .AddAdmin();

var app = builder.Build();

app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseAntiforgery();
app.UseScreamAuth();
app.MapScreamAuthEndpoints();
app.MapRazorPages();
app.MapScreamAuthAdmin();                  // ← BEFORE MapRazorComponents

app.MapRazorComponents<App>()
   .AddInteractiveServerRenderMode();
   // Do NOT add ScreamCode.Auth.Admin.App to AddAdditionalAssemblies

app.Run();

⚠️ MapScreamAuthAdmin() must be called before MapRazorComponents. Calling it after causes the Auth Admin portal to render through the host app pipeline, losing its CSS and layout.

⚠️ Do not add typeof(ScreamCode.Auth.Admin.App).Assembly to AddAdditionalAssemblies.

Existing Blazor Server app

Add to services (before builder.Build()):

builder.Services.AddHttpContextAccessor();
builder.Services.AddCascadingAuthenticationState();
builder.Services.AddRazorPages();              // ← required
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

builder.Services
    .AddScreamAuth(builder.Configuration)
    .AddAspNetCore()
    .AddAdmin();

Add to middleware (after builder.Build()):

app.UseAuthentication();
app.UseAuthorization();
app.UseScreamAuth();
app.MapScreamAuthEndpoints();
app.MapRazorPages();
app.MapScreamAuthAdmin();      // ← BEFORE your existing MapRazorComponents call

Using with ScreamCode.Reporting (Blazor Server)

When using both modules together, add Reporting services and adjust the middleware order:

// Services
builder.Services
    .AddScreamAuth(builder.Configuration)
    .AddAspNetCore()
    .AddAdmin();

builder.Services
    .AddScreamReporting(builder.Configuration)
    .AddPdf().AddExcel().AddBuilder().AddTemplates()
    .AddAdmin().AddAdminScheduler()
    .AddAuditTrail(options => options.UseSqlite("Data Source=reporting-audit.db"));

// Middleware
app.MapScreamAuthEndpoints();
app.MapRazorPages();
app.MapScreamAuthAdmin();                  // ← BEFORE MapRazorComponents

app.MapRazorComponents<App>()
   .AddInteractiveServerRenderMode();

app.UseScreamReportingAdmin();             // ← AFTER MapRazorComponents

MVC

New project

dotnet new mvc -f net8.0

Program.cs:

using ScreamCode.Auth.Core.Extensions;
using ScreamCode.Auth.AspNetCore.Extensions;
using ScreamCode.Auth.Admin;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();
builder.Services.AddHttpContextAccessor();
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
builder.Services.AddSignalR();             // ← required

builder.Services
    .AddScreamAuth(builder.Configuration)
    .AddAspNetCore()
    .AddAdmin();

var app = builder.Build();

app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseSession();
app.UseAntiforgery();
app.UseScreamAuth();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.MapRazorPages();
app.MapScreamAuthEndpoints();
app.MapBlazorHub();                        // ← BEFORE MapScreamAuthAdmin
app.MapScreamAuthAdmin();

app.Run();

Existing MVC app

Add to services:

builder.Services.AddRazorPages();          // ← required
builder.Services.AddSignalR();             // ← required
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

builder.Services
    .AddScreamAuth(builder.Configuration)
    .AddAspNetCore()
    .AddAdmin();

Add to middleware after MapControllerRoute:

app.UseAuthentication();
app.UseAuthorization();
app.UseScreamAuth();
app.MapScreamAuthEndpoints();
app.MapRazorPages();
app.MapBlazorHub();            // ← BEFORE MapScreamAuthAdmin
app.MapScreamAuthAdmin();

Using with ScreamCode.Reporting (MVC)

app.MapRazorPages();
app.MapScreamAuthEndpoints();
app.UseScreamReportingAdmin();  // ← BEFORE MapBlazorHub and MapScreamAuthAdmin
app.MapBlazorHub();
app.MapScreamAuthAdmin();

Razor Pages

New project

dotnet new razor -f net8.0

Program.cs:

using ScreamCode.Auth.Core.Extensions;
using ScreamCode.Auth.AspNetCore.Extensions;
using ScreamCode.Auth.Admin;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddHttpContextAccessor();
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
builder.Services.AddSignalR();             // ← required

builder.Services
    .AddScreamAuth(builder.Configuration)
    .AddAspNetCore()
    .AddAdmin();

var app = builder.Build();

app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseSession();
app.UseAntiforgery();
app.UseScreamAuth();

app.MapRazorPages();
app.MapScreamAuthEndpoints();
app.MapBlazorHub();                        // ← BEFORE MapScreamAuthAdmin
app.MapScreamAuthAdmin();

app.Run();

Existing Razor Pages app

Add to services:

builder.Services.AddSignalR();             // ← required
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

builder.Services
    .AddScreamAuth(builder.Configuration)
    .AddAspNetCore()
    .AddAdmin();

Add to middleware after MapRazorPages:

app.UseAuthentication();
app.UseAuthorization();
app.UseScreamAuth();
app.MapScreamAuthEndpoints();
app.MapBlazorHub();            // ← BEFORE MapScreamAuthAdmin
app.MapScreamAuthAdmin();

Using with ScreamCode.Reporting (Razor Pages)

app.MapRazorPages();
app.MapScreamAuthEndpoints();
app.UseScreamReportingAdmin();  // ← BEFORE MapBlazorHub and MapScreamAuthAdmin
app.MapBlazorHub();
app.MapScreamAuthAdmin();

Minimal API

New project

dotnet new web -f net8.0

Program.cs:

using ScreamCode.Auth.Core.Extensions;
using ScreamCode.Auth.AspNetCore.Extensions;
using ScreamCode.Auth.Admin;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddHttpContextAccessor();
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
builder.Services.AddSignalR();             // ← required

builder.Services
    .AddScreamAuth(builder.Configuration)
    .AddAspNetCore()
    .AddAdmin();

var app = builder.Build();

app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseSession();
app.UseAntiforgery();
app.UseScreamAuth();

// Your Minimal API endpoints
app.MapGet("/api/hello", () => "Hello!");
app.MapGet("/api/secure", () => "Secure!").RequireAuthorization();

app.MapRazorPages();
app.MapScreamAuthEndpoints();
app.MapBlazorHub();                        // ← BEFORE MapScreamAuthAdmin
app.MapScreamAuthAdmin();

app.Run();

Existing Minimal API app

Add to services:

builder.Services.AddRazorPages();          // ← required
builder.Services.AddSignalR();             // ← required
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

builder.Services
    .AddScreamAuth(builder.Configuration)
    .AddAspNetCore()
    .AddAdmin();

Add to middleware after your existing endpoint mappings:

app.UseAuthentication();
app.UseAuthorization();
app.UseScreamAuth();
app.MapScreamAuthEndpoints();
app.MapRazorPages();
app.MapBlazorHub();            // ← BEFORE MapScreamAuthAdmin
app.MapScreamAuthAdmin();

Using with ScreamCode.Reporting (Minimal API)

app.MapRazorPages();
app.MapScreamAuthEndpoints();
app.UseScreamReportingAdmin();  // ← BEFORE MapBlazorHub and MapScreamAuthAdmin
app.MapBlazorHub();
app.MapScreamAuthAdmin();

Web API

New project

dotnet new webapi -f net8.0

Program.cs:

using ScreamCode.Auth.Core.Extensions;
using ScreamCode.Auth.AspNetCore.Extensions;
using ScreamCode.Auth.Admin;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddRazorPages();
builder.Services.AddHttpContextAccessor();
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
builder.Services.AddSignalR();             // ← required

builder.Services
    .AddScreamAuth(builder.Configuration)
    .AddAspNetCore()
    .AddAdmin();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseSession();
app.UseAntiforgery();
app.UseScreamAuth();

app.MapRazorPages();
app.MapScreamAuthEndpoints();
app.MapControllers();
app.MapBlazorHub();                        // ← BEFORE MapScreamAuthAdmin
app.MapScreamAuthAdmin();

app.Run();

Existing Web API app

Add to services:

builder.Services.AddRazorPages();          // ← required
builder.Services.AddSignalR();             // ← required
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

builder.Services
    .AddScreamAuth(builder.Configuration)
    .AddAspNetCore()
    .AddAdmin();

Add to middleware:

app.UseAuthentication();
app.UseAuthorization();
app.UseScreamAuth();
app.MapRazorPages();
app.MapScreamAuthEndpoints();
app.MapControllers();
app.MapBlazorHub();            // ← BEFORE MapScreamAuthAdmin
app.MapScreamAuthAdmin();

Using with ScreamCode.Reporting (Web API)

app.MapRazorPages();
app.MapScreamAuthEndpoints();
app.UseScreamReportingAdmin();  // ← BEFORE MapControllers, MapBlazorHub, MapScreamAuthAdmin
app.MapControllers();
app.MapBlazorHub();
app.MapScreamAuthAdmin();

Admin portal

Available at /authadmin. On first visit, redirects to setup page to create the first admin user.

Sections: Users, Roles, Sessions, Audit Log, Settings, Social Login, LDAP/AD, IP Filter [Enterprise], API Keys [Enterprise], Webhooks [Enterprise], GDPR [Enterprise], License.

Auth endpoints

POST /auth/register
POST /auth/login
POST /auth/logout
POST /auth/logout-all
POST /auth/refresh
POST /auth/forgot-password
POST /auth/reset-password
POST /auth/login/magic-link/send       [Professional]
GET  /auth/login/magic-link/verify     [Professional]
GET  /auth/login/social/{provider}     [Professional]
POST /auth/passkey/register/begin      [Professional]
POST /auth/passkey/login/begin         [Professional]
POST /auth/mfa/verify                  [Professional]
POST /auth/otp/send
POST /auth/otp/verify
POST /auth/otp/totp/setup              [Professional]
GET  /auth/gdpr/{userId}/export        [Enterprise]
DELETE /auth/gdpr/{userId}             [Enterprise]
GET  /auth/available-methods
GET  /auth/users                       [Admin]

Reading the current user in Blazor

@inject IHttpContextAccessor HttpContext

@code {
    private string? _userId;
    private string? _email;
    private IEnumerable<string> _roles = [];

    protected override void OnInitialized()
    {
        var user = HttpContext.HttpContext?.User;
        _userId = user?.FindFirst("sub")?.Value;
        _email  = user?.FindFirst("email")?.Value;
        _roles  = user?.FindAll("roles").Select(c => c.Value) ?? [];
    }
}

Common mistakes

Missing AddRazorPages() Required in all architectures. The Auth Admin portal depends on Razor Pages even if your app does not use them directly.

Missing AddSignalR() and MapBlazorHub() Required in MVC, Razor Pages, Minimal API, and Web API. Not needed in Blazor Server. MapBlazorHub() must be called before MapScreamAuthAdmin().

MapScreamAuthAdmin() after MapRazorComponents (Blazor Server) Always call MapScreamAuthAdmin() before MapRazorComponents. Calling it after causes the portal to render through the host app, losing its CSS.

Adding Auth.Admin.App to AddAdditionalAssemblies (Blazor Server) Do not add typeof(ScreamCode.Auth.Admin.App).Assembly to AddAdditionalAssemblies.

Installing database provider packages manually All database providers are already included in ScreamCode.Auth.Infrastructure. Do not install Microsoft.EntityFrameworkCore.SqlServer, Npgsql.EntityFrameworkCore.PostgreSQL, or Pomelo.EntityFrameworkCore.MySql separately — this causes version conflicts.

Wrong middleware order when using with ScreamCode.Reporting See the "Using with ScreamCode.Reporting" section for your architecture above. The order differs between Blazor Server and other architectures.

Support

• Docs: screamcode.com/docs/auth
• Issues: screamcode.com/support