PostgreSQL pg_hba.conf 인증 기준 정리

PostgreSQL pg_hba.conf 인증 기준 정리

pg_hba.conf는 PostgreSQL 서버에 들어오는 연결이 어떤 사용자, 어떤 데이터베이스, 어떤 주소 대역에서 어떤 인증 방식으로 접속할 수 있는지 결정하는 핵심 설정 파일이다. 2026년 5월 26일 기준 PostgreSQL 공식 문서를 보면 이 파일은 연결 시도마다 위에서 아래로 순서대로 평가되며, 처음 일치한 규칙 하나만 적용된다.

실무에서는 접속이 안 되는 원인 분석, 로컬 개발 환경과 운영 환경 분리, md5에서 scram-sha-256로의 전환 판단이 자주 이 파일과 연결된다. 이 글은 공식 문서 기준으로 pg_hba.conf의 동작 방식, 안전한 기본값, 자주 헷갈리는 포인트를 객관적으로 정리한다.

pg_hba.conf는 무엇을 제어할까?

PostgreSQL 공식 문서에서 pg_hba.conf는 클라이언트 인증을 제어하는 파일로 설명된다. 기본 파일은 initdb로 데이터 디렉터리를 만들 때 함께 생성되며, 위치는 hba_file 설정으로 확인하거나 바꿀 수 있다.

이 파일의 한 줄은 대체로 다음 다섯 가지를 정한다.

• 연결 유형: local, host, hostssl, hostnossl 같은 타입
• 대상 데이터베이스
• 대상 사용자 또는 역할
• 허용할 클라이언트 주소 범위
• 적용할 인증 방식: scram-sha-256, peer, reject 등

왜 순서가 중요할까?

공식 문서는 pg_hba.conf가 연결 시도마다 순차적으로 검사되고, 처음 일치한 레코드가 인증에 사용된다고 설명한다. 뒤에 더 구체적이거나 더 강한 규칙이 있어도 앞의 규칙이 먼저 맞아 버리면 뒤 규칙은 보지 않는다.

그래서 실무 기준으로는 더 좁은 범위, 더 예외적인 규칙을 위에 두고, 넓은 범위 규칙을 아래에 두는 편이 안전하다. 특정 IP 하나를 막는 reject 규칙을 네트워크 전체 허용 규칙보다 앞에 두는 패턴이 대표적이다.

어떤 인증 방식을 우선적으로 보면 될까?

방식	적합한 상황	주의점
scram-sha-256	일반적인 비밀번호 기반 운영 환경	구형 클라이언트는 지원하지 않을 수 있다.
peer	로컬 유닉스 소켓 기반 접속	운영체제 사용자명과 DB 사용자명 매핑을 이해해야 한다.
reject	특정 호스트 또는 대역 차단	순서가 뒤로 밀리면 차단되지 않을 수 있다.
md5	구형 클라이언트 호환이 필요한 전환 구간	MD5 저장 비밀번호 지원은 deprecated 상태다.
trust	엄격히 통제된 로컬 테스트 환경	접속만 가능하면 어떤 DB 사용자로든 로그인할 수 있다.

현재 공식 문서는 scram-sha-256를 가장 안전한 비밀번호 기반 방식으로 설명한다. 반면 md5는 여전히 호환 목적으로 문서에 남아 있지만, MD5로 저장된 비밀번호 지원은 deprecated이며 향후 릴리스에서 제거될 예정이라고 안내한다.

안전한 기본값은 어떻게 잡는 편이 나을까?

대부분의 운영 환경에서는 다음 기준이 무난하다.

• 로컬 소켓 접속은 필요 범위 안에서 peer 또는 scram-sha-256를 사용한다.
• 원격 접속은 필요한 네트워크 대역만 CIDR로 좁혀서 허용한다.
• 비밀번호 기반 인증은 가능하면 scram-sha-256를 사용한다.
• 0.0.0.0/0, ::0/0 같은 전체 허용 대역은 특별한 이유가 없으면 피한다.
• 예외 차단 규칙이 필요하면 넓은 허용 규칙보다 위에 둔다.

공식 예시에서도 단일 호스트는 /32, IPv6 단일 호스트는 /128처럼 좁은 범위로 표현한다. 허용 대역을 구체적으로 적는 습관이 가장 기본적인 안전장치다.

예시는 어떻게 읽으면 될까?

local   all             all                                     peer
host    appdb           app_user        10.20.30.40/32          scram-sha-256
host    all             all             10.20.30.0/24           scram-sha-256
host    all             all             10.20.30.99/32          reject

