Authentication

SCRIPE provides a secure authentication system with JWT access tokens, refresh token rotation, optional two-factor authentication, multi-workspace login discovery, password expiry enforcement, and comprehensive rate limiting. The system supports separate Admin and User authentication flows with different JWT claims and permissions.

Authentication Flow

Two-Factor Authentication (Deep)

Multi-Workspace Login Discovery

When an admin logs in from the platform domain (no pre-resolved tenant), the backend executes a 3-case routing algorithm. Case A uses a provided tenantId for strict domain isolation. Case A' triggers when the isPlatformAdmin flag is set — this directly looks up the platform admin (TenantId = null) and bypasses workspace discovery entirely, preventing an infinite loop. Case B performs workspace discovery: it first checks for a platform admin, then searches all tenants by email — returning a workspace picker if multiple matches are found.

OIDC/SSO Callback & Workspace Selection

For Single Sign-On (OIDC/SAML) callbacks, the system resolves the email and checks if multiple workspaces are linked. If there are multiple candidate workspaces, a temporary workspace selection token is generated and stored in a cache under `sso-login-selection:{token}`. The user is redirected to choose a workspace, which then dispatches `CompleteOidcWorkspaceSelectionCommand` to decrypt the selected tenant ID and issue final JWTs.

// Temporary selection cache setup in OIDC Callback:
var token = Guid.NewGuid().ToString("N");
await _cache.SetAsync($"sso-login-selection:{token}", new SsoTempLoginData
{
    Email = email,
    Provider = provider
}, TimeSpan.FromMinutes(10));

// Complete Workspace Selection command handler:
var loginData = await _cache.GetAsync<SsoTempLoginData>($"sso-login-selection:{request.Token}");
var targetTenantId = _idEncryption.Decrypt(request.TenantId);
var admin = allMatchingAdmins.FirstOrDefault(a => a.IsActive && a.TenantId == targetTenantId);

Password Expiry Enforcement

During login, after BCrypt verification and lockout checks, the handler invokes ITenantPasswordValidator to check if the admin's password has exceeded the tenant's PasswordExpiryDays setting. If expired, the response includes MustChangePassword = true, forcing the frontend to redirect the admin to the change-password page. The admin receives a valid JWT but cannot access the dashboard until the password is updated.

MustChangePassword Middleware & Whitelist

When a password expires, the user's JWT receives the `mcp: true` claim. The `MustChangePasswordMiddleware` blocks all incoming requests with 403 Forbidden unless the request matches the whitelist: password change endpoint `/api/v1/admins/{adminId}/change-password`, profile details `/api/v1/auth/admin/me`, token refresh `/api/v1/auth/admin/refresh`, session logouts `/api/v1/auth/admin/logout` or `/api/v1/auth/admin/revoke`, and the system `/health` endpoint.

public async Task InvokeAsync(HttpContext context)
{
    if (context.User.Identity?.IsAuthenticated == true)
    {
        var mcpClaim = context.User.FindFirst("mcp")?.Value;
        if (mcpClaim == "true")
        {
            var path = context.Request.Path.Value ?? "";
            var isAllowed = AllowedPatterns.Any(pattern => pattern.IsMatch(path));

            if (!isAllowed)
            {
                context.Response.StatusCode = (int)HttpStatusCode.Forbidden;
                context.Response.ContentType = "application/json";
                await context.Response.WriteAsync("{\"error\":\"Password change required.\",\"code\":\"MustChangePassword\"}");
                return;
            }
        }
    }
    await _next(context);
}

SSO Tenant Suspension Gate

The ExternalLoginCommandHandler includes a tenant suspension security gate. After SSO token validation and account linking, the handler checks the admin's tenant status. If the tenant is Suspended or Cancelled, login is rejected with a localized error — preventing deactivated users from bypassing standard login checks via SSO providers like Google or Azure AD.

JWT Token Configuration

