credcheck

Overview

Version

Install

You can install credcheck directly. First, make sure the PGDG repository is added and enabled:

pig repo add pgdg -u          # Add PGDG repo and update cache

Install the extension using pig or apt/yum/dnf:

pig install credcheck;          # Install for current active PG version

pig ext install -y credcheck -v 18  # PG 18
pig ext install -y credcheck -v 17  # PG 17
pig ext install -y credcheck -v 16  # PG 16
pig ext install -y credcheck -v 15  # PG 15
pig ext install -y credcheck -v 14  # PG 14

dnf install -y credcheck_18       # PG 18
dnf install -y credcheck_17       # PG 17
dnf install -y credcheck_16       # PG 16
dnf install -y credcheck_15       # PG 15
dnf install -y credcheck_14       # PG 14

apt install -y postgresql-18-credcheck   # PG 18
apt install -y postgresql-17-credcheck   # PG 17
apt install -y postgresql-16-credcheck   # PG 16
apt install -y postgresql-15-credcheck   # PG 15
apt install -y postgresql-14-credcheck   # PG 14

Preload:

shared_preload_libraries = 'credcheck';

Create Extension:

CREATE EXTENSION credcheck;

Usage

Sources: README, release 4.7

credcheck enforces configurable rules for PostgreSQL usernames and passwords during CREATE ROLE, ALTER ROLE, password changes, and role renames. It can reject weak credentials, enforce password expiration windows, track password reuse, ban users after repeated authentication failures, delay failed authentication responses, force first-login password changes, and block password changes for ordinary users.

Required Setup

Add to postgresql.conf:

shared_preload_libraries = 'credcheck'

Restart PostgreSQL after changing preload libraries. Password reuse history, authentication failure banning, first-login password changes, and login-time expiry warnings depend on preload or login-event support described in the upstream README.

Configuration Parameters

Username Checks

Password Checks

If built with cracklib support, credcheck can also reject passwords that are easy to crack.

Examples

-- Rejected: username too short
CREATE USER abc WITH PASSWORD 'pass';
-- ERROR: username length should match the configured credcheck.username_min_length

-- Rejected: password contains username
CREATE USER abcd$ WITH PASSWORD 'abcd$xyz';
-- ERROR: password should not contain username

Enforce password lifetime bounds:

SET credcheck.password_valid_until = 30;
SET credcheck.password_valid_max = 180;

CREATE USER abcd$;
-- ERROR: require a VALID UNTIL option with a date older than 30 days

Password Reuse Policy

SET credcheck.password_reuse_history = 2;
SET credcheck.password_reuse_interval = 365;  -- days

View password history:

SELECT rolename, password_hash FROM pg_password_history;

The upstream README says password hashes are kept in shared memory and saved to $PGDATA/pg_password_history, so include that file in backup planning. Use credcheck.history_max_size to size the cache; changing it requires a PostgreSQL restart.

Authentication Failure Ban

SET credcheck.max_auth_failure = 3;  -- ban after 3 failures
SET credcheck.auth_delay_ms = 1000;  -- delay failed authentication
SET credcheck.whitelist_auth_failure = 'appuser1,appuser2';

Reset banned users:

SELECT pg_banned_role_reset();              -- reset all
SELECT pg_banned_role_reset('username');     -- reset specific user

credcheck.reset_superuser can force superusers to be exempt from banning or reset a banned superuser.

First-Login And Password-Change Controls

Force a new user to change the password before running normal queries:

SET credcheck.password_change_first_login = true;
CREATE USER user1 PASSWORD 'Rkd89,34' VALID UNTIL '2050-12-31';
-- first login:
-- ERROR: you must change your password first.
ALTER USER user1 PASSWORD 'Zkd89,34';

Force the same behavior later:

ALTER USER user1 SET credcheck_internal.force_change_password = true;

Version 4.7 adds credcheck.disallow_password_change for sites where users must not change their own password:

SET credcheck.disallow_password_change = on;
ALTER ROLE user1 PASSWORD 'My-New-Pass#123';
-- ERROR: you are not allowed to change your password.