Kong Gateway PostgreSQL OAuth2 authentication

Kong Gateway supports connecting to PostgreSQL 18 using OAuth2 authentication via the SASL OAUTHBEARER mechanism and a server-side validator. This is a more secure alternative to password-based authentication that enables single sign-on (SSO) and centralized access management through any OIDC-compliant identity provider such as Okta, Azure AD, Google, or Keycloak.

The following diagram shows how Kong Gateway authenticates to PostgreSQL using OAUTHBEARER:

1. Kong Gateway obtains an OAuth access token from the IdP (using client_credentials or password grant).
2. Kong Gateway connects to PostgreSQL using OAUTHBEARER SASL mechanism, sending the token.
3. PostgreSQL’s OAuth validator plugin contacts the IdP to validate the token.
4. The validator verifies the token’s authenticity (issuer, signature, expiration) and extracts the user’s identity, typically the sub claim, which is mapped to an existing PostgreSQL role.
5. If the role exists and the token is valid, the connection succeeds.

 
sequenceDiagram
    participant Kong as Kong Gateway
    participant IdP
    participant PG as PostgreSQL 18 (oauth validator)

    Kong->>IdP: 1. Request token
    IdP-->>Kong: 2. Return token
    Kong->>PG: 3. Connect with OAUTHBEARER (send access token)
    PG->>IdP: 4. Validate token
  

The token-to-role mapping in step 4 is critical: a PostgreSQL role must exist that matches the identity the validator extracts from the token. Which claim is used and how it maps to a role is determined entirely by the validator library or cloud provider.

Because OAUTHBEARER transmits tokens in plaintext, SSL is required. When pg_oauth_auth is set to on, Kong Gateway automatically enforces pg_ssl=on and pg_ssl_required=on. PostgreSQL must also have SSL enabled or the connection will fail.

1. Install an OAuth validator plugin

PostgreSQL 18 introduced OAuth support but delegates token validation entirely to third-party libraries, it does not implement token verification itself. Self-managed deployments therefore require a validator library configured via the oauth_validator_libraries parameter. Kong supports pg_oidc_validator from Percona. Install and configure it according to its documentation.

2. Configure postgresql.conf

ssl = on
ssl_cert_file = '<path_to_server_certificate>'
ssl_key_file = '<path_to_server_private_key>'

oauth_validator_libraries = 'pg_oidc_validator'

3. Configure pg_hba.conf

# TYPE   DATABASE  USER      ADDRESS  METHOD  OPTIONS
local    all       all                trust
host     all       postgres  all      trust
host     all       all       all      oauth   issuer=https://<idp-host>/realms/<realm> scope=openid

Rules are evaluated top-down, first match wins:

4. Create a database role matching the token identity

The validator determines how to map a token to a PostgreSQL role. For client credentials flow, the sub claim is typically set to the client_id by the IdP, so the role name usually matches the client ID. Refer to your validator library or cloud provider’s documentation to confirm the expected format.

CREATE ROLE "<matched_identity>" WITH LOGIN;

Token endpoint vs Discovery endpoint

Kong Gateway needs to know where to request tokens. There are two mutually exclusive ways to configure this:

One of the two is required. If both are set, token_endpoint takes precedence. Discovery mode is useful when you prefer not to hardcode the token endpoint, or when the IdP may change its endpoint URL.

Token endpoint auth method

pg_oauth_token_endpoint_auth_method controls how Kong Gateway sends client credentials to the IdP’s token endpoint:

Choose the method your IdP supports. Most IdPs support both; some (e.g., certain enterprise IdPs) may only accept one.

Client credentials grant (with token endpoint)

This is the most common pattern for service-to-service authentication, where Kong Gateway uses client_id and client_secret to obtain a token.

KONG_PG_HOST=127.0.0.1
KONG_PG_PORT=5432
KONG_PG_DATABASE=kong
KONG_PG_USER=<db_role>

KONG_PG_OAUTH_AUTH=on
KONG_PG_OAUTH_CLIENT_ID=<client_id>
KONG_PG_OAUTH_CLIENT_SECRET=<client_secret>
KONG_PG_OAUTH_TOKEN_ENDPOINT=https://<idp-host>/token
KONG_PG_OAUTH_SCOPE=openid
KONG_PG_OAUTH_GRANT_TYPE=client_credentials

KONG_PG_SSL_VERIFY=on

