FreeIPA HBAC rule testing with hbactest

Why test FreeIPA HBAC rules before they enforce access

Replacing the default allow-all policy on FreeIPA hosts is a change to who can log in at all, so the safest time to find gaps is before enforcement starts. FreeIPA HBAC rules decide which users, through which services, may access which hosts. Until those rules are tested, a team cannot say with confidence who keeps access once the default is removed. The ipa hbactest command lets you ask that question directly, without changing live login behavior.

For a given user, host and service combination, ipa hbactest reports whether access would be granted and which rule produced the result. That second part matters most in review. A denial can point to a missing rule, a rule scoped to the wrong host group, or a service name that does not match what the login path actually uses. A grant can point to a broad rule that was added years ago and nobody remembers. Either result tells you which rule to change before enforcement, rather than after a locked-out administrator reports the problem.

Teams usually need this step at three points: when a default allow-all policy is about to be replaced, when a new host group or service joins an existing environment, and when auditors or internal reviewers ask how access was decided. Confirm with your own change process who owns the sign-off, which user and host groups must keep access, and which service names your SSH, console and sudo paths use in your environment. Those answers form the test matrix the rest of this page builds.

Which hbactest inputs to test and when each one fits

This table compares the main ways to scope an hbactest run, from one user across all hosts to one service path, and what each answer tells you before a rule is enforced. Read each row as a question you can answer with the command, then confirm the exact flag names and output format with ipa help hbactest on your FreeIPA version.

Test approach	What it answers	When it fits	What to confirm first
One user across all hosts	Which hosts this person could reach under the rules being evaluated	Checking a role change, a leaver, or a group that has grown beyond its original purpose	Whether your version lets you omit the host input to span hosts, and how results are listed
One host across all users	Which users or groups could log in to a given server	Reviewing a sensitive server such as a bastion, database host or jump box before a rule change	How the group input is handled and whether nested groups are expanded in the result
One service path, such as SSH	Whether a specific service entry in a rule permits the login	Separating SSH access from console, sudo or other PAM services that share a host	Which service names your rules reference and how they map to PAM service names on clients
Console or local login	Whether a login through the host console is allowed separately from remote access	Hosts where physical or console access is treated differently from network access	Whether your rules use a dedicated console service entry or rely on a broader one
Current enabled rules	How access behaves today under the rules actually enforced	Baseline capture before any change, and evidence of the state at a given date	That disabled rules are excluded from the evaluation on your version
Draft or proposed rule set	How access would behave after a planned change	Testing a replacement for allow_all or a narrowed rule before enabling it	How to build the candidate rule set without enabling it on the live domain
Specific user, host and service combination	A single yes or no for one exact login path	Regression cases you keep for audits and rerun after every rule change	How to record the expected result alongside the command output so reruns can be compared

Replacing allow_all safely without locking people out

The default `allow_all` rule hides who actually has access to each host. While it stays enabled, every authenticated identity in the directory can log in everywhere, so a test run against it proves very little. Replacement works in stages: first inventory which users, groups and hosts really need access, then write an explicit rule for each group, then run ipa hbactest against every login path on the expected access list. Keep allow_all enabled until the results match that list exactly. Only then disable it, and keep the disabled state as a tested result rather than an assumption.

Overlapping rules are the most common source of surprises. HBAC rules are additive, so a user matched by two rules keeps the union of their access, and a narrow rule written for one team can quietly stay in force after a broader rule is added. Access can also arrive by accident through group membership: a user placed in a group nested under an access group, or a host added to a hostgroup that a rule references, gains access without anyone editing the rule itself. Check nested groups and hostgroups in each test case, not only the rule's direct members. Confirm with your own environment how your FreeIPA version resolves nested membership before you rely on the results.

Automember rules and ordinary group changes can change test results without any HBAC edit. A new automember rule can place newly enrolled users or hosts into a group that a rule already references, and a membership change made by a team lead or delegated manager can do the same. For that reason, rerun the full test set after any change to groups, hostgroups or automember configuration, and treat a failing case as a signal to investigate membership first. Store the expected access list and the test cases with the change record, so the evidence used to remove allow_all can be reproduced later.

How to build and run hbactest test cases

This sequence turns FreeIPA access rules into a tested, recorded set of expected outcomes, so you can change HBAC rules and retire allow_all with evidence rather than assumption. The output is a signed expected-access matrix, saved hbactest results and a clean run that justifies the change.

