PostgreSQL require_auth 기준 정리

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

PostgreSQL libpq의 require_auth는 클라이언트가 서버로부터 허용할 인증 방식을 제한하는 연결 파라미터입니다. 서버의 pg_hba.conf를 대신 설정하는 옵션이 아니라, 클라이언트가 예상하지 않은 인증 흐름으로 연결되는 것을 막는 안전장치에 가깝습니다.

기본값에서는 libpq가 서버가 제시하는 인증 방식을 폭넓게 받아들일 수 있습니다. 반대로 require_auth=scram-sha-256처럼 명시하면 서버가 해당 인증 교환을 완료하지 않을 때 연결이 실패합니다. 애플리케이션이 어떤 인증 정책을 기대하는지 연결 문자열에 드러내고 싶을 때 검토할 만한 옵션입니다.

require_auth는 어디에서 동작하나

PostgreSQL 연결은 네트워크 연결, 선택적 TLS/GSS 협상, 인증 교환, 세션 시작 순서로 진행됩니다. require_auth는 이 중 인증 교환 단계에서 서버가 어떤 방식을 사용했는지 클라이언트 쪽에서 검사합니다.

공식 문서 기준으로 서버가 요구한 인증 방식이 require_auth의 조건과 맞지 않거나, 인증 handshake가 끝까지 완료되지 않으면 연결은 실패합니다. 따라서 이 옵션은 서버 설정을 바꾸지 않고, 클라이언트가 받아들일 인증 범위를 좁히는 역할을 합니다.

기본값과 명시값의 차이

require_auth를 지정하지 않으면 libpq는 기본적으로 어떤 인증 방식이든 받아들일 수 있고, 서버가 인증 요청을 생략하는 흐름도 허용될 수 있습니다. 이 동작은 개발 환경에서는 편할 수 있지만, 운영 연결 문자열에서는 기대한 인증 방식이 문서로 남지 않는다는 단점이 있습니다.

postgresql://app@example.com/service?require_auth=scram-sha-256

host=example.com dbname=service user=app require_auth=scram-sha-256

위 예시는 서버가 SCRAM-SHA-256 인증 교환을 성공적으로 완료해야 연결을 허용합니다. 서버가 다른 인증 방식을 요구하거나 인증을 생략하면 클라이언트 연결이 실패하는 식으로 해석하면 됩니다.

지정할 수 있는 방식

값	의미	확인할 점
scram-sha-256	SCRAM-SHA-256 인증 교환을 요구한다.	서버의 사용자 비밀번호가 SCRAM으로 설정되어 있어야 한다.
md5	MD5 password 인증을 요구한다.	PostgreSQL 문서는 MD5 암호화 비밀번호 지원이 향후 제거될 예정이라고 경고한다.
password	평문 password 인증 요청을 요구한다.	신뢰할 수 없는 네트워크에서는 피해야 하며, TLS 같은 전송 보호와 별도로 판단해야 한다.
gss, sspi	GSSAPI 또는 Windows SSPI 인증을 요구한다.	플랫폼과 인증 인프라 지원 여부가 전제다.
oauth	OAuth bearer token 인증 요청을 요구한다.	PostgreSQL OAuth 구성이 실제로 준비되어 있어야 한다.
none	서버가 인증 challenge를 사용하지 않아야 한다.	인증을 생략해야 하는 특수한 로컬 또는 테스트 조건인지 분명해야 한다.

쉼표로 여러 방식을 지정할 수도 있습니다. 이 경우 서버는 목록 중 정확히 하나의 인증 방식을 사용해야 연결이 성공합니다. 예를 들어 마이그레이션 기간에 scram-sha-256,md5처럼 쓸 수 있지만, 새 설정이라면 MD5 의존을 줄이는 방향을 같이 봐야 합니다.

부정 조건은 언제 쓰나

값 앞에 !를 붙이면 해당 인증 방식을 금지할 수 있습니다. 예를 들어 require_auth=!password는 서버가 평문 password 인증을 시도하면 연결을 거부하고, 그 외의 인증 방식이나 인증 생략은 허용하는 형태입니다.

