{"Entry":{"collection":"auth","key":"oauth","name":"oauth","aliases":[],"metadata":{"aliases":[],"category":"Authentication and access control","content_hash":"adcc9e3a1de9c0fb61793cd1ddaf7b9442b64cbfee41a896c84a61309f46c424","imported_at":"2026-09-30T00:40:33.311433+08:00","name":"oauth","name_zh":"","slug":"oauth","summary":"Authorize and optionally authenticate using a third-party OAuth 2.0 identity provider. See Section 20.14 for details."}},"Definition":{"Collection":"auth","Key":"oauth","SourceDatabase":"center","Version":"18","SourceTable":"authentication_method","SourceKey":"oauth","SourceRevision":"555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f","Facts":{"aliases":[],"attributes":{"configuration":"pg_hba.conf","inventory":"User-visible source authentication method","method":"oauth"},"comparison_data":{"documented_option_names":["Authorization Server","Client","Issuer","Provider","Resource Owner (or End User)","Resource Server","delegate_ident_mapping","issuer","map","scope","validator"],"method":"oauth"},"comparison_hash":"614b1b99c2894fb23e3ddaf7706a1e06dd6cc3fd020965f4d8e18ed32ea3a772","description":["Authorize and optionally authenticate using a third-party OAuth 2.0 identity provider. See Section 20.15 for details."],"facts":[{"label":"Method","value":"oauth"},{"label":"Configuration","value":"pg_hba.conf"},{"label":"Inventory","value":"User-visible source authentication method"}],"manual_html":"\u003cdiv class=\"sect1\" id=\"AUTH-OAUTH\"\u003e\n\u003cdiv class=\"titlepage\"\u003e\n\u003cdiv\u003e\n\u003cdiv\u003e\n\u003ch2 class=\"title\"\u003e20.15. OAuth Authorization/Authentication \u003c/h2\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003cp\u003eOAuth 2.0 is an industry-standard framework, defined in \u003ca class=\"ulink\" href=\"https://datatracker.ietf.org/doc/html/rfc6749\"\u003eRFC 6749\u003c/a\u003e, to enable third-party applications to obtain limited access to a protected resource. OAuth client support has to be enabled when \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e is built, see \u003ca class=\"xref\" href=\"/docs/18/installation.html\" title=\"Chapter 17. Installation from Source Code\"\u003eChapter 17\u003c/a\u003e for more information.\u003c/p\u003e\n\u003cp\u003eThis documentation uses the following terminology when discussing the OAuth ecosystem:\u003c/p\u003e\n\u003cdiv class=\"variablelist\"\u003e\n\u003cdl class=\"variablelist\"\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003eResource Owner (or End User)\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe user or system who owns protected resources and can grant access to them. This documentation also uses the term \u003cspan class=\"emphasis\"\u003e\u003cem\u003eend user\u003c/em\u003e\u003c/span\u003e when the resource owner is a person. When you use \u003cspan class=\"application\"\u003epsql\u003c/span\u003e to connect to the database using OAuth, you are the resource owner/end user.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003eClient\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe system which accesses the protected resources using access tokens. Applications using libpq, such as \u003cspan class=\"application\"\u003epsql\u003c/span\u003e, are the OAuth clients when connecting to a \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e cluster.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003eResource Server\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe system hosting the protected resources which are accessed by the client. The \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e cluster being connected to is the resource server.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003eProvider\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe 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.\u003c/p\u003e\n\u003cp\u003eThis 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 \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e is intended to be interoperable and compatible with OpenID Connect/OIDC, it is not itself an OIDC client and does not require its use.)\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003eAuthorization Server\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe system which receives requests from, and issues access tokens to, the client after the authenticated resource owner has given approval. \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e does not provide an authorization server; it is the responsibility of the OAuth provider.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\" id=\"AUTH-OAUTH-ISSUER\"\u003eIssuer\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eAn identifier for an authorization server, printed as an \u003ccode class=\"literal\"\u003ehttps://\u003c/code\u003e 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003c/dl\u003e\n\u003c/div\u003e\n\u003cdiv class=\"note\"\u003e\n\u003ch3 class=\"title\"\u003eNote\u003c/h3\u003e\n\u003cp\u003eFor 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.\u003c/p\u003e\n\u003c/div\u003e\n\u003cp\u003e\u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e supports bearer tokens, defined in \u003ca class=\"ulink\" href=\"https://datatracker.ietf.org/doc/html/rfc6750\"\u003eRFC 6750\u003c/a\u003e, 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.\u003c/p\u003e\n\u003cp\u003eThe following configuration options are supported for OAuth:\u003c/p\u003e\n\u003cdiv class=\"variablelist\"\u003e\n\u003cdl class=\"variablelist\"\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"literal\"\u003eissuer\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eAn HTTPS URL which is either the exact \u003ca class=\"link\" href=\"/docs/18/auth-oauth.html#AUTH-OAUTH-ISSUER\"\u003eissuer identifier\u003c/a\u003e 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.\u003c/p\u003e\n\u003cp\u003eWhen 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 \u003ccode class=\"literal\"\u003e/.well-known/openid-configuration\u003c/code\u003e will be appended to the end of the issuer identifier. Alternatively, if the \u003ccode class=\"literal\"\u003eissuer\u003c/code\u003e contains a \u003ccode class=\"literal\"\u003e/.well-known/\u003c/code\u003e path segment, that URL will be provided to the client as-is.\u003c/p\u003e\n\u003cdiv class=\"warning\"\u003e\n\u003ch3 class=\"title\"\u003eWarning\u003c/h3\u003e\n\u003cp\u003eThe 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 \u003ca class=\"xref\" href=\"/docs/18/libpq-connect.html#LIBPQ-CONNECT-OAUTH-ISSUER\"\u003eoauth_issuer\u003c/a\u003e setting. No variations in case or formatting are permitted.\u003c/p\u003e\n\u003c/div\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"literal\"\u003escope\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eA 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 \u003ca class=\"xref\" href=\"/docs/18/oauth-validators.html\" title=\"Chapter 50. OAuth Validator Modules\"\u003eChapter 50\u003c/a\u003e for more information on validators). This parameter is required.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"literal\"\u003evalidator\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe library to use for validating bearer tokens. If given, the name must exactly match one of the libraries listed in \u003ca class=\"xref\" href=\"/docs/18/runtime-config-connection.html#GUC-OAUTH-VALIDATOR-LIBRARIES\"\u003eoauth_validator_libraries\u003c/a\u003e. This parameter is optional unless \u003ccode class=\"literal\"\u003eoauth_validator_libraries\u003c/code\u003e contains more than one library, in which case it is required.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"literal\"\u003emap\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eAllows for mapping between OAuth identity provider and database user names. See \u003ca class=\"xref\" href=\"/docs/18/auth-username-maps.html\" title=\"20.2. User Name Maps\"\u003eSection 20.2\u003c/a\u003e 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\" id=\"AUTH-OAUTH-DELEGATE-IDENT-MAPPING\"\u003e\u003ccode class=\"literal\"\u003edelegate_ident_mapping\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eAn advanced option which is not intended for common use.\u003c/p\u003e\n\u003cp\u003eWhen set to \u003ccode class=\"literal\"\u003e1\u003c/code\u003e, standard user mapping with \u003ccode class=\"filename\"\u003epg_ident.conf\u003c/code\u003e 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.\u003c/p\u003e\n\u003cp\u003eThis parameter is incompatible with \u003ccode class=\"literal\"\u003emap\u003c/code\u003e.\u003c/p\u003e\n\u003cdiv class=\"warning\"\u003e\n\u003ch3 class=\"title\"\u003eWarning\u003c/h3\u003e\n\u003cp\u003e\u003ccode class=\"literal\"\u003edelegate_ident_mapping\u003c/code\u003e 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 \u003ca class=\"link\" href=\"/docs/18/oauth-validators.html\" title=\"Chapter 50. OAuth Validator Modules\"\u003estandard checks\u003c/a\u003e required of all validators. Use with caution.\u003c/p\u003e\n\u003c/div\u003e\n\u003c/dd\u003e\n\u003c/dl\u003e\n\u003c/div\u003e\n\u003c/div\u003e","manual_path":"/docs/18/auth-oauth.html","related":[],"release":{"catalog_fingerprint":"65c93d6048ef30e61023a84f9680fa6a92b1c383b7eb226741170077eb078502","channel":"stable","label":"18.6","major":"18","ref":"https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2","revision":"555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f","source_sha256":"555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f"},"sections":[],"signature":"","sources":[{"label":"Matching PostgreSQL source archive","sha256":"555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f","url":"https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2"},{"label":"PostgreSQL 18 English manual","path":"auth-oauth.html","sha256":"1e2e63530e79522cd93d2c34bc34a464927dbe46de9b01cdbf324648f1adda8d","url":"/docs/18/auth-oauth.html"},{"label":"PostgreSQL 18 English manual","path":"auth-pg-hba-conf.html","sha256":"6340d4abea2e0a3482afc31bcd1599a0fa10dc28a6f1e05d79ba831e2dd0b4c9","url":"/docs/18/auth-pg-hba-conf.html"}],"tables":[{"columns":[{"key":"name","label":"Option or term"},{"key":"description","label":"Meaning"}],"key":"method-options","rows":[{"description":"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.","name":"Resource Owner (or End User)"},{"description":"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.","name":"Client"},{"description":"The system hosting the protected resources which are accessed by the client. The PostgreSQL cluster being connected to is the resource server.","name":"Resource Server"},{"description":"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.)","name":"Provider"},{"description":"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.","name":"Authorization Server"},{"description":"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.","name":"Issuer"},{"description":"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.","name":"issuer"},{"description":"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.","name":"scope"},{"description":"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.","name":"validator"},{"description":"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.","name":"map"},{"description":"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.","name":"delegate_ident_mapping"}],"title":"Documented method options and alternatives"}]},"ManualEvidence":{"manual_path":"/docs/18/auth-oauth.html","release":{"catalog_fingerprint":"65c93d6048ef30e61023a84f9680fa6a92b1c383b7eb226741170077eb078502","channel":"stable","label":"18.6","major":"18","ref":"https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2","revision":"555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f","source_sha256":"555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f"},"sources":[{"label":"Matching PostgreSQL source archive","sha256":"555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f","url":"https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2"},{"label":"PostgreSQL 18 English manual","path":"auth-oauth.html","sha256":"1e2e63530e79522cd93d2c34bc34a464927dbe46de9b01cdbf324648f1adda8d","url":"/docs/18/auth-oauth.html"},{"label":"PostgreSQL 18 English manual","path":"auth-pg-hba-conf.html","sha256":"6340d4abea2e0a3482afc31bcd1599a0fa10dc28a6f1e05d79ba831e2dd0b4c9","url":"/docs/18/auth-pg-hba-conf.html"}]},"MeasuredEvidence":{}},"Text":{"Collection":"auth","Key":"oauth","SourceDatabase":"center","Version":"18","Locale":"en","Title":"oauth","Summary":"Authorize and optionally authenticate using a third-party OAuth 2.0 identity provider. See Section 20.15 for details.","BodyHTML":"\u003cdiv id=\"AUTH-OAUTH\"\u003e\n\u003cdiv\u003e\n\u003cdiv\u003e\n\u003cdiv\u003e\n\u003ch2\u003e20.15. OAuth Authorization/Authentication \u003c/h2\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003cp\u003eOAuth 2.0 is an industry-standard framework, defined in \u003ca href=\"https://datatracker.ietf.org/doc/html/rfc6749\" rel=\"nofollow\"\u003eRFC 6749\u003c/a\u003e, to enable third-party applications to obtain limited access to a protected resource. OAuth client support has to be enabled when \u003cspan\u003ePostgreSQL\u003c/span\u003e is built, see \u003ca href=\"/docs/18/installation.html\" rel=\"nofollow\"\u003eChapter 17\u003c/a\u003e for more information.\u003c/p\u003e\n\u003cp\u003eThis documentation uses the following terminology when discussing the OAuth ecosystem:\u003c/p\u003e\n\u003cdiv\u003e\n\u003cdl\u003e\n\u003cdt\u003e\u003cspan\u003eResource Owner (or End User)\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe user or system who owns protected resources and can grant access to them. This documentation also uses the term \u003cspan\u003e\u003cem\u003eend user\u003c/em\u003e\u003c/span\u003e when the resource owner is a person. When you use \u003cspan\u003epsql\u003c/span\u003e to connect to the database using OAuth, you are the resource owner/end user.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003eClient\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe system which accesses the protected resources using access tokens. Applications using libpq, such as \u003cspan\u003epsql\u003c/span\u003e, are the OAuth clients when connecting to a \u003cspan\u003ePostgreSQL\u003c/span\u003e cluster.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003eResource Server\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe system hosting the protected resources which are accessed by the client. The \u003cspan\u003ePostgreSQL\u003c/span\u003e cluster being connected to is the resource server.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003eProvider\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe 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.\u003c/p\u003e\n\u003cp\u003eThis use of the term \u0026#34;provider\u0026#34; is not standard, but it seems to be in wide use colloquially. (It should not be confused with OpenID\u0026#39;s similar term \u0026#34;Identity Provider\u0026#34;. While the implementation of OAuth in \u003cspan\u003ePostgreSQL\u003c/span\u003e is intended to be interoperable and compatible with OpenID Connect/OIDC, it is not itself an OIDC client and does not require its use.)\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003eAuthorization Server\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe system which receives requests from, and issues access tokens to, the client after the authenticated resource owner has given approval. \u003cspan\u003ePostgreSQL\u003c/span\u003e does not provide an authorization server; it is the responsibility of the OAuth provider.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan id=\"AUTH-OAUTH-ISSUER\"\u003eIssuer\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eAn identifier for an authorization server, printed as an \u003ccode\u003ehttps://\u003c/code\u003e URL, which provides a trusted \u0026#34;namespace\u0026#34; 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003c/dl\u003e\n\u003c/div\u003e\n\u003cdiv\u003e\n\u003ch3\u003eNote\u003c/h3\u003e\n\u003cp\u003eFor small deployments, there may not be a meaningful distinction between the \u0026#34;provider\u0026#34;, \u0026#34;authorization server\u0026#34;, and \u0026#34;issuer\u0026#34;. 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.\u003c/p\u003e\n\u003c/div\u003e\n\u003cp\u003e\u003cspan\u003ePostgreSQL\u003c/span\u003e supports bearer tokens, defined in \u003ca href=\"https://datatracker.ietf.org/doc/html/rfc6750\" rel=\"nofollow\"\u003eRFC 6750\u003c/a\u003e, 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.\u003c/p\u003e\n\u003cp\u003eThe following configuration options are supported for OAuth:\u003c/p\u003e\n\u003cdiv\u003e\n\u003cdl\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003eissuer\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eAn HTTPS URL which is either the exact \u003ca href=\"/docs/18/auth-oauth.html#AUTH-OAUTH-ISSUER\" rel=\"nofollow\"\u003eissuer identifier\u003c/a\u003e 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.\u003c/p\u003e\n\u003cp\u003eWhen 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 \u003ccode\u003e/.well-known/openid-configuration\u003c/code\u003e will be appended to the end of the issuer identifier. Alternatively, if the \u003ccode\u003eissuer\u003c/code\u003e contains a \u003ccode\u003e/.well-known/\u003c/code\u003e path segment, that URL will be provided to the client as-is.\u003c/p\u003e\n\u003cdiv\u003e\n\u003ch3\u003eWarning\u003c/h3\u003e\n\u003cp\u003eThe OAuth client in libpq requires the server\u0026#39;s issuer setting to exactly match the issuer identifier which is provided in the discovery document, which must in turn match the client\u0026#39;s \u003ca href=\"/docs/18/libpq-connect.html#LIBPQ-CONNECT-OAUTH-ISSUER\" rel=\"nofollow\"\u003eoauth_issuer\u003c/a\u003e setting. No variations in case or formatting are permitted.\u003c/p\u003e\n\u003c/div\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003escope\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eA 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 \u003ca href=\"/docs/18/oauth-validators.html\" rel=\"nofollow\"\u003eChapter 50\u003c/a\u003e for more information on validators). This parameter is required.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003evalidator\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe library to use for validating bearer tokens. If given, the name must exactly match one of the libraries listed in \u003ca href=\"/docs/18/runtime-config-connection.html#GUC-OAUTH-VALIDATOR-LIBRARIES\" rel=\"nofollow\"\u003eoauth_validator_libraries\u003c/a\u003e. This parameter is optional unless \u003ccode\u003eoauth_validator_libraries\u003c/code\u003e contains more than one library, in which case it is required.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003emap\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eAllows for mapping between OAuth identity provider and database user names. See \u003ca href=\"/docs/18/auth-username-maps.html\" rel=\"nofollow\"\u003eSection 20.2\u003c/a\u003e 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan id=\"AUTH-OAUTH-DELEGATE-IDENT-MAPPING\"\u003e\u003ccode\u003edelegate_ident_mapping\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eAn advanced option which is not intended for common use.\u003c/p\u003e\n\u003cp\u003eWhen set to \u003ccode\u003e1\u003c/code\u003e, standard user mapping with \u003ccode\u003epg_ident.conf\u003c/code\u003e 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.\u003c/p\u003e\n\u003cp\u003eThis parameter is incompatible with \u003ccode\u003emap\u003c/code\u003e.\u003c/p\u003e\n\u003cdiv\u003e\n\u003ch3\u003eWarning\u003c/h3\u003e\n\u003cp\u003e\u003ccode\u003edelegate_ident_mapping\u003c/code\u003e 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 \u003ca href=\"/docs/18/oauth-validators.html\" rel=\"nofollow\"\u003estandard checks\u003c/a\u003e required of all validators. Use with caution.\u003c/p\u003e\n\u003c/div\u003e\n\u003c/dd\u003e\n\u003c/dl\u003e\n\u003c/div\u003e\n\u003c/div\u003e","SourceRevision":"555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f","ContentHash":"2697b7ee3bb0a049ed741be8e4310d4ce6821e499f009eb3f02c298d5725e581","Payload":{"description":["Authorize and optionally authenticate using a third-party OAuth 2.0 identity provider. See Section 20.15 for details."],"manual_html":"\u003cdiv class=\"sect1\" id=\"AUTH-OAUTH\"\u003e\n\u003cdiv class=\"titlepage\"\u003e\n\u003cdiv\u003e\n\u003cdiv\u003e\n\u003ch2 class=\"title\"\u003e20.15. OAuth Authorization/Authentication \u003c/h2\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003cp\u003eOAuth 2.0 is an industry-standard framework, defined in \u003ca class=\"ulink\" href=\"https://datatracker.ietf.org/doc/html/rfc6749\"\u003eRFC 6749\u003c/a\u003e, to enable third-party applications to obtain limited access to a protected resource. OAuth client support has to be enabled when \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e is built, see \u003ca class=\"xref\" href=\"/docs/18/installation.html\" title=\"Chapter 17. Installation from Source Code\"\u003eChapter 17\u003c/a\u003e for more information.\u003c/p\u003e\n\u003cp\u003eThis documentation uses the following terminology when discussing the OAuth ecosystem:\u003c/p\u003e\n\u003cdiv class=\"variablelist\"\u003e\n\u003cdl class=\"variablelist\"\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003eResource Owner (or End User)\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe user or system who owns protected resources and can grant access to them. This documentation also uses the term \u003cspan class=\"emphasis\"\u003e\u003cem\u003eend user\u003c/em\u003e\u003c/span\u003e when the resource owner is a person. When you use \u003cspan class=\"application\"\u003epsql\u003c/span\u003e to connect to the database using OAuth, you are the resource owner/end user.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003eClient\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe system which accesses the protected resources using access tokens. Applications using libpq, such as \u003cspan class=\"application\"\u003epsql\u003c/span\u003e, are the OAuth clients when connecting to a \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e cluster.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003eResource Server\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe system hosting the protected resources which are accessed by the client. The \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e cluster being connected to is the resource server.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003eProvider\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe 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.\u003c/p\u003e\n\u003cp\u003eThis 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 \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e is intended to be interoperable and compatible with OpenID Connect/OIDC, it is not itself an OIDC client and does not require its use.)\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003eAuthorization Server\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe system which receives requests from, and issues access tokens to, the client after the authenticated resource owner has given approval. \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e does not provide an authorization server; it is the responsibility of the OAuth provider.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\" id=\"AUTH-OAUTH-ISSUER\"\u003eIssuer\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eAn identifier for an authorization server, printed as an \u003ccode class=\"literal\"\u003ehttps://\u003c/code\u003e 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003c/dl\u003e\n\u003c/div\u003e\n\u003cdiv class=\"note\"\u003e\n\u003ch3 class=\"title\"\u003eNote\u003c/h3\u003e\n\u003cp\u003eFor 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.\u003c/p\u003e\n\u003c/div\u003e\n\u003cp\u003e\u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e supports bearer tokens, defined in \u003ca class=\"ulink\" href=\"https://datatracker.ietf.org/doc/html/rfc6750\"\u003eRFC 6750\u003c/a\u003e, 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.\u003c/p\u003e\n\u003cp\u003eThe following configuration options are supported for OAuth:\u003c/p\u003e\n\u003cdiv class=\"variablelist\"\u003e\n\u003cdl class=\"variablelist\"\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"literal\"\u003eissuer\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eAn HTTPS URL which is either the exact \u003ca class=\"link\" href=\"/docs/18/auth-oauth.html#AUTH-OAUTH-ISSUER\"\u003eissuer identifier\u003c/a\u003e 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.\u003c/p\u003e\n\u003cp\u003eWhen 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 \u003ccode class=\"literal\"\u003e/.well-known/openid-configuration\u003c/code\u003e will be appended to the end of the issuer identifier. Alternatively, if the \u003ccode class=\"literal\"\u003eissuer\u003c/code\u003e contains a \u003ccode class=\"literal\"\u003e/.well-known/\u003c/code\u003e path segment, that URL will be provided to the client as-is.\u003c/p\u003e\n\u003cdiv class=\"warning\"\u003e\n\u003ch3 class=\"title\"\u003eWarning\u003c/h3\u003e\n\u003cp\u003eThe 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 \u003ca class=\"xref\" href=\"/docs/18/libpq-connect.html#LIBPQ-CONNECT-OAUTH-ISSUER\"\u003eoauth_issuer\u003c/a\u003e setting. No variations in case or formatting are permitted.\u003c/p\u003e\n\u003c/div\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"literal\"\u003escope\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eA 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 \u003ca class=\"xref\" href=\"/docs/18/oauth-validators.html\" title=\"Chapter 50. OAuth Validator Modules\"\u003eChapter 50\u003c/a\u003e for more information on validators). This parameter is required.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"literal\"\u003evalidator\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThe library to use for validating bearer tokens. If given, the name must exactly match one of the libraries listed in \u003ca class=\"xref\" href=\"/docs/18/runtime-config-connection.html#GUC-OAUTH-VALIDATOR-LIBRARIES\"\u003eoauth_validator_libraries\u003c/a\u003e. This parameter is optional unless \u003ccode class=\"literal\"\u003eoauth_validator_libraries\u003c/code\u003e contains more than one library, in which case it is required.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"literal\"\u003emap\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eAllows for mapping between OAuth identity provider and database user names. See \u003ca class=\"xref\" href=\"/docs/18/auth-username-maps.html\" title=\"20.2. User Name Maps\"\u003eSection 20.2\u003c/a\u003e 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\" id=\"AUTH-OAUTH-DELEGATE-IDENT-MAPPING\"\u003e\u003ccode class=\"literal\"\u003edelegate_ident_mapping\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eAn advanced option which is not intended for common use.\u003c/p\u003e\n\u003cp\u003eWhen set to \u003ccode class=\"literal\"\u003e1\u003c/code\u003e, standard user mapping with \u003ccode class=\"filename\"\u003epg_ident.conf\u003c/code\u003e 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.\u003c/p\u003e\n\u003cp\u003eThis parameter is incompatible with \u003ccode class=\"literal\"\u003emap\u003c/code\u003e.\u003c/p\u003e\n\u003cdiv class=\"warning\"\u003e\n\u003ch3 class=\"title\"\u003eWarning\u003c/h3\u003e\n\u003cp\u003e\u003ccode class=\"literal\"\u003edelegate_ident_mapping\u003c/code\u003e 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 \u003ca class=\"link\" href=\"/docs/18/oauth-validators.html\" title=\"Chapter 50. OAuth Validator Modules\"\u003estandard checks\u003c/a\u003e required of all validators. Use with caution.\u003c/p\u003e\n\u003c/div\u003e\n\u003c/dd\u003e\n\u003c/dl\u003e\n\u003c/div\u003e\n\u003c/div\u003e","related":[],"sections":[],"tables":[{"columns":[{"key":"name","label":"Option or term"},{"key":"description","label":"Meaning"}],"key":"method-options","rows":[{"description":"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.","name":"Resource Owner (or End User)"},{"description":"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.","name":"Client"},{"description":"The system hosting the protected resources which are accessed by the client. The PostgreSQL cluster being connected to is the resource server.","name":"Resource Server"},{"description":"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.)","name":"Provider"},{"description":"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.","name":"Authorization Server"},{"description":"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.","name":"Issuer"},{"description":"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.","name":"issuer"},{"description":"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.","name":"scope"},{"description":"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.","name":"validator"},{"description":"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.","name":"map"},{"description":"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.","name":"delegate_ident_mapping"}],"title":"Documented method options and alternatives"}]}},"RequestedLocale":"zh-Hans","Fallback":true,"Versions":["18","19","20"],"Locales":["en"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}