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

   1
   2 20.15. OAuth Authorization/Authentication #
   3
   4    OAuth 2.0 is an industry-standard framework, defined in RFC 6749, to
   5    enable third-party applications to obtain limited access to a protected
   6    resource. OAuth client support has to be enabled when PostgreSQL is
   7    built, see Chapter 17 for more information.
   8
   9    This documentation uses the following terminology when discussing the
  10    OAuth ecosystem:
  11
  12    Resource Owner (or End User)
  13           The user or system who owns protected resources and can grant
  14           access to them. This documentation also uses the term end user
  15           when the resource owner is a person. When you use psql to
  16           connect to the database using OAuth, you are the resource
  17           owner/end user.
  18
  19    Client
  20           The system which accesses the protected resources using access
  21           tokens. Applications using libpq, such as psql, are the OAuth
  22           clients when connecting to a PostgreSQL cluster.
  23
  24    Resource Server
  25           The system hosting the protected resources which are accessed by
  26           the client. The PostgreSQL cluster being connected to is the
  27           resource server.
  28
  29    Provider
  30           The organization, product vendor, or other entity which develops
  31           and/or administers the OAuth authorization servers and clients
  32           for a given application. Different providers typically choose
  33           different implementation details for their OAuth systems; a
  34           client of one provider is not generally guaranteed to have
  35           access to the servers of another.
  36
  37           This use of the term "provider" is not standard, but it seems to
  38           be in wide use colloquially. (It should not be confused with
  39           OpenID's similar term "Identity Provider". While the
  40           implementation of OAuth in PostgreSQL is intended to be
  41           interoperable and compatible with OpenID Connect/OIDC, it is not
  42           itself an OIDC client and does not require its use.)
  43
  44    Authorization Server
  45           The system which receives requests from, and issues access
  46           tokens to, the client after the authenticated resource owner has
  47           given approval. PostgreSQL does not provide an authorization
  48           server; it is the responsibility of the OAuth provider.
  49
  50    Issuer
  51           An identifier for an authorization server, printed as an
  52           https:// URL, which provides a trusted "namespace" for OAuth
  53           clients and applications. The issuer identifier allows a single
  54           authorization server to talk to the clients of mutually
  55           untrusting entities, as long as they maintain separate issuers.
  56
  57 Note
  58
  59    For small deployments, there may not be a meaningful distinction
  60    between the "provider", "authorization server", and "issuer". However,
  61    for more complicated setups, there may be a one-to-many (or
  62    many-to-many) relationship: a provider may rent out multiple issuer
  63    identifiers to separate tenants, then provide multiple authorization
  64    servers, possibly with different supported feature sets, to interact
  65    with their clients.
  66
  67    PostgreSQL supports bearer tokens, defined in RFC 6750, which are a
  68    type of access token used with OAuth 2.0 where the token is an opaque
  69    string. The format of the access token is implementation specific and
  70    is chosen by each authorization server.
  71
  72    The following configuration options are supported for OAuth:
  73
  74    issuer
  75           An HTTPS URL which is either the exact issuer identifier of the
  76           authorization server, as defined by its discovery document, or a
  77           well-known URI that points directly to that discovery document.
  78           This parameter is required.
  79
  80           When an OAuth client connects to the server, a URL for the
  81           discovery document will be constructed using the issuer
  82           identifier. By default, this URL uses the conventions of OpenID
  83           Connect Discovery: the path /.well-known/openid-configuration
  84           will be appended to the end of the issuer identifier.
  85           Alternatively, if the issuer contains a /.well-known/ path
  86           segment, that URL will be provided to the client as-is.
  87
  88 Warning
  89
  90           The OAuth client in libpq requires the server's issuer setting
  91           to exactly match the issuer identifier which is provided in the
  92           discovery document, which must in turn match the client's
  93           oauth_issuer setting. No variations in case or formatting are
  94           permitted.
  95
  96    scope
  97           A space-separated list of the OAuth scopes needed for the server
  98           to both authorize the client and authenticate the user.
  99           Appropriate values are determined by the authorization server
 100           and the OAuth validation module used (see Chapter 50 for more
 101           information on validators). This parameter is required.
 102
 103    validator
 104           The library to use for validating bearer tokens. If given, the
 105           name must exactly match one of the libraries listed in
 106           oauth_validator_libraries. This parameter is optional unless
 107           oauth_validator_libraries contains more than one library, in
 108           which case it is required.
 109
 110    map
 111           Allows for mapping between OAuth identity provider and database
 112           user names. See Section 20.2 for details. If a map is not
 113           specified, the user name associated with the token (as
 114           determined by the OAuth validator) must exactly match the role
 115           name being requested. This parameter is optional.
 116
 117    delegate_ident_mapping
 118           An advanced option which is not intended for common use.
 119
 120           When set to 1, standard user mapping with pg_ident.conf is
 121           skipped, and the OAuth validator takes full responsibility for
 122           mapping end user identities to database roles. If the validator
 123           authorizes the token, the server trusts that the user is allowed
 124           to connect under the requested role, and the connection is
 125           allowed to proceed regardless of the authentication status of
 126           the user.
 127
 128           This parameter is incompatible with map.
 129
 130 Warning
 131
 132           delegate_ident_mapping provides additional flexibility in the
 133           design of the authentication system, but it also requires
 134           careful implementation of the OAuth validator, which must
 135           determine whether the provided token carries sufficient end-user
 136           privileges in addition to the standard checks required of all
 137           validators. Use with caution.