🔐 Security & Encryption

Blazor Blueprint protects sensitive data in three layers:

• Field-level encryption for credentials and PII the app needs to read back later (API keys, OAuth secrets, names, phone numbers).
• One-way hashing for tokens you only need to verify (invitation links, recovery codes, single-use access links).
• Storage-layer protection — encrypted backups, network isolation, and disk encryption — handled at deploy time, not in code.

Encryption is on by default. There is a single config knob — Security:Encryption:Mode — but the only production-safe value is the default. The two dev-only modes refuse to start in any environment that is not Development, so an accidental flip fails loudly at startup rather than silently leaking plaintext into the database.

How it works

Tag a string property with the [Encrypted] attribute. The active backend picks it up automatically — a global BSON convention swaps the string serializer on MongoDB, and an EF value converter does the same job on PostgreSQL / SQL Server — running the value through ISecretProtector (ASP.NET Core Data Protection) on every read and write. Call sites only ever see plaintext; the database only ever stores ciphertext, on all three backends.

No code change at any call site. Settings services, repositories, and admin pages already deal in plaintext; the BSON layer takes care of the rest.

What's encrypted

• EmailSettings.ApiKey — provider API key (SendGrid, MailerSend, Mailgun)
• EmailSettings.SmtpPassword — SMTP password
• ExternalAuthSettings.FacebookAppSecret, GoogleClientSecret, MicrosoftClientSecret — OAuth provider secrets
• PlatformPushSettings.VapidPrivateKey — the deployment's Web Push private key
• SsoSettings.ClientSecret — per-organisation OIDC client secret (nested on Organisation)
• ApiIntegration.ApiKey, ApiIntegration.Settings — third-party AI provider keys (OpenAI, OpenRouter, Ollama, N8N). Stored in the platform database; one set shared across every tenant. (SMS and inbound-email credentials are encrypted too, but they're not ApiIntegration. The operator's default sender and inbound mailbox are SmsProviderCredentials / MailgunCredentials rows in the platform organisation's own tenant database — not the platform database — used by every organisation that hasn't configured its own; an organisation that does keeps that override in its own tenant database. Payments below differ again — those are per-tenant only, with no shared row to fall back to.)
• PaymentProviderCredentials.ApiKey, PaymentProviderCredentials.Settings — Stripe / PayPal keys + webhook signing secrets. Stored per-tenant (money flows to the tenant's own merchant account, so the credentials are tenant-scoped for regulatory reasons).
• ApplicationUser.AuthenticatorKey — TOTP seed
• ApplicationUser.FirstName, LastName, PhoneNumber, DateOfBirth — PII fields (DateOfBirth stored as ISO string? like "1990-05-15")

What's not encrypted, on purpose

• Email / NormalizedEmail / UserName / NormalizedUserName — Identity uses these for login lookup. Encrypting them breaks FindByEmailAsync.
• DisplayName — used by the registration uniqueness check (DisplayNameExistsAsync).
• WebAuthn passkey CredentialId / PublicKey, VapidPublicKey — public by design.
• DomainVerificationToken — deterministic HMAC of the org name + domain, intentionally readable so DNS verification can replay.

Trade-off: queries against encrypted fields don't work

Data Protection produces non-deterministic ciphertext (same plaintext, different output every time). That defeats frequency analysis — but it also means server-side equality checks, substring searches, and sort operations against encrypted fields return nothing useful. The platform users search at /Platform/Users intentionally restricts its filter to the unencrypted fields (DisplayName, UserName, Email) for this reason.

If you ever need exact-match lookups on an encrypted field (e.g. "find user with this exact phone"), the standard pattern is a blind index: store an HMAC of the normalised value alongside the encrypted field and query by HMAC. Be cautious about adding blind indexes on low-entropy fields like first names — they're vulnerable to frequency attacks where an attacker matches hash counts against public name distributions to recover plaintext.

A single configuration knob, Security:Encryption:Mode, controls how the BSON serializer behaves. Default is Required. The other two values are escape hatches for local debugging and refuse to start in Production.

Required (default)

• Write: values go through ISecretProtector.Protect.
• Read: values go through Unprotect; bad ciphertext throws CryptographicException — fail loud.
• When to use: always, in every environment, unless you're actively debugging.

ReadOnly (dev only)

• Write: plaintext — the protector is not invoked.
• Read: tries to decrypt; if the value isn't valid ciphertext (e.g. it was just written in this mode), the failure is caught and the raw value is returned.
• When to use: debugging an existing dev database where you want to inspect raw values in Mongo Compass without losing the ability to read existing encrypted fields.

Disabled (dev only)

• Write: plaintext.
• Read: the stored value is returned verbatim, with no decryption attempt. Existing ciphertext therefore comes back as-is — unreadable, but it does not throw. If your dev database already holds encrypted values, use ReadOnly instead.
• When to use: a fresh dev database you've never run with encryption on, where you want to inspect everything raw.

Some values only need to be verified, never read back. Those are stored as SHA-256 hashes of the original — the raw value is sent to the user once and never stored.

• OrganisationMembership.InvitationToken — random token in the invitation email link; only the SHA-256 hash is persisted. AcceptInvitationByTokenAsync hashes the submitted token and looks up by hash. That token is the only route to accepting an invitation — matching a signed-in account's email address against the invited address is deliberately not sufficient, since nothing independently proves control of that mailbox.
• ApplicationUser.RecoveryCodes — UserManager surfaces plaintext codes once when generated; only hashes go into the database. RedeemCodeAsync hashes the submitted code and removes the matching hash from the list.
• Single-use access-link tokens — a feature that hands an unauthenticated visitor a random token in a URL stores only its SHA-256 hash plus an expiry, then constant-time-compares on revisit. The host exposes this as a reusable ITokenHasher primitive (Sha256TokenHasher).

A database read alone never reveals a usable token or code — the attacker would need both the database and a way to brute-force the hash, and the values are random enough that brute force isn't practical.

PII fields on ApplicationUser are tagged with the standard ASP.NET Identity attributes:

• [PersonalData] on FirstName, LastName, DateOfBirth, DisplayName, ProfilePictureUrl
• [ProtectedPersonalData] on AuthenticatorKey, RecoveryCodes

These attributes drive the GDPR data-download endpoint at /Account/Manage/DownloadPersonalData. When a user requests their personal data, the endpoint reflects over the user record and returns a JSON file containing every [PersonalData] value in plaintext (the BSON layer transparently decrypts on read), plus an explicit Authenticator Key entry and a Recovery Codes Remaining count. [ProtectedPersonalData] fields are excluded from the auto-reflection and handled explicitly because their treatment differs (TOTP key needs decryption; recovery codes are hashed and not exportable).

The endpoint is independent of the [Encrypted] attribute — encryption is for storage; [PersonalData] is for export.

Three things a user can do about their own account's security, all built:

• Active sessions (/Account/Manage/Sessions) — every sign-in listed with device, IP and last-active time, "this device" marked, and per-session or sign-out-everywhere revocation. A session id is minted into the auth cookie at sign-in and validated per request and per circuit revalidation, so a revoked session stops working across instances rather than only on the one that revoked it. A password change revokes the others to match the security-stamp bump.
• Security activity (/Account/Manage/SecurityActivity) — the user's own paginated history of sign-ins, password and 2FA changes, recovery-code use, external-login and role changes. Backed by a platform-scoped event log that is dual-written from the audit trail so the two cannot drift, and pruned on the audit retention window. Distinct from the tenant-scoped audit log behind the admin views: this one is the user's, that one is the organisation's.
• Lockout (Authentication:Lockout:*) — configurable thresholds on repeated failures.

Creating the platform organisation and the first platform admin is the one operation that hands out total control of a deployment, and on a fresh install nobody is signed in yet to authorise it. Two things can, and either alone is enough:

• A trusted connection — the request's real socket peer is loopback, or an address you named in Security:Setup:TrustedProxies / :TrustedNetworks, and the Host header is localhost, 127.0.0.1 or ::1. Both halves, and the host half cannot be widened by configuration — so this path is for a browser on the box, whatever address the peer arrives from.
• A setup token — Security:Setup:Token if you set it, otherwise 256 bits generated per process. Passed as /initial-setup?setupToken=…, compared in constant time, held in memory only and never persisted. The app writes it to the log at Warning, once per process, the first time a setup attempt is refused — so it appears exactly when you need it and never on a deployment that is already set up.

Both stop mattering permanently once an organisation exists: the gate is only reached while there is none.

Why an address alone cannot be the answer

In a container the peer is never loopback. The port is published, so a browser on the host reaches the app through Docker's port forwarding and the app sees the bridge gateway — and so does everyone else who can reach that port. An address cannot separate the operator from a stranger in that topology, which is why the token exists and why trusting the container network is a deliberate choice rather than a default.

The deploy compose files make that choice for you, on the web service:

- "Security__Setup__TrustedNetworks__0=172.16.0.0/12"

It keeps first run a single click on the box, and it trusts every caller that can reach the published port until setup completes. Keep it when that port is not reachable from outside the host; delete it — and use the token — when a fresh instance will sit on a public address unattended. The application's own default ships both lists empty.

Reaching a first run over a domain

Use the token — the trusted-network line will not help. Before setup there is no configured domain to reach: the platform organisation is what setup creates, and its domain comes off that very form. The host check accepts only localhost, 127.0.0.1 and ::1, so a first run opened at https://app.example.com/initial-setup is refused however you have set the peer lists.

A valid token satisfies both halves at once, which is exactly what makes this case work: it is a secret only the operator holds, so it is stronger evidence than either property of the connection. Either browse the box over localhost and set the domain on the form, or open /initial-setup?setupToken=… over the domain.

All field-level encryption is backed by ASP.NET Core Data Protection. The master key ring is what protects every encrypted value in the database. Lose the keys and you lose the data — the ciphertext becomes permanently unreadable.

Where the keys live

Configured by ServiceDefaults.AddDataProtection() in Core/BlazorBlueprint.ServiceDefaults/Extensions/ServiceCollectionExtensions.cs, with a 90-day key lifetime and automatic rotation. Where it is stored depends on your deploy mode:

• Full stack — in Redis, under the list BlazorBlueprint-DataProtection-Keys. All three hosts (Web, InternalApi, BackgroundWorker) connect to the same Redis with the same ApplicationDiscriminator ("BlazorBlueprint"), so they share one ring and can decrypt one another's writes.
• Lite — on the filesystem, via a named volume mounted at /keys. There is no Redis in Lite, so that volume is your key ring, and it is the one Lite volume you cannot afford to lose. Back it up by its host name, bb_lite_dp_keys — dp_keys is only the compose-local alias, so a backup job keyed on that literal matches nothing.

Everything below about rotation, backup and sharing applies to both — only the storage location differs.

The list name is {Caching:RedisKeyPrefix}-DataProtection-Keys. That prefix — which also namespaces the caches, the SignalR backplane and the cache-eviction channel — only needs setting when two deployments share one Redis instance, so that each keeps its own ring instead of writing over the other's. Set it once, at first deploy. Changing it on a running deployment points the app at an empty ring: it mints a fresh key, and every value encrypted under the old ring becomes permanently unreadable.

Keys are auto-generated by the framework on first use — you never set them by hand. You only configure where they're stored.

Key rotation (automatic)

Data Protection rotates the active key on a fixed schedule — every 90 days by default. Rotation is automatic, transparent, and does not require any action on your part. Here's what happens:

• A few days before the current key expires, a new key is generated and added to the ring.
• From that point on, new writes use the new key.
• Old keys stay in the ring permanently — they're never deleted. This is by design, so existing ciphertext written under any previous key is always decryptable.
• The ciphertext itself carries the ID of the key it was encrypted with, so the framework picks the right key from the ring automatically on read. You don't track this anywhere.

Practical implication: the Redis list at BlazorBlueprint-DataProtection-Keys grows by one entry every ~90 days. Each entry is a few KB of XML. Over a year of running you might have 4–5 keys in the ring. Storage cost is negligible.

Backup implication: back up the ring (the whole Redis list / volume / managed-Redis snapshot), not "the key" — singular. A backup taken today contains every key the app has ever generated; restore that backup at any point in the future and all historical ciphertext is readable. The reason to back up on a regular schedule (daily snapshot of Redis or the host VM) isn't because keys "disappear" — it's so a backup taken today still covers ciphertext written next month with the next rotated key.

The only rotation event you'd ever drive manually is a revocation — explicitly marking a key as compromised via IKeyManager.RevokeKey(...). That stops the key being used for new encryption and renders all ciphertext written under it unreadable. Drastic, deliberate, and not something that happens automatically.

Sharing keys across hosts

Any process that (a) connects to the same Redis and (b) uses the same ApplicationDiscriminator reads the same key ring. That's already how Web + InternalApi + BackgroundWorker share keys today; they all point at the same ConnectionStrings:redisCache.

Scaling out to additional servers? Point them at the same Redis. Done. Different Redis instances generate different key rings and cannot decrypt one another's data.

The BlazorBlueprint.AppHost Aspire project provisions a Redis container with a persistent volume and snapshotting enabled, so the key ring survives dotnet run cycles, image rebuilds, and machine reboots:

WithDataVolume() creates a named Docker volume on first run; Aspire reuses it on subsequent runs. WithPersistence(...) tells Redis to flush its in-memory state to disk every minute, so a hard crash loses at most ~60 seconds of writes. The only ways to lose the keys locally are docker volume rm on the named volume, reformatting your machine, or deleting the volume from Docker Desktop's UI.

Both the GitHub Actions and Azure DevOps deploy paths use the same docker-compose.yml shape, with Redis configured for durable storage:

The redis_data named volume persists on the host's Docker volume directory. The --appendonly yes flag enables AOF (append-only file) persistence so every write is durable, not just periodic snapshots.

The other three arguments are not tuning, and none of them is optional.

• --requirepass — Redis publishes no host port, but "not published" is not "not reachable": anything else attached to the compose network can talk to it. This instance holds the Data Protection key ring unencrypted, so an unauthenticated Redis is every encrypted field in the deployment, plus the ability to forge auth cookies, plus one FLUSHALL away from making all encrypted data permanently unreadable. The ${VAR:?message} form makes docker compose up refuse to start without the password rather than quietly bringing up an open instance. There is deliberately no username variable — --requirepass sets the password of Redis's implicit default ACL user, which is why the connection string carries password= and no user=.
• --maxmemory-policy noeviction — this instance also carries the job streams. Any allkeys-* policy evicts them under memory pressure, which loses queued work silently: no error, no log line, just background jobs that never run.
• --maxmemory 2gb — the ceiling that policy applies at. Under noeviction, reaching it makes Redis refuse writes rather than evict, which stops every publish and takes the cache, the SignalR backplane and the key ring with it. Size it against the worst worker outage you want to survive, and alert on it.

What survives a deploy, what doesn't

• ✅ New image pushed → server pulls + restarts containers — named volumes are not touched. Keys persist.
• ✅ docker compose down && docker compose up -d — volumes survive a regular down/up cycle.
• ✅ Server reboots — Docker remounts named volumes on restart.
• ❌ docker compose down -v — the -v flag removes volumes. Wipes Redis keys and Mongo data.
• ❌ docker volume rm redis_data — explicit volume deletion.
• ❌ Server's disk fails or VM is destroyed — same risk as your MongoDB.

Backup strategy

The simplest answer: snapshot the host VM. Whatever's running your Docker host (Azure VM, AWS EC2, DigitalOcean, Hetzner, etc.) almost certainly has a "snapshot" or "backup" feature in its console. Schedule daily snapshots, retain ~7 days. That captures the whole disk including all Docker volumes — Redis keys, Mongo data, n8n data — in one operation.

For more granular backup of just the key ring volume:

Copy the resulting tarball off the server (S3, Azure Blob, etc.). Restore by extracting it back into the same volume location. Note the :ro — mount the key-ring volume READ-ONLY for a backup. An ad-hoc container given write access to a live data volume can rewrite it, and for this volume that means losing the key ring, which is the exact loss the backup exists to prevent.

The default setup is appropriate for most SaaS applications. The following upgrades are worth considering as the application grows or compliance requirements emerge:

• Encrypt the keys-in-Redis with ProtectKeysWithCertificate(...) — not wired up by default; a suggestion comment marks where it would go, inside AddDataProtection() in ServiceCollectionExtensions.cs. The keys inside Redis become themselves encrypted by a certificate you control. If Redis is dumped, the contents are useless without the cert. Shifts your "thing to keep safe" from "all of Redis" to one X.509 cert in your secrets manager.
• Move the key ring to Azure Key Vault / AWS KMS (PersistKeysToAzureBlobStorage + ProtectKeysWithAzureKeyVault, or AWS equivalents). Keys live in a managed KMS, multiple regions can read them with appropriate IAM, audit logs are built in. Heavier ops setup.
• Mount the key ring on a network file share (PersistKeysToFileSystem on EFS / Azure Files / NFS). Useful if you want to keep the keys outside Redis but don't want to introduce cloud KMS dependencies.
• Storage-layer encryption-at-rest for MongoDB (Atlas built-in EAR, encrypted EBS volumes, encrypted backups). Protects against an attacker who gets a raw disk image but not against one with database credentials. Transparent — doesn't break any query — and complements field-level encryption rather than replacing it.

Adding a new encrypted field

1. Make sure the property type is string (the convention throws at startup for non-strings).
2. Add [Encrypted] from BlazorBlueprint.Domain.Attributes.
3. That's it. No service-layer changes, no migration needed for new data.

Existing plaintext rows written before the attribute was added will throw CryptographicException on read — by design, so misconfiguration fails loud rather than silently returning ciphertext as plaintext. For a fresh database this is a non-issue. If you're retrofitting, add a one-time migration that reads + re-saves affected documents.

Key file locations

• Core/BlazorBlueprint.Domain/Attributes/EncryptedAttribute.cs — the attribute
• Infrastructure/BlazorBlueprint.Infrastructure.Persistence.MongoDB/Encryption/ — BSON serializer, convention, host (MongoDB backend)
• Infrastructure/BlazorBlueprint.Infrastructure.Persistence.EntityFrameworkCore/Encryption/ — value converter + mode resolver (PostgreSQL / SQL Server backends)
• Core/BlazorBlueprint.Application/Services/Security/DataProtectionSecretProtector.cs — protector implementation
• Core/BlazorBlueprint.ServiceDefaults/Extensions/ServiceCollectionExtensions.cs — Data Protection / Redis wiring