Product SiteDocumentation Site

14.4. Testing Host-Based Access Control Rules

Implementing host-based access controls effectively can be tricky because it requires that all of the hosts be properly configured and the access is properly applied to users and services.
The hbactest command can test different host-based access control scenarios to make sure that the rules are working as expected.

14.4.1. The Limits of Host-Based Access Control Configuration

When a request is made to one of the domain services, the identifier of the source host is sent to a PAM interface for the login application (like OpenSSH, telnet, or rlogin) which is used to access SSSD on the target host machine. This identifier can be the hostname, the IP address, or even the alias of the source host.
This is essentially a long chain, from the source host to the target host to the service. The access control mechanism uses the identifier that is sent to the SSSD service on the target machine to verify that the source host has proper authorization granted in an access control rule.
However, if the identifier sent to SSSD cannot be traced back to the source host, then authorization fails. This can happen if any part of the host information does not match the access control rule configuration:
  • The source host uses an alias which is not listed in the rule.
  • The domain service on the target host sends an IP address instead of the hostname.
  • DNS is misconfigured and does not return the proper information for the DNS lookup or reverse lookup.
  • The client sends a malformed string to SSSD.
The name that is sent by the client must match the name in the rule, otherwise host-based access control fails.
The access control configuration should always be tested before it is implemented to prevent authorization failures.
Host-based access control rules depend on a lot of interactions — between hosts, services, DNS lookups, and users. If any element is misconfigured, then the rule can behave in unexpected ways.
FreeIPA includes a testing tool to verify that access control rules are behaving in the expected way by testing the access in a defined scenario. There are several situations where this testing is useful:
  • A new rule needs to be tested before it is implemented.
  • There are problems with the existing rules, and the testing tool can identify what rule is behaving badly.
  • A subset of existing rules can be tested to see how they are performing.

14.4.2. Test Scenarios for Host-Based Access Control (CLI-Based)

The hbactest command tests configured host-based access control rules in very specific situations. A test run defines:
  • The user to run the operation as to test the rule performance for that user (--user).
  • From the source host X (--srchost).
  • Using the login client Y (--service).
  • To target host Z (--host).
  • The rule to test (--rules); if this is not used, then all enabled rules are tested.
  • Optional The hbactest returns detailed information about which rules were matched, not matched, or invalid. This detailed rule output can be disabled using --nodetail, so the test simply runs and returns whether access was granted.


The hbactest script does not actually connect to the target host. Instead, it uses the rules within the FreeIPA database to simulate how those rules would be applied in a specific situation as if an SSSD client were connecting to the FreeIPA server.
More briefly, it performs a simulated test run based on the given information and configuration, but it does not actually attempt a service request against the target host.
Example 14.4. Testing All Active Rules
The most basic command checks all active rules. It requires a specific connection scenario, so the user, login service, source host, and target host have to be given, and the testing tool checks the connection.
$ ipa  hbactest --user=jsmith --service=ssh
Access granted: True
  notmatched: my-second-rule
  notmatched: my-third-rule
  matched: myrule
  matched: allow_all

Example 14.5. Testing a Specific Rule
It is possible to check a specific rule (or several rules).
$ ipa hbactest --user=jsmith --service=ssh --rules=myrule
Access granted: True
   notmatched: myrule

Example 14.6. Testing Specific Rules Plus All Enabled
The --rules option lists specific rules to test, but it may be useful to test the specified rules against all of the enabled rules in the domain. This can be done by adding the --enabled option, which includes the (unspecified) enabled rules along with the specified rules.
$ ipa hbactest --user=jsmith --service=ssh --rules=myrule --enabled
Access granted: True
  matched: my-second-rule
  notmatched: my-third-rule
  matched: myrule
  matched: allow_all
It is possible to run a similar comparison against disabled rules by using the --disable option. With the --rules option, the specified rule plus all of the disabled rules are checked. With the --disabled option, all disabled rules are checked.

14.4.3. Testing Host-Based Access Control Rules in the UI

As Section 14.4.1, “The Limits of Host-Based Access Control Configuration” details, misconfiguring a host-based access-control rule can result in unpredictable behavior when users or services attempt to connect to a remote host.
Testing host-based access control can help confirm that the rule performs as expected before it is deployed or to troubleshoot a rule once it is already active.
By the nature of host-based access control rules, a test must define and verify a very specific set of criteria, A test run defines:
  • The user to run the operation as to test the rule performance for that user (Who).
  • To target host Z (Accessing).
  • Using the login client Y (Via Service).
  • From the source host X (From); this can be an FreeIPA client or an external host.
  • The rule to test; if this is not used, then all enabled rules are tested (Rules).
The test environment is defined on the HBAC TEST page in the Host Based Access Control tab under Policy. A series of tabs is set up for each configuration step.
The From Tab to Set up an HBAC Test
Figure 14.2. The From Tab to Set up an HBAC Test

Once the environment is defined, then the test is run simply by clicking a button on the Run Test page. The results show clearly whether access was granted or denied to the users, and then runs through the rules which matched the given parameters.
HBAC Test Results
Figure 14.3. HBAC Test Results


To change some of the parameters and check for other results, click the New Test button at the bottom of the test results page. If that button is not selected, the form is not reset, so a new test will not run, even if test settings are changed.