FreeIPA
Draft version. Content is hallucinated. Do not use!
policy

HBAC Rule Management

Manage host-based access control rules to restrict which users can access specific hosts and services. HBAC rules enforce fine-grained access policies based on user groups, host groups, and service groups. Features include rule categories (all users/hosts or specific groups), source hosts, service targeting, external host support, and testing capabilities to verify access decisions before deployment.

13 commands
policy
hbac access-control security

Overview

Host-Based Access Control (HBAC) in FreeIPA provides centralized, policy-driven enforcement of which users can access which services on which hosts. HBAC operates at the authentication boundary, determining whether authentication requests should succeed based on the user’s identity, the service being accessed, and the target host. This access control layer prevents unauthorized access even when users have valid credentials, enforcing security policies that transcend simple authentication.

HBAC rules define relationships between users (individuals or groups), hosts (specific systems or host groups), and services (SSH, login, specific applications). When a user attempts to access a service on a host, IPA clients evaluate applicable HBAC rules to determine whether the access should be permitted. Multiple rules can apply to a single access attempt; if any rule permits the access, authentication proceeds. If no rules permit access, authentication fails regardless of password correctness.

HBAC integration with SSSD on IPA clients eliminates per-host access control configuration files. Rather than maintaining /etc/security/access.conf or similar files on each system, administrators define centralized HBAC policies in IPA. These policies automatically distribute to clients through SSSD, adapting dynamically as organizational structure changes. When users join groups or hosts join host groups, their access rights automatically adjust according to HBAC rules targeting those groups.

Rule Components

Users and User Groups

The “who” dimension specifies which users are granted access by the rule. Individual users can be specified directly for user-specific access grants, or user groups enable access for collections of users organized by role, department, or function. User category “all” creates rules applying to every IPA user, useful for services that should be universally accessible like Kerberos authentication.

Group-based user specifications enable role-based access control patterns where access follows organizational structure. As users change roles and group memberships, their access automatically adjusts without modifying HBAC rules. This dynamic behavior reduces administrative overhead and ensures access controls remain current.

When multiple HBAC rules apply to a user, access is granted if ANY applicable rule permits it. There is no deny mechanism in HBAC; access control is purely positive (allow-based). If no rules permit access, access is denied by default.

Target Hosts and Host Groups

The “where” dimension defines which hosts the rule grants access to. Target hosts must be IPA-enrolled systems; HBAC cannot control access to non-IPA systems. Individual hosts can be specified for host-specific access controls, or host groups enable access to fleets of similar systems.

Host groups organize systems by function (webservers, databases), environment (production, staging), location (datacenter-east), or security classification (high-security, dmz). HBAC rules targeting host groups automatically apply to all group members, adapting as hosts join or leave groups.

Host category “all” permits access to every IPA-enrolled host, appropriate for universal services like user authentication or organization-wide access for administrators.

Services and Service Groups

The “what” dimension specifies which services users can access. Services represent authentication contexts like SSH (sshd), console login (login), web authentication, or custom applications. Each service is registered through hbacsvc-add, creating named service objects referenced by HBAC rules.

Service groups collect related services for easier policy management. For example, a “remote_access” service group might include sshd, rdp, and vnc, enabling a single HBAC rule to control all remote access protocols. Service groups are managed through hbacsvcgroup-* commands.

Service category “all” permits access to all services on target hosts. This broad grant is suitable for administrative access rules where trusted administrators need unrestricted service access.

Source Hosts (Deprecated)

Earlier IPA versions supported source host specifications, controlling which hosts users could access from. This feature has been largely deprecated as it proved difficult to enforce reliably and added complexity without proportionate security value. Modern HBAC focuses on user, target host, and service dimensions.

Rule Categories

Categories provide shorthand for “all” specifications, avoiding the need to explicitly list every user, host, or service. While convenient, category-based rules should be used judiciously as they create broad access grants that may not align with least privilege principles.

User Category (—usercat=all): Grants access to all IPA users. Useful for services that every user legitimately needs, such as Kerberos authentication or basic network services.

Host Category (—hostcat=all): Permits access to all IPA-enrolled hosts. Appropriate for universal services or administrator access rules.

Service Category (—servicecat=all): Allows access to all services on target hosts. Generally reserved for full administrative access rules.

