PrimusSaaS.Identity.Broker 2.6.0

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

• Getting started (15 min):
• Full config & endpoint reference:
• Architecture deep dive:
• Edge cases & troubleshooting:
• Docs site:

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.

Related guides

• — 15-minute first login with Angular + React + curl
• — Every config key and endpoint
• — BFF architecture deep dive
• — Security edge cases and troubleshooting
• — All 8 Identity packages at a glance