OIDC authentication

OpenID Connect (or OIDC) authentication allows you to authenticate using tokens issued by an external identity provider. Instead of managing database passwords, you can delegate authentication to centralized identity services.

Percona Distribution for PostgreSQL supports OIDC authentication through the pg_oidc_validator library. This library validates OIDC tokens during PostgreSQL authentication.

If you want to test PostgreSQL OAuth authentication using pg_oidc_validator with Keycloak using Docker containers, see the PostgreSQL OIDC Authentication with pg_oidc_validator blog post.

For additional configuration details and source code, see the pg_oidc_validator project .

Important

OIDC authentication relies on PostgreSQL OAuth authentication , introduced in PostgreSQL 18.

When to use OIDC authentication

OIDC authentication is useful when you want to:

• integrate PostgreSQL with an existing single sign-on (SSO) platform
• reduce the need to manage database passwords
• centralize identity management across applications and databases

Tip

OIDC authentication simplifies access management for PostgreSQL when using an identity provider that supports OpenID Connect.

OIDC authentication architecture

OIDC authentication works as follows:

1. The client obtains an access token from an external identity provider
2. The client connects to PostgreSQL using OAuth authentication
3. PostgreSQL forwards the token to the pg_oidc_validator module
4. The validator verifies the token signature and claims
5. If validation succeeds, PostgreSQL allows the connection

The following diagram shows how OIDC authentication works between the client, the identity provider, and PostgreSQL:

Tip

Before configuring OIDC authentication, ensure that your PostgreSQL deployment can access the identity provider that issues OIDC tokens.

Set up OIDC authentication

Follow these steps to set up OIDC authentication for your PostgreSQL database.

1. Install the pg_oidc_validator package:

   For Debian/Ubuntu:

   sudo apt install pg-oidc-validator-pgdg18
   

   For RHEL/Oracle Linux/Rocky Linux:

   sudo dnf install pg-oidc-validator-pgdg18
   

2. Edit postgresql.conf and add the validator library:

   oauth_validator_libraries = 'pg_oidc_validator'
   

   Note

   This setting tells PostgreSQL to load the OIDC validator during startup.

3. Add an OAuth authentication rule to pg_hba.conf:

   host all all 192.168.1.0/24 oauth scope="openid",issuer=https://your-oidc-provider
   

   Where:

   • oauth enables OAuth authentication
   • scope is the required OIDC scope
   • issuer is the URL of the OIDC identity provider

4. Restart PostgreSQL for the changes to take effect:

   sudo systemctl restart postgresql-18
   

Important

PostgreSQL does not issue OIDC tokens. Clients must obtain an access token from an external identity provider such as Keycloak, Okta, or Microsoft Entra ID before connecting.