Categories can be combined, creating rules like “all users can access sshd on all hosts” or “administrators can access all services on database servers.” While powerful, broad category usage reduces defense-in-depth and should be balanced against security requirements.

Default HBAC Rules

IPA ships with a default HBAC rule named “allow_all” permitting all users to access all services on all hosts. This permissive default facilitates initial deployment but should be disabled once specific HBAC rules are defined. Disabling “allow_all” without creating replacement rules will deny all access, so rule migration should be carefully planned and tested.

The migration strategy typically involves:

  1. Create specific HBAC rules matching organizational access requirements
  2. Test new rules using hbactest
  3. Disable “allow_all” after verifying specific rules provide necessary access
  4. Monitor authentication logs for denied access attempts indicating missing rules

Some deployments maintain “allow_all” in disabled state as a break-glass emergency access mechanism, enabling it temporarily if specific rules malfunction.

HBAC Evaluation Model

HBAC evaluation follows an allow-only model without explicit deny rules. Access is permitted if ANY applicable rule matches the access attempt (user, target host, service). If no rules match, access is denied by default.

Evaluation considers the intersection of rule components:

  • User must match rule’s user list (or rule has usercat=all)
  • Target host must match rule’s host list (or rule has hostcat=all)
  • Service must match rule’s service list (or rule has servicecat=all)

If all components match, the rule permits access. SSSD evaluates all enabled rules; finding one matching rule is sufficient for access grant.

This positive-only model simplifies policy reasoning but requires careful attention to avoid overly broad rules. There’s no way to explicitly block specific access - denial occurs only through absence of permitting rules.

External Host Support

HBAC rules can specify external hosts for limited external access scenarios. External hosts are non-IPA systems referenced by hostname or IP address. This feature supports hybrid environments where IPA users need access to systems not enrolled in IPA.

External host support is limited as HBAC enforcement occurs on IPA clients. External systems don’t evaluate HBAC rules unless they’re configured with appropriate PAM modules querying IPA for authorization decisions. Most commonly, external hosts appear in source host specifications (deprecated feature) or in specialized integration scenarios.

Examples

Basic Rule Management

Create a new HBAC rule:

ipa hbacrule-add allow_ssh --desc="Allow SSH access to servers"

Create a rule with categories (all users, specific hosts):

ipa hbacrule-add admin_access --usercat=all --desc="Admin access to management servers"

Delete an HBAC rule:

ipa hbacrule-del allow_ssh

Display rule details:

ipa hbacrule-show allow_ssh --all

Search for rules:

ipa hbacrule-find ssh

Find all enabled rules:

ipa hbacrule-find --enabled=TRUE

Find rules affecting a specific user:

ipa hbacrule-find --users=jsmith

Find rules for specific hosts:

ipa hbacrule-find --hosts=web01.example.com

User Assignment

Add individual users to a rule:

ipa hbacrule-add-user allow_ssh --users=jsmith

Add user groups:

ipa hbacrule-add-user allow_ssh --groups=sysadmins

Add both users and groups:

ipa hbacrule-add-user allow_ssh --users=jsmith --groups=operators

Remove users from a rule:

ipa hbacrule-remove-user allow_ssh --users=jsmith

Host Assignment

Add individual hosts:

ipa hbacrule-add-host allow_ssh --hosts=web01.example.com

Add host groups:

ipa hbacrule-add-host allow_ssh --hostgroups=webservers

Add multiple hosts and hostgroups:

ipa hbacrule-add-host allow_ssh --hosts=web01.example.com --hostgroups=databases

Remove hosts from a rule:

ipa hbacrule-remove-host allow_ssh --hosts=web01.example.com

Service Assignment

First create HBAC services:

ipa hbacsvc-add sshd
ipa hbacsvc-add login
ipa hbacsvc-add gdm

Add services to a rule:

ipa hbacrule-add-service allow_ssh --hbacsvcs=sshd

Create and use service groups:

ipa hbacsvcgroup-add remote_access
ipa hbacsvcgroup-add-member remote_access --hbacsvcs=sshd --hbacsvcs=login
ipa hbacrule-add-service allow_remote --hbacsvcgroups=remote_access

Add multiple services:

ipa hbacrule-add-service console_access --hbacsvcs=login --hbacsvcs=gdm

Remove services from a rule:

ipa hbacrule-remove-service allow_ssh --hbacsvcs=sshd

