20.15. Авторизация/аутентификация по OAuth #

OAuth 2.0 — стандартизированный механизм, определённый в RFC 6749, который позволяет сторонним приложениям получать ограниченный доступ к защищённым ресурсам. Поддержка клиента OAuth должна быть включена при сборке PostgreSQL; за дополнительными сведениями обратитесь к Главе 17.

Для описания экосистемы OAuth в документации используются следующие термины:

Владелец ресурса (или конечный пользователь)

Пользователь или система, которая владеет защищёнными ресурсами и может предоставлять доступ к ним. В документации также используется термин конечный пользователь, если владельцем ресурса является человек. Если для подключения к БД по OAuth используется psql, вы являетесь владельцем ресурса/конечным пользователем.

Клиент

Система, которая обращается к защищённым ресурсам, используя токены доступа. Приложения, использующие libpq, например psql, являются клиентами OAuth при подключении к кластеру PostgreSQL.

Сервер ресурса

Система, где размещены защищённые ресурсы, к которым обращается клиент. Сервером ресурса является кластер PostgreSQL, к которому происходит подключение.

Поставщик

Организация, поставщик продукта или иной субъект, который разрабатывает и/или администрирует серверы и клиенты авторизации OAuth для определённого приложения. Разные поставщики обычно выбирают разные способы реализации своих OAuth-систем. Как правило, не гарантируется, что клиент одного поставщика сможет обращаться к серверам другого поставщика.

Использование термина «поставщик» (provider) в этом смысле не является стандартным, но, по всей видимости, уже широко используется. (Его не следует путать с термином «поставщик удостоверений» (identity provider) в контексте OpenID. Хотя OAuth в PostgreSQL реализован взаимно совместимым с протоколом OpenID Connect/OIDC, сам по себе клиентом OIDC он не является и не требует его использовать.)

Сервер авторизации

Система, получающая запросы от клиента и выпускающая токены доступа для него, после получения одобрения от аутентифицированного владельца ресурса. PostgreSQL не предоставляет сервер авторизации — за это отвечает поставщик OAuth.

Издатель

