backends.netlogon

netlogon

The Netlogon backend is experimental. Its configuration options, defaults, and log messages may change in a later release.

The netlogon backend authenticates PAP, MSCHAP and MSCHAPv2 users against an Active Directory domain controller. Radiator joins the domain as a computer account, opens a Netlogon secure channel, and asks the domain controller to verify each user's credentials. Radiator does not need to store the users' passwords.

For MSCHAP and MSCHAPv2, the domain controller verifies the challenge response that the user's device sent. For PAP, Radiator computes an NTLMv2 response from the password and the domain controller verifies it, so PAP works in domains that allow only NTLMv2. This includes passwords that EAP-TTLS carries as inner PAP and that EAP-TEAP carries in Basic-Password-Auth.

The backend authenticates the computer account once and shares the resulting secure channel across a pool of connections. All Netlogon messages are signed and encrypted with AES.

Example

backends {
    netlogon "AD" {
        endpoint "dc1.example.com:50001";
        domain_controller "\\\\DC1";
        domain "EXAMPLE";
        computer_name "RADIATOR1";
        machine_account "RADIATOR1$";
        machine_password "%{env.NETLOGON_MACHINE_PASSWORD}";
        connections 4;
        timeout 5s;
    }
}

aaa {
    policy "RADIUS" {
        handler "AUTHENTICATION" {
            conditions all {
                radius.request.code == radius.ACCESS_REQUEST;
            }

            @execute {
                until accept reject {
                    pap response;
                    mschapv2 response;
                }
                backend "AD";
            }
        }
    }
}

Requirements

• The computer account named by machine_account must exist in Active Directory, and machine_password must hold its current password.
• Radiator connects directly to endpoint and does not query the RPC endpoint mapper. On Windows domain controllers, set a fixed Netlogon port with the DCTcpipPort value under HKLM\SYSTEM\CurrentControlSet\Services\Netlogon\Parameters, and use that port in endpoint.
• The domain controller must support AES-protected Netlogon. Radiator refuses domain controllers that do not.
• Give each Radiator instance its own computer account. Each system that authenticates with an account replaces the secure channel that the domain controller stores for it.

Capacity and scaling

Each connection carries one logon at a time. Radiator sends the next logon on a connection only after the domain controller has answered the previous one. A request uses any free connection. When all connections are busy, the request waits until one is free.

The number of logons per second that a backend can carry is therefore limited by connections divided by the time the domain controller takes to answer one logon. For example, when the domain controller answers a logon in 5 ms, one connection carries at most 200 logons per second and four connections carry at most 800. Requests beyond that wait for a connection, which increases their latency but not the throughput.

To increase capacity:

• Increase connections. All connections share one secure channel, so adding connections does not authenticate the computer account again.
• Check the domain controller's own limit. Windows domain controllers limit the number of concurrent Netlogon calls on one secure channel with the MaxConcurrentApi value under HKLM\SYSTEM\CurrentControlSet\Services\Netlogon\Parameters. Connections beyond that limit wait on the domain controller instead of in Radiator.
• Set timeout to cover the expected wait at peak load. The time a request waits for a free connection counts toward the timeout.
• Run more Radiator instances, each with its own computer account. Each instance has its own secure channel and connection pool.

Parameters

endpoint

Host and TCP port of the Netlogon RPC endpoint, written as host:port. The host is a DNS name, an IPv4 address, or an IPv6 address in square brackets, such as [2001:db8::1]:50001. Required.

A domain controller stores the secure channel only in its own memory. When the DNS name resolves to several addresses, Radiator tries them in order, waiting up to 2 seconds for each connection, and sets up the secure channel with the first address that accepts the connection. Every connection of that channel goes to the same address. When a new connection to that address fails or is refused, Radiator sets up a new secure channel and resolves the name again, so it can move to another domain controller behind the name.

domain_controller

Domain controller name that Radiator sends as the Netlogon server name, usually in the form \\DC1. Required.

domain

NetBIOS name of the domain that owns the computer account, such as EXAMPLE. The value is 1 to 15 printable ASCII characters. Required.

computer_name

NetBIOS computer name of this Radiator instance, such as RADIATOR1. The value is 1 to 15 printable ASCII characters. Required.

machine_account

Name of the Active Directory computer account, including its trailing $, such as RADIATOR1$. Required.

machine_password

Current password of the computer account. The value can use interpolation, for example %{env.NETLOGON_MACHINE_PASSWORD}. Required.

To change the password, update machine_password and reload the configuration. A reload rebuilds the backend when its configuration changes, so new connections authenticate with the new password. Radiator does not change the computer account password itself.

A reload that changes other settings but keeps endpoint, domain_controller, domain, computer_name, machine_account, and machine_password keeps the established secure channel, so requests that are still running on the previous configuration are not interrupted.

connections

Number of connections to the domain controller, from 1 to 65535. All connections share one secure channel. Each connection carries one logon at a time, so this value sets how many logons run concurrently. Radiator opens a connection the first time a request uses it. See Capacity and scaling. Default: 1.

keepalive

TCP keepalive probes for every connection to the domain controller. Keepalive is enabled even without this block, with the values shown below. Probes keep idle pooled connections open through firewalls and NAT devices and detect a domain controller that disappeared without closing the connection. A connection that carries traffic is never probed.

keepalive {
    idle 10s;
    interval 3s;
    count 3;
}

A keepalive block replaces these values. It must set all three parameters; a block that omits one is a configuration error:

• idle: time without traffic before the first probe.
• interval: time to wait for an answer before sending the next probe.
• count: number of unanswered probes in a row before the connection is closed.

A healthy idle connection gets one probe every idle. Only unanswered probes are repeated every interval. With the defaults, a domain controller that stops answering is detected at most 10s + 3 * 3s = 19s after the last traffic on the connection:

The next request on that pooled connection opens a new connection. See keepalive for how the probes work.

timeout

Maximum duration of one backend action when the backend action sets no timeout. The duration includes waiting for a free connection and opening a new connection when needed. See duration units. Default: 5s.

Results

• The backend accepts the request when the domain controller verifies the credentials. For MSCHAPv2, Radiator uses the user session key from the domain controller to build the MSCHAPv2 reply.
• The backend rejects the request when the domain controller rejects the credentials or the account, for example for a wrong password, a disabled account, or a locked account.
• The backend action fails with an error when the domain controller cannot complete the logon for another reason, such as a broken domain trust.
• If a request cannot be sent because its pooled connection was already closed, for example by a firewall after a period without traffic, Radiator retries it once on a new connection. A request that was sent is never retried, because the domain controller may already have counted a wrong password toward account lockout.
• The backend rejects a logon that the domain controller validates only as the Guest account.
• A machine identity in the form host/name or host/name.example.com, as Windows sends for EAP machine authentication, is verified as the computer account name$.
• When an alerts block enables backend incidents, a domain controller that cannot be reached, times out, fails logons, or refuses the secure channel opens a backend incident. The next logon that the domain controller answers, accepted or rejected, starts clearing it.
• If the domain controller no longer accepts the secure channel, Radiator authenticates the computer account again and retries the request once.
• The domain controller records PAP logons as NTLMv2 network logons from the computer named by computer_name.
• Requests without credentials are ignored. Requests that use other authentication protocols, such as CHAP, fail with an error.

The backend also supports the service_level_objective and statistics blocks.