Skip to main content

PearDrop Authentication

PearDrop provides a comprehensive, modular authentication system that supports multiple authentication strategies, Multi-Factor Authentication (MFA), and flexible provider integration.

Core Architecture​

Authentication Model​

PearDrop uses cookie-based authentication with security stamps for validation:

  1. Cookies - HTTP-only cookies store session information
  2. Security Stamps - Server-side tokens (GUIDs with timestamps) validate each request
  3. Token Serialization - Secure serialization of authentication tokens
  4. Device Remembrance - Optional device-based trust to reduce MFA friction

Security Flow​

User Login Request
    ↓
Authenticate against User aggregate (password/external provider)
    ↓
Generate Security Stamp (Guid + timestamp)
    ↓
Store in In-Memory Security Stamp Accessor
    ↓
Issue HTTP-only Cookie
    ↓
On Subsequent Requests
    ↓
Validate Security Stamp
    ↓
If Valid → Allow Request
    If Invalid → Redirect to Login

Authentication Providers​

Internal Provider​

Local username/password authentication system with:

  • Configurable password rules
  • Account locking and unlock mechanisms
  • Password reset workflows
  • Account verification and email confirmation

External Providers​

Connect your app to enterprise identity systems:

  • Microsoft Entra ID (formerly Azure AD) - Cloud-based identity platform
  • AAD/Office 365 - Corporate directory integration
  • Extensible provider model for custom integrations

Multi-Factor Authentication (MFA)​

Three MFA methods:

  1. Email MFA - One-time codes sent to email address
  2. SMS MFA - One-time codes sent via SMS
  3. Authenticator Apps - TOTP codes (Google Authenticator, Microsoft Authenticator, etc.)
  4. Authenticator Devices - FIDO2-compatible hardware devices (Windows Hello, YubiKey, etc.)

Each method can be independently configured with:

  • Token generation limits
  • Help message thresholds
  • Enrollment and management

User Model​

The User aggregate supports:

  • Accounts - Enable/disable, lock/unlock, verification
  • Passwords - Change, reset, set during authentication
  • Roles - Permission-based access control
  • MFA Methods - Multiple authenticators per user
  • External Accounts - Link users to external providers
  • User Principal Names - Alternative identifiers with verification
  • Profile - First/last name and custom metadata
  • Authentication History - Track login attempts and patterns

Configuration​

appsettings.json Structure​

{
  "ConnectionStrings": {
    "PearDrop-Auth": "Server=localhost,1433;Database=MyApp;..."
  },
  "PearDrop": {
    "modules": {
      "authentication": {
        "useSessionStore": false,
        "isDistributed": false,
        "useInternal": true,
        "authCookieName": "peardrop.auth",
        "cookieExpiryLengthMinutes": 2880,
        "appAddress": "https://myapp.com",
        "emailMfaTokenGenerations": 3,
        "smsMfaTokenGenerations": 3,
        "userPrincipleNameTokenGenerations": 3,
        "authHelpMessageThreshold": 3,
        "emailMfaHelpMessageThreshold": 3,
        "smsMfaHelpMessageThreshold": 3,
        "emailChangeRevertWindowHours": 48,
        "useRegistration": false,
        "useUPNAsContactEmail": true,
        "providers": {
          "internal": {
            // Internal provider settings
          },
          "external": {
            "entra": {
              // Entra ID configurations
            }
          }
        }
      }
    }
  }
}

Registration Pattern​

Server-Side​

// Program.cs
builder.Services.AddPearDropAuthentication(builder.Configuration);

Client-Side (Blazor)​

// Program.cs
builder.Services.AddPearDropAuthentication();

Command Categories​

User Management​

  • CreateUser - Create new user with credentials
  • DisableAccount / EnableAccount - Account status management
  • LockAccount / UnlockAccount - Account locks (failed login protection)
  • DeleteUserPrincipalName - Remove username/UPN

Authentication​

  • AuthenticateUser - Authenticate with credentials
  • SignInExternalUser - Sign in via external provider
  • ChangePassword - User changes own password
  • ForceOverridePassword - Admin override user password

Account Recovery​

  • InitiatePasswordReset - Start password reset flow
  • PasswordReset - Complete password reset
  • RequestAccountVerification - Request email verification
  • VerifyAccountAndSetPassword - Complete account verification

Multi-Factor Authentication​

  • InitiateAuthenticatorAppEnrollment - Enroll TOTP app
  • EnrollAuthenticatorApp - Complete app enrollment
  • EmailMfaRequested / SmsMfaRequested / AppMfaRequested - Request MFA code
  • ValidateEmailMfaCode / ValidateSmsMfaCode / ValidateAppMfaCode - Verify code
  • RevokeAuthenticatorApp / RevokeAuthenticatorDevice - Remove MFA method

User Principal Names​

  • AddUserPrincipalName - Add username or alternative identifier
  • InitiateUserPrincipleNameChange - Initiate change with verification
  • VerifyUserPrincipalName - Complete change verification
  • RevertUserPrincipleNameChange - Revert within window

Next Steps​