[role="xpack"]
[testenv="basic"]
[[sql-security]]
== Security

{es-sql} integrates with security, if this is enabled on your cluster. 
In such a scenario, {es-sql} supports both security at the transport layer (by encrypting the communication between the consumer and the server) and authentication (for the access layer).

[float]
[[ssl-tls-config]]
==== SSL/TLS configuration

In case of an encrypted transport, the SSL/TLS support needs to be enabled in {es-sql} to properly establish communication with {es}. This is done by setting the `ssl` property to `true` or by using the `https` prefix in the URL. +
Depending on your SSL configuration (whether the certificates are signed by a CA or not, whether they are global at JVM level or just local to one application), might require setting up the `keystore` and/or `truststore`, that is where the _credentials_ are stored (`keystore` - which typically stores private keys and certificates) and how to _verify_ them (`truststore` - which typically stores certificates from third party also known as CA - certificate authorities). +
Typically (and again, do note that your environment might differ significantly), if the SSL setup for {es-sql} is not already done at the JVM level, one needs to setup the keystore if the {es-sql} security requires client authentication (PKI - Public Key Infrastructure), and setup `truststore` if SSL is enabled.

[float]
==== Authentication

The authentication support in {es-sql} is of two types:

Username/Password:: Set these through `user` and `password` properties.
PKI/X.509:: Use X.509 certificates to authenticate {es-sql} to {es}. For this, one would need to setup the `keystore` containing the private key and certificate to the appropriate user (configured in {es}) and the `truststore` with the CA certificate used to sign the SSL/TLS certificates in the {es} cluster. That is, one should setup the key to authenticate {es-sql} and also to verify that is the right one. To do so, one should set the `ssl.keystore.location` and `ssl.truststore.location` properties to indicate the `keystore` and `truststore` to use. It is recommended to have these secured through a password in which case `ssl.keystore.pass` and `ssl.truststore.pass` properties are required.

[float]
[[sql-security-permissions]]
==== Permissions (server-side)
Lastly, one the server one need to add a few permissions to
users so they can run SQL. To run SQL a user needs `read` and
`indices:admin/get` permissions at minimum while some parts of 
the API require `cluster:monitor/main`. 

The following example configures a role that can run SQL in JDBC querying the `test` and `bort`
indices:

["source","yaml",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-tests}/security/roles.yml[cli_drivers]
--------------------------------------------------