pg_host=127.0.0.1
pg_port=5432
pg_database=kong
pg_user=<db_role>

pg_oauth_auth=on
pg_oauth_client_id=<client_id>
pg_oauth_client_secret=<client_secret>
pg_oauth_token_endpoint=https://<idp-host>/token
pg_oauth_scope=openid
pg_oauth_grant_type=client_credentials

pg_ssl_verify=on

Client credentials grant (with discovery endpoint)

Use this variant when you prefer not to hardcode the token endpoint URL, Kong Gateway resolves it automatically from the OIDC discovery document.

KONG_PG_HOST=127.0.0.1
KONG_PG_PORT=5432
KONG_PG_DATABASE=kong
KONG_PG_USER=<db_role>

KONG_PG_OAUTH_AUTH=on
KONG_PG_OAUTH_CLIENT_ID=<client_id>
KONG_PG_OAUTH_CLIENT_SECRET=<client_secret>
KONG_PG_OAUTH_DISCOVERY_ENDPOINT=https://<idp-host>/.well-known/openid-configuration
KONG_PG_OAUTH_SCOPE=openid
KONG_PG_OAUTH_GRANT_TYPE=client_credentials

KONG_PG_SSL_VERIFY=on

pg_host=127.0.0.1
pg_port=5432
pg_database=kong
pg_user=<db_role>

pg_oauth_auth=on
pg_oauth_client_id=<client_id>
pg_oauth_client_secret=<client_secret>
pg_oauth_discovery_endpoint=https://<idp-host>/.well-known/openid-configuration
pg_oauth_scope=openid
pg_oauth_grant_type=client_credentials

pg_ssl_verify=on

Password grant

Use this grant type when the IdP requires resource owner credentials.

KONG_PG_HOST=127.0.0.1
KONG_PG_PORT=5432
KONG_PG_DATABASE=kong
KONG_PG_USER=<db_role>

KONG_PG_OAUTH_AUTH=on
KONG_PG_OAUTH_CLIENT_ID=<client_id>
KONG_PG_OAUTH_CLIENT_SECRET=<client_secret>
KONG_PG_OAUTH_TOKEN_ENDPOINT=https://<idp-host>/token
KONG_PG_OAUTH_SCOPE=openid
KONG_PG_OAUTH_GRANT_TYPE=password
KONG_PG_OAUTH_USERNAME=<username>
KONG_PG_OAUTH_PASSWORD=<password>

KONG_PG_SSL_VERIFY=on

pg_host=127.0.0.1
pg_port=5432
pg_database=kong
pg_user=<db_role>

pg_oauth_auth=on
pg_oauth_client_id=<client_id>
pg_oauth_client_secret=<client_secret>
pg_oauth_token_endpoint=https://<idp-host>/token
pg_oauth_scope=openid
pg_oauth_grant_type=password
pg_oauth_username=<username>
pg_oauth_password=<password>

pg_ssl_verify=on

Password grant with ADFS

ADFS (Active Directory Federation Services) typically uses password grant with a resource parameter to identify the target application, and may use a public client (no client_secret).

KONG_PG_HOST=127.0.0.1
KONG_PG_PORT=5432
KONG_PG_DATABASE=kong
KONG_PG_USER=<db_role>

KONG_PG_OAUTH_AUTH=on
KONG_PG_OAUTH_CLIENT_ID=<client_id>
KONG_PG_OAUTH_TOKEN_ENDPOINT=https://<adfs-host>/adfs/oauth2/token
KONG_PG_OAUTH_GRANT_TYPE=password
KONG_PG_OAUTH_USERNAME=<domain\\user>
KONG_PG_OAUTH_PASSWORD=<password>
KONG_PG_OAUTH_RESOURCE=https://<database-resource-uri>

KONG_PG_SSL_VERIFY=on

pg_host=127.0.0.1
pg_port=5432
pg_database=kong
pg_user=<db_role>

pg_oauth_auth=on
pg_oauth_client_id=<client_id>
pg_oauth_token_endpoint=https://<adfs-host>/adfs/oauth2/token
pg_oauth_grant_type=password
pg_oauth_username=<domain\\user>
pg_oauth_password=<password>
pg_oauth_resource=https://<database-resource-uri>

pg_ssl_verify=on

pg_oauth_resource is only sent with the password grant type. pg_oauth_client_secret can be omitted for ADFS public clients.

All parameters also have pg_ro_oauth_* variants for read-only replica connections.