PostgreSQL OAuth 인증 기준

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

PostgreSQL OAuth 인증은 데이터베이스가 비밀번호를 직접 받는 구조가 아니라, 외부 OAuth 제공자가 발급한 bearer token을 PostgreSQL 서버가 검증하는 구조입니다. 그래서 설정을 볼 때는 서버, libpq 클라이언트, OAuth 제공자의 역할을 나누어 봐야 합니다.

PostgreSQL 18 문서 기준으로 OAuth 2.0 지원은 클라이언트 인증 영역에 들어갑니다. PostgreSQL은 authorization server를 제공하지 않으며, 토큰 발급과 사용자 승인은 OAuth 제공자 쪽 책임입니다. PostgreSQL 서버는 resource server로 동작하고, libpq 기반 애플리케이션이나 psql은 OAuth client로 동작합니다.

OAuth 인증은 어디에서 동작하나

일반적인 비밀번호 인증은 클라이언트가 비밀번호나 SCRAM 응답을 서버에 보내고, 서버가 이를 검증하는 흐름입니다. OAuth 인증에서는 클라이언트가 먼저 적절한 access token을 얻고, PostgreSQL 서버는 그 bearer token을 검증합니다.

이 구조에서 중요한 점은 PostgreSQL 서버가 로그인 화면이나 토큰 발급 서비스를 대신 제공하지 않는다는 것입니다. 조직이 사용하는 OAuth 제공자, issuer, scope, validator 정책이 이미 정해져 있어야 PostgreSQL 쪽 설정도 의미가 생깁니다.

서버 설정에서 먼저 볼 항목

PostgreSQL 서버의 OAuth 인증 설정은 pg_hba.conf의 OAuth 항목에서 출발합니다. 공식 문서가 설명하는 핵심 옵션은 issuer, scope, validator, map, delegate_ident_mapping입니다.

항목	역할	확인 기준
issuer	신뢰할 authorization server의 식별자 또는 discovery 문서 위치를 지정한다.	discovery 문서의 issuer 값, 서버 설정, 클라이언트의 oauth_issuer가 정확히 맞아야 한다.
scope	서버 접속에 필요한 OAuth scope 목록을 지정한다.	토큰이 어떤 권한을 담아야 하는지 제공자와 validator 정책에서 확인한다.
validator	bearer token을 검증할 라이브러리를 지정한다.	사용 가능한 validator가 여러 개라면 이름을 명시해야 한다.
map	OAuth identity와 PostgreSQL role 이름을 매핑한다.	토큰의 사용자 식별자가 DB role과 다르면 매핑 정책이 필요하다.
delegate_ident_mapping	일반 사용자 매핑을 건너뛰고 validator가 role 허용 판단까지 맡게 한다.	validator 구현이 권한 판단까지 정확히 수행할 때만 검토한다.

issuer는 특히 엄격하게 봐야 합니다. 공식 문서는 서버의 issuer 설정, discovery 문서의 issuer identifier, 클라이언트의 oauth_issuer가 대소문자와 표기까지 정확히 일치해야 한다고 설명합니다. 비슷한 URL처럼 보여도 포맷이 다르면 연결이 실패할 수 있습니다.

libpq 클라이언트에서 필요한 값

libpq 쪽에서는 서버가 OAuth bearer token을 요청할 때 사용할 연결 파라미터를 준비해야 합니다. 최소 기준은 oauth_issuer와 oauth_client_id입니다. 제공자 정책에 따라 oauth_client_secret이 필요할 수도 있고, 고급 상황에서는 oauth_scope를 명시할 수 있습니다.

dbname=postgres user=app \
oauth_issuer=https://issuer.example.com \
oauth_client_id=example-client

oauth_scope를 직접 지정하면 서버가 요청한 scope 목록 대신 클라이언트가 지정한 scope가 사용됩니다. 이는 덜 신뢰하는 서버가 과한 scope를 요청하는 것을 줄이는 데 도움이 될 수 있지만, 서버가 요구하는 scope가 빠지면 토큰 검증에서 실패할 수 있습니다.

내장 Device Authorization 흐름의 조건

PostgreSQL 문서 기준으로 libpq는 OAuth v2 Device Authorization client flow를 선택 모듈로 지원합니다. 지원이 빌드되고 모듈이 설치되어 있으며 서버가 bearer token을 요청하면, libpq는 기본적으로 이 내장 흐름을 사용할 수 있습니다.

이 흐름은 SSH처럼 클라이언트가 실행되는 환경에 직접 사용할 브라우저가 없어도 쓸 수 있습니다. 기본 동작에서는 방문할 URL과 user code가 출력되고, 사용자는 OAuth 제공자에서 승인한 뒤 접속을 이어갑니다.