Confirm FreeIPA version and current HBAC rules
Record the FreeIPA server version on every server, not only the one you administer from, and confirm which options your version's ipa hbactest and ipa hbacrule commands accept by checking their help output. Then list every HBAC rule with its enabled state, user groups, host groups and service groups. Check that all replicas report the same version, because a mixed topology can give you different results depending on which server answers. Done when you have a dated inventory showing the version and the full rule list, and you have confirmed the hbactest options against that version.
Export and record the existing rule set
Export the current HBAC configuration to a file kept under change control, including the allow_all rule, every custom rule and the group memberships they reference. Store the export with the server version and the date, and record who took it. A restore or rollback depends on this copy, so keep it in a location the system owner can read. Check that the export opens, lists every rule shown in the inventory, and that the file hash or version label is written in the change record.
Write the expected-access matrix
Build a table with one row per combination you intend to allow or deny: user or user group, target host or host group, and service such as sshd, sudo or login. Add a column for the expected result and a reason that traces back to a business or control requirement. Include negative cases, such as contractors on production hosts and service accounts on interactive services, because allow-only tests miss accidental grants. Ask the system owner to review and sign off the matrix before any test runs. Done when the signed matrix is stored with the change record.
Run ipa hbactest for each matrix row
Run ipa hbactest once per row using the user, host and service values from the matrix, and capture the full output for each run, including the matched rules when the command reports them. Use the same syntax across all rows so results are comparable. Run the tests against the production topology only after you have confirmed the rule set on a non-production realm, if you have one. Done when every row has a saved output file named or indexed to its matrix row.
Compare results against expectations
Compare each actual result with the expected value in the matrix and mark every mismatch, including any row where the result is right for the wrong reason, such as a match through an unexpected group. Investigate mismatches before changing rules, since a wrong expectation is as likely as a wrong rule. Record the comparison in a results sheet with the row, expected value, actual value and disposition. Done when every row is marked pass, or has a documented explanation and owner for a fail.
Adjust rules and retest after every change
Make one change at a time, such as narrowing a rule's user group or adding a host group, and rerun the full matrix rather than only the affected rows. A change to one rule can alter matches for others, so partial retests can hide regressions. Log each change with the reason and the matrix rows it was meant to fix. Done when a full run after the last change shows no unexplained differences from the matrix and the change log links each edit to its test results.
Disable allow_all after a clean run
Disable the allow_all rule only after a complete matrix run with no unexplained failures, and only after the system owner has approved the result. Run the matrix once more immediately after disabling, because this is the change most likely to lock out legitimate access. Keep the final outputs, the signed matrix, the change log and the exported pre-change rule set together as the audit record for this test cycle. Confirm that the audit folder contains all four items before closing the change.

Security risks hidden in HBAC rule sets

HBAC rules fail quietly: a permissive default, an overlap nobody noticed or a group change made outside the review process can grant access that no one intended. The cards below name six risks that a test matrix for hbactest should be designed to catch, along with the control to apply to each. hbactest only evaluates the rules you give it, so it proves nothing about access paths you never model.

allow_all masking unintended access

The built-in allow_all rule grants every user access to every host and service. While it stays enabled, any test that expects a denial can pass or fail for reasons unrelated to your own rules, so the rule hides the access you meant to restrict. Before you disable it, run hbactest with allow_all still active and again without it, then confirm that each expected denial appears in the second run. Record both results so the reviewer can see the change in outcome.

Overlapping rules that are hard to reason about

When several HBAC rules match the same user, host and service, the effective outcome depends on the combined result of all of them, and a narrow rule can be widened by a broad one that someone added later. Reviewers rarely trace every overlap by hand. Export the rule set, list the rules that match each user group, and write one test case per overlap so that a new rule that grants more access fails a named test.

Group changes that alter outcomes silently

HBAC decisions depend on group membership, so adding a user to a group or letting an automember rule place a host into a group can change access without any rule being edited. A change of this kind is easy to miss in a rule review. Re-run the full test matrix after every membership change, and treat automember rules as part of the access policy, reviewing them with the same care as HBAC rules themselves.

Service names missing from the test matrix

A login path is only tested if its service name appears in the matrix, and a common gap is a service such as sshd being covered while sudo, su, console or a PAM service used by a third-party tool is omitted. The login path that goes untested is often the one an attacker or a misconfigured tool will use. Build the service list from the PAM configuration on each host class, and confirm it with the platform owner before you sign off the matrix.

Privileged accounts left outside the tests

Administrative accounts, break-glass users and service accounts often sit in separate groups and are excluded from user lists copied from ordinary directories. These accounts carry the highest impact if they are denied when they should be allowed, or allowed when they should be denied. Include named administrators, emergency accounts and service identities in the matrix as explicit test subjects, and record the owner of each one so that changes to their access have a named approver.

Test data that exposes real identities

Saved test cases that list real usernames, host names and internal service addresses become a map of your environment for anyone who can read the repository or the audit folder. Use a naming convention for test subjects, such as role-based placeholders, and keep the mapping from placeholder to real identity in a restricted store. Confirm with your security team where the test files are kept, who can read them and how long they are retained.

Where to run hbactest in a staged FreeIPA rollout