Rule State Management

Disable a rule temporarily:

ipa hbacrule-disable allow_ssh

Re-enable a disabled rule:

ipa hbacrule-enable allow_ssh

Complete Rule Examples

SSH access for sysadmins to web servers:

ipa hbacrule-add ssh_webservers --desc="Sysadmin SSH to web servers"
ipa hbacrule-add-user ssh_webservers --groups=sysadmins
ipa hbacrule-add-host ssh_webservers --hostgroups=webservers
ipa hbacrule-add-service ssh_webservers --hbacsvcs=sshd

Console login for specific user on specific host:

ipa hbacrule-add admin_console --desc="Admin console access to management server"
ipa hbacrule-add-user admin_console --users=admin
ipa hbacrule-add-host admin_console --hosts=mgmt.example.com
ipa hbacrule-add-service admin_console --hbacsvcs=login

Universal SSH access (all users, all hosts):

ipa hbacrule-add ssh_universal --usercat=all --hostcat=all --desc="Universal SSH access"
ipa hbacrule-add-service ssh_universal --hbacsvcs=sshd

Database access for DBAs:

ipa hbacrule-add dba_access --desc="DBA access to database servers"
ipa hbacrule-add-user dba_access --groups=dbas
ipa hbacrule-add-host dba_access --hostgroups=databases
ipa hbacrule-add-service dba_access --servicecat=all

Developer access to development environment:

ipa hbacsvcgroup-add dev_services
ipa hbacsvcgroup-add-member dev_services --hbacsvcs=sshd --hbacsvcs=login
ipa hbacrule-add dev_access --desc="Developer access to dev environment"
ipa hbacrule-add-user dev_access --groups=developers
ipa hbacrule-add-host dev_access --hostgroups=dev_servers
ipa hbacrule-add-service dev_access --hbacsvcgroups=dev_services

Break-glass admin access (normally disabled):

ipa hbacrule-add emergency_admin --desc="Emergency full access (normally disabled)"
ipa hbacrule-add-user emergency_admin --users=emergency_account
ipa hbacrule-add-host emergency_admin --hostcat=all
ipa hbacrule-add-service emergency_admin --servicecat=all
ipa hbacrule-disable emergency_admin

Working with Default allow_all Rule

Disable the permissive default (after creating specific rules):

ipa hbacrule-disable allow_all

Re-enable temporarily for troubleshooting:

ipa hbacrule-enable allow_all

Rule Modification

Change rule description:

ipa hbacrule-mod allow_ssh --desc="Updated description"

Convert from specific users to all users:

ipa hbacrule-mod allow_ssh --usercat=all

Best Practices

Rule Design

Follow least privilege: Grant minimal access necessary for each role. Specific rules are more secure than broad category-based rules.

Use groups instead of individuals: Target user groups and host groups rather than individual users/hosts. This enables access that automatically adapts to organizational changes.

Create role-based rules: Design rules around organizational roles (developers, DBAs, help desk) rather than individuals or one-off access needs.

Separate concerns: Create multiple focused rules rather than complex multi-purpose rules. This improves clarity and maintainability.

Document rule purposes: Use --desc to clearly explain why each rule exists and what access pattern it supports.

Category Usage

Avoid excessive category use: --usercat=all, --hostcat=all, and --servicecat=all create broad access grants. Use categories only when genuinely appropriate.

Prefer specific grants over categories: “sysadmins can SSH to webservers” is more secure than “all users can access all services on webservers.”

Document category decisions: When categories are necessary, document why broad access is required for the specific use case.

Service Management

Register all services: Use hbacsvc-add to create service objects for all authentication contexts. Don’t rely on servicecat=all.

Group related services: Use service groups to manage collections of related services (all remote access protocols, all console access methods).

Standardize service names: Use consistent service naming across your environment. The service name must match what PAM/SSSD expect.

Test service configurations: Verify services are properly registered and HBAC evaluation works correctly before deploying to production.

Migration from allow_all

Plan the migration: Don’t disable allow_all without replacement rules. Create and test specific rules first.

Test thoroughly: Use hbactest (separate tool) to verify new rules provide necessary access before disabling allow_all.

Migrate incrementally: Consider creating rules for each department/function, testing each, before final allow_all disable.

Monitor logs: After disabling allow_all, closely monitor authentication logs for denied access attempts indicating missing rules.

