--- title: "TLS and authentication" url: "https://docs.yugabyte.com/stable/secure/tls-encryption/tls-authentication/" --- # TLS and authentication Use authentication in conjunction with TLS encryption. Use authentication in conjunction with TLS encryption TLS can be configured in conjunction with authentication using the following configuration flags related to TLS and authentication: - [ysql\_enable\_auth](/stable/secure/authentication/password-authentication/ "ysql_enable_auth") to enable password authentication (SCRAM-SHA-256 by default for new clusters; MD5 for upgraded clusters unless overridden) - [use\_client\_to\_server\_encryption](/stable/secure/tls-encryption/server-to-server/ "use_client_to_server_encryption") to enable client-server TLS encryption - [ysql\_hba\_conf\_csv](/stable/secure/authentication/host-based-authentication/ "ysql_hba_conf_csv") to manually set a host-based authentication (HBA) configuration The default (auto-generated) configuration in the `ysql_hba.conf` file depends on whether auth (`ysql_enable_auth`) and/or TLS (`use_client_to_server_encryption`) are enabled. The four default cases are shown in the following table. Auth disabled Auth enabled TLS disabled `host all all all trust` (no ssl, no password) `host all all all scram-sha-256` (no ssl, password required; default for new clusters; upgraded clusters may use `md5` unless overridden) TLS enabled `hostssl all all all trust` (require ssl, no password) `hostssl all all all scram-sha-256` (require ssl and password; default for new clusters; upgraded clusters may use `md5` unless overridden) Additionally, `ysql_hba_conf_csv` can be used to manually configure a custom HBA configuration. For instance, to use TLS with both password authentication and client certificate verification, you can set the `ysql_hba_conf_csv` flag as follows (use `scram-sha-256` for SCRAM, or `md5` if needed for compatibility): ```sh hostssl all all all scram-sha-256 clientcert=verify-full ``` Note To use the client certificate only for verification (signed by the CA) but not for authentication, you can set `clientcert` to `verify-ca`. The `ysql_hba_conf_csv` rules are added above the auto-generated rules in the `ysql_hba.conf` file, so if they do not match the connection type, database, user, or host, then the auto-generated rules (that is, from the table above) may still be used. If the custom user-defined rules only apply to some connection types (for example, host vs hostssl), databases, users, or hosts, the auto-generated rules are applied to the non-matching hosts, users, or databases. To fully disable the auto-generated rules, use the `reject` auth option. For instance, to enable TLS with `cert` authentication, but only for some particular database, user, and host, use the following `ysql_hba_conf_csv` setting: ```sh hostssl mydb myuser myhost cert,hostssl all all all reject ``` ## Examples To secure clusters when deploying using yugabyted, you use the [--secure flag](/stable/reference/configuration/yugabyted/#start "--secure flag"), which enables encryption in transit and authentication. For the purposes of illustration, the following examples enable these features manually. To begin, generate and configure certificates using the following steps: 1. Generate the certificates and keys for the local IP address (`127.0.0.1` in this example) using the `cert generate_server_certs` command. See [create certificates for a secure local cluster](/stable/reference/configuration/yugabyted/#create-certificates-for-a-secure-local-multi-node-cluster "create certificates for a secure local cluster") for more information. ```sh ./bin/yugabyted cert generate_server_certs --hostnames=127.0.0.1 ``` Certificates are generated in the `/var/generated_certs/` directory. ```output 127.0.0.1 ├── ca.crt ├── node.127.0.0.1.crt └── node.127.0.0.1.key ``` `node.127.0.0.1.crt` and `node.127.0.0.1.key` are the default values for the `ssl_cert_file` and `ssl_key_file` server-side configuration for a YSQL node. If your local IP is not 127.0.0.1, then use the appropriate local IP to name the two files. Alternatively, use [ysql\_pg\_conf\_csv](/stable/reference/configuration/all-flags-yb-tserver/#ysql-pg-conf-csv "ysql_pg_conf_csv") to set `ssl_cert_file` and `ssl_key_file` to the appropriate values. 2. Set the `ENABLE_TLS` variable to point to the directory where the certificates are stored, and set the `use_client_to_server_encryption` flag to true as follows: ```sh $ cd ~/var/generated_certs/127.0.0.1 $ CERTS=$(pwd) $ ENABLE_TLS="use_client_to_server_encryption=true,certs_for_client_dir=$CERTS" ``` ### TLS without authentication This configuration requires the client to use client-to-server encryption to connect. Create the database: ```sh $ ./bin/yugabyted start \ --tserver_flags="$ENABLE_TLS" ``` Without SSL enabled in the client, the connection fails. ```sh $ ./bin/ysqlsh "sslmode=disable" ``` ```output ysqlsh: FATAL: no pg_hba.conf entry for host "127.0.0.1", user "yugabyte", database "yugabyte", SSL off ``` To connect, SSL must be enabled in the client. ```sh $ ./bin/ysqlsh "sslmode=require" ``` ```output ysqlsh (15.2-YB-2026.1.2.0-b0) SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off) Type "help" for help. ``` The default ysqlsh SSL mode is `prefer` (refer to [SSL Support](https://www.postgresql.org/docs/15/libpq-ssl.html "SSL Support") in the PostgreSQL documentation), which tries SSL first, but falls back to `disable` if the server does not support it. In this case, a plain ysqlsh with no options will work and use encryption: ```sh $ ./bin/ysqlsh ``` ```output ysqlsh (15.2-YB-2026.1.2.0-b0) SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off) Type "help" for help. ``` The following examples omit setting `sslmode` for brevity. ### TLS with authentication This configuration requires the client to use client-to-server encryption and authenticate with a password to connect. To create the database, execute the following command: ```sh $ ./bin/yugabyted destroy && \ ./bin/yugabyted cert generate_server_certs --hostnames=127.0.0.1 && \ ./bin/yugabyted start \ --tserver_flags="$ENABLE_TLS,ysql_enable_auth=true" ``` To connect to the database, the password is required (see second line below): ```sh $ ./bin/ysqlsh ``` ```output Password for user yugabyte: ysqlsh (15.2-YB-2026.1.2.0-b0) SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off) Type "help" for help. ``` The other modes (that is, `sslmode=require` or `disable`) behave analogously. ### TLS with SCRAM-based password authentication This configuration (also known as SCRAM-SHA-256-PLUS) enables authentication with SCRAM using TLS channel-binding as described in [RFC 7677](https://tools.ietf.org/html/rfc7677 "RFC 7677"). When enabled, information about the TLS channel is encoded in the authentication messages exchanged; this ensures the client and server share the same TLS channel (that is, binding the channel to the authentication mechanism). To enable SCRAM-SHA-256-PLUS for a user already using SCRAM-SHA-256, you set the `ysql_enable_scram_channel_binding` YB-TServer flag to true. For example, to create a database, execute the following command: ```sh $ ./bin/yugabyted destroy && \ ./bin/yugabyted cert generate_server_certs --hostnames=127.0.0.1 && \ ./bin/yugabyted start \ --tserver_flags="ysql_enable_auth=true,ysql_enable_scram_channel_binding=true,$ENABLE_TLS" ``` Note that this configuration requires the client to use client-to-server encryption. For more information on enabling SCRAM-SHA-256 password encryption, refer to [Password authentication](/stable/secure/authentication/password-authentication/#scram-sha-256 "Password authentication"). ### TLS with authentication via certificate This configuration requires the client to use client-to-server encryption and authenticate with the appropriate certificate to connect. To create the database, execute the following command: ```sh $ ./bin/yugabyted destroy && \ ./bin/yugabyted cert generate_server_certs --hostnames=127.0.0.1 && \ ./bin/yugabyted start \ --tserver_flags="$ENABLE_TLS,ysql_hba_conf_csv={hostssl all all all cert}" ``` Without a certificate, the connection fails. ```sh $ ./bin/ysqlsh ``` ```output ysqlsh: FATAL: connection requires a valid client certificate FATAL: no pg_hba.conf entry for host "127.0.0.1", user "yugabyte", database "yugabyte", SSL off ``` Use the following command to connect with a certificate: ```sh $ ./bin/ysqlsh "sslcert=$CERTS/node.127.0.0.1.crt sslkey=$CERTS/node.127.0.0.1.key sslrootcert=$CERTS/ca.crt" ``` ```output ysqlsh (15.2-YB-2026.1.2.0-b0) SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off) Type "help" for help. ``` ### TLS with password and certificate authentication This configuration requires the client to use client-to-server encryption and authenticate with both the appropriate certificate and the password to connect. To create the database, execute the following command: ```sh $ ./bin/yugabyted destroy && \ ./bin/yugabyted cert generate_server_certs --hostnames=127.0.0.1 && \ ./bin/yugabyted start \ --tserver_flags="$ENABLE_TLS,ysql_hba_conf_csv={hostssl all all all scram-sha-256 clientcert=verify-full}" ``` The `ysql_enable_auth=true` flag is redundant in this case, but included to demonstrate the ability to override the auto-generated configuration using `ysql_hba_conf_csv`. Without a certificate and password, the connection fails. ```sh $ ./bin/ysqlsh ``` ```output ysqlsh: FATAL: connection requires a valid client certificate FATAL: no pg_hba.conf entry for host "127.0.0.1", user "yugabyte", database "yugabyte", SSL off ``` Use the following command to connect with a certificate and password: ```sh $ ./bin/ysqlsh "sslcert=$CERTS/node.127.0.0.1.crt sslkey=$CERTS/node.127.0.0.1.key sslrootcert=$CERTS/ca.crt" ``` ```output Password for user yugabyte: ysqlsh (15.2-YB-2026.1.2.0-b0) SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off) Type "help" for help. ```