PostgreSQL 18 OAuth2 인증 작동 원리와 설정 방법 (1)
작성자: Guang Yi Xu
2025년 9월 15일
PostgreSQL 18 (RC1은 2025년 9월 5일 공개)은 SASL OAUTHBEARER 메커니즘을 기반으로 네이티브 OAuth2 인증 방식을 도입했습니다. 비밀번호 대신 클라이언트가 IdP(Identity Provider, 신원 공급자)에서 발급받은 베어러 토큰을 제시하면, PostgreSQL은 플러그형 검증기 모듈을 통해 토큰을 검증합니다. 이후 인증된 신원을 데이터베이스 롤에 매핑해 액세스를 허용합니다. 이를 통해 Postgres에서도 최신 SSO(Single Sign-On) 방식을 활용하면서 롤과 권한은 기존과 마찬가지로 DBA가 관리할 수 있습니다.
이 시리즈는 총 3편으로 구성됩니다.
- Part-1 (이 글): PostgreSQL 18 OAuth2 인증 작동 원리와 설정 방법
- Part-2: Rust로 커스텀 검증기 작성하기
- Part-3: PostgreSQL proto3 클라이언트 라이브러리에 OAUTHBEARER 지원 추가
PostgreSQL 18 OAuth2 인증을 위한 준비 사항
PostgreSQL 18에서 OAuth2 인증을 구성하려면 다음 요소를 준비해야 합니다.
- IdP(OAuth2/OIDC): 토큰 발급에 필요하며, 서버는 최종적으로 검증기에서 허용한 토큰을 신뢰합니다.
- PostgreSQL v3 프로토콜 클라이언트: 현재
psql(libpq 기반)이 확인되었으며, 통합된 디바이스 인증 플로우를 지원합니다. - PostgreSQL 18:
--with-openssl --with-libcurl옵션으로 빌드하고,pg_hba.conf및 필요한 경우pg_ident.conf를 설정해야 합니다. - 서버 측 검증기 모듈: 토큰을 검증하고 인증 여부를 결정합니다.
PostgreSQL 18 OAuth2 인증은 어떻게 작동할까?
인증 과정은 SASL 교환으로 이루어지며, 서버는 OAUTHBEARER 메커니즘을 클라이언트에 알립니다. 클라이언트는 베어러 토큰을 바로 제시하거나 discovery 정보를 요청한 뒤 OAuth 플로우(예: 디바이스 코드)를 실행해 토큰을 획득하고 다시 인증을 시도할 수 있습니다. 서버는 설정된 검증기 모듈을 통해 토큰을 확인한 뒤 인증을 완료합니다.
OAUTHBEARER SASL 인증 흐름의 핵심
pg_hba.conf에서oauth메서드를 선택하면 서버는OAUTHBEARER를 클라이언트에 알립니다.- 클라이언트는 베어러 토큰을 바로 전송할 수도 있고,
auth=""를 전송해 discovery 정보를 가져온 뒤 토큰을 획득하고 다시 시도할 수도 있습니다.libpq는 디바이스 인증을 구현합니다. - 토큰을 획득하는 방식은 프로토콜과 별개이며, SASL 교환에서는 획득한 토큰을 전달합니다.
OAuth2 인증을 위한 PostgreSQL 서버 설정
1) pg_hba.conf에서 oauth 인증 설정
일반적인 규칙은 다음과 같습니다.
# TYPE DATABASE USER ADDRESS METHOD OPTIONS...
host all tester ::1/128 oauth scope="openid profile" issuer=https://my-system.my-domain/auth validator=my_system_validator map="my_oauth_map"
method=oauth: 매칭되는 연결에 OAuth 인증을 활성화issuer와scope: 서버가 토큰에서 확인할 값validator: 사용할 검증기 이름map: 기존pg_ident.conf를 이용한 사용자 ↔ 롤 매핑 활성화
pg_ident.conf 설정 예시는 다음과 같습니다.
# MAPNAME SYSTEM-USERNAME PG-USERNAME
my_oauth_map abcdef_my_user_id tester
2) postgresql.conf에서 검증기 로드
# - Authentication -
oauth_validator_libraries = 'my_system_validator'
# comma-separated list of trusted validator modules
- 신뢰할 수 있는 검증기 모듈을 쉼표로 구분해 나열합니다.
- 여기에 등록된 검증기만 HBA 규칙에서 사용할 수 있습니다.
3) 사용자 ID와 PostgreSQL 롤 매핑
- pg_ident.conf 매핑 (기본): 검증기는
authn_id를 반환해야 하며, 이 값은 요청된 사용자 또는pg_ident.conf를 통해 매핑된 롤과 정확히 일치해야 합니다. 일치하지 않으면 로그인이 실패합니다. - 위임 매핑(Delegated mapping): HBA 규칙에서
delegate_ident_mapping=1을 설정합니다. PostgreSQL은authn_id를 사용하지 않고, 검증기가authorized=true를 반환하면 요청된 사용자를 허용합니다. 이 방식은 토큰과 요청된 롤이 엄격하게 연결된 경우에만 사용해야 합니다.
OAuth2 인증 시 클라이언트의 동작 방식
psql/libpq를 이용해 연결하려면 다음 두 가지 연결 매개변수가 필요하며, 누락되면 연결에 실패합니다.
oauth_issueroauth_client_id
libpq는 터미널 환경에서 디바이스 인증 플로우를 실행할 수 있습니다. 이 경우 verification_uri와 user_code를 출력하고, 토큰이 발급될 때까지 폴링합니다.
기타 클라이언트와 드라이버(jackc/pgx, launchbadge/sqlx)는 다음 두 가지 패턴 중 하나를 채택할 수 있습니다.
- Full SASL OAUTHBEARER: 서버가 제공하는 discovery/scope 정보를 바탕으로 OAuth 플로우를 실행한 후 SASL 교환을 계속 진행
- Token-first: 외부에서 토큰을 미리 획득한 뒤 초기 SASL 메시지에 포함해 전송
일반적으로 GUI 툴은 첫 번째 방식을, 서비스에서 사용하는 SDK나 라이브러리는 두 번째 방식을 선택할 수 있습니다.
OAuth2 토큰을 검증하는 Validator 모듈
검증기 모듈은 Postgres와 IdP 사이에서 토큰의 신뢰성을 확인하는 역할을 합니다.
주요 역할은 다음과 같습니다.
- 토큰 검증(발급자, 서명/키(JWT의 경우), opaque 토큰의 경우 introspection, scope, 수명 등)
{ authorized: true/false, authn_id: "username" }반환- 위임 매핑이 활성화된 경우 ID-롤 바인딩을 강제
검증 방식 선택 시 고려 사항:
- 오프라인 JWT 검증은 지연 시간을 최소화합니다.
- 온라인 introspection은 토큰 폐기를 단순화하지만
authentication_timeout내에 완료되어야 합니다. - 자세한 내용은 공식 문서를 참고하세요.
OAuth2 인증에서 사용할 수 있는 토큰 형식
- SASL OAUTHBEARER는 JWT 형식의 토큰만을 요구하지 않습니다.
- 허용된 문자 집합을 따르는 베어러 토큰이라면 프로토콜 수준에서 사용할 수 있으며, 실제 토큰을 검증하는 방식은 검증기 구현에 따라 달라집니다.
OAuth2 인증과 PostgreSQL 롤·권한 관리
OAuth2 지원으로 달라지는 것은 인증 방식이며, PostgreSQL의 롤과 권한 관리 방식 자체가 변경되는 것은 아닙니다.
- 롤 생성, 권한 부여 및 회수 등은 기존 DBA 프로세스나 자동화 방식을 그대로 사용할 수 있습니다.
PostgreSQL 18 OAuth2 인증 설정 절차
- Postgres에 매핑할 롤을 프로비저닝합니다.
- IdP를 선택하고 JWT(오프라인)와 introspection(온라인) 중 사용할 방식을 결정합니다.
- 검증기를 구현하고
oauth_validator_libraries에 추가합니다. issuer,scope,map또는delegate_ident_mapping=1을 포함한 OAuth HBA 규칙을 작성합니다.- 클라이언트를 설정합니다.
psql의 경우oauth_issuer와oauth_client_id를 지정하고, 필요한 경우 디바이스 플로우가 정상적으로 동작하는지 확인합니다.
psql을 이용한 PostgreSQL 18 OAuth2 인증 흐름
PostgreSQL 18 서버에 OAuth2 방식으로 인증하여 연결하는 일반적인 psql 명령 예시는 다음과 같습니다.
psql "postgres://tester@my_pg.my-domain:5432/upm?oauth_issuer=https://my-system.my-domain/auth&oauth_client_id=my-app-client-id"
실제 인증 과정은 아래 다이어그램과 같은 흐름으로 진행됩니다. 클라이언트는 다음 두 가지 방식으로 인증할 수 있습니다.
- 처음부터 토큰을 전송
- discovery 정보를 가져와 디바이스 플로우를 실행한 뒤 인증을 계속 진행
PostgreSQL 18 OAuth2 psql 디바이스 코드 플로우
libpq의 디바이스 플로우 프롬프트(verification_uri, user_code)에 대한 자세한 내용은 공식 libpq OAuth 문서에서 확인할 수 있습니다.
PostgreSQL 18 OAuth2 관련 문서
- PostgreSQL 18 릴리스 노트 E.1.3.6. 서버 설정
- OAuth 인증 방식과 HBA 옵션
- PostgreSQL 18 매뉴얼 Chapter 50. OAuth Validator Modules
- RFC 7628: SASL OAUTHBEARER
메일: salesinquiry@enterprisedb.com