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하면 새 접속이 모두 거부되며 원격 복구가 매우 번거롭습니다.정리
pg_hba.conf= 누가·어디서·어떤 DB에·어떤 메서드로 접속할지 정의- 행은 위에서부터 매칭 — 순서가 매우 중요
- 운영 표준: scram-sha-256 + hostssl + replication 별도 행
pg_hba_file_rules뷰로 변경 검증- 변경은 reload (재시작 불필요)
- md5는 SCRAM으로 단계적 전환 권장
다음 절(9.3)에서는 row 단위 권한 — Row-Level Security(RLS)를 봅니다.