89 lines (57 loc) · 3.5 KB

OIDC authentication

OpenID Connect :octicons-link-external-16: (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 :octicons-link-external-16: blog post.

For additional configuration details and source code, see the pg_oidc_validator project :octicons-link-external-16:.

!!! important OIDC authentication relies on PostgreSQL OAuth authentication :octicons-link-external-16:, 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:

The client obtains an access token from an external identity provider
The client connects to PostgreSQL using OAuth authentication
PostgreSQL forwards the token to the pg_oidc_validator module
The validator verifies the token signature and claims
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. {.power-number}

Install the pg_oidc_validator package:

For Debian/Ubuntu:

sudo apt install pg-oidc-validator-pgdg{{pgversion}}

For RHEL/Oracle Linux/Rocky Linux:

sudo dnf install pg-oidc-validator-pgdg{{pgversion}}

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.
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
Restart PostgreSQL for the changes to take effect:
```
sudo systemctl restart postgresql-{{pgversion}}
```

!!! 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.