ResearchCave.PasswordProtect (1.1.68)
Installation
dotnet nuget add source --name ResearchCave --username your_username --password your_token https://git.researchcave.com/api/packages/ResearchCave/nuget/index.jsondotnet add package --source ResearchCave --version 1.1.68 ResearchCave.PasswordProtectAbout this package
Drop-in shared-password access gate for ASP.NET Core applications. Provides a self-contained password page and remembers successful access with a secure hashed cookie.
ResearchCave.PasswordProtect
ResearchCave.PasswordProtect is a drop-in shared-password access gate for ASP.NET Core
applications. It returns a self-contained password page until the visitor enters the configured
password, then remembers access with a protected browser cookie.
The package is application-agnostic: it can be used by any ASP.NET Core application. The password
page, CSS, and default logo are embedded in the package, so consuming applications do not need to
copy files into wwwroot.
This is not user authentication or authorization. There is one shared password, no user identity, and no permissions model. Use it only as an additional access barrier for preview, staging, maintenance, private demonstration, or other limited-access deployments. Keep normal application authentication and authorization enabled behind it.
Installation
Install the package:
dotnet add package ResearchCave.PasswordProtect
Quick start
Register the service before building the application and add the middleware near the start of the request pipeline:
using ResearchCave.PasswordProtect;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddPasswordProtection();
var app = builder.Build();
// Place trusted proxy/error middleware before this when applicable. Keep routing,
// static files, authentication, authorization, and endpoints after it.
app.UsePasswordProtection();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
By default, the password is read from the RcPassword configuration key. ASP.NET Core maps an
environment variable with the same name automatically:
$env:RcPassword = "choose-a-strong-password"
dotnet run
For containers:
environment:
RcPassword: "${APP_ACCESS_PASSWORD}"
If neither PasswordProtectOptions.Password nor RcPassword contains a value, the middleware is
disabled and requests pass through unchanged.
Configuration
Options can be supplied during registration:
builder.Services.AddPasswordProtection(options =>
{
// Prefer configuration or a secret store instead of committing a password in source.
options.Password = builder.Configuration["PreviewAccess:Password"];
options.PageTitle = "Private preview";
options.CookieName = "preview_access";
options.CookieMaxAge = TimeSpan.FromHours(12);
// Leave null for a host-only cookie. Set a parent domain only when access should be
// shared by applications on subdomains of that same parent domain.
options.CookieDomain = null;
// Optional full inline <svg> element. The default is the ResearchCave brand mark.
options.LogoSvg = "<svg viewBox=\"0 0 32 32\">...</svg>";
});
| Option | Default | Purpose |
|---|---|---|
Password |
RcPassword configuration |
Shared password. An empty value disables the gate. |
CookieName |
rc_beta_access |
Name of the access cookie. |
CookieDomain |
null |
Optional parent domain used to share access across its subdomains. |
CookieMaxAge |
180 days | Lifetime of remembered access. |
PageTitle |
Beta Access |
Browser and page title. |
LogoSvg |
Embedded ResearchCave mark | Full inline SVG rendered on the password page. |
Request behavior
- A visitor without a valid cookie receives
401 Unauthorizedwith the embedded HTML password page. - The page submits to the package-owned
/__rc-password-protect/verifyendpoint. - A correct password creates the access cookie and redirects to the original local URL.
- An incorrect password redisplays the page with its validation message.
- Return URLs are restricted to safe local relative paths.
- The password page has no dependency on application static files.
The access cookie contains a SHA-256-derived value rather than the plaintext password. It is
written with HttpOnly, Secure, SameSite=Lax, Path=/, and the configured maximum age.
Password and cookie comparisons use fixed-time equality checks. Use HTTPS; browsers will not send
the Secure cookie over plain HTTP.
Built-in bypass paths
Infrastructure and protocol endpoints that must remain reachable bypass the gate:
/health,/healthz,/alive,/ready,/metrics/.well-known/signin-oidc,/signout-callback-oidc
Common browser metadata paths also bypass it by exact match:
/favicon.ico,/favicon.svg/apple-touch-icon.png,/apple-touch-icon-precomposed.png/site.webmanifest,/manifest.webmanifest/browserconfig.xml,/robots.txt
The bypass list is intentionally fixed and narrow. Application endpoints should use their normal authorization rules even when they are behind this shared-password gate.
Changing the embedded page
Package developers can edit Resources/PasswordPage.html and Resources/ResearchCaveLogo.svg
directly. Both files are embedded into the assembly during build and loaded once per process.