---
title: "OAuth Validator Callbacks"
id: oauth-validator-callbacks
pg_version: "20devel"
---

<a id="oauth-validator-callbacks"></a>

## 50.3. OAuth Validator Callbacks

OAuth validator modules implement their functionality by defining a set of callbacks. The server will call them as required to process the authentication request from the user. 

<a id="oauth-validator-callback-startup"></a>

### 50.3.1. Startup Callback

The `startup_cb` callback is executed directly after loading the module. This callback can be used to set up local state, define [custom HBA options](oauth-validator-hba.md), and perform additional initialization if required. If the validator module has state it can use `state->private_data` to store it. 
typedef void (*ValidatorStartupCB) (ValidatorModuleState *state);
 

<a id="oauth-validator-callback-validate"></a>

### 50.3.2. Validate Callback

The `validate_cb` callback is executed during the OAuth exchange when a user attempts to authenticate using OAuth. Any state set in previous calls will be available in `state->private_data`. 
typedef bool (*ValidatorValidateCB) (const ValidatorModuleState *state,
                                     const char *token, const char *role,
                                     ValidatorModuleResult *result);
 `token` will contain the bearer token to validate. PostgreSQL has ensured that the token is well-formed syntactically, but no other validation has been performed. `role` will contain the role the user has requested to log in as. The callback must set output parameters in the `result` struct, which is defined as below: 
typedef struct ValidatorModuleResult
{
    bool        authorized;
    char       *authn_id;
    char       *error_detail;
} ValidatorModuleResult;
 The connection will only proceed if the module sets `result->authorized` to `true`. To authenticate the user, the authenticated user name (as determined using the token) shall be palloc'd and returned in the `result->authn_id` field. Alternatively, `result->authn_id` may be set to NULL if the token is valid but the associated user identity cannot be determined. If the validator returns `true` and sets `result->authn_id` then the identity appears in the server log when [`log_connections` (`string`)](runtime-config-logging.md#guc-log-connections) includes `authentication`. This happens before authorization and will log authentication even if the connection is later rejected due to authorization. 

A validator may return `false` to signal an internal error, in which case the connection fails. Otherwise the validator should return `true` to indicate that it has processed the token and made an authorization decision. 

In either failure case (validation error or internal error) the module may store a user-readable reason for the failure in `result->error_detail`. This will be printed to the server logs (not sent to the client) as a `DETAIL` entry for the authentication failure. The memory pointed to by `error_detail` may be either palloc'd or of static duration. `error_detail` is ignored on success. 

The behavior after `validate_cb` returns depends on the specific HBA setup. Normally, the `result->authn_id` user name must exactly match the role that the user is logging in as. (This behavior may be modified with a usermap.) But when authenticating against an HBA rule with `delegate_ident_mapping` turned on, PostgreSQL will not perform any checks on the value of `result->authn_id` at all; in this case it is up to the validator to ensure that the token carries enough privileges for the user to log in under the indicated `role`. 

<a id="oauth-validator-callback-shutdown"></a>

### 50.3.3. Shutdown Callback

The `shutdown_cb` callback is executed when the server backend has finished validating tokens for the connection. If the validator module has any allocated state, this callback should free it to avoid resource leaks. 
typedef void (*ValidatorShutdownCB) (ValidatorModuleState *state);