2025年9月25日: PostgreSQL 18 发布!
支持的版本: 当前 (18)
开发版本: devel

20.15. OAuth 授权/认证 #

OAuth 2.0 是一个行业标准框架,定义在 RFC 6749 中,它允许第三方应用程序获得对受保护资源的有限访问权限。当构建 PostgreSQL 时,必须启用 OAuth 客户端支持,有关更多信息,请参阅 第 17 章

在讨论 OAuth 生态系统时,本文档使用以下术语:

资源所有者(或最终用户)

拥有受保护资源并可以授予对这些资源访问权限的用户或系统。当资源所有者是个人时,本文档也使用“最终用户”一词。当您使用 psql 通过 OAuth 连接到数据库时,您就是资源所有者/最终用户。

客户端

使用访问令牌访问受保护资源的系统。当连接到 PostgreSQL 集群时,使用 libpq 的应用程序(如 psql)是 OAuth 客户端。

资源服务器

托管客户端访问的受保护资源的系统。连接到的 PostgreSQL 集群是资源服务器。

提供商

开发和/或管理给定应用程序的 OAuth 授权服务器和客户端的组织、产品供应商或其他实体。不同的提供商通常会为他们的 OAuth 系统选择不同的实现细节;一个提供商的客户端通常不能保证访问另一个提供商的服务器。

“提供商”一词的用法并不标准,但似乎在口语中有广泛使用。(不应将其与 OpenID 类似的术语“身份提供商”混淆。虽然 PostgreSQL 中的 OAuth 实现旨在与 OpenID Connect/OIDC 互操作并兼容,但它本身不是 OIDC 客户端,也不需要使用 OIDC。)

授权服务器

在经过身份验证的资源所有者已获得批准后,接收来自客户端的请求并向客户端颁发访问令牌的系统。PostgreSQL 不提供授权服务器;这是 OAuth 提供商的责任。

颁发者

授权服务器的标识符,以 https:// URL 的形式打印,为 OAuth 客户端和应用程序提供可信的“命名空间”。颁发者标识符允许单个授权服务器与互不信任的实体的客户端进行通信,只要它们维护独立的颁发者。

注意

对于小型部署,可能“提供商”、“授权服务器”和“颁发者”之间没有明显的区别。然而,对于更复杂的设置,可能存在一对多(或多对多)的关系:提供商可能将多个颁发者标识符租给不同的租户,然后提供多个授权服务器,可能具有不同的支持功能集,以与他们的客户端进行交互。

PostgreSQL 支持 RFC 6750 中定义的持有者令牌(bearer tokens),这是一种与 OAuth 2.0 配合使用的访问令牌类型,其中令牌是匿名字符串。访问令牌的格式是实现特定的,并由每个授权服务器选择。

以下配置选项支持 OAuth:

issuer

一个 HTTPS URL,它要么是授权服务器的精确 颁发者标识符(根据其发现文档定义),要么是一个指向该发现文档本身的知名 URI。此参数是必需的。

当 OAuth 客户端连接到服务器时,将使用颁发者标识符构建发现文档的 URL。默认情况下,该 URL 使用 OpenID Connect Discovery 的约定:将在颁发者标识符的末尾附加路径 /.well-known/openid-configuration。或者,如果 issuer 包含 /.well-known/ 路径段,则该 URL 将按原样提供给客户端。

警告

libpq 中的 OAuth 客户端要求服务器的颁发者设置必须与发现文档中提供的颁发者标识符完全匹配,而发现文档又必须匹配客户端的 oauth_issuer 设置。不允许有任何大小写或格式上的差异。

scope

用于服务器授权客户端和认证用户的 OAuth 范围列表,以空格分隔。适当的值由授权服务器和使用的 OAuth 验证模块确定(有关验证模块的更多信息,请参阅 第 50 章)。此参数是必需的。

validator

用于验证持有者令牌的库。如果给定,名称必须与 oauth_validator_libraries 中列出的库之一完全匹配。除非 oauth_validator_libraries 包含多个库,否则此参数是可选的,但在这种情况下是必需的。

map

允许 OAuth 身份提供商和数据库用户名称之间的映射。有关详细信息,请参阅 第 20.2 节。如果未指定映射,则令牌关联的用户名称(由 OAuth 验证器确定)必须与请求的角色名称完全匹配。此参数是可选的。

delegate_ident_mapping

一个高级选项,不用于常见用途。

当设置为 1 时,将跳过与 pg_ident.conf 的标准用户映射,OAuth 验证器将全权负责将最终用户身份映射到数据库角色。如果验证器授权了令牌,则服务器会信任用户有权以请求的角色连接,并且即使用户身份验证状态如何,连接也可以继续。

此参数与 map 不兼容。

警告

delegate_ident_mapping 为身份验证系统的设计提供了额外的灵活性,但它也要求 OAuth 验证器的仔细实现,该验证器必须确定提供的令牌是否带有足够的最终用户权限,以及 所有验证器所需的标准检查。请谨慎使用。

提交更正

如果您在文档中看到任何不正确、与您对特定功能的体验不符或需要进一步澄清的内容,请使用 此表单 报告文档问题。