이 예시에서 첫 줄은 로컬 유닉스 소켓 접속을 운영체제 사용자 기준으로 인증한다. 둘째 줄은 특정 애플리케이션 사용자와 단일 호스트를 아주 좁게 허용한다. 셋째 줄은 더 넓은 대역을 허용하지만, 넷째 줄처럼 특정 주소를 막으려면 그 reject 규칙을 더 위로 올려야 실제로 차단된다.

즉 사람 눈에 보기 쉬운 정렬보다, PostgreSQL이 실제로 어떤 줄을 먼저 만나는지가 더 중요하다.

설정 변경 후 바로 반영될까?

공식 문서 기준으로 pg_hba.conf는 서버 시작 시 읽히고, 실행 중에는 메인 서버 프로세스가 SIGHUP를 받으면 다시 읽는다. 문서는 pg_ctl reload, SQL 함수 pg_reload_conf(), 또는 kill -HUP를 예로 든다.

예외도 있다. Windows에서는 이후 새 연결부터 변경 사항이 즉시 적용된다고 공식 문서에 별도 주석이 있다.

호스트명과 CIDR 중 무엇이 나을까?

공식 문서는 주소 필드에 CIDR, 키워드, 호스트명을 모두 허용한다. 다만 호스트명은 역방향 조회와 정방향 조회를 모두 사용해 일치 여부를 판단하므로, 이름 해석이 느리거나 불안정하면 연결 지연과 운영 난이도를 만들 수 있다.

운영 환경에서 허용 대역이 명확하다면 보통 CIDR이 더 예측 가능하다. 호스트명 기반 제어가 필요하다면 DNS 응답 속도와 정확성이 전제돼야 한다.

자주 헷갈리는 포인트는 무엇일까?

1. md5로 적어도 실제 인증은 SCRAM일 수 있을까?

그럴 수 있다. 현재 공식 문서는 pg_hba.conf에 md5를 적었더라도 서버에 저장된 사용자 비밀번호가 SCRAM 형식이면 SCRAM 기반 인증이 자동으로 선택될 수 있다고 설명한다. 다만 이것은 전환 편의 기능이지, 장기적으로 md5를 계속 유지하라는 의미는 아니다.

2. 연결 허용과 DB 권한은 같은 문제일까?

아니다. 공식 문서는 사용자가 pg_hba.conf를 통과해도 데이터베이스의 CONNECT 권한이 별도로 필요하다고 설명한다. 데이터베이스별 접속 가능 여부를 모두 pg_hba.conf에만 몰아넣기보다, 권한 관리와 나눠서 생각하는 편이 단순할 수 있다.

3. 문법 오류는 어떻게 점검할까?

현재 공식 문서는 시스템 뷰 pg_hba_file_rules가 파일 변경 사전 점검이나 문제 진단에 도움이 된다고 설명한다. 이 뷰에서 error 필드가 비어 있지 않은 행은 해당 규칙에 문제가 있다는 뜻이다.

FAQ

Q. 운영 서버에서 trust를 써도 될까?

공식 문서 설명대로 trust는 접속 가능한 누구나 원하는 PostgreSQL 사용자명으로 로그인하게 허용한다. 그래서 일반적인 운영 서버의 원격 접속 규칙에는 적합하지 않다.

Q. 로컬 접속은 무조건 peer가 정답일까?

항상 그렇지는 않다. 같은 머신 안에서 운영체제 사용자와 DB 사용자 매핑이 명확하면 peer가 간단하지만, 애플리케이션 계정 구조나 배포 방식에 따라 로컬도 scram-sha-256를 쓰는 구성이 더 관리하기 쉬울 수 있다.

Q. 원격 접속 한 줄만 넓게 열고 권한으로 막으면 충분할까?

권한 관리가 중요하긴 하지만, 네트워크 허용 범위를 좁히는 것은 별도의 방어층이다. 공식 예시와 설명을 기준으로 보면, 필요한 주소 대역만 허용하는 쪽이 더 보수적인 기본값이다.

정리

pg_hba.conf에서 가장 중요한 기준은 규칙의 순서, 허용 주소 범위의 폭, 그리고 인증 방식의 선택이다. 현재 공식 문서 기준으로 비밀번호 기반 운영 환경의 기본값은 대체로 scram-sha-256 쪽에 가깝고, md5는 호환성 전환 구간으로 보는 편이 맞다.

접속 장애나 보안 설정 점검을 할 때는 규칙이 위에서 아래로 어떻게 매치되는지, 너무 넓은 주소 대역을 열어 두지 않았는지, 그리고 변경 후 재적용이 필요한 환경인지부터 확인하면 된다.

참고 자료

• PostgreSQL Documentation: The pg_hba.conf File
• PostgreSQL Documentation: Password Authentication
• PostgreSQL Documentation Home