Security and Encryption
The simplest way to log into PostgreSQL is by specifying a
Username and a
Password in your connection string. Depending on how your PostgreSQL is configured (in the
pg_hba.conf file), Npgsql will send the password in MD5 or in cleartext (not recommended).
Password is not specified and your PostgreSQL is configured to request a password (plain or MD5), Npgsql will look for a standard PostgreSQL password file. If you specify the
Passfile connection string parameter, the file it specifies will be used. If that parameter isn't defined, Npgsql will look under the path taken from
PGPASSFILE environment variable. If the environment variable isn't defined, Npgsql will fall back to the system-dependent default directory which is
$HOME/.pgpass for Unix and
%APPDATA%\postgresql\pgpass.conf for Windows.
NpgsqlConnection can also be configured with a
ProvidePasswordCallback. This will be executed when new database connections are opened to generate a password in code. This can be useful if you are using Amazon Web Services RDS for Postgres which can be configured to use short lived tokens generated based on access credentials. The
ProvidePasswordCallback delegate is executed when both password and
Passfile connection string parameters are not specified.
For documentation about all auth methods supported by PostgreSQL, see this page. Note that Npgsql supports Unix-domain sockets (auth method
local), simply set your
Host parameter to the absolute path of your PostgreSQL socket directory, as configured in your
Integrated Security (GSS/SSPI/Kerberos)
Logging in with a username and password may not be ideal, since your application must have access to your password, and raise questions around secret management. An alternate way of authenticating is "Integrated Security", which uses GSS or SSPI to negotiate Kerberos. The advantage of this method is that authentication is handed off to your operating system, using your already-open login session. Your application never needs to handle a password. You can use this method for a Kerberos login, Windows Active Directory or a local Windows session. Note that since 3.2, this method of authentication also works on non-Windows platforms.
Once your PostgreSQL is configured correctly, simply include
Integrated Security=true in your connection string and drop the
Password parameter. However, Npgsql must still send a username to PostgreSQL. If you specify a
Username connection string parameter, Npgsql will send that as usual. If you omit it, Npgsql will attempt to detect your system username, including the Kerberos realm. Note that by default, PostgreSQL expects your Kerberos realm to be sent in your username (e.g.
username@REALM); you can have Npgsql detect the realm by setting
Include Realm to true in your connection string. Alternatively, you can disable add
include_realm=0 in your PostgreSQL's pg_hba.conf entry, which will make it strip the realm. You always have the possibility of explicitly specifying the username sent to PostgreSQL yourself.
By default PostgreSQL connections are unencrypted, but you can turn on SSL/TLS encryption if you wish. First, you have to set up your PostgreSQL to receive SSL/TLS connections as described here. Once that's done, specify
SSL Mode in your connection string, setting it to either
Require (connection will fail if the server isn't set up for encryption), or
Prefer (use encryption if possible but fallback to unencrypted otherwise).
By default, Npgsql will validate your server's certificate; if you're using a self-signed certificate, this will fail. You can instruct Npgsql to ignore this by specifying
Trust Server Certificate=true in the connection string. To precisely control how the server's certificate is validated, you can register
NpgsqlConnection (this works just like on .NET's
If you need provide client certificates as part of authentication, you can point Npgsql to a certificate file by setting the
Client Certificate connection string parameter. Npgsql will also implement the standard PostgreSQL behavior and will recognize the
PGSSLCERT environment variable, as well as
%APPDATA%\postgresql\postgresql.crt on Windows). Finally, you can set the
NpgsqlConnection to further customize how client certificates are provided (this works just like on .NET's