diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 8d351c2089..c5d1a1fe69 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -2341,7 +2341,7 @@ host ... radius radiusservers="server1,server2" radiussecrets="""secret one"",""
to enable third-party applications to obtain limited access to a protected
resource.
- OAuth support has to be enabled when PostgreSQL
+ OAuth client support has to be enabled when PostgreSQL
is built, see for more information.
@@ -2353,23 +2353,23 @@ host ... radius radiusservers="server1,server2" radiussecrets="""secret one"",""
- Client: The system which accesses to the protected resources using access
+ Client: The system which accesses the protected resources using access
tokens. Applications using libpq are the clients in connecting to a
PostgreSQL cluster.
- Authentication server: The system which recieves requests from, and
- issues access tokens to, the client upon successful authentication by
- the resource owner.
+ Authorization server: The system which receives requests from, and
+ issues access tokens to, the client after the authenticated resource
+ owner has given approval.
- Resource server: The system which owns the protected resources and can
- grant access to them. The PostgreSQL cluster
+ Resource server: The system which hosts the protected resources which are
+ accessed by the client. The PostgreSQL cluster
being connected to is the resource server.
@@ -2379,7 +2379,7 @@ host ... radius radiusservers="server1,server2" radiussecrets="""secret one"",""
PostgreSQL supports bearer tokens, defined in
- RFC 6750
+ RFC 6750,
which are a type of access token used with OAuth 2.0 where the token is an
opaque string. The format of the access token is implementation specific
and is chosen by each authentication server.
@@ -2402,10 +2402,11 @@ host ... radius radiusservers="server1,server2" radiussecrets="""secret one"",""
scope
- The OAuth scope required for the server to authenticate and/or authorize
- the user. The value of the scope is dependent on the OAuth validation
- module used (see for more information
- on validators). This parameter is required.
+ A space-separated list of the OAuth scopes needed for the server to
+ both authorize the client and authenticate the user. Appropriate values
+ are determined by the authorization server and the OAuth validation
+ module used (see for more
+ information on validators). This parameter is required.
@@ -2416,8 +2417,9 @@ host ... radius radiusservers="server1,server2" radiussecrets="""secret one"",""
Allows for mapping between OAuth identity provider and database user
names. See for details. If a
- map is not specified the user name returned from the OAuth validator
- must match the role being requested. This parameter is optional.
+ map is not specified, the user name associated with the token (as
+ determined by the OAuth validator) must exactly match the role name
+ being requested. This parameter is optional.
@@ -2426,10 +2428,29 @@ host ... radius radiusservers="server1,server2" radiussecrets="""secret one"",""
trust_validator_authz
- When set to 1 standard user mapping is skipped. If
- the OAuth token is validated the user can connect under its desired
- role.
+ An advanced option which is not intended for common use.
+
+ When set to 1, standard user mapping is skipped, and
+ the OAuth validator takes full responsibility for mapping end user
+ identities to database roles. If the validator authorizes the token,
+ the server trusts that the user is allowed to connect under the
+ requested role, and the connection is allowed to proceed regardless of
+ the authentication status of the user.
+
+
+ This parameter is incompatible with map.
+
+
+
+ trust_validator_authz provides additional
+ flexibility in the design of the authentication system, but it also
+ requires careful implementation of the OAuth validator, which must
+ determine whether the provided token carries sufficient end-user
+ privileges in addition to the standard
+ checks required of all validators. Use with caution.
+
+
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 73bf21c599..7cb3afb7af 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1202,19 +1202,6 @@ include_dir 'conf.d'
-
- oauth_validator_library (string)
-
- oauth_validator_library configuration parameter
-
-
-
-
- TODO
-
-
-
-
oauth_validator_library (string)
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 86fd146af2..62b8ae3b42 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -2341,7 +2341,12 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
oauth_client_id
- The client identifier as issued by the authorization server.
+ An OAuth 2.0 client identifier, as issued by the authorization server.
+ If the PostgreSQL server
+ requests an OAuth token for the
+ connection (and if no custom OAuth
+ hook is installed to provide one), then this parameter must be
+ set; otherwise, the connection will fail.
@@ -2350,7 +2355,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
oauth_client_secret
- The client password.
+ The client password, if any, to use when contacting the OAuth
+ authorization server. Whether this parameter is required or not is
+ determined by the OAuth provider; "public" clients generally do not use
+ a secret, whereas "confidential" clients generally do.
@@ -2359,7 +2367,27 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
oauth_issuer
- TODO
+ The HTTPS URL of an issuer to contact if the server requests an OAuth
+ token for the connection. This parameter is optional and intended for
+ advanced usage; see also .
+
+
+ If no oauth_issuer is provided, the client will ask
+ the PostgreSQL server to provide an
+ acceptable issuer URL (as configured in its
+ HBA settings). This is convenient, but
+ it requires two separate network connections to the server per attempt.
+
+
+ Providing an explicit oauth_issuer (and, typically,
+ an accompanying oauth_scope) skips this initial
+ "discovery" phase, which may speed up certain custom OAuth flows.
+
+ This parameter may also be set defensively, to prevent the backend
+ server from directing the client to arbitrary URLs.
+ However: if the client's issuer setting differs
+ from the server's expected issuer, the server is likely to reject the
+ issued token, and the connection will fail.
@@ -2368,8 +2396,26 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
oauth_scope
- The scope of the access request sent to the authorization server.
- This parameter is optional.
+ The scope of the access request sent to the authorization server,
+ specified as a (possibly empty) space-separated list of OAuth scope
+ identifiers. This parameter is optional and intended for advanced usage.
+
+
+
+ If neither nor
+ oauth_scope is specified, the client will obtain
+ appropriate scope settings from the
+ PostgreSQL server. Otherwise, the value of
+ this parameter will be used. Similarly to
+ oauth_issuer, if the client's scope setting does not
+ contain the server's required scopes, the server is likely to reject the
+ issued token, and the connection will fail.
+
+
+ The meaning of an empty scope list is provider-dependent. An OAuth
+ authorization server may choose to issue a token with "default scope",
+ whatever that happens to be, or it may reject the token request
+ entirely.
diff --git a/src/backend/libpq/auth-oauth.c b/src/backend/libpq/auth-oauth.c
index cfa5769b10..90e68dbc93 100644
--- a/src/backend/libpq/auth-oauth.c
+++ b/src/backend/libpq/auth-oauth.c
@@ -669,7 +669,7 @@ cleanup:
*
* Load the configured validator library in order to perform token validation.
* There is no built-in fallback since validation is implementation specific. If
- * no validator library is configured, or of it fails to load, then error out
+ * no validator library is configured, or if it fails to load, then error out
* since token validation won't be possible.
*/
static void
diff --git a/src/backend/libpq/hba.c b/src/backend/libpq/hba.c
index dcb1558ad3..c623b8463d 100644
--- a/src/backend/libpq/hba.c
+++ b/src/backend/libpq/hba.c
@@ -2482,20 +2482,17 @@ parse_hba_auth_opt(char *name, char *val, HbaLine *hbaline,
}
else if (strcmp(name, "issuer") == 0)
{
- if (hbaline->auth_method != uaOAuth)
- INVALID_AUTH_OPTION("issuer", gettext_noop("oauth"));
+ REQUIRE_AUTH_OPTION(uaOAuth, "issuer", "oauth");
hbaline->oauth_issuer = pstrdup(val);
}
else if (strcmp(name, "scope") == 0)
{
- if (hbaline->auth_method != uaOAuth)
- INVALID_AUTH_OPTION("scope", gettext_noop("oauth"));
+ REQUIRE_AUTH_OPTION(uaOAuth, "scope", "oauth");
hbaline->oauth_scope = pstrdup(val);
}
else if (strcmp(name, "trust_validator_authz") == 0)
{
- if (hbaline->auth_method != uaOAuth)
- INVALID_AUTH_OPTION("trust_validator_authz", gettext_noop("oauth"));
+ REQUIRE_AUTH_OPTION(uaOAuth, "trust_validator_authz", "oauth");
if (strcmp(val, "1") == 0)
hbaline->oauth_skip_usermap = true;
else
diff --git a/src/backend/libpq/pg_hba.conf.sample b/src/backend/libpq/pg_hba.conf.sample
index bad13497a3..b64c8dea97 100644
--- a/src/backend/libpq/pg_hba.conf.sample
+++ b/src/backend/libpq/pg_hba.conf.sample
@@ -53,8 +53,8 @@
# directly connected to.
#
# METHOD can be "trust", "reject", "md5", "password", "scram-sha-256",
-# "gss", "sspi", "ident", "peer", "pam", "ldap", "radius" or "cert".
-# Note that "password" sends passwords in clear text; "md5" or
+# "gss", "sspi", "ident", "peer", "pam", "oauth", "ldap", "radius" or
+# "cert". Note that "password" sends passwords in clear text; "md5" or
# "scram-sha-256" are preferred since they send encrypted passwords.
#
# OPTIONS are a set of options for the authentication in the format