A lab or staging FreeIPA deployment is the place to build and iterate on HBAC rules before anything touches production. It can prove that a rule set is syntactically valid, that the intended user, host and service combinations produce the expected allow or deny results, and that your test cases run cleanly in a repeatable way. It cannot prove that production behaves the same way, because host inventory, group membership and automember results often differ between environments.

Representative copies, not live data: Load copies of representative users, groups, hosts and host groups, and document which ones are synthetic. Test data must not come from a stale restore. Restoring an outdated backup into an active replica topology can break replication, so build the lab from exports or scripted creation instead.
Known gaps: Record which production hosts, groups or services are missing from the lab. Any combination involving them is untested.
Version parity: Run the same FreeIPA release as production, or note the difference, since rule evaluation results should not be assumed identical across versions.
Repeatable test cases: Keep the ipa hbactest inputs in version control so the same cases run every time a rule changes.
Re-run trigger: Repeat the lab run after every rule edit, and before any group or host change is promoted.

Before leaving this tab, confirm the lab's gaps list is written down and that someone other than the rule author has reviewed the expected results.

Keeping hbactest cases as audit evidence

Keep each hbactest case as a versioned record that ties together four things: the expected-access matrix, the exact ipa hbactest command and its output, the version of the HBAC rule set being tested, and the approval that allowed the rules into production. Store these in the same repository as your rule definitions, so a reviewer can see what access was intended, what the rules actually returned, and who signed off on the difference. A matrix of users, hosts and services with an expected allow or deny in each cell is the core artifact. Record the FreeIPA server version alongside the rule set, because the same rule can evaluate differently after an upgrade. Confirm with your own change process whether your auditors expect the approval to be a ticket, a signed change record or a pull request review.

Re-run the same cases after every FreeIPA upgrade, after changes to group membership that feed HBAC rules, and after any change to host or service groups. Save each run as a new dated output and diff it against the previous baseline. Treat any case whose result changed as a finding: either the change was intended and the expected matrix must be updated with a new approval, or the change is a regression that needs fixing before the rule stays enforced. Upgrade release notes are the place to check for changes that touch access behavior, so read them against your matrix before scheduling the rerun. Keep the diff output with the change record so the history of decisions is preserved, not only the latest result.

DeployOpen prepares systems, controls and evidence for compliance assessments, including test cases, change records and the procedures that produce them. An independent auditor or certification body decides whether those controls meet a given requirement and issues any audit opinion, attestation or certification. Ask your auditor early which evidence format and retention period they accept, and agree the scope of the test matrix with them before the first baseline is recorded. Any change to the matrix after the baseline should be visible in its history, with a reason and an approver, so the evidence does not look edited after the fact.

What buyers ask about FreeIPA HBAC rule testing

How much effort does FreeIPA HBAC rule testing take?

The effort depends mostly on how many access paths you need to prove, not on the hbactest command itself. Each test case is a combination of user or group, host or host group, and service, and the expected result must be written down before the run. The main drivers are the number of hosts and host groups, the number of services and HBAC rules in place, how many rules have grown through years of additions, and how many expected access paths the business can confirm. A small directory with clean rules is quick to test. A large estate with overlapping allow rules, nested groups and no written access matrix takes longer, mostly because someone has to decide what the right answer is. Ask a provider to show how it will count test cases against your inventory before agreeing to a price.

Can our internal team test HBAC rules without outside help?

Yes, many teams can. The ipa hbactest command is part of the standard FreeIPA administration tools, and an engineer who knows the directory can run it against user, host and service combinations. The harder part is usually not the command but the expected results. Someone must own the access matrix, state which combinations should be allowed and denied, and review disagreements. Internal teams often struggle when they lack time for a change window, do not have a lab that mirrors production, or have no one who can explain why an old rule exists. An outside partner adds value mainly when those gaps exist, or when you want an independent reviewer of the test set before rules are enforced.

What does the client need to provide for this work?

Plan to provide four things. First, named owners for the access matrix who can say which users should reach which hosts and services, and who approve exceptions. Second, a current export of your FreeIPA HBAC rules, host groups, user groups and sudo rules, along with any documentation of past changes. Third, a lab or staging FreeIPA environment with hosts that resemble production, so that test runs do not depend on live logins. Fourth, change windows for enforcing the final rules, plus a rollback plan agreed with operations. Confirm with your own team which of these already exist, because missing owners or missing lab capacity are the most common reasons the work stalls.

How long does HBAC rule testing usually take?

Duration follows the same drivers as effort: the size of the directory, the number of rules to review, and how quickly the business confirms expected access. No supplied figure gives a standard duration, so treat any number a vendor offers as something to test against your own inventory. A useful way to plan is to split the work into inventory and reconciliation, writing the access matrix, running and recording test cases, reviewing failures with owners, and a staged enforcement window. The slowest phase is usually the business confirmation step, not the technical runs. Ask for a timeline tied to written milestones and to the number of owner review sessions it assumes.

