ntlm & lsa backends

This document covers the NTLM and LSA backend types, which enable integration with Windows authentication ecosystems.

BackendPurpose
ntlmAuthenticate users via an external helper implementing NTLM challenge/response (domain or local accounts).
lsaAuthenticate locally (or domain via local security authority) exposing group membership & contextual identity attributes.

Both backends are typically used in environments where existing Windows account infrastructure must be reused for RADIUS / TACACS+ / HTTP-based authentication.

1. NTLM Backend

The ntlm backend delegates credential validation to an external helper program. This offers isolation and allows reuse of platform-specific or privileged code without embedding it directly into the main server process.

Configuration Example

backends {
    ntlm "NTLM_AUTH" {
        program "/usr/local/libexec/radiator/ntlm-helper";
        arguments ["--mode","auth"];
        processes 4;
        username "radiator_svc";
        domain "EXAMPLE";
    }
}

Key Directives

DirectiveRequiredDescription
programYesAbsolute path to helper binary/script. Must be executable.
arguments [...]NoStatic array of arguments passed at helper startup.
processes <n>;NoPreforked helper process pool size (throughput scaling).
username "...";NoService / machine account hint (helper-dependent).
domain "...";NoWindows domain hint forwarded to helper.
statistics { ... }NoPer-backend stats configuration (if metrics enabled).
service_level_objective { ... }NoPerformance expectations guiding health logic.

The helper generally implements:

  1. Challenge generation (for MSCHAPv2 / NTLM handshake).
  2. Response verification against a Windows domain controller or local SAM.
  3. Return of success/failure and optionally group data (if protocol supports).

Scaling

Increase processes to improve concurrency if many simultaneous authentications occur and the helper is CPU or I/O bound. Oversizing wastes memory / context switch time. Monitor throughput before adjusting.

Failure Modes

SymptomCauseAction
Frequent timeoutsHelper hung or DC unreachableInspect helper logs / network to DC
High failure rate after upgradeHelper version mismatchRoll back or rebuild helper with compatible libraries
Crash loopBad arguments / missing binaryVerify program path & permissions

Security Considerations

  • Restrict file permissions on the helper binary (750 or tighter).
  • Keep helper updated with security patches.
  • Limit environment variables to avoid leaking secrets.
  • Validate that helper does not expose shell injection surfaces via arguments.

2. LSA Backend

The lsa backend authenticates against the local Windows Security Authority (Lsass). It may provide group membership and other contextual attributes directly from the local or domain-joined machine.

Configuration Example

backends {
    lsa "LSA_LOCAL" {
        group ["Administrators","NetworkOps"];
        domain "EXAMPLE";
        domain_controller "dc01.example.com";
        connections 8;
    }
}

Key Directives

DirectiveRequiredDescription
group [ ... ];Yes (at least one)Static groups to associate (augmentation baseline).
process "name";NoTarget process/context hint (advanced / rarely needed).
username "...";NoService context user (if needed).
workstation "...";NoWorkstation / host identifier hint.
domain "...";NoDomain override (if machine is multi-domain or needs explicit selection).
domain_controller "...";NoPreferred DC hostname.
connections <n>;NoMaximum parallel LSA logical sessions.
statistics { ... }NoPer-backend metrics configuration.
service_level_objective { ... }NoLatency / error budget hints.

Behavior

  • Authentication is performed locally; domain join state influences available accounts and groups.
  • Static group entries act as guaranteed role tags; dynamic group retrieval (if implemented internally) is additive.

Performance

connections controls parallel LSA contexts. Start conservatively (4–8) and increase only if latency or queueing appears under load.

Failure Modes

SymptomCauseAction
Intermittent auth failuresDomain controller switching / replication delaySpecify domain_controller or review AD health
Slow logonsDC latencyIncrease connections; profile network path
Missing groupsDomain trust / replication gapConfirm group membership in AD; check dynamic mapping logic

Mapping to AAA Pipelines

Typical handler snippet incorporating Windows-based authentication:

aaa {
  policy "WIN_AUTH" {
    handler "NTLM_USERS" {
      authentication {
        backend "NTLM_AUTH";
        mschapv2;
      }
      authorization {
        # Use static/dynamic groups populated from backend
        if all {
          user.group == "Administrators";
        } then {
          set response.reply-message = "Admin access granted";
          accept;
        }
        accept;
      }
    }
  }
}

For LSA:

authentication {
    backend "LSA_LOCAL";
    mschapv2;
}
Navigation
Home
Parents