From: Marko Kreen <markokr@gmail.com>
Date: Thu, 18 Feb 2016 16:36:42 +0000 (+0200)
Subject: doc: improve auth_user docs
X-Git-Tag: pgbouncer_1_7_1~1
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=cf6c46c742ba44e05859cc9a6c5682120ec39641;p=pgbouncer

doc: improve auth_user docs
---

diff --git a/doc/config.rst b/doc/config.rst
index 1a863ae..b3abfbc 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -134,7 +134,10 @@ any
 auth_query
 ----------
 
-Query to load user's password from db.
+Query to load user's password from database.
+
+Direct access to pg_shadow requires admin rights.  It's preferable to
+use non-admin user that calls SECURITY DEFINER function instead.
 
 Default: ``SELECT usename, passwd FROM pg_shadow WHERE usename=$1``
 
@@ -848,8 +851,11 @@ auth_user
 ---------
 
 If ``auth_user`` is set, any user not specified in auth_file will be
-queried from pg_shadow in the database using auth_user. Auth_user's
-password will be taken from auth_file.
+queried from pg_shadow in the database using ``auth_user``. Auth_user's
+password will be taken from ``auth_file``.
+
+Direct access to pg_shadow requires admin rights.  It's preferable to
+use non-admin user that calls SECURITY DEFINER function instead.
 
 pool_size
 ---------
@@ -996,6 +1002,20 @@ Database defaults::
   ; access to destination database will go with single user
   forcedb = host=127.0.0.1 port=300 user=baz password=foo client_encoding=UNICODE datestyle=ISO
 
+Example of secure function for auth_query::
+
+  CREATE OR REPLACE FUNCTION pgbouncer.user_lookup(in i_username text, out uname text, out phash text)
+  RETURNS record AS $$
+  BEGIN
+      SELECT usename, passwd FROM pg_catalog.pg_shadow
+      WHERE usename = i_username INTO uname, phash;
+      RETURN;
+  END;
+  $$ LANGUAGE plpgsql SECURITY DEFINER;
+  REVOKE ALL ON FUNCTION pgbouncer.user_lookup(text) FROM public, pgbouncer;
+  GRANT EXECUTE ON FUNCTION pgbouncer.user_lookup(text) TO pgbouncer;
+
+
 See also
 ========