The system uses short-lived access tokens (15 minutes) with long-lived refresh tokens (7 days). Refresh tokens are rotated on each use to prevent reuse attacks.

Token Validation & Claim Checks

Both authentication pipelines share the same JWT token validation process. The middleware verifies name identifier claims, checks the 'admin' flag, and queries the database bypassing global query filters using `IgnoreQueryFilters()` to verify the admin or user account is still active and has not been soft-deleted.

OnTokenValidated = async context =>
{
    var idClaim = context.Principal?.FindFirst(ClaimTypes.NameIdentifier)?.Value;
    var isAdmin = context.Principal?.FindFirst("admin")?.Value == "true";

    if (string.IsNullOrEmpty(idClaim) || !Guid.TryParse(idClaim, out var id))
    {
        context.Fail("Invalid token: missing or invalid ID claim");
        return;
    }

    using var scope = context.HttpContext.RequestServices.CreateScope();
    var dbContext = scope.ServiceProvider.GetRequiredService<IdentityDbContext>();

    if (isAdmin)
    {
        var admin = await dbContext.Admins
            .IgnoreQueryFilters()
            .FirstOrDefaultAsync(a => a.Id == id && !a.IsDeleted, context.HttpContext.RequestAborted);

        if (admin == null || !admin.IsActive)
        {
            context.Fail("Admin no longer exists or is inactive");
        }
    }
    else
    {
        var user = await dbContext.Users
            .IgnoreQueryFilters()
            .FirstOrDefaultAsync(u => u.Id == id && !u.IsDeleted, context.HttpContext.RequestAborted);

        if (user == null || !user.IsActive)
        {
            context.Fail("User no longer exists or is inactive");
        }
    }
}

Dual Authentication (Admin & User)

SCRIPE has two separate authentication pipelines. Admin auth (AdminAuthController) issues JWTs with admin-specific claims (TenantId, IsSuperAdmin, Roles). User auth (UserAuthController) issues JWTs with user-specific claims (NationalId, Gender, Country). Each has its own login, register, and token refresh endpoints.

Admin Entity (Security Features)

The Admin entity has several security-critical fields that control account behavior and protection.

Anti-Replay Windowing & TOTP Security

To prevent token reuse attacks, the `Verify2FACommandHandler` implements a strict 60-second anti-replay window. It computes a SHA256 hash of the verification code and matches it against `LastTwoFactorCodeUsed` and checks `LastTwoFactorCodeUsedAt` timestamp. If the same code is used again within 60 seconds, it is rejected.

public bool CheckAndTrackTotpReplay(string code, Func<string, string> hashCode)
{
    var hashedCode = hashCode(code);
    if (LastTwoFactorCodeUsedAt.HasValue)
    {
        var timeSinceLastUse = DateTime.UtcNow - LastTwoFactorCodeUsedAt.Value;
        if (timeSinceLastUse.TotalSeconds < 60 && LastTwoFactorCodeUsed == hashedCode)
        {
            return false; // Code replayed within the 60-second window
        }
    }

    LastTwoFactorCodeUsed = hashedCode;
    LastTwoFactorCodeUsedAt = DateTime.UtcNow;
    return true;
}

Tenant-Scoped Password Policy

Password requirements are configurable per-tenant via TenantSettings. Each tenant can set minimum length, uppercase requirements, numbers, special characters, and expiry duration. The PasswordLastChanged field on the Admin entity is checked against the tenant's PasswordExpiryDays to enforce password rotation.

Admin Auth Endpoints

User Auth Endpoints

Rate Limiting

Authentication endpoints are protected by multiple rate limiting policies to prevent brute-force attacks and abuse.

Lockout Policies & brute-force limits

Brute-force protection sets `MaxFailedAttempts = 5` and a lockout duration of `LockoutMinutes = 15`. During a lockout, password validation is bypassed entirely to avoid timing attacks and CPU exhaustion, returning an immediate account locked error.