다만 부정 조건과 일반 조건은 같은 설정에서 섞을 수 없습니다. scram-sha-256,!password처럼 “이것은 요구하고 저것은 금지한다”를 한 번에 표현하는 방식이 아니라, 허용 목록 또는 금지 목록 중 하나를 선택하는 옵션입니다.

 

 

channel_binding과의 관계

require_auth=scram-sha-256은 SCRAM 인증 교환 자체를 요구합니다. 반면 channel_binding=require는 가능한 경우가 아니라 반드시 channel binding을 사용해야 한다는 조건입니다. 둘은 같은 문제가 아니라 서로 다른 축의 조건입니다.

PostgreSQL 문서는 SCRAM의 channel binding 변형을 SCRAM-SHA-256-PLUS라고 설명합니다. 이 방식은 서버 인증서의 서명을 인증 계산에 섞어 중간자 공격 위험을 줄이는 데 쓰입니다. 따라서 TLS를 쓰는 환경에서 서버 정체성 검증까지 강하게 보고 싶다면 sslmode=verify-full, channel_binding=require, require_auth=scram-sha-256의 역할을 각각 나누어 확인해야 합니다.

host=example.com dbname=service user=app sslmode=verify-full channel_binding=require require_auth=scram-sha-256

환경변수로 지정할 수 있다

libpq 환경변수 목록에는 PGREQUIREAUTH가 있으며, 이 값은 require_auth 연결 파라미터와 같은 역할을 합니다. 여러 도구가 같은 정책을 써야 하는 운영 셸에서는 환경변수가 편할 수 있습니다.

PGREQUIREAUTH=scram-sha-256
PGCHANNELBINDING=require

애플리케이션마다 정책이 다르거나 배포 설정을 읽는 사람이 바로 이해해야 한다면 연결 문자열에 명시하는 편이 더 낫습니다. 환경변수는 프로세스 실행 환경에 숨기 쉬우므로, 장애 분석 때 실제 적용값을 확인하는 절차도 같이 필요합니다.

선택 기준

• 일반적인 새 원격 연결에서는 scram-sha-256을 우선 검토한다.
• 기존 시스템이 MD5에서 SCRAM으로 이동 중이면 허용 목록을 임시로 넓히되 제거 시점을 정한다.
• 평문 password 인증을 막는 목적이면 !password처럼 금지 조건을 검토한다.
• TLS 위에서 서버 정체성까지 확인해야 하면 sslmode와 channel_binding을 함께 본다.
• 로컬 테스트에서 none을 쓰더라도 운영 연결 문자열에 그대로 남기지 않는다.

자주 묻는 질문

require_auth만 설정하면 서버 인증 방식이 바뀌나

아닙니다. 서버가 어떤 인증을 요구할지는 서버의 인증 설정이 결정합니다. require_auth는 클라이언트가 그 방식을 받아들일지 검사하는 옵션입니다.

require_auth=scram-sha-256와 channel_binding=require는 같은가

같지 않습니다. 앞의 값은 SCRAM 인증 방식을 요구하고, 뒤의 값은 channel binding 사용을 요구합니다. TLS와 SCRAM을 함께 쓰는 환경에서는 두 조건을 조합해서 볼 수 있습니다.

md5를 허용해도 되나

기존 클라이언트 호환 때문에 일시적으로 필요할 수는 있습니다. 다만 PostgreSQL 문서는 MD5 암호화 비밀번호 지원이 향후 제거될 예정이라고 경고하므로, 새 설정의 기본값으로 두는 것은 피하는 편이 안전합니다.

정리

require_auth는 PostgreSQL 서버의 인증 정책을 만드는 옵션이 아니라, libpq 클라이언트가 허용할 인증 방식을 좁히는 옵션입니다. 기본값을 그대로 두면 서버가 제시하는 방식에 넓게 맞추지만, 명시값을 두면 예상과 다른 인증 흐름을 연결 실패로 드러낼 수 있습니다.

실무에서는 “서버가 어떤 인증을 요구하게 할 것인가”와 “클라이언트가 어떤 인증만 받아들일 것인가”를 분리해서 봐야 합니다. 전자는 서버 인증 설정의 문제이고, 후자는 require_auth, PGREQUIREAUTH, channel_binding, sslmode 조합으로 표현하는 클라이언트 정책입니다.