Umbraco Package

Overview

DarkStrata Credential Check for Umbraco stops compromised credentials being used on your Umbraco site. When a member or backoffice user logs in or sets a password, the email and password pair is hashed locally and checked against the DarkStrata breach corpus using k-anonymity: only the first five characters of a SHA-256 hash ever leave your server. Passwords are never sent to DarkStrata.

It is a single NuGet install with no backoffice UI and no database changes. Supports Umbraco 13 LTS, 15 and 16.

What it does:

Requirements

You will also need:

• A DarkStrata plan that includes Credential Check and an API key with the credential_check:read scope
• Outbound HTTPS connectivity to api.darkstrata.io (port 443)

Installation

Install from NuGet into your Umbraco web project:

dotnet add package DarkStrata.CredentialCheck.Umbraco

The package registers itself through an Umbraco composer, so there is nothing to wire up in code. Rebuild and run.

Configuration

1. Create an API key

In app.darkstrata.io go to Integrations > API keys > Create key and tick the credential_check:read scope. Copy the key (it starts with ds_live_); it is shown once. The scope is only offered on plans that include Credential Check.

2. Give the key to the site

The package reads the standard ASP.NET Core configuration section DarkStrata:CredentialCheck, so use whichever configuration source your hosting already uses. Pick one:

Environment variable (recommended for production, Umbraco Cloud, Azure App Service, Docker):

DarkStrata__CredentialCheck__ApiKey=ds_live_...

User secrets (local development, keeps the key out of git):

dotnet user-secrets set "DarkStrata:CredentialCheck:ApiKey" "ds_live_..."

appsettings.json (simplest, but the key is then committed with your site):

{
  "DarkStrata": {
    "CredentialCheck": {
      "ApiKey": "ds_live_...",
      "ValidatePasswords": true,
      "CheckLogins": true,
      "LoginAction": "Deny",
      "FailOpen": true
    }
  }
}

Azure Key Vault, AWS Parameter Store and similar work through their normal configuration providers. Changes are picked up without a restart where the provider supports reload.

3. Check it is working

Open Settings > Health Check > Security in the backoffice. DarkStrata Credential Check is green when the key is configured and accepted by the API, and red with a message when the key is missing or rejected.

There is no backoffice settings screen for the key. It is a secret, so it lives in configuration, not in the CMS database.

All settings

React to a hit

Every compromised credential publishes CompromisedCredentialDetectedNotification. Handle it like any other Umbraco notification to email your security team, lock the member or open a ticket:

using DarkStrata.CredentialCheck.Umbraco;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Core.Events;

public class CompromisedCredentialHandler
    : INotificationAsyncHandler<CompromisedCredentialDetectedNotification>
{
    public Task HandleAsync(CompromisedCredentialDetectedNotification n, CancellationToken ct)
    {
        // n.Source: MemberPassword | BackOfficePassword | MemberLogin | BackOfficeLogin
        // n.Email, n.UserId
        return Task.CompletedTask;
    }
}

public class MyComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder) =>
        builder.AddNotificationAsyncHandler<CompromisedCredentialDetectedNotification, CompromisedCredentialHandler>();
}

Failure behaviour

Pause or uninstall

Pause without uninstalling. Remove or blank the API key and every check is skipped. To switch off only part of it, set CheckLogins or ValidatePasswords to false. Setting LoginAction to Warn keeps the checks running but stops them blocking anyone, which is useful for a trial period.

Uninstall.

dotnet remove package DarkStrata.CredentialCheck.Umbraco

Rebuild and redeploy. The package writes nothing to the Umbraco database and adds no content types, data types, tables or backoffice files, so there is nothing else to clean up. The DarkStrata configuration section is harmless if left behind.

Resources & support

The package is open source under the Apache-2.0 licence. For the full API reference and other integrations, see the developer documentation. If you need a hand, our team is happy to help.