[PostgreSQL 18][OAuth] 비밀번호 없이 DB에 로그인하려면 서버·libpq·검증 모듈을 어디까지 준비해야 하나

IT 리서치 노트

[PostgreSQL 18][OAuth] 비밀번호 없이 DB에 로그인하려면 서버·libpq·검증 모듈을 어디까지 준비해야 하나

PostgreSQL 18은 OAuth 인증을 정식으로 추가했지만 pg_hba.conf에 oauth 한 단어를 넣는 것만으로 동작하지 않는다. 2026년 9월 5일 KST 기준 공식 문서를 보면 외부 authorization server, OAuth 지원 libpq, 서버의 검증 모듈, DB role 매핑이 모두 맞아야 한다. 이 글은 비밀번호 없이 DB에 로그인하려는 팀이 도입 전에 어디까지 준비해야 하는지 한 번에 정리한다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론은 네 층을 따로 준비하는 것이다. 외부 제공자가 토큰을 발급하고, libpq가 device flow를 수행하며, PostgreSQL이 bearer token을 validator에 넘기고, 검증된 identity가 DB role로 매핑돼야 한다.

OAuth는 비밀번호를 없애는 버튼이 아니라 인증 책임을 외부 issuer와 검증 모듈로 이동하는 구조다.

아래 공식 문서 화면과 설정 예시에서 어느 값과 결과를 봐야 하는지 차례대로 확인한다.

2. 어디서 실제로 막히는가

가장 흔한 막힘은 서버가 토큰을 직접 발급한다고 생각하는 것이다. PostgreSQL은 authorization server를 제공하지 않는다. 또 libpq가 OAuth 지원 없이 빌드됐거나 provider에 device authorization endpoint가 없으면 내장 흐름이 시작되지 않는다.

• psql이 OAuth 옵션을 인식하지 않는다.
• discovery는 되지만 device endpoint가 없다.
• 토큰은 유효하지만 DB role 매핑이 실패한다.

증상을 단계별로 나누면 확인 위치도 분명해진다. 접속 명령이 옵션 단계에서 끝나면 client 빌드와 연결 문자열을 확인한다. user code 화면이 나오지 않으면 issuer와 discovery 응답을 확인한다. provider 승인 뒤 거부되면 requested scope와 validator 결과를 확인한다. validator가 accepted를 반환했는데도 실패하면 authn_id, requested role, pg_ident map을 대조한다. 이 순서를 건너뛰면 앞단 URL 오류를 DB 권한 오류로 잘못 보고 설정을 반복해서 바꾸게 된다.

운영 로그에는 단계 이름, 확인 시각, issuer 문자열, scope 이름, validator 결과, 최종 role만 남긴다. bearer token과 client secret은 남기지 않는다. 같은 trace에서 어느 화면까지 도달했는지 기록하면 network, provider, PostgreSQL 담당자가 같은 실패를 서로 다른 말로 설명하는 일을 줄일 수 있다.

3. 실무에서 적용하는 순서

먼저 provider의 issuer와 discovery 문서를 확인한다. 다음으로 서버 빌드와 oauth_validator_libraries를 확인하고, validator를 배포한다. 그 뒤 pg_hba.conf에 issuer·scope·validator·map을 적는다. 마지막으로 OAuth 지원 libpq에서 oauth_issuer와 oauth_client_id를 지정해 접속한다.

provider → libpq device flow → PostgreSQL HBA → validator → role map

실행할 때는 먼저 테스트 전용 role과 제한된 source network를 정한다. discovery URL을 열어 issuer와 device endpoint를 확인하고, pg_hba_file_rules에서 새 규칙의 파싱 상태를 확인한다. 이어 psql을 실행해 user code 안내 화면을 확인하고 provider에서 승인한다. 서버에서는 token 원문 대신 validator accepted 여부와 authn_id를 확인하며, 접속 후에는 SELECT current_user를 실행해 기대한 role인지 검증한다.

실패하면 마지막 단계부터 되돌아가지 않는다. URL, discovery, device flow, scope, validator, role map 순으로 첫 실패 지점을 찾는다. 각 단계의 성공 화면이나 로그 한 줄을 배포 기록에 붙이고, 성공한 단계는 다시 수정하지 않는다. 이 방식은 설정 변경 범위를 줄이고 rollback 기준도 명확하게 만든다.

1. issuer와 discovery 문서를 확인한다.
2. device endpoint와 client 지원을 점검한다.
3. HBA rule과 validator를 적용한다.
4. user code 화면과 provider 승인을 확인한다.
5. validator 결과와 current_user를 검증한다.

4. 공식 문서와 예시 화면으로 확인하기

