---
name: nexus-identity-saas
description: Standards for Identity, Authentication, and SaaS feature implementations
---
# Identity & SaaS Integration

- **Core Identity Model:**
  - Extend `IdentityUser` to create a custom `NexusUser` model containing SaaS-specific properties (e.g., `AITokenLimit`, `AITokensUsed`, `TenantId`, `CurrentPlan`).
  - Place core domain models in the core project layer (e.g., `NexusArchitect.Core` or `NexusReader.Domain`).
  - Configure `ApplicationDbContext` to inherit from `IdentityDbContext<NexusUser>` and map custom fields and relationships correctly.

- **Authentication Endpoints & Providers:**
  - Use native ASP.NET Core Identity API endpoints (`/register`, `/login`, `/refresh`) or scaffolded Razor components in Blazor (`Components/Account/Pages`).
  - Integrate OAuth2 providers (like Google, Facebook, Microsoft) natively via ASP.NET Core's external login providers.
  - Utilize `SignInManager<TUser>` and `UserManager<TUser>` for custom login logic and user management.

- **Service Configuration & Policies:**
  - Register Identity using `builder.Services.AddDefaultIdentity<NexusUser>()` or `AddIdentity<NexusUser, IdentityRole>()` followed by `.AddEntityFrameworkStores<ApplicationDbContext>()`.
  - Configure `IdentityOptions` in `Program.cs` to enforce strict security standards:
    - **Password:** `RequireDigit`, `RequireLowercase`, `RequireUppercase`, `RequireNonAlphanumeric`, `RequiredLength` (min 8).
    - **Lockout:** Set `MaxFailedAccessAttempts` and `DefaultLockoutTimeSpan` to prevent brute-force attacks.
    - **User:** Enforce `RequireUniqueEmail = true`.

- **Authorization & Policies:**
  - Implement Roles and Claims-based authorization.
  - Create robust Policies (e.g., `ProUser`) and use custom `Requirement` handlers for specific business logic like checking if `AITokensUsed < AITokenLimit`.

- **Mobile / Blazor Hybrid Auth State:**
  - Ensure authentication state persists securely within the MAUI container.
  - Store JWT tokens and sensitive session data in `SecureStorage`.
  - Provide a seamless mechanism to restore the `AuthenticationStateProvider` on app launch if the token is valid.

- **SaaS Features & Webhooks:**
  - Integrate third-party payment/subscription providers (e.g., Stripe) using secure webhooks.
  - Sync external subscription status with internal user claims and limits (e.g., upgrade `AITokenLimit` upon a webhook success event for a "Pro" plan).

- **Verification:**
  - Write unit tests for custom authorization handlers and token limit logic.
  - Ensure the UI handles unauthorized and out-of-tokens states gracefully and points users to subscription management.