9.2 pg_hba.conf 인증 메서드
pg_hba.conf는 PostgreSQL의 Host-Based Authentication 정책 파일입니다. 누가(user) 어디서(host) 어떤 DB에(database) 어떤 방법으로(auth-method) 접속할 수 있는지 정의합니다. 권한 매칭의 첫 관문이라 잘못 쓰면 운영 클러스터가 잠깁니다.
파일 위치
| 배포 | 위치 |
|---|---|
| RHEL/Rocky (PGDG) | /var/lib/pgsql/<ver>/data/pg_hba.conf (PGDATA 안) |
| Debian/Ubuntu (PGDG) | /etc/postgresql/<ver>/<cluster>/pg_hba.conf |
| 소스 빌드 | PGDATA 안 |
Docker postgres | /var/lib/postgresql/data/pg_hba.conf |
행 형식
TYPE DATABASE USER ADDRESS METHOD [OPTIONS]| TYPE | 의미 |
|---|---|
local | Unix 도메인 소켓 |
host | TCP/IP (SSL/non-SSL 둘 다) |
hostssl | TCP/IP + SSL 강제 |
hostnossl | TCP/IP + SSL 거부 |
hostgssenc | GSSAPI 암호화 |
hostnogssenc | GSSAPI 거부 |
자주 쓰는 인증 메서드
| METHOD | 설명 | 운영 권장도 |
|---|---|---|
trust | 비밀번호 검증 없음 — 위험 | 절대 금지 (localhost 일부 예외) |
reject | 무조건 거부 | 명시적 차단에 유용 |
md5 | MD5 해시 비밀번호 | 옛 — SCRAM 권장 |
scram-sha-256 | SCRAM-SHA-256 | 표준 |
peer | OS 사용자명 = DB 사용자명 (Unix 소켓 전용) | 로컬 관리에 편리 |
ident | RFC 1413 ident 서버 | 잘 안 씀 |
gss / sspi | Kerberos / Windows | 엔터프라이즈 |
ldap | LDAP bind | 엔터프라이즈 |
pam | PAM 모듈 | OS 통합 |
cert | 클라이언트 SSL 인증서 | 보안 강 |
radius | RADIUS 서버 | 엔터프라이즈 |
운영 표준 한 줄 모음
# TYPE DATABASE USER ADDRESS METHOD
local all postgres peer
local all all scram-sha-256
host all all 127.0.0.1/32 scram-sha-256
host all all ::1/128 scram-sha-256
hostssl app_main app_readers 10.0.0.0/8 scram-sha-256
hostssl replication repl_user 10.0.1.5/32 scram-sha-256
host all all 0.0.0.0/0 reject핵심 원칙
localpostgres = peer: 호스트의 postgres 사용자가 비밀번호 없이 슈퍼유저 접속- 로컬 일반 사용자는 scram-sha-256: 트러스트 금지
- 외부 TCP는 hostssl + scram-sha-256: 평문 + 인증서 검증
replication데이터베이스는 별도 행: 복제 사용자 분리- 모르는 곳은
reject로 명시 차단: catch-all 정책
매칭 순서
행은 위에서부터 순차로 매칭되고, 첫 번째로 걸린 행이 결과가 됩니다.
# 잘못된 예 — host all all 이 먼저라 hostssl 룰이 무시됨
host all all 10.0.0.0/8 md5
hostssl all all 10.0.0.0/8 scram-sha-256
# 올바른 예
hostssl all all 10.0.0.0/8 scram-sha-256
hostnossl all all 10.0.0.0/8 rejectdatabase 컬럼 특수 값
| 값 | 의미 |
|---|---|
all | 모든 DB |
sameuser | 사용자명과 같은 이름의 DB만 |
samerole | 멤버로 속한 역할 이름의 DB |
replication | 복제 연결 전용 (PG 9+) |
db1,db2 | 콤마로 여러 DB |
@filename | 외부 파일에서 목록 읽기 |
user 컬럼
| 값 | 의미 |
|---|---|
all | 모든 역할 |
alice | 단일 역할 |
+app_readers | app_readers 그룹의 멤버 모두 (PG 9.1+) |
alice,bob | 여러 사용자 |
@filename | 외부 파일 |
hostssl app_main +app_readers 10.0.0.0/8 scram-sha-256적용 — reload
pg_hba.conf 변경은 재시작 없이 reload만으로 적용됩니다.
sudo systemctl reload postgresql-17
# 또는
psql -c "SELECT pg_reload_conf();"테스트:
SELECT * FROM pg_hba_file_rules;
-- 파싱 결과를 SQL로 조회. 잘못된 행은 에러 표시운영자가 변경 후 이 뷰로 검증하는 게 표준입니다.
디버깅
접속이 실패하면 PostgreSQL 로그에 정확한 매칭 행이 적힙니다.
2026-05-23 09:12:01 KST [12345] FATAL: no pg_hba.conf entry for host "203.0.113.5", user "alice", database "app_main", SSL off| 메시지 | 원인 |
|---|---|
no pg_hba.conf entry for ... | 매칭 행 없음 — 새 행 추가 또는 IP 잘못 |
password authentication failed | scram-sha-256 / md5 메서드인데 비밀번호 불일치 |
pg_hba.conf rejects connection | 명시적 reject 행에 걸림 |
SSL connection is required | hostnossl 가 아닌 행에 SSL 없이 접속 |
SCRAM 마이그레이션
옛 클러스터가 md5로 운영 중이면 점진 전환:
-- 1. password_encryption을 scram-sha-256으로
ALTER SYSTEM SET password_encryption = 'scram-sha-256';
SELECT pg_reload_conf();
-- 2. 각 사용자가 비밀번호를 다시 설정 (이때 SCRAM으로 저장됨)
ALTER ROLE alice PASSWORD 'new_secret';
-- 3. 모든 사용자가 마이그레이션 끝나면 pg_hba.conf를 md5 → scram-sha-256으로확인:
SELECT rolname, rolpassword IS NULL AS no_pw,
LEFT(rolpassword, 14) AS pw_kind
FROM pg_authid
WHERE rolcanlogin;
-- pw_kind가 'SCRAM-SHA-256'이면 SCRAM, 'md5...'이면 MD5운영 안티패턴
| 안티패턴 | 위험 |
|---|---|
host all all 0.0.0.0/0 trust | 인터넷에서 누구나 슈퍼유저 접속 |
md5 유지 | rainbow table·sniffing 위험 |
hostnossl 명시 안 함 | 평문 접속 허용 |
| 회사망 안이라고 평문 OK 가정 | 내부망도 capture 가능 — TLS 필수 |
pg_hba.conf 변경 후 검증 없이 reload | 잘못된 행이 클러스터 잠금 사고 |
pg_hba.conf 변경은 항상 pg_hba_file_rules 뷰로 검증 후 reload. 변경 전 백업 카피를 두고, 변경 후 다른 세션에서 새 접속이 가능한지 즉시 확인합니다. 잘못된 파일로 reload하면 새 접속이 모두 거부되며 원격 복구가 매우 번거롭습니다.정리
- 운영 표준: scram-sha-256 + hostssl + replication 별도 행
pg_hba_file_rules뷰로 변경 검증 후 reload
pg_hba.conf는 누가 어디서 어떤 DB에 어떤 메서드로 접속할지 정의하는 파일입니다. 행을 위에서부터 순서대로 매칭하므로 나열 순서가 결과를 좌우합니다. md5로 운영 중인 클러스터는 SCRAM으로 단계적으로 전환하는 편이 안전하고, 변경은 재시작 없이 reload만으로 적용됩니다.