Have a rollback plan: Know how to quickly re-enable allow_all if migration causes unexpected access denials.

Security Considerations

Regular rule audits: Periodically review HBAC rules to ensure they still match organizational structure and security requirements.

Remove obsolete rules: When organizational changes make rules unnecessary, delete or disable them rather than leaving stale policy.

Monitor authentication failures: Track HBAC-related authentication denials. Patterns may indicate attacks or policy gaps.

Coordinate with sudo: HBAC controls initial access; sudo controls privilege escalation. Both must permit operations for sudo to function.

Test before production: Always test new rules in non-production before deploying to production systems.

Operational Practices

Version control rule changes: Document HBAC rule changes, rationale, and approval in version control or ticketing systems.

Plan for SSSD caching: HBAC rule changes may take time to reach clients due to SSSD caching. For urgent changes, clear SSSD cache manually.

Use descriptive names: Rule names should clearly indicate purpose (ssh_webservers, dba_access, dev_environment).

Maintain rule inventory: Track all HBAC rules, their purposes, and owners. This aids troubleshooting and policy review.

Coordinate with groups: HBAC effectiveness depends on correct group membership. Ensure user and host groups are properly maintained.

External Host Considerations

Minimize external host use: HBAC works best with IPA-enrolled hosts. External hosts may not properly enforce HBAC policies.

Document external integrations: Clearly document how external hosts integrate with IPA and what HBAC enforcement they provide.

Test external host HBAC: If using HBAC with external hosts, thoroughly test to verify policies are actually enforced.

High Availability

Expect SSSD caching: SSSD caches HBAC rules locally. Clients can enforce HBAC even when IPA servers are unreachable.

Plan for cache expiration: Understand SSSD cache lifetimes. Outdated cached rules may permit or deny access based on old policy.

Test offline scenarios: Verify HBAC behavior when IPA servers are unavailable matches expectations.

Integration with Other IPA Components

HBAC Services and Service Groups

HBAC services (hbacsvc-*) define authentication contexts that rules can reference. Service groups (hbacsvcgroup-*) collect related services for easier policy management.

User and Group Management

HBAC rules reference user groups created through group-* commands. User group membership changes immediately affect HBAC access decisions (subject to SSSD cache).

Host and Host Group Management

HBAC rules reference host groups created through hostgroup-* commands. Host group membership changes immediately affect which HBAC rules apply on systems (subject to SSSD cache).

Sudo Rules

Sudo rules (sudorule-*) depend on HBAC permitting initial access. HBAC controls whether users can authenticate; sudo controls what they can do after authentication.

SSSD Integration

SSSD on IPA clients retrieves HBAC rules and enforces them during authentication. SSSD caching enables offline HBAC enforcement and improves performance.

Automember Rules

Automember rules can automatically populate user and host group membership based on attributes. This automation helps maintain correct group membership for HBAC evaluation.

External Users and Trusts

HBAC can control access for external users from trusted Active Directory domains. Trust configuration must be functional for external user HBAC to work.

Commands

Command Description

hbacrule-add Create a new HBAC rule.

hbacrule-add-host Add target hosts and hostgroups to an HBAC rule.

hbacrule-add-service Add services to an HBAC rule.

hbacrule-add-user Add users and groups to an HBAC rule.

hbacrule-del Delete an HBAC rule.

hbacrule-disable Disable an HBAC rule.

hbacrule-enable Enable an HBAC rule.

hbacrule-find Search for HBAC rules.

hbacrule-mod Modify an HBAC rule.

hbacrule-remove-host Remove target hosts and hostgroups from an HBAC rule.

hbacrule-remove-service Remove service and service groups from an HBAC rule.

hbacrule-remove-user Remove users and groups from an HBAC rule.

hbacrule-show Display the properties of an HBAC rule.

hbacrule-add

Usage: ipa [global-options] hbacrule-add NAME [options]

Create a new HBAC rule.

Arguments

Argument Required Description

NAME yes Rule name

Options

Option Description

--usercat USERCAT User category the rule applies to

--hostcat HOSTCAT Host category the rule applies to

--servicecat SERVICECAT Service category the rule applies to

--desc DESC Description

--setattr SETATTR Set an attribute to a name/value pair. Format is attr=value.

--addattr ADDATTR Add an attribute/value pair. Format is attr=value. The attribute

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

