TACACS+ AAA

What it does

Minimal config

system {
    authentication {
        tacacs {
            server 10.0.0.1 { port 49; key "$9$encrypted-key"; }
            server 10.0.0.2 { port 49; key "$9$encrypted-key"; }
            timeout 5
        }
        tacacs-profile 15 { profile [ admin ]; }
        tacacs-profile 1  { profile [ read-only ]; }
    }
    authorization {
        profile admin     { run { default-action allow; } edit { default-action allow; } }
        profile read-only { run { default-action allow; } edit { default-action deny;  } }
    }
}

Authentication flow

1. SSH client connects with username + password.
2. Daemon's AAA chain calls TacacsAuthenticator first (priority 100; local bcrypt is priority 200).
3. The client opens TCP to the first configured server and sends a PAP AUTHEN START. The body is XOR-encrypted with the MD5 pseudo-pad keyed on the shared secret.
4. PASS -- the server's reply data byte is the priv-lvl. The authenticator looks up tacacs-profile <priv-lvl>.profile. A matching entry yields the authz profiles attached to the SSH session. An unmapped priv-lvl rejects the login (AC-18) so adding new TACACS+ levels in the upstream server does not accidentally grant access.
5. FAIL -- explicit rejection. The chain stops here. Local bcrypt is NOT tried. This prevents a wrong password against TACACS+ from succeeding via a stale local hash.
6. Connection error / ERROR status -- the next server in the list is tried. When every server is unreachable (or all return ERROR) the chain falls through to the local bcrypt authenticator.

Privilege level mapping

TACACS+ servers send a numeric priv-lvl (0-15) in the AUTHEN REPLY. Ze's internal authorization model is name-based, so each priv-lvl must be mapped to one or more locally-defined system.authorization.profile entries.

Levels not present in tacacs-profile, and levels mapped to an empty profile list, reject the login. Look for TACACS+ unmapped privilege level in the daemon log when extending the upstream config. A TACACS+ user therefore always reaches authorization with at least one resolved profile, or does not authenticate at all: there is no path where an authenticated TACACS+ user has no profile.

Even so, authorization fails closed at the second layer: if a session ever reaches authorization resolving no applicable profile, every command is denied rather than allowed. A priv-level whose mapping names only profiles you have not defined resolves nothing and is denied, not granted admin. Local break-glass accounts (the ze init bootstrap admin, or any system.authentication.user you keep) are the way back into a box whose mapping is wrong.

What the mapped profiles govern

The mapped profiles decide every command the session may run after login succeeds. Ze resolves them once at authentication and authorizes each command against them, so tacacs-profile 1 { profile [ read-only ]; } gives that session exactly what the local read-only profile allows and refuses the rest with command restricted by access control.

Only the profile names are fixed at login. Each command is evaluated against the profile as it is defined at that moment, so editing read-only and committing applies to sessions already open, without a reconnect.

A local system.authentication.user block with the same username takes precedence over the mapped profiles: an explicit local assignment is a stated intent for that name, so it is not widened or narrowed by how the user logged in.

Verify the mapping with a command the profile denies, not with one Ze does not have. A command that does not exist reports unknown command and exits non-zero for everyone, so it passes whatever the mapping says and proves nothing.

Setting authorization true moves the per-command decision to the TACACS+ server itself: Ze sends an AUTHOR REQUEST per command, and the profiles above apply only as the fallback when the server is unreachable, unless strict-fallback true makes that case deny.

Accounting

When accounting true is set, every command dispatched through the CLI emits two records:

Records are queued to a single long-lived background worker. The worker sends one record at a time over the same TACACS+ client used for authentication, with the same server failover. Accounting failures are logged (TACACS+ accounting failed) and never block the command. Records that cannot be queued increment the local drop counter.

Use ze show aaa accounting to inspect the counter:

ze show aaa accounting

The response includes dropped-records. A non-zero value means at least one START/STOP record was lost locally before the TACACS+ client could send it.

Verification

The .ci tests in test/plugin/ cover the main behaviours:

Strict fallback is covered by TestExtractConfigStrictFallback and TestTacacsAuthorizerStrictFallbackDeniesUnreachable in the TACACS+ unit tests.

For ad-hoc verification, point the daemon at a real TACACS+ server and run any command via ze cli -c "show bgp summary" -- the daemon log tags the satisfying backend on every login, e.g.:

INFO SSH auth success subsystem=ssh username=alice remote=10.0.0.1:51408 source=tacacs

source=tacacs confirms the chain consulted TACACS+ and returned PASS. source=local means TACACS+ was unreachable (or unconfigured) and the local bcrypt user accepted the credentials.

Operational notes

• Shared secrets are stored as $9$-encoded ciphertext, never as plaintext. The CLI never echoes them; ze config dump --strip-private replaces them with /* SECRET-DATA */.
• VRF: when the SSH server runs in a non-default VRF, TACACS+ TCP connections inherit the same VRF context.
• Single-connect mode (RFC 8907 §4.4) is tested via tacacs-singleconnect.ci.
• Operational tooling: ze tacacs show <config> displays the parsed TACACS+ configuration offline. Runtime ze show aaa accounting exposes local accounting queue drops. Per-server reachability remains tracked in plan/deferrals/.

RFC reference

• RFC 8907 -- The TACACS+ Protocol (formalises the original Cisco draft). Local summary: rfc/short/rfc8907.md.