첫 화면은 PostgreSQL 18 릴리스 노트다. OAuth가 단순 접속 문자열 옵션이 아니라 pg_hba.conf, libpq, 검증 라이브러리를 함께 추가한 기능임을 확인해야 한다. 화면에서 강조된 문장과 설정 이름을 확인하고 다음 단계의 입력값과 비교한다.

PostgreSQL 18은 oauth 인증 방식과 libpq 옵션, 검증 모듈 기반을 함께 도입했다.

따라서 서버 설정만 바꾸거나 클라이언트 옵션만 넣는 것으로 끝나지 않는다. 성공 여부는 다음 화면이나 실행 결과에서 같은 값이 이어지는지 확인한다.

두 번째 화면에서는 issuer, scope, validator, map의 역할을 본다. 화면에서 강조된 문장과 설정 이름을 확인하고 다음 단계의 입력값과 비교한다.

OAuth HBA 규칙은 issuer와 scope가 필수이며 검증·역할 매핑 경계도 정해야 한다.

특히 PostgreSQL 자체가 authorization server를 제공하지 않으므로 외부 제공자와 validator가 먼저 있어야 한다. 성공 여부는 다음 화면이나 실행 결과에서 같은 값이 이어지는지 확인한다.

세 번째 화면은 libpq 내장 Device Authorization 흐름이다. SSH 환경에서도 URL과 user code로 로그인을 이어갈 수 있다. 화면에서 강조된 문장과 설정 이름을 확인하고 다음 단계의 입력값과 비교한다.

libpq 내장 흐름은 브라우저 없는 원격 셸에서도 device authorization을 사용할 수 있다.

다만 Windows 미지원과 빌드 옵션을 배포 전 확인해야 한다. 성공 여부는 다음 화면이나 실행 결과에서 같은 값이 이어지는지 확인한다.

구성요소를 한 줄로 묶으면 장애 위치를 찾기 어렵다. 아래 표처럼 발급, 전달, 검증, 역할 매핑을 나눈다. 화면에서 강조된 문장과 설정 이름을 확인하고 다음 단계의 입력값과 비교한다.

PostgreSQL OAuth 도입에 필요한 네 구성요소와 성공 기준이다.

이 표를 배포 체크리스트로 쓰면 인증 서버 장애와 DB 역할 매핑 오류를 구분할 수 있다. 성공 여부는 다음 화면이나 실행 결과에서 같은 값이 이어지는지 확인한다.

마지막 화면은 실제 비밀값 없이 배포 구조만 검토할 수 있는 설정 뼈대다. 화면에서 강조된 문장과 설정 이름을 확인하고 다음 단계의 입력값과 비교한다.

issuer와 scope, validator, client id의 연결 구조를 안전한 placeholder로 확인한다.

성공 시 psql은 device URL을 안내하고, 승인 뒤 요청한 DB role로 접속한다. 성공 여부는 다음 화면이나 실행 결과에서 같은 값이 이어지는지 확인한다.

5. 주의사항과 리스크

issuer는 대소문자와 URL 형식까지 discovery 문서와 정확히 맞아야 한다. delegate_ident_mapping은 validator가 role 권한 판단까지 책임지므로 일반 도입에서는 먼저 쓰지 않는 편이 안전하다. 토큰이나 client secret을 접속 로그에 남기지 않는다.

6. 결론

PostgreSQL 18 OAuth 도입은 issuer, client, HBA, validator, role map을 각각 검증해야 끝난다. 먼저 테스트 role 하나로 device flow와 매핑을 확인한 뒤 서비스 계정과 사람 계정을 나누어 확대하는 편이 안전하다. psql은 되지만 애플리케이션만 실패하면 서버를 다시 고치기 전에 드라이버·libpq·빌드·운영체제의 OAuth 지원 범위를 비교한다. 검증 방식은 온라인 introspection과 로컬 서명 검증의 취소·지연 기준으로 결정하고, 외부 검증기 지연이 실제 장애로 번질 때는 커넥션 풀 신규 연결 폭주를 차단하는 순서로 범위를 좁힌다.

구현 단계에서는 validate_cb의 token·role·authn_id 검증 순서를 기준으로 거부 사례를 만들고, 접속 승인 뒤 role이 맞지 않으면 pg_ident.conf role map 점검 순서로 이어서 확인한다. 표준 usermap을 건너뛰려는 경우에는 먼저 delegate_ident_mapping의 권한 책임과 위험을 검토해야 한다.

7. 참고 링크

1. https://www.postgresql.org/docs/18/release-18.html
2. https://www.postgresql.org/docs/18/auth-oauth.html
3. https://www.postgresql.org/docs/18/libpq-oauth.html
4. https://www.postgresql.org/docs/18/oauth-validator-callbacks.html