Skip to main content
Version: 2026.04.0

Local Authentication (Email & Password)

Use the broker’s local login endpoint (POST /api/auth/login) with your own credential validator.

Step 1: Install the package​

dotnet add package PrimusSaaS.Identity.Broker

Step 2: Configure Program.cs and middleware​

Register a credential validator and the broker.

using PrimusSaaS.Identity.Broker;

var builder = WebApplication.CreateBuilder(args);

// Register your credential validator — the broker calls this on POST /api/auth/login
builder.Services.AddScoped<IPrimusAuthCredentialValidator, PortalAuthCredentialValidator>();
// Register broker services and read configuration from appsettings.json
builder.Services.AddPrimusAuthBroker(builder.Configuration, builder.Environment.IsDevelopment());
builder.Services.AddControllers();

var app = builder.Build();
app.UseAuthentication();  // REQUIRED — reads the session cookie and populates User on every request
app.UseAuthorization();   // REQUIRED — enforces [Authorize] attributes on controllers and minimal API endpoints
// Sets the XSRF-TOKEN cookie on responses and validates X-Primus-CSRF on all mutating broker requests
app.UsePrimusCsrfProtection();
app.MapControllers();
// Registers all /api/auth/* endpoints: GET /providers, POST /login, POST /logout, GET /me, etc.
app.MapPrimusAuthBroker();
app.Run();

Example credential validator:

using PrimusSaaS.Identity.Broker;

public class PortalAuthCredentialValidator : IPrimusAuthCredentialValidator
{
    public Task<PrimusAuthUser?> ValidateCredentialsAsync(string email, string password, CancellationToken ct = default)
    {
        // Validate user from your database and return a PrimusAuthUser on success.
        return Task.FromResult<PrimusAuthUser?>(new PrimusAuthUser { Id = "1", Email = email, Role = "Admin" });
    }
}
note

This is a placeholder implementation. In production, query your user database, verify the password hash, and return null on failure. The Id, Email, Role, and Roles fields on PrimusAuthUser populate the session cookie claims.

Step 3: Configure appsettings.json​

The broker itself has no required configuration for local login — it reads from your registered IPrimusAuthCredentialValidator. The settings below are your application's own config (not consumed by the broker).

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=PrimusDB;Trusted_Connection=True;"
  }
}
info

The broker does not read ConnectionStrings, DatabaseProvider, or any seed-user settings. Wire those up in your own IPrimusAuthCredentialValidator implementation using your DI container.

Production requirement

In production (isDevelopment: false), you must register your own IPrimusAuthUserStore. Without it, all logins fail. The broker logs a Critical-level error at startup if none is registered.

Step 4: Configure endpoint​

Broker endpoints are mapped by app.MapPrimusAuthBroker().

  • POST /api/auth/login
  • POST /api/auth/logout
  • GET /api/auth/me

Local login is protected by CSRF. Before the first login attempt, have your client call GET /api/auth/providers. The broker sets the XSRF-TOKEN cookie on the response. Pass that value as the X-Primus-CSRF header on every mutating request (POST /login, POST /logout). A missing or mismatched token returns HTTP 400.

Step 5: Test the endpoint​

Before the first POST to /api/auth/login, your client needs to obtain the XSRF-TOKEN cookie. Call GET /api/auth/providers first — it is unauthenticated, returns the list of active providers, and seeds the CSRF cookie in the same round-trip. Pass the cookie value as the X-Primus-CSRF header on every POST to /api/auth/*.

Recommended — use a REST client

Bruno, Postman, Insomnia, and HTTPie manage cookies and CSRF tokens automatically:

  1. Send GET http://localhost:5000/api/auth/providers — seeds the CSRF cookie and returns the active provider list.
  2. Send POST http://localhost:5000/api/auth/login with body {"email": "you@example.com", "password": "yourPassword"} — the client forwards the saved cookie automatically.

No manual token extraction needed.

Using curl (Linux / macOS)
# Step 5a — seed the CSRF cookie (also returns the active provider list)
curl -c cookies.txt http://localhost:5000/api/auth/providers

# The response sets an XSRF-TOKEN cookie. Extract its value:
CSRF_TOKEN=$(grep XSRF-TOKEN cookies.txt | awk '{print $NF}')

# Step 5b — login (replace you@example.com and yourPassword with real credentials)
curl -b cookies.txt -c cookies.txt \
  -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -H "X-Primus-CSRF: $CSRF_TOKEN" \
  -d '{ "email": "you@example.com", "password": "yourPassword" }'

# Step 5c — token exchange (Postman-compatible cURL shape)
# Reuses the authenticated Primus.Session cookie from cookies.txt.
curl -b cookies.txt -c cookies.txt \
  -X POST http://localhost:5000/api/auth/token/exchange \
  -H "accept: */*" \
  -H "X-Primus-CSRF: $CSRF_TOKEN"

Expected failures:

  • 401 Unauthorized when the session cookie is missing or expired
  • 400 Bad Request when X-Primus-CSRF does not match XSRF-TOKEN

Then call GET /api/auth/me to confirm the session.

Next Steps​