Идентификатор сервера авторизации (в виде URL c https://), предоставляющего доверенное «пространство имён» для клиентов и приложений OAuth. Идентификатор издателя позволяет одному серверу авторизации взаимодействовать с клиентами недоверяющих друг другу субъектов, использующих разных издателей.

Примечание

Для небольших окружений существенных различий между понятиями «поставщик», «сервер авторизации» и «издатель» может не быть. Однако в более сложных возможны взаимосвязи один-ко-многим (или многие-ко-многим): поставщик может выпускать несколько идентификаторов издателей разным арендаторам и затем предоставлять несколько серверов авторизации (возможно, с разными наборами поддерживаемой функциональности) для взаимодействия с клиентами.

PostgreSQL поддерживает токены типа bearer, которые определены в RFC 6750 как тип токенов доступа, используемых с протоколом OAuth 2.0, где токен является непрозрачной строкой. Формат токена доступа зависит от реализации и выбирается каждым сервером авторизации.

Для протокола OAuth доступны следующие параметры конфигурации:

issuer

Адрес с HTTPS, который либо полностью совпадает с идентификатором издателя сервера авторизации, как определено в документе обнаружения, либо является известным URI, который указывает прямо на документ обнаружения. Это обязательный параметр.

Когда клиент OAuth подключается к серверу, адрес для документа обнаружения создаётся с помощью идентификатора издателя. По умолчанию этот адрес соответствует соглашениям OpenID Connect Discovery: путь /.well-known/openid-configuration добавляется в конце идентификатора издателя. Как вариант, если параметр issuer содержит сегмент пути /.well-known/, адрес предоставляется клиенту как есть.

Предупреждение

Клиент OAuth в libpq требует, чтобы значение параметра сервера issuer полностью совпадало с идентификатором издателя, который содержится в документе обнаружения. А значение идентификатора издателя, в свою очередь, должно совпадать со значением параметра oauth_issuer клиента. При этом совпадение должно быть строгое — варианты регистра и форматирования не допускаются.

scope

Разделённый пробелами список сфер действия OAuth, необходимых серверу для авторизации клиента и аутентификации пользователя. Корректные значения определяет сервер авторизации и используемый модуль проверки OAuth (за дополнительной информацией о модулях проверки обратитесь к Главе 50). Это обязательный параметр.

validator

Библиотека для проверки токенов типа bearer. Если задаётся, имя должно полностью совпадать с одной из библиотек, указанных в oauth_validator_libraries. Этот параметр является обязательным, только если в oauth_validator_libraries указано больше одной библиотеки.

map

Позволяет сопоставлять имена поставщиков удостоверений OAuth с именами пользователей БД. За дополнительной информацией обратитесь к Разделу 20.2. Если сопоставление не указано, имя пользователя, связанное с токеном (как определено модулем проверки OAuth), должно полностью совпадать с именем запрашиваемой роли. Это необязательный параметр.

delegate_ident_mapping

Дополнительный параметр, не предназначенный для широкого использования.

Если задано значение 1, стандартное сопоставление пользователей при помощи pg_ident.conf пропускается и за сопоставление удостоверений конечных пользователей с ролями БД начинает отвечать модуль проверки OAuth. Если модуль проверки авторизует токен, сервер доверяет тому, что пользователю разрешено подключаться с запрошенной ролью и что подключение должно состояться вне зависимости от статуса аутентификации пользователя.

Этот параметр несовместим с map.

Предупреждение

Параметр delegate_ident_mapping обеспечивает дополнительную гибкость в проектировании системы аутентификации, однако требует аккуратной реализации модуля проверки OAuth. Такой модуль должен определять, обеспечивает ли токен достаточный уровень прав конечного пользователя в дополнение к стандартным проверкам, которые должны выполнять все модули проверки. Используйте этот параметр с осторожностью.

20.15. OAuth Authorization/Authentication #

OAuth 2.0 is an industry-standard framework, defined in RFC 6749, to enable third-party applications to obtain limited access to a protected resource. OAuth client support has to be enabled when PostgreSQL is built, see Chapter 17 for more information.

This documentation uses the following terminology when discussing the OAuth ecosystem:

Resource Owner (or End User)

The user or system who owns protected resources and can grant access to them. This documentation also uses the term end user when the resource owner is a person. When you use psql to connect to the database using OAuth, you are the resource owner/end user.

Client

The system which accesses the protected resources using access tokens. Applications using libpq, such as psql, are the OAuth clients when connecting to a PostgreSQL cluster.

Resource Server

The system hosting the protected resources which are accessed by the client. The PostgreSQL cluster being connected to is the resource server.

Provider

The organization, product vendor, or other entity which develops and/or administers the OAuth authorization servers and clients for a given application. Different providers typically choose different implementation details for their OAuth systems; a client of one provider is not generally guaranteed to have access to the servers of another.

This use of the term "provider" is not standard, but it seems to be in wide use colloquially. (It should not be confused with OpenID's similar term "Identity Provider". While the implementation of OAuth in PostgreSQL is intended to be interoperable and compatible with OpenID Connect/OIDC, it is not itself an OIDC client and does not require its use.)

Authorization Server

The system which receives requests from, and issues access tokens to, the client after the authenticated resource owner has given approval. PostgreSQL does not provide an authorization server; it is the responsibility of the OAuth provider.

Issuer

An identifier for an authorization server, printed as an https:// URL, which provides a trusted "namespace" for OAuth clients and applications. The issuer identifier allows a single authorization server to talk to the clients of mutually untrusting entities, as long as they maintain separate issuers.

Note

For small deployments, there may not be a meaningful distinction between the "provider", "authorization server", and "issuer". However, for more complicated setups, there may be a one-to-many (or many-to-many) relationship: a provider may rent out multiple issuer identifiers to separate tenants, then provide multiple authorization servers, possibly with different supported feature sets, to interact with their clients.

PostgreSQL supports bearer tokens, defined in 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 authorization server.

The following configuration options are supported for OAuth:

issuer

An HTTPS URL which is either the exact issuer identifier of the authorization server, as defined by its discovery document, or a well-known URI that points directly to that discovery document. This parameter is required.

When an OAuth client connects to the server, a URL for the discovery document will be constructed using the issuer identifier. By default, this URL uses the conventions of OpenID Connect Discovery: the path /.well-known/openid-configuration will be appended to the end of the issuer identifier. Alternatively, if the issuer contains a /.well-known/ path segment, that URL will be provided to the client as-is.

Warning

The OAuth client in libpq requires the server's issuer setting to exactly match the issuer identifier which is provided in the discovery document, which must in turn match the client's oauth_issuer setting. No variations in case or formatting are permitted.

scope

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 Chapter 50 for more information on validators). This parameter is required.

validator

The library to use for validating bearer tokens. If given, the name must exactly match one of the libraries listed in oauth_validator_libraries. This parameter is optional unless oauth_validator_libraries contains more than one library, in which case it is required.

map

Allows for mapping between OAuth identity provider and database user names. See Section 20.2 for details. If a 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.

delegate_ident_mapping

An advanced option which is not intended for common use.

When set to 1, standard user mapping with pg_ident.conf 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.

Warning

delegate_ident_mapping 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.

FAQ