begriffs open source - ai-pg/blob - full-docs/html/auth-oauth.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.15. OAuth Authorization/Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-bsd.html" title="20.14. BSD Authentication" /><link rel="next" href="client-authentication-problems.html" title="20.16. Authentication Problems" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.15. OAuth Authorization/Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-bsd.html" title="20.14. BSD Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 20. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 20. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="client-authentication-problems.html" title="20.16. Authentication Problems">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-OAUTH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.15. OAuth Authorization/Authentication <a href="#AUTH-OAUTH" class="id_link">#</a></h2></div></div></div><a id="id-1.6.7.22.2" class="indexterm"></a><p>
   3     OAuth 2.0 is an industry-standard framework, defined in
   4     <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc6749" target="_top">RFC 6749</a>,
   5     to enable third-party applications to obtain limited access to a protected
   6     resource.
   7
   8     OAuth client support has to be enabled when <span class="productname">PostgreSQL</span>
   9     is built, see <a class="xref" href="installation.html" title="Chapter 17. Installation from Source Code">Chapter 17</a> for more information.
  10    </p><p>
  11     This documentation uses the following terminology when discussing the OAuth
  12     ecosystem:
  13
  14     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Resource Owner (or End User)</span></dt><dd><p>
  15         The user or system who owns protected resources and can grant access to
  16         them. This documentation also uses the term <span class="emphasis"><em>end user</em></span>
  17         when the resource owner is a person. When you use
  18         <span class="application">psql</span> to connect to the database using OAuth,
  19         you are the resource owner/end user.
  20        </p></dd><dt><span class="term">Client</span></dt><dd><p>
  21         The system which accesses the protected resources using access
  22         tokens. Applications using libpq, such as <span class="application">psql</span>,
  23         are the OAuth clients when connecting to a
  24         <span class="productname">PostgreSQL</span> cluster.
  25        </p></dd><dt><span class="term">Resource Server</span></dt><dd><p>
  26         The system hosting the protected resources which are
  27         accessed by the client. The <span class="productname">PostgreSQL</span>
  28         cluster being connected to is the resource server.
  29        </p></dd><dt><span class="term">Provider</span></dt><dd><p>
  30         The organization, product vendor, or other entity which develops and/or
  31         administers the OAuth authorization servers and clients for a given application.
  32         Different providers typically choose different implementation details
  33         for their OAuth systems; a client of one provider is not generally
  34         guaranteed to have access to the servers of another.
  35        </p><p>
  36         This use of the term "provider" is not standard, but it seems to be in
  37         wide use colloquially. (It should not be confused with OpenID's similar
  38         term "Identity Provider". While the implementation of OAuth in
  39         <span class="productname">PostgreSQL</span> is intended to be interoperable
  40         and compatible with OpenID Connect/OIDC, it is not itself an OIDC client
  41         and does not require its use.)
  42        </p></dd><dt><span class="term">Authorization Server</span></dt><dd><p>
  43         The system which receives requests from, and issues access tokens to,
  44         the client after the authenticated resource owner has given approval.
  45         <span class="productname">PostgreSQL</span> does not provide an authorization
  46         server; it is the responsibility of the OAuth provider.
  47        </p></dd><dt><span class="term" id="AUTH-OAUTH-ISSUER">Issuer</span></dt><dd><p>
  48         An identifier for an authorization server, printed as an
  49         <code class="literal">https://</code> URL, which provides a trusted "namespace"
  50         for OAuth clients and applications. The issuer identifier allows a
  51         single authorization server to talk to the clients of mutually
  52         untrusting entities, as long as they maintain separate issuers.
  53        </p></dd></dl></div><p>
  54
  55     </p><div class="note"><h3 class="title">Note</h3><p>
  56       For small deployments, there may not be a meaningful distinction between
  57       the "provider", "authorization server", and "issuer". However, for more
  58       complicated setups, there may be a one-to-many (or many-to-many)
  59       relationship: a provider may rent out multiple issuer identifiers to
  60       separate tenants, then provide multiple authorization servers, possibly
  61       with different supported feature sets, to interact with their clients.
  62      </p></div><p>
  63    </p><p>
  64     <span class="productname">PostgreSQL</span> supports bearer tokens, defined in
  65     <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc6750" target="_top">RFC 6750</a>,
  66     which are a type of access token used with OAuth 2.0 where the token is an
  67     opaque string.  The format of the access token is implementation specific
  68     and is chosen by each authorization server.
  69    </p><p>
  70     The following configuration options are supported for OAuth:
  71     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">issuer</code></span></dt><dd><p>
  72         An HTTPS URL which is either the exact
  73         <a class="link" href="auth-oauth.html#AUTH-OAUTH-ISSUER">issuer identifier</a> of the
  74         authorization server, as defined by its discovery document, or a
  75         well-known URI that points directly to that discovery document. This
  76         parameter is required.
  77        </p><p>
  78         When an OAuth client connects to the server, a URL for the discovery
  79         document will be constructed using the issuer identifier. By default,
  80         this URL uses the conventions of OpenID Connect Discovery: the path
  81         <code class="literal">/.well-known/openid-configuration</code> will be appended
  82         to the end of the issuer identifier. Alternatively, if the
  83         <code class="literal">issuer</code> contains a <code class="literal">/.well-known/</code>
  84         path segment, that URL will be provided to the client as-is.
  85        </p><div class="warning"><h3 class="title">Warning</h3><p>
  86          The OAuth client in libpq requires the server's issuer setting to
  87          exactly match the issuer identifier which is provided in the discovery
  88          document, which must in turn match the client's
  89          <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-OAUTH-ISSUER">oauth_issuer</a> setting. No variations in
  90          case or formatting are permitted.
  91         </p></div></dd><dt><span class="term"><code class="literal">scope</code></span></dt><dd><p>
  92         A space-separated list of the OAuth scopes needed for the server to
  93         both authorize the client and authenticate the user.  Appropriate values
  94         are determined by the authorization server and the OAuth validation
  95         module used (see <a class="xref" href="oauth-validators.html" title="Chapter 50. OAuth Validator Modules">Chapter 50</a> for more
  96         information on validators).  This parameter is required.
  97        </p></dd><dt><span class="term"><code class="literal">validator</code></span></dt><dd><p>
  98         The library to use for validating bearer tokens. If given, the name must
  99         exactly match one of the libraries listed in
 100         <a class="xref" href="runtime-config-connection.html#GUC-OAUTH-VALIDATOR-LIBRARIES">oauth_validator_libraries</a>.  This parameter is
 101         optional unless <code class="literal">oauth_validator_libraries</code> contains
 102         more than one library, in which case it is required.
 103        </p></dd><dt><span class="term"><code class="literal">map</code></span></dt><dd><p>
 104         Allows for mapping between OAuth identity provider and database user
 105         names.  See <a class="xref" href="auth-username-maps.html" title="20.2. User Name Maps">Section 20.2</a> for details.  If a
 106         map is not specified, the user name associated with the token (as
 107         determined by the OAuth validator) must exactly match the role name
 108         being requested.  This parameter is optional.
 109        </p></dd><dt><span class="term" id="AUTH-OAUTH-DELEGATE-IDENT-MAPPING">
 110        <code class="literal">delegate_ident_mapping</code>
 111       </span></dt><dd><p>
 112         An advanced option which is not intended for common use.
 113        </p><p>
 114         When set to <code class="literal">1</code>, standard user mapping with
 115         <code class="filename">pg_ident.conf</code> is skipped, and the OAuth validator
 116         takes full responsibility for mapping end user identities to database
 117         roles.  If the validator authorizes the token, the server trusts that
 118         the user is allowed to connect under the requested role, and the
 119         connection is allowed to proceed regardless of the authentication
 120         status of the user.
 121        </p><p>
 122         This parameter is incompatible with <code class="literal">map</code>.
 123        </p><div class="warning"><h3 class="title">Warning</h3><p>
 124          <code class="literal">delegate_ident_mapping</code> provides additional
 125          flexibility in the design of the authentication system, but it also
 126          requires careful implementation of the OAuth validator, which must
 127          determine whether the provided token carries sufficient end-user
 128          privileges in addition to the <a class="link" href="oauth-validators.html" title="Chapter 50. OAuth Validator Modules">standard
 129          checks</a> required of all validators.  Use with caution.
 130         </p></div></dd></dl></div><p>
 131    </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-bsd.html" title="20.14. BSD Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 20. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="client-authentication-problems.html" title="20.16. Authentication Problems">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.14. BSD Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.16. Authentication Problems</td></tr></table></div></body></html>