6.2. Authentication Methods

The following subsections describe the authentication methods in more detail.

6.2.1. Trust Authentication

When trust authentication is specified, Pgpool-II assumes that anyone who can connect to the server is authorized to access connect with whatever database user name they specify.

6.2.2. Clear Text Password Authentication

The method password sends the password in clear-text and is therefore vulnerable to password "sniffing" attacks. It should always be avoided if possible. If the connection is protected by SSL encryption then password can be used safely, though. For this sake, it is recommended to use hostssl in pool_hba.conf so that clients are enforced to use SSL encryption.

A benefit to use the method is, the password for authentication is provided by client side and pool_passwd is not consulted. So you can avoid maintaining pool_passwd file.

You can avoid maintaining pool_passwd by using allow_clear_text_frontend_auth as well but it does not enforce to use SSL encryption because pool_hba.conf cannot be used with the parameter.

6.2.3. MD5 Password Authentication

This authentication method is the password-based authentication methods in which MD-5-hashed password is sent by client. Since Pgpool-II does not has the visibility of PostgreSQL's database user password and client application only sends the MD5-hash of the password, so md5 authentication in Pgpool-II is supported using the pool_passwd authentication file.

Note: If Pgpool-II is operated in raw mode or there's only 1 backend configured, you don't need to setup pool_passwd.

6.2.3.1. Authentication file format

To use the md5 authentication pool_passwd authentication file must contain the user password in either plain text md5 or AES encrypted format.

The pool_passwd file should contain lines in the following format:

       "username:plain_text_passwd"
      

       "username:encrypted_passwd"
      

6.2.3.2. Setting md5 Authentication

here are the steps to enable md5 authentication:

1- Login as the database's operating system user and type "pg_md5 --config-file=path_to_pgpool.conf --md5auth --username=username password" user name and md5 encrypted password are registered into pool_passwd. If pool_passwd does not exist yet, pg_md5 command will automatically create it for you.

Note: user name and password must be identical to those registered in PostgreSQL server.

2- Add an appropriate md5 entry to pool_hba.conf. See Section 6.1 for more details.

3- After changing md5 password (in both pool_passwd and PostgreSQL of course), reload the pgpool configurations.

6.2.4. scram-sha-256 Authentication

This authentication method also known as SCRAM is a challenge-response based authentication that prevents the password sniffing on untrusted connections. Since Pgpool-II does not has the visibility of PostgreSQL's database user password, so SCRAM authentication is supported using the pool_passwd authentication file.

6.2.4.1. Authentication file entry for SCRAM

To use the SCRAM authentication pool_passwd authentication file must contain the user password in either plain text or AES encrypted format.

       "username:plain_text_passwd"
      

       "username:AES_encrypted_passwd"
      

Note: md5 type user passwords in pool_passwd file can't be used for scram authentication

6.2.4.2. Setting scram-sha-256 Authentication

Here are the steps to enable scram-sha-256 authentication:

1- Create pool_passwd file entry for database user and password in plain text or AES encrypted format. The pg_enc utility that comes with Pgpool-II can be used to create the AES encrypted password entries in the pool_passwd file.

Note: User name and password must be identical to those registered in the PostgreSQL server.

2- Add an appropriate scram-sha-256 entry to pool_hba.conf. See Section 6.1 for more details.

3- After changing SCRAM password (in both pool_passwd and PostgreSQL of course), reload the Pgpool-II configuration.

6.2.5. Certificate Authentication

This authentication method uses SSL client certificates to perform authentication. It is therefore only available for SSL connections. When using this authentication method, the Pgpool-II will require that the client provide a valid certificate. No password prompt will be sent to the client. The cn (Common Name) attribute of the certificate will be compared to the requested database user name, and if they match the login will be allowed.

Note: The certificate authentication works between only client and Pgpool-II. The certificate authentication does not work between Pgpool-II and PostgreSQL. For backend authentication you can use any other authentication method.

6.2.6. PAM Authentication

This authentication method uses PAM (Pluggable Authentication Modules) as the authentication mechanism. The default PAM service name is pgpool. PAM authentication is supported using user information on the host where Pgpool-II is executed. For more information about PAM, please read the Linux-PAM Page.

To enable PAM authentication, you need to create a service-configuration file for Pgpool-II in the system's PAM configuration directory (which is usually at "/etc/pam.d"). A sample service-configuration file is installed as "share/pgpool-II/pgpool.pam" under the install directory.

Note: To enable PAM support the Pgpool-II must be configured with "--with-pam"

6.2.7. GSSAPI Authentication

GSSAPI is an industry-standard protocol for secure authentication defined in RFC 2743. Currently Pgpool-II does not support GSSAPI. Clients should not use GSSAPI authentication, or should use "prefer GSSAPI authentication if possible" option (this is the default setting of PostgreSQL clients). If latter is chosen, Pgpool-II requests non-GSSAPI authentication to client, and the clients will fall back to non-GSSAPI authentication method. Thus, usually users do not need to worry about that Pgpool-II does not accept GSSAPI authentication.