From a9c0160745ea89ed6baeab9737d6af122017f4b3 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Fri, 6 Mar 2026 16:09:09 +0200 Subject: [PATCH 1/6] PG-2238 - Add the OIDC topic This PR reorganizes the authentication methods in Solutions, adding a folder to future proof the authentication methods, and adds the OIDC topic. --- docs/solutions.md | 6 +++--- docs/{ => solutions/authentication}/ldap.md | 0 docs/solutions/authentication/oidc.md | 0 docs/solutions/authentication/overview.md | 19 +++++++++++++++++++ mkdocs.yml | 6 ++++-- 5 files changed, 26 insertions(+), 5 deletions(-) rename docs/{ => solutions/authentication}/ldap.md (100%) create mode 100644 docs/solutions/authentication/oidc.md create mode 100644 docs/solutions/authentication/overview.md diff --git a/docs/solutions.md b/docs/solutions.md index 0fcec063b..8f29d8a77 100644 --- a/docs/solutions.md +++ b/docs/solutions.md @@ -30,11 +30,11 @@ Dealing with spatial data? Learn how you can store and manipulate it.
-### :material-account-lock: LDAP authentication +### :material-account-lock: Authentication -Need a central authentication solution? Learn how you can manage users and access control using LDAP directories. +Need centralized authentication? Learn how to integrate PostgreSQL with identity providers such as LDAP directories or OpenID Connect. -[LDAP authentication :material-arrow-right:](ldap.md){.md-button} +[Authentication :material-arrow-right:](solutions/authentication/index.md){.md-button}
diff --git a/docs/ldap.md b/docs/solutions/authentication/ldap.md similarity index 100% rename from docs/ldap.md rename to docs/solutions/authentication/ldap.md diff --git a/docs/solutions/authentication/oidc.md b/docs/solutions/authentication/oidc.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/solutions/authentication/overview.md b/docs/solutions/authentication/overview.md new file mode 100644 index 000000000..748d2be4e --- /dev/null +++ b/docs/solutions/authentication/overview.md @@ -0,0 +1,19 @@ +# Authentication + +Centralized authentication allows you to manage database access using external identity systems instead of local PostgreSQL users. + +Percona Distribution for PostgreSQL supports multiple authentication mechanisms that integrate with enterprise identity infrastructure. + +## Available authentication methods + +### LDAP authentication + +Use LDAP directories such as OpenLDAP or Active Directory to centrally manage database users. + +[LDAP authentication](ldap.md) + +### OIDC authentication + +Authenticate users using OpenID Connect identity providers such as Keycloak, Okta, or Microsoft Entra ID. + +[OIDC authentication](oidc.md) diff --git a/mkdocs.yml b/mkdocs.yml index d183ea8d7..66b184884 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -62,8 +62,10 @@ nav: - Deployment: solutions/postgis-deploy.md - Query spatial data: solutions/postgis-testing.md - Upgrade spatial database: solutions/postgis-upgrade.md - - LDAP authentication: - - ldap.md + - Authentication: + - Overview: solutions/authentication/overview.md + - LDAP authentication: solutions/authentication/ldap.md + - OIDC authentication: solutions/authentication/oidc.md - Upgrade: - "Major upgrade": major-upgrade.md - minor-upgrade.md From 9b712db7b84f21344afcd227497cf6f4b64b94b9 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Mon, 9 Mar 2026 18:23:03 +0200 Subject: [PATCH 2/6] Add content to oidc.md - add content to oidc, which includes beginner explanations for authentication flow, why use OIDC and standard setup from the PG side. --- docs/solutions.md | 2 +- docs/solutions/authentication/oidc.md | 75 +++++++++++++++++++++++++++ 2 files changed, 76 insertions(+), 1 deletion(-) diff --git a/docs/solutions.md b/docs/solutions.md index 8f29d8a77..7b20d28a0 100644 --- a/docs/solutions.md +++ b/docs/solutions.md @@ -34,7 +34,7 @@ Dealing with spatial data? Learn how you can store and manipulate it. Need centralized authentication? Learn how to integrate PostgreSQL with identity providers such as LDAP directories or OpenID Connect. -[Authentication :material-arrow-right:](solutions/authentication/index.md){.md-button} +[Authentication :material-arrow-right:](solutions/authentication/overview.md){.md-button} diff --git a/docs/solutions/authentication/oidc.md b/docs/solutions/authentication/oidc.md index e69de29bb..898f60a5a 100644 --- a/docs/solutions/authentication/oidc.md +++ b/docs/solutions/authentication/oidc.md @@ -0,0 +1,75 @@ +# 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 the PostgreSQL authentication process. + +## 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. + +## Authentication flow + +The 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 + +## Set up OIDC authentication + +Follow these steps to set up OIDC authentication for your PostgreSQL database. +{.power-number} + +1. Install the `pg_oidc_validator` package: + + For Debian/Ubuntu: + + ```bash + sudo apt install pg-oidc-validator-pgdg{{pgversion}} + ``` + + For RHEL/Oracle Linux/Rocky Linux: + + ```bash + sudo dnf install pg-oidc-validator-pgdg{{pgversion}} + ``` + +2. Edit `postgresql.conf` and add the validator library: + + ```ini + 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`: + + ```ini + 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: + + ```ini + sudo systemctl restart postgresql + ``` + +!!! important + Percona Distribution for PostgreSQL does not issue OIDC tokens. You must obtain a valid access token from an external identity provider such as Keycloak, Okta, or Microsoft Entra ID before connecting. From fb388e2908c0f014e67c7b7ab56715d447cdefb6 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Tue, 10 Mar 2026 13:58:41 +0200 Subject: [PATCH 3/6] Add buttons and links - Add buttons to overview, and add a lot of links to the oidc chapter for all of our sources. --- docs/_images/diagrams/oidc-auth-flow.svg | 102 ++++++++++++++++++++++ docs/solutions/authentication/oidc.md | 32 +++++-- docs/solutions/authentication/overview.md | 4 +- 3 files changed, 127 insertions(+), 11 deletions(-) create mode 100644 docs/_images/diagrams/oidc-auth-flow.svg diff --git a/docs/_images/diagrams/oidc-auth-flow.svg b/docs/_images/diagrams/oidc-auth-flow.svg new file mode 100644 index 000000000..a4de037ea --- /dev/null +++ b/docs/_images/diagrams/oidc-auth-flow.svg @@ -0,0 +1,102 @@ +pg_oidc_validatorPostgreSQLIdentity Provider (OIDC)Clientpg_oidc_validatorPostgreSQLIdentity Provider (OIDC)ClientRequest authenticationReturn OIDC access tokenConnect using OAuth tokenValidate tokenToken valid / invalidConnection allowed or rejected \ No newline at end of file diff --git a/docs/solutions/authentication/oidc.md b/docs/solutions/authentication/oidc.md index 898f60a5a..cd15a07fa 100644 --- a/docs/solutions/authentication/oidc.md +++ b/docs/solutions/authentication/oidc.md @@ -1,8 +1,15 @@ # 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. +[OpenID Connect :octicons-link-external-16:](https://openid.net/developers/how-connect-works/) (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 the PostgreSQL authentication process. +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:](https://www.percona.com/blog/postgresql-oidc-authentication-with-pg_oidc_validator/) blog post. + +For additional configuration details and source code, see the [pg_oidc_validator project :octicons-link-external-16:](https://github.com/Percona-Lab/pg_oidc_validator). + +!!! important + OIDC authentication relies on [PostgreSQL OAuth authentication :octicons-link-external-16:](https://www.postgresql.org/docs/current/auth-oauth.html), introduced in PostgreSQL 18. ## When to use OIDC authentication @@ -13,11 +20,11 @@ OIDC authentication is useful when you want to: * 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 simplifies access management for PostgreSQL when using an identity provider that supports OpenID Connect. -## Authentication flow +## OIDC authentication architecture -The OIDC authentication works as follows: +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 @@ -25,6 +32,13 @@ The OIDC authentication works as follows: 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: + +![OIDC authentication flow](../../_images/diagrams/oidc-auth-flow.svg) + +!!! 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. @@ -51,7 +65,7 @@ Follow these steps to set up OIDC authentication for your PostgreSQL database. ``` !!! note - This setting tells PostgreSQL to load the OIDC validator during startup. + This setting tells PostgreSQL to load the OIDC validator during startup. 3. Add an OAuth authentication rule to `pg_hba.conf`: @@ -67,9 +81,9 @@ Follow these steps to set up OIDC authentication for your PostgreSQL database. 4. Restart PostgreSQL for the changes to take effect: - ```ini - sudo systemctl restart postgresql + ```bash + sudo systemctl restart postgresql-{{pgversion}} ``` !!! important - Percona Distribution for PostgreSQL does not issue OIDC tokens. You must obtain a valid access token from an external identity provider such as Keycloak, Okta, or Microsoft Entra ID before connecting. + 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. diff --git a/docs/solutions/authentication/overview.md b/docs/solutions/authentication/overview.md index 748d2be4e..d2f0b31ba 100644 --- a/docs/solutions/authentication/overview.md +++ b/docs/solutions/authentication/overview.md @@ -10,10 +10,10 @@ Percona Distribution for PostgreSQL supports multiple authentication mechanisms Use LDAP directories such as OpenLDAP or Active Directory to centrally manage database users. -[LDAP authentication](ldap.md) +[LDAP authentication :material-arrow-right:](ldap.md){.md-button} ### OIDC authentication Authenticate users using OpenID Connect identity providers such as Keycloak, Okta, or Microsoft Entra ID. -[OIDC authentication](oidc.md) +[OIDC authentication :material-arrow-right:](oidc.md){.md-button} From 4ac80d07dedf849a2db54868824c4c07383c4b5a Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Fri, 17 Apr 2026 17:01:17 +0300 Subject: [PATCH 4/6] reword the intro paragraph and remove leading config to blog --- docs/solutions/authentication/oidc.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/solutions/authentication/oidc.md b/docs/solutions/authentication/oidc.md index cd15a07fa..3265ee182 100644 --- a/docs/solutions/authentication/oidc.md +++ b/docs/solutions/authentication/oidc.md @@ -2,11 +2,11 @@ [OpenID Connect :octicons-link-external-16:](https://openid.net/developers/how-connect-works/) (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. +Percona Distribution for PostgreSQL integrates OIDC authentication using the pg_oidc_validator library, which validates OIDC tokens during client 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:](https://www.percona.com/blog/postgresql-oidc-authentication-with-pg_oidc_validator/) blog post. +The library is compatible with standard OIDC providers. -For additional configuration details and source code, see the [pg_oidc_validator project :octicons-link-external-16:](https://github.com/Percona-Lab/pg_oidc_validator). +For configuration details and source code, see the [pg_oidc_validator project :octicons-link-external-16:](https://github.com/Percona-Lab/pg_oidc_validator). !!! important OIDC authentication relies on [PostgreSQL OAuth authentication :octicons-link-external-16:](https://www.postgresql.org/docs/current/auth-oauth.html), introduced in PostgreSQL 18. From 80c666de0993a0054ed3febc4e5838eaab9036cc Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Mon, 20 Apr 2026 15:21:06 +0300 Subject: [PATCH 5/6] Updated the oidc topic - Proper installation steps, updated step 1 with readme info and remove step 2 - Reordered TOC to put OIDC first - create a snippet folder with proper oidc authentication flow which can be modified any time to render immediately as opposed to having an svg, using mermaid. - standardize the external identity providers, making a list of them is too bloaty. --- docs/solutions/authentication/oidc.md | 32 +++++++++++------------ docs/solutions/authentication/overview.md | 12 ++++----- mkdocs.yml | 2 +- snippets/diagrams/oidc/auth-flow.md | 16 ++++++++++++ 4 files changed, 38 insertions(+), 24 deletions(-) create mode 100644 snippets/diagrams/oidc/auth-flow.md diff --git a/docs/solutions/authentication/oidc.md b/docs/solutions/authentication/oidc.md index 3265ee182..ad0df8248 100644 --- a/docs/solutions/authentication/oidc.md +++ b/docs/solutions/authentication/oidc.md @@ -2,9 +2,9 @@ [OpenID Connect :octicons-link-external-16:](https://openid.net/developers/how-connect-works/) (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 integrates OIDC authentication using the pg_oidc_validator library, which validates OIDC tokens during client authentication. +Percona Distribution for PostgreSQL integrates OIDC authentication using the `pg_oidc_validator` library, which validates OIDC tokens during client authentication. -The library is compatible with standard OIDC providers. +The library is compatible with any identity provider that implements the OIDC standard. For configuration details and source code, see the [pg_oidc_validator project :octicons-link-external-16:](https://github.com/Percona-Lab/pg_oidc_validator). @@ -34,7 +34,7 @@ OIDC authentication works as follows: The following diagram shows how OIDC authentication works between the client, the identity provider, and PostgreSQL: -![OIDC authentication flow](../../_images/diagrams/oidc-auth-flow.svg) +--8<-- "diagrams/oidc/auth-flow.md" !!! tip Before configuring OIDC authentication, ensure that your PostgreSQL deployment can access the identity provider that issues OIDC tokens. @@ -44,20 +44,24 @@ The following diagram shows how OIDC authentication works between the client, th Follow these steps to set up OIDC authentication for your PostgreSQL database. {.power-number} -1. Install the `pg_oidc_validator` package: +1. Install the `pg_oidc_validator` package. - For Debian/Ubuntu: + Pre-built packages are not available in the default system repositories. - ```bash - sudo apt install pg-oidc-validator-pgdg{{pgversion}} - ``` + You can download pre-built packages from the `pg_oidc_validator` project (see the project releases page): + + - Debian/Ubuntu: available for Ubuntu 24.04 + - RHEL/Oracle Linux/Rocky Linux: RPM packages for OL8 and OL9 - For RHEL/Oracle Linux/Rocky Linux: + Alternatively, you can build the extension from source: ```bash - sudo dnf install pg-oidc-validator-pgdg{{pgversion}} + make USE_PGXS=1 install -j ``` + !!! note + A C++23 compiler and standard library is required to build pg_oidc_validator. + 2. Edit `postgresql.conf` and add the validator library: ```ini @@ -79,11 +83,5 @@ Follow these steps to set up OIDC authentication for your PostgreSQL database. * `scope` is the required OIDC scope * `issuer` is the URL of the OIDC identity provider -4. Restart PostgreSQL for the changes to take effect: - - ```bash - 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. + PostgreSQL does not issue OIDC tokens. Clients must obtain an access token from an external identity provider before connecting. diff --git a/docs/solutions/authentication/overview.md b/docs/solutions/authentication/overview.md index d2f0b31ba..10f206835 100644 --- a/docs/solutions/authentication/overview.md +++ b/docs/solutions/authentication/overview.md @@ -6,14 +6,14 @@ Percona Distribution for PostgreSQL supports multiple authentication mechanisms ## Available authentication methods -### LDAP authentication - -Use LDAP directories such as OpenLDAP or Active Directory to centrally manage database users. - -[LDAP authentication :material-arrow-right:](ldap.md){.md-button} - ### OIDC authentication Authenticate users using OpenID Connect identity providers such as Keycloak, Okta, or Microsoft Entra ID. [OIDC authentication :material-arrow-right:](oidc.md){.md-button} + +### LDAP authentication + +Use LDAP directories such as OpenLDAP or Active Directory to centrally manage database users. + +[LDAP authentication :material-arrow-right:](ldap.md){.md-button} diff --git a/mkdocs.yml b/mkdocs.yml index 66b184884..636374af7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -64,8 +64,8 @@ nav: - Upgrade spatial database: solutions/postgis-upgrade.md - Authentication: - Overview: solutions/authentication/overview.md - - LDAP authentication: solutions/authentication/ldap.md - OIDC authentication: solutions/authentication/oidc.md + - LDAP authentication: solutions/authentication/ldap.md - Upgrade: - "Major upgrade": major-upgrade.md - minor-upgrade.md diff --git a/snippets/diagrams/oidc/auth-flow.md b/snippets/diagrams/oidc/auth-flow.md new file mode 100644 index 000000000..f24fb1ed3 --- /dev/null +++ b/snippets/diagrams/oidc/auth-flow.md @@ -0,0 +1,16 @@ +```mermaid +sequenceDiagram + participant Client + participant IdP as Identity Provider (OIDC) + participant PostgreSQL + participant Validator as pg_oidc_validator + + Client->>IdP: Request authentication + IdP-->>Client: Return OIDC access token + + Client->>PostgreSQL: Connect using OAuth token + PostgreSQL->>Validator: Validate token + Validator-->>PostgreSQL: Token valid / invalid + + PostgreSQL-->>Client: Connection allowed or rejected +``` From d8fe01a2769c38b9b598d1dffae38df71498c4bb Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Mon, 20 Apr 2026 16:07:43 +0300 Subject: [PATCH 6/6] Update overview.md --- docs/solutions/authentication/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/solutions/authentication/overview.md b/docs/solutions/authentication/overview.md index 10f206835..e5bc06857 100644 --- a/docs/solutions/authentication/overview.md +++ b/docs/solutions/authentication/overview.md @@ -8,7 +8,7 @@ Percona Distribution for PostgreSQL supports multiple authentication mechanisms ### OIDC authentication -Authenticate users using OpenID Connect identity providers such as Keycloak, Okta, or Microsoft Entra ID. +Authenticate users using OpenID Connect identity providers. [OIDC authentication :material-arrow-right:](oidc.md){.md-button}