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.md b/docs/solutions.md index 0fcec063b..7b20d28a0 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/overview.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..cd15a07fa --- /dev/null +++ b/docs/solutions/authentication/oidc.md @@ -0,0 +1,89 @@ +# OIDC authentication + +[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. + +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 + +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: + +![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. +{.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: + + ```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. diff --git a/docs/solutions/authentication/overview.md b/docs/solutions/authentication/overview.md new file mode 100644 index 000000000..d2f0b31ba --- /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 :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} 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