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

   1
   2 50.3. OAuth Validator Callbacks #
   3
   4    50.3.1. Startup Callback
   5    50.3.2. Validate Callback
   6    50.3.3. Shutdown Callback
   7
   8    OAuth validator modules implement their functionality by defining a set
   9    of callbacks. The server will call them as required to process the
  10    authentication request from the user.
  11
  12 50.3.1. Startup Callback #
  13
  14    The startup_cb callback is executed directly after loading the module.
  15    This callback can be used to set up local state and perform additional
  16    initialization if required. If the validator module has state it can
  17    use state->private_data to store it.
  18 typedef void (*ValidatorStartupCB) (ValidatorModuleState *state);
  19
  20 50.3.2. Validate Callback #
  21
  22    The validate_cb callback is executed during the OAuth exchange when a
  23    user attempts to authenticate using OAuth. Any state set in previous
  24    calls will be available in state->private_data.
  25 typedef bool (*ValidatorValidateCB) (const ValidatorModuleState *state,
  26                                      const char *token, const char *role,
  27                                      ValidatorModuleResult *result);
  28
  29    token will contain the bearer token to validate. PostgreSQL has ensured
  30    that the token is well-formed syntactically, but no other validation
  31    has been performed. role will contain the role the user has requested
  32    to log in as. The callback must set output parameters in the result
  33    struct, which is defined as below:
  34 typedef struct ValidatorModuleResult
  35 {
  36     bool        authorized;
  37     char       *authn_id;
  38 } ValidatorModuleResult;
  39
  40    The connection will only proceed if the module sets result->authorized
  41    to true. To authenticate the user, the authenticated user name (as
  42    determined using the token) shall be palloc'd and returned in the
  43    result->authn_id field. Alternatively, result->authn_id may be set to
  44    NULL if the token is valid but the associated user identity cannot be
  45    determined.
  46
  47    A validator may return false to signal an internal error, in which case
  48    any result parameters are ignored and the connection fails. Otherwise
  49    the validator should return true to indicate that it has processed the
  50    token and made an authorization decision.
  51
  52    The behavior after validate_cb returns depends on the specific HBA
  53    setup. Normally, the result->authn_id user name must exactly match the
  54    role that the user is logging in as. (This behavior may be modified
  55    with a usermap.) But when authenticating against an HBA rule with
  56    delegate_ident_mapping turned on, PostgreSQL will not perform any
  57    checks on the value of result->authn_id at all; in this case it is up
  58    to the validator to ensure that the token carries enough privileges for
  59    the user to log in under the indicated role.
  60
  61 50.3.3. Shutdown Callback #
  62
  63    The shutdown_cb callback is executed when the backend process
  64    associated with the connection exits. If the validator module has any
  65    allocated state, this callback should free it to avoid resource leaks.
  66 typedef void (*ValidatorShutdownCB) (ValidatorModuleState *state);