The pg_hba.conf file is PostgreSQL’s client authentication control point. It defines which users, hosts, and connection types can access the database and which authentication method applies. Rules are evaluated from top to bottom, so ordering matters as much as the methods themselves when teams are hardening access.
Expanded Definition
pg_hba.conf is PostgreSQL’s connection admission policy, not just a login file. It determines whether a client is allowed to connect, which authentication method applies, and how PostgreSQL interprets the source host, database, and user combination.
The practical boundary is that pg_hba.conf governs access control decisions at the database edge, while role design, password policy, and network segmentation govern adjacent layers. A common misunderstanding is to treat it as a simple list of users; in reality, the first matching rule wins, so rule order can override an otherwise stronger method later in the file. That makes the file both a security control and a policy engine. For readers comparing security guidance, PostgreSQL’s own client authentication documentation is the most direct reference for syntax and matching behavior.
Examples and Use Cases
In practice, pg_hba.conf shows up wherever teams need to separate trusted application paths from broader database access. It is commonly used to enforce different rules for local administration, application service accounts, replication, and remote operator access.
- A production database allows password-based access only from an application subnet, while localhost connections use a more trusted local method for admin workflows.
- A staging environment permits broad developer access, but production restricts the same usernames to a bastion host or a small set of source IP ranges.
- Replication traffic is given its own rule so standby nodes authenticate differently from interactive clients, reducing accidental overlap in privileges.
- A team tightens access during migration work by inserting temporary rules near the top of the file, then removing them after cutover. The tradeoff is operational convenience versus the risk of stale exceptions.
Because rule order is decisive, teams often validate changes in a lower environment first to avoid accidentally shadowing a restrictive rule with a broader one above it.
Security Implications
Misconfiguring pg_hba.conf can produce immediate exposure or silent lockouts. If a permissive rule appears too early, unintended networks or users may gain access; if a necessary rule is missing, legitimate services may fail during startup or failover. The file is therefore part of both availability and containment.
One of the most common failure modes is assuming that strong authentication methods compensate for weak rule placement. They do not. A broad host rule can still permit connections from places that should never reach the database, and that widens the blast radius if a workstation, application host, or VPN path is compromised. NHIMG research shows that 80% of identity breaches involved compromised non-human identities such as service accounts and API keys, which is a reminder that database access paths often depend on machine-driven credentials and tightly scoped connection rules.
Practitioners should watch for unexplained authentication successes from unexpected source ranges, too-broad catch-all rules, and emergency edits that are never reversed. Those symptoms usually indicate the policy has drifted away from the intended trust boundary.
Domain and Governance Relevance
In NHI governance, pg_hba.conf matters because many PostgreSQL clients are not people at all. Application runtimes, jobs, integration services, and replication nodes frequently authenticate as service identities, so this file becomes part of the control surface for machine access rather than just human admin access.
That changes the governance question from "who can log in?" to "which workload, from which network path, using which method, is allowed to reach the database?" A weak or stale pg_hba.conf policy can leave service accounts overexposed even when passwords or secrets are otherwise managed well. It also affects offboarding and change control: if a workload is retired, its network and authentication rules should disappear with it, or the database may continue trusting a dead path.
For teams managing non-human identities, pg_hba.conf is one of the places where identity inventory, source restriction, and authentication method choice meet operational reality.
Risk and Threat Considerations
pg_hba.conf creates material risk when its rules over-admit clients or fail to reflect current network and workload boundaries. The danger is not abstract: a single permissive entry can turn database reachability into a broad trust path for compromised hosts, stale service accounts, or misrouted automation.
Failure mechanism: PostgreSQL evaluates rules top to bottom, so a broad early match can override a later restrictive rule. Attackers or unauthorized insiders benefit when source restrictions are weak, because they can pivot from an allowed subnet, a compromised application host, or a trusted VPN path into the database and then reuse valid credentials or brute-force weak ones within the permitted pattern.
Impact: The result can be unauthorized query access, privilege escalation through overbroad service roles, disruption during failover or deployment, and hidden persistence if obsolete rules remain after a system or workload is decommissioned.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP Non-Human Identity Top 10 address the attack and risk surface, while CIS Controls v8 and NIST CSF 2.0 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| CIS Controls v8 | CIS 6 — Access Control Management | pg_hba.conf restricts which users and hosts may reach PostgreSQL. |
| CIS 4 — Secure Configuration of Enterprise Assets and Software | The file is a security-relevant configuration that can weaken or harden access. | |
| Recommendation — Limit database access paths to approved hosts and accounts, and remove broad allow rules. Baseline and review pg_hba.conf changes so restrictive rules are not shadowed by permissive entries. | ||
| OWASP Non-Human Identity Top 10 | NHI-02 — Secrets and Credential Management | Database clients often authenticate with service credentials governed through this file. |
| Recommendation — Constrain machine identities to the minimum database access their credentials require. | ||
| NIST CSF 2.0 | PR.AA — Identity Management, Authentication and Access Control | pg_hba.conf implements authentication and access control decisions for database sessions. |
| Recommendation — Map PostgreSQL admission rules to access-control policy and verify they match intended trust boundaries. | ||
Related resources from NHI Mgmt Group
Deepen Your Knowledge
Reviewed and updated by the NHIMG editorial team on September 8, 2026.
NHI Mgmt Group — the #1 independent authority on Non-Human Identity, IAM, and Agentic AI security. nhimg.org
