PrimusSaaS.Identity.Broker 2.6.0

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. 
dotnet add package PrimusSaaS.Identity.Broker --version 2.6.0
                    


                    

                
NuGet\Install-Package PrimusSaaS.Identity.Broker -Version 2.6.0
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="PrimusSaaS.Identity.Broker" Version="2.6.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="PrimusSaaS.Identity.Broker" Version="2.6.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="PrimusSaaS.Identity.Broker" />
                    


                            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 PrimusSaaS.Identity.Broker --version 2.6.0
                    


                    

                
#r "nuget: PrimusSaaS.Identity.Broker, 2.6.0"
#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 PrimusSaaS.Identity.Broker@2.6.0
#: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=PrimusSaaS.Identity.Broker&version=2.6.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=PrimusSaaS.Identity.Broker&version=2.6.0
                    


                            Install as a Cake Tool

Primus SaaS Identity Broker (BFF)

Server-side authentication middleware for ASP.NET Core browser apps.

This package implements a Backend-for-Frontend pattern for applications that want secure cookie sessions instead of storing access tokens in the browser. It handles local login, OIDC and SAML sign-in, MFA, and session lifecycle on the server side.

Package boundary

  • Browser login and secure cookie session management
  • Local login plus external providers such as Azure AD, Auth0, Google, Okta, and SAML
  • CSRF protection with the double-submit-cookie pattern
  • JIT provisioning hooks through WithUserCheck(...) and WithAutoProvision(...)
  • Optional session refresh and impersonation endpoints

This package is not:

  • an API token validator for downstream services
  • a hosted identity provider
  • a frontend UI kit

If your APIs already receive JWTs and only need validation, use PrimusSaaS.Identity.Validator instead.

Start here

Quick Start

1. Install Package

dotnet add package PrimusSaaS.Identity.Broker

2. Configure Access

Tell the broker how to look up or provision your users.

// In Program.cs
builder.Services.AddPrimusAuthBroker(builder.Configuration, builder.Environment.IsDevelopment())
    .WithUserCheck(async (email, sp) => 
    {
         var db = sp.GetRequiredService<MyDbContext>();
         var user = await db.Users.FirstOrDefaultAsync(u => u.Email == email);
         return user == null ? null : new PrimusAuthUser { Id = user.Id, Email = user.Email, Role = user.Role };
    })
    .WithAutoProvision(async (email, provider, principal, sp) =>
    {
        // JIT provisioning (optional)
        var db = sp.GetRequiredService<MyDbContext>();
        var user = new User { Email = email, CreatedAt = DateTime.UtcNow };
        db.Users.Add(user);
        await db.SaveChangesAsync();
        return new PrimusAuthUser { Id = user.Id, Email = user.Email };
    });

3. Implement Credential Validator (Required for Local Login)

Local login is handled by the broker at POST /api/auth/login. To enable it, implement IPrimusAuthCredentialValidator and verify credentials against your data store.

public class MyCredentialValidator : IPrimusAuthCredentialValidator
{
    private readonly MyDbContext _db;
    private readonly IPasswordHasher _hasher;

    public MyCredentialValidator(MyDbContext db, IPasswordHasher hasher)
    {
        _db = db;
        _hasher = hasher;
    }

    public async Task<PrimusAuthUser?> ValidateCredentialsAsync(string email, string password, CancellationToken ct = default)
    {
        var user = await _db.Users.FirstOrDefaultAsync(u => u.Email == email, ct);
        if (user == null || !_hasher.VerifyPassword(password, user.PasswordHash))
        {
            return null;
        }

        return new PrimusAuthUser { Id = user.Id, Email = user.Email, Role = user.Role };
    }
}

4. Register Services (Program.cs)

builder.Services.AddScoped<IPrimusAuthCredentialValidator, MyCredentialValidator>(); // If using local login

builder.Services.AddPrimusAuthBroker(builder.Configuration, builder.Environment.IsDevelopment());

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.UsePrimusCsrfProtection();

app.MapPrimusAuthBroker();

If token encryption remains enabled, configure PrimusAuth:Security:TokenEncryptionKey before startup. For a local-only sample host, you can instead use:

builder.Services.AddPrimusAuthBroker(
    builder.Configuration,
    builder.Environment.IsDevelopment(),
    options => options.Security.EncryptTokens = false);

Azure AD uses /api/auth/azure/callback by default (or {AuthBroker:BasePath}/azure/callback). Override with AzureAd:CallbackPath if your app registration already uses /signin-oidc.

Note: POST /api/auth/login requires a CSRF token. Call a safe endpoint like GET /api/auth/providers on app startup to receive the XSRF-TOKEN cookie, then mirror it in the X-Primus-CSRF header for state-changing requests.

Production checklist

  1. HTTPS: Mandatory. Cookies are Secure and __Host- prefixed.
  2. Data Protection: For multi-server deployments, configure shared keys so all instances can decrypt the session cookie: 
    builder.Services.AddPrimusBrokerDataProtection("MyUniqueAppName", new DirectoryInfo(@"C:\Keys"));
  3. Secrets: Set PrimusAuth:Security:TokenEncryptionKey via Environment Variables.

Security note

You may see an SCS0009 warning about the XSRF-TOKEN cookie missing the HttpOnly flag. That is intentional. The browser-side code must be able to read that value and mirror it into the X-Primus-CSRF header for the double-submit-cookie pattern to work.

Configuration reference

Redirects

You can control where users are sent after login or error.

"Auth": {
  "PostLoginRedirect": "/",
  "ErrorRedirect": "/login" 
}
  • PostLoginRedirect: Where to go after success.
  • ErrorRedirect: Where to go after failure (e.g. User is not provisioned). If not set, a simple HTML error page is shown. The error message is passed as a query string: ?error=....

7. Impersonation

The broker includes an impersonation flow for support and administrative scenarios.

How to use:

  1. Ensure your Admin user has the claim role: Admin.
  2. POST /api/auth/impersonate with {"targetEmail": "customer@example.com"}.
  3. You are now logged in as the customer. Your token includes act: admin@me.com for audit trails.
  4. To exit, POST /api/auth/revert (Logs you out).

Troubleshooting

Startup Diagnostics

In Development environment only, you can view the current configuration status at: GET /api/auth/__auth/diagnostics

This endpoint will show:

  • Which User Store is active.
  • Which Providers are enabled.
  • Warnings if critical configuration is missing.

Common Errors

  • NullPrimusAuthUserStore is active: You forgot to register IPrimusAuthUserStore. See Step 2 above.
  • 401/403 loop: Check CookieSameSiteMode. If using HTTP (not HTTPS), ensure your browser allows cookies.
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 is compatible.  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 is compatible.  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 (6)

Showing the top 5 NuGet packages that depend on PrimusSaaS.Identity.Broker:

Package Downloads
PrimusSaaS.Identity.Broker.Tokens

Optional token issuance add-on for PrimusSaaS.Identity.Broker. Adds broker-issued access tokens, refresh tokens, and token exchange endpoints without changing the broker's default cookie-based behavior.
PrimusSaaS.Memberships.InMemory

In-memory stores and bridge adapters for PrimusSaaS.Memberships development and test scenarios.
PrimusSaaS.Identity.Broker.EntityFrameworkCore

Entity Framework Core user store for PrimusSaaS.Identity.Broker. Provides a generic base class for persisting broker user state using any EF Core-compatible database.
PrimusSaaS.Memberships.Broker

Optional bridge that revokes Broker sessions and refresh tokens from Memberships lifecycle events.
PrimusSaaS.Memberships.EFCore

Entity Framework Core integration for PrimusSaaS.Memberships.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.6.0 128 4/3/2026
2.5.4 259 3/31/2026
2.0.3 92 3/12/2026
2.0.2 86 3/12/2026
2.0.1 87 3/12/2026
2.0.0 87 3/12/2026
1.0.0 136 1/30/2026

v2.5.1: Dedicated M2M app credentials — PrimusM2MOptions gains ClientId/ClientSecret; token service prefers them over broker credentials with fallback. | v2.5.0: M2M support — IPrimusM2MTokenService (outbound client credentials) + AddPrimusM2MValidation (inbound JwtBearer). | v2.4.0: Domain Allowlist, Webhooks, Bot Protection. | v2.3.0: TOTP MFA + token refresh. | v2.2.0: SAML 2.0.