Is HBAC rule testing a one-time task or ongoing work?

The first full test is a one-time project, but the test set should be kept and rerun. Every new host, service, user group or HBAC rule can change who gets access, so the saved test cases become a regression check. Running them after each change request, and before upgrades or host group reorganizations, catches accidental grants. The recurring cost is therefore small compared with the initial build, but it needs an owner and a habit. Ask whether the test suite will be delivered in a form your team can rerun, and whether the provider offers ongoing review as a retainer for the parts you do not want to keep in-house.

What should a fixed-scope quote for this work include?

A fixed-scope quote should state in writing what is in and out of scope before work starts. Ask for the number of hosts, host groups, user groups, services and HBAC rules covered, and for the list of test cases or the method used to generate them. Also ask which deliverables you receive: the access matrix, the test scripts or command records, a results report, a list of rules to change or remove, and the procedure for rerunning tests. Clarify who approves expected results, how many review rounds are included, whether lab setup is in scope, and what happens if the inventory is larger than assumed. Compare quotes on these items, not on a single headline figure.

Does DeployOpen issue a compliance certificate for HBAC testing?

No. DeployOpen prepares systems, controls and evidence for compliance assessments, and the test records, access matrix and results can serve as evidence for an auditor. Independent auditors and certification bodies issue audit reports, attestations and certifications, so the outcome of any assessment rests with them. Ask your auditor early which evidence they expect, such as the expected-result matrix, the test run records and the change approvals, so the testing work is designed to produce that evidence from the start.

What hbactest does not prove and what to confirm

hbactest answers one question: given the rules and the input you supply, which rule matches. The cards below list what that answer does not cover, so you can plan the checks that sit around it before you enforce anything.

Simulated input is not a real login

hbactest evaluates the user, host, service and rule set you pass to it. It does not authenticate anyone, does not read the PAM stack on the target host, and does not see the source address or time of a real session. Before you treat a passing test as proof, confirm that the service names your PAM configuration sends match the services in your test matrix, and run a supervised login on a pilot host for each important path.

Other policy layers need separate checks

A user who passes HBAC can still be stopped or granted more by sudo rules, SELinux user maps and host-side configuration. hbactest covers none of these. Plan separate tests for each layer, and confirm in your environment how an SELinux user map linked to an HBAC rule behaves for the same user and host pairs you tested.

Syntax and output vary by release

Command options, output format and default behavior of hbactest can change between FreeIPA versions. Scripts that parse its output can break after an upgrade. Check the command help and the documentation for the exact release running on your servers, and retest your saved cases after every upgrade before you rely on the results again.

Test matrix must match the inventory

A test matrix built from memory or an old host list proves nothing about current hosts. Compare the hosts and services in your cases against the live inventory, including hosts added by automation, retired servers still in groups, and hosts enrolled in other sites. Record the date of each comparison so auditors can see when the matrix was last aligned.

Application access is outside HBAC

HBAC decides whether a user can use a host and service through the operating system login path. It does not decide what a user can do inside an application, database or web portal once inside. Identify which applications on your hosts handle their own authorization, and confirm with their owners which permissions they grant independently of FreeIPA.

Confirm behavior in your own environment

Vendor documentation describes intended behavior, and your own hosts, PAM stack, client versions and rule history determine what actually happens. Before enforcing a rule set, confirm the supported behavior for your release in the FreeIPA documentation and reproduce the key outcomes on a representative host in your environment.

How DeployOpen scopes and delivers HBAC rule testing

DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including FreeIPA. For HBAC rule testing, we start from the access decisions your organization needs to prove, build the hbactest cases around them, and leave you with a test suite your own team can rerun before every rule change.

How we scope

The written scope lists the FreeIPA realm, the HBAC rules in question and the users, hosts and services each rule must cover.
Scope names the allow_all rules to be replaced and the order in which they will be retired once tests pass.
Engagements are fixed-scope, with deliverables and timelines agreed in writing before any test work starts.

How we build

We write hbactest cases for each user, host and service combination, including expected allow and deny results.
Replacement rules are drafted and checked against the test cases in a non-production FreeIPA environment you control.
Negative cases cover users outside the intended groups, hosts outside the rule's scope and services not named in it.

How we hand over

You receive the hbactest command set, the case inventory and the results from the agreed test runs.
Documentation explains how to rerun the suite after rule changes and how to record results for audit review.
Your team walks through the cases and the rule changes so that the suite can be maintained after the engagement ends.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer for teams that change access rules often.
A retainer can cover rerunning the suite after FreeIPA upgrades, since rule behavior should be confirmed against each release.
Confirm with DeployOpen whether a retainer covers new cases, rule reviews or only test execution before you sign.

Testing FreeIPA HBAC rules with hbactest