hbacrule-add-host

Usage: ipa [global-options] hbacrule-add-host NAME [options]

Add target hosts and hostgroups to an HBAC rule.

Arguments

Argument Required Description

NAME yes Rule name

Options

Option Description

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--hosts HOSTS hosts to add

--hostgroups HOSTGROUPS host groups to add

hbacrule-add-service

Usage: ipa [global-options] hbacrule-add-service NAME [options]

Add services to an HBAC rule.

Arguments

Argument Required Description

NAME yes Rule name

Options

Option Description

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--hbacsvcs HBACSVCS HBAC services to add

--hbacsvcgroups HBACSVCGROUPS HBAC service groups to add

hbacrule-add-user

Usage: ipa [global-options] hbacrule-add-user NAME [options]

Add users and groups to an HBAC rule.

Arguments

Argument Required Description

NAME yes Rule name

Options

Option Description

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--users USERS users to add

--groups GROUPS groups to add

hbacrule-del

Usage: ipa [global-options] hbacrule-del NAME [options]

Delete an HBAC rule.

Arguments

Argument Required Description

NAME yes Rule name

Options

Option Description

--continue Continuous mode: Don’t stop on errors.

hbacrule-disable

Usage: ipa [global-options] hbacrule-disable NAME [options]

Disable an HBAC rule.

Arguments

Argument Required Description

NAME yes Rule name

hbacrule-enable

Usage: ipa [global-options] hbacrule-enable NAME [options]

Enable an HBAC rule.

Arguments

Argument Required Description

NAME yes Rule name

hbacrule-find

Usage: ipa [global-options] hbacrule-find [CRITERIA] [options]

Search for HBAC rules.

Arguments

Argument Required Description

CRITERIA no A string searched in all relevant object attributes

Options

Option Description

--name NAME Rule name

--usercat USERCAT User category the rule applies to

--hostcat HOSTCAT Host category the rule applies to

--servicecat SERVICECAT Service category the rule applies to

--desc DESC Description

--timelimit TIMELIMIT Time limit of search in seconds (0 is unlimited)

--sizelimit SIZELIMIT Maximum number of entries returned (0 is unlimited)

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--pkey-only Results should contain primary key attribute only (“name”)

hbacrule-mod

Usage: ipa [global-options] hbacrule-mod NAME [options]

Modify an HBAC rule.

Arguments

Argument Required Description

NAME yes Rule name

Options

Option Description

--usercat USERCAT User category the rule applies to

--hostcat HOSTCAT Host category the rule applies to

--servicecat SERVICECAT Service category the rule applies to

--desc DESC Description

--setattr SETATTR Set an attribute to a name/value pair. Format is attr=value.

--addattr ADDATTR Add an attribute/value pair. Format is attr=value. The attribute

--delattr DELATTR Delete an attribute/value pair. The option will be evaluated

--rights Display the access rights of this entry (requires —all). See ipa man page for details.

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--rename RENAME Rename the HBAC rule object

hbacrule-remove-host

Usage: ipa [global-options] hbacrule-remove-host NAME [options]

Remove target hosts and hostgroups from an HBAC rule.

Arguments

Argument Required Description

NAME yes Rule name

Options

Option Description

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--hosts HOSTS hosts to remove

--hostgroups HOSTGROUPS host groups to remove

hbacrule-remove-service

Usage: ipa [global-options] hbacrule-remove-service NAME [options]

Remove service and service groups from an HBAC rule.

Arguments

Argument Required Description

NAME yes Rule name

Options

Option Description

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--hbacsvcs HBACSVCS HBAC services to remove

--hbacsvcgroups HBACSVCGROUPS HBAC service groups to remove

hbacrule-remove-user

Usage: ipa [global-options] hbacrule-remove-user NAME [options]

Remove users and groups from an HBAC rule.

Arguments

Argument Required Description

NAME yes Rule name

Options

Option Description

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--users USERS users to remove

--groups GROUPS groups to remove

hbacrule-show

Usage: ipa [global-options] hbacrule-show NAME [options]

Display the properties of an HBAC rule.

Arguments

Argument Required Description

NAME yes Rule name

Options

Option Description

--rights Display the access rights of this entry (requires —all). See ipa man page for details.

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

Related Topics

hbacsvc hbacsvcgroup sudorule