mirror of
https://github.com/pgadmin-org/pgadmin4.git
synced 2026-11-03 12:49:23 -06:00
Kundan SableandClaude Sonnet 5
8ed0ecc06b
Two non-blocking items from asheshv/pgAdmin4-cve#66's approval review: - The auth_source lockout remedy was circular for the deployments most likely to hit it: telling a locked-out admin to "sign in through another authentication source" doesn't help when AUTHENTICATION_SOURCES = ['webserver'] and there is no other source. Documented the actual way out - temporarily add 'internal' back, fix the affected users, remove it again. - A malformed WEBSERVER_REMOTE_USER (not a non-empty string) was demoted to info logging along with the client-triggered rejections in the previous round, but it's a static operator misconfiguration, not something a client varies per request - at info it would go unnoticed while every header-based login silently fails. Moved back to warning, consistent with the other config-error checks. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
99 lines
5.5 KiB
ReStructuredText
99 lines
5.5 KiB
ReStructuredText
.. _webserver:
|
||
|
||
********************************************
|
||
`Enabling Webserver Authentication`:index:
|
||
********************************************
|
||
|
||
To configure Webserver authentication, you must setup your webserver
|
||
with any authentication plug-in (such as Shibboleth, HTTP BASIC auth)
|
||
as long as it sets the REMOTE_USER environment variable.
|
||
To enable Webserver authentication for pgAdmin, you must configure the Webserver
|
||
settings in the *config_local.py* or *config_system.py* file (see the
|
||
:ref:`config.py <config_py>` documentation) on the system where pgAdmin is
|
||
installed in Server mode. You can copy these settings from *config.py* file
|
||
and modify the values for the following parameters:
|
||
|
||
|
||
.. csv-table::
|
||
:header: "**Parameter**", "**Description**"
|
||
:class: longtable
|
||
:widths: 35, 55
|
||
|
||
"AUTHENTICATION_SOURCES", "The default value for this parameter is *internal*.
|
||
To enable OAUTH2 authentication, you must include *webserver* in the list of values
|
||
for this parameter. you can modify the value as follows:
|
||
|
||
* [‘webserver’]: pgAdmin will use only Webserver authentication.
|
||
|
||
* [‘webserver’, ‘internal’]: pgAdmin will first try to authenticate the user
|
||
through webserver. If that authentication fails, then it will return back
|
||
to the login page where you need to provide internal pgAdmin user
|
||
credentials for authentication."
|
||
"WEBSERVER_AUTO_CREATE_USER", "Set the value to *True* if you want to automatically
|
||
create a pgAdmin user corresponding to a successfully authenticated Webserver user.
|
||
Please note that password is not stored in the pgAdmin database."
|
||
"WEBSERVER_REMOTE_USER", "To get the web server remote user details, set this variable to any header or
|
||
environment variable name which comes from the web server after webserver authentication.
|
||
The default value is REMOTE_USER and the possible values are REMOTE_USER,
|
||
HTTP_X_FORWARDED_USER, X-Forwarded-User."
|
||
"WEBSERVER_REMOTE_USER_FROM_HEADER", "Set to *True* only if your reverse proxy passes the
|
||
authenticated identity as an HTTP request header rather than the REMOTE_USER CGI variable.
|
||
Defaults to *False*. See the warning below before enabling this."
|
||
"WEBSERVER_TRUSTED_PROXIES", "A list of IP addresses/CIDR ranges of the reverse proxies
|
||
that are allowed to assert the identity header. Required (non-empty) for
|
||
WEBSERVER_REMOTE_USER_FROM_HEADER to take effect. Defaults to an empty list."
|
||
"WEBSERVER_SHARED_SECRET", "An optional shared secret that the trusted proxy must inject
|
||
into every request, as additional proof that the identity header was set by the proxy
|
||
and not the client. Defaults to *None* (not checked)."
|
||
"WEBSERVER_SHARED_SECRET_HEADER", "The header name carrying WEBSERVER_SHARED_SECRET.
|
||
Defaults to *X-Pgadmin-Webserver-Secret*."
|
||
|
||
.. warning::
|
||
Setting WEBSERVER_REMOTE_USER to a header-derived name (such as
|
||
HTTP_X_FORWARDED_USER, or REMOTE-USER/Remote-user) means the identity is
|
||
read from a client-controlled HTTP request header, not necessarily a
|
||
value set by your webserver's authentication plug-in. Any client that
|
||
can reach pgAdmin can set this header itself and impersonate any user,
|
||
including an existing Administrator, unless you:
|
||
|
||
* Set ``WEBSERVER_REMOTE_USER_FROM_HEADER = True``.
|
||
* List every reverse proxy allowed to assert the identity in
|
||
``WEBSERVER_TRUSTED_PROXIES``.
|
||
* Configure your reverse proxy to strip *every* inbound spelling of the
|
||
header (any hyphen/underscore variant, in any case) before it sets its
|
||
own, so a client cannot smuggle a value past it.
|
||
* Optionally configure ``WEBSERVER_SHARED_SECRET`` /
|
||
``WEBSERVER_SHARED_SECRET_HEADER`` as an additional proof that the
|
||
header was set by your proxy.
|
||
|
||
Without all of the above, pgAdmin does not trust a header-asserted
|
||
identity and login through it is rejected.
|
||
|
||
.. warning::
|
||
A user matched via Webserver authentication is only logged in if their
|
||
*Authentication source* is *webserver*. This prevents a header-asserted
|
||
identity from ever logging into an account that was created some other
|
||
way - most importantly, the default administrator account created by
|
||
pgAdmin's own setup, whose *Authentication source* is *internal*.
|
||
|
||
If you are enabling Webserver authentication on a site that already has
|
||
users (including that default administrator) with an *Authentication
|
||
source* other than *webserver*, none of them will be able to log in
|
||
through Webserver authentication until you change it. To do so, sign in
|
||
through another configured authentication source and, for each such
|
||
user, set *Authentication source* to *webserver* on the
|
||
:ref:`User Management <user_management>` page. If ``AUTHENTICATION_SOURCES``
|
||
lists only *webserver*, there is no other source to sign in with -
|
||
temporarily add *internal* back to ``AUTHENTICATION_SOURCES``, sign in
|
||
with the internal administrator's password, fix the affected users'
|
||
*Authentication source*, then remove *internal* again.
|
||
|
||
Master Password
|
||
===============
|
||
|
||
In the multi user mode, pgAdmin uses user's login password to encrypt/decrypt the PostgreSQL server password.
|
||
In the Webserver authentication, the pgAdmin does not store the user's password, so we need an encryption key to store
|
||
the PostgreSQL server password.
|
||
To accomplish this, set the configuration parameter MASTER_PASSWORD to *True*, so upon setting the master password,
|
||
it will be used as an encryption key while storing the password. If it is False, the server password can not be stored.
|