다만 내장 Device Authorization 흐름은 모든 조건에서 자동으로 되는 기능이 아닙니다. libpq가 해당 지원을 포함해야 하고, authorization server가 device authorization endpoint를 제공해야 합니다. PostgreSQL 18 문서는 내장 Device Authorization 흐름이 현재 Windows에서는 지원되지 않는다고도 설명합니다. Windows 애플리케이션은 custom client flow 구현을 검토할 수 있습니다.

 

 

require_auth=oauth와의 차이

libpq에는 require_auth 연결 파라미터도 있습니다. 이 값에 oauth를 지정하면 클라이언트는 서버가 OAuth 인증을 사용해야 한다고 요구할 수 있습니다. 서버가 다른 인증 방식을 쓰거나 인증 절차가 기대대로 완료되지 않으면 연결은 실패합니다.

dbname=postgres user=app \
oauth_issuer=https://issuer.example.com \
oauth_client_id=example-client \
require_auth=oauth

require_auth=oauth는 OAuth 설정 자체를 완성해 주는 옵션이 아닙니다. 서버가 어떤 인증 방식을 제시해야 하는지 클라이언트가 확인하는 안전장치에 가깝습니다. 실제 토큰 발급에는 oauth_issuer, oauth_client_id, 제공자 설정, server-side validator가 필요합니다.

토큰 검증과 사용자 매핑을 분리해서 봐야 한다

OAuth 토큰이 유효하다는 사실과 PostgreSQL role로 접속해도 된다는 사실은 같은 말이 아닙니다. 서버는 validator를 통해 bearer token을 검증하고, 필요하면 pg_ident.conf 기반의 사용자 매핑을 적용합니다.

map이 없으면 validator가 판단한 사용자 이름이 요청한 PostgreSQL role 이름과 정확히 맞아야 합니다. 조직의 사용자 식별자가 이메일, subject ID, 사번처럼 DB role 이름과 다르게 관리된다면 매핑 정책을 명확히 둬야 합니다.

운영 기준

• PostgreSQL이 OAuth 제공자 역할을 한다고 가정하지 않는다. 토큰 발급과 사용자 승인은 외부 제공자 정책으로 관리한다.
• issuer 값은 discovery 문서, 서버 설정, 클라이언트 설정에서 정확히 일치시키며 별칭 URL을 섞지 않는다.
• scope는 접속 권한을 설명할 수 있을 만큼 좁게 잡고, 서버와 클라이언트가 서로 다른 scope를 요구하지 않는지 확인한다.
• DB role 이름과 OAuth identity가 다르면 map을 사용해 매핑 기준을 문서화한다.
• 클라이언트가 반드시 OAuth 인증만 받아야 하는 상황에서는 require_auth=oauth를 같이 검토한다.
• 내장 Device Authorization 흐름을 쓸 때는 libpq 빌드 옵션, provider endpoint, 플랫폼 제한을 먼저 확인한다.

디버깅 설정은 운영에 두지 않는다

libpq 문서는 PGOAUTHDEBUG=UNSAFE를 위험한 디버깅 모드로 설명합니다. 이 모드는 로컬 개발과 테스트 편의를 위한 기능이며, HTTP 허용, CA 목록 대체, OAuth 흐름의 HTTP traffic 출력 같은 운영에 두기 어려운 동작을 포함합니다.

특히 OAuth 흐름의 출력에는 공격에 악용될 수 있는 secret이 포함될 수 있습니다. 따라서 OAuth 연결 문제를 분석할 때도 디버그 출력 공유 범위와 저장 위치를 제한해야 합니다.

자주 묻는 질문

PostgreSQL만 설정하면 OAuth 로그인이 바로 되나

아닙니다. PostgreSQL은 authorization server를 제공하지 않습니다. OAuth 제공자, issuer, client 등록, scope, token validator가 준비되어야 합니다.

oauth_issuer는 대략 같은 도메인이면 되나

그렇지 않습니다. 공식 문서 기준으로 서버 issuer 설정, discovery 문서의 issuer 값, 클라이언트의 oauth_issuer가 정확히 일치해야 합니다.

내장 Device Authorization 흐름은 모든 libpq 환경에서 동작하나

아닙니다. libpq가 해당 지원을 포함해 빌드되어야 하고, provider가 device authorization endpoint를 제공해야 합니다. 공식 문서는 내장 흐름이 현재 Windows에서는 지원되지 않는다고 설명합니다.

정리

PostgreSQL OAuth 인증의 핵심은 역할 분리입니다. PostgreSQL 서버는 bearer token을 검증하는 resource server이고, libpq 클라이언트는 토큰을 얻어 서버에 제시합니다. 토큰 발급과 사용자 승인은 OAuth 제공자가 담당합니다.

설정 기준은 issuer의 정확한 일치, 필요한 scope, 적절한 validator, 사용자 매핑 정책입니다. 클라이언트에서는 oauth_issuer와 oauth_client_id를 먼저 확인하고, 인증 방식 자체를 고정해야 할 때 require_auth=oauth를 함께 검토하는 편이 안전합니다.