Security
editSecurity
editElasticsearch SQL integrates with security, if this is enabled on your cluster. In such a scenario, Elasticsearch SQL supports both security at the transport layer (by encrypting the communication between the consumer and the server) and authentication (for the access layer).
SSL/TLS configuration
editIn case of an encrypted transport, the SSL/TLS support needs to be enabled in Elasticsearch SQL to properly establish communication with Elasticsearch. 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 Elasticsearch SQL is not already done at the JVM level, one needs to setup the keystore if the Elasticsearch SQL security requires client authentication (PKI - Public Key Infrastructure), and setup truststore
if SSL is enabled.
Authentication
editThe authentication support in Elasticsearch SQL is of two types:
- Username/Password
-
Set these through
user
andpassword
properties. - PKI/X.509
-
Use X.509 certificates to authenticate Elasticsearch SQL to Elasticsearch. For this, one would need to setup the
keystore
containing the private key and certificate to the appropriate user (configured in Elasticsearch) and thetruststore
with the CA certificate used to sign the SSL/TLS certificates in the Elasticsearch cluster. That is, one should setup the key to authenticate Elasticsearch SQL and also to verify that is the right one. To do so, one should set thessl.keystore.location
andssl.truststore.location
properties to indicate thekeystore
andtruststore
to use. It is recommended to have these secured through a password in which casessl.keystore.pass
andssl.truststore.pass
properties are required.
Permissions (server-side)
editOn the server, one needs 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
.
You can add permissions by creating a role, and assigning
that role to the user. Roles can be created using Kibana, an
API call or the roles.yml
configuration file. Using Kibana or the role management APIs is the preferred
method for defining roles. File-based role management is useful if you want to
define a role that doesn’t need to change. You cannot use the role management
APIs to view or edit a role defined in roles.yml
.
Add permissions with the role management APIs
editThis example configures a role that can run SQL in JDBC querying the test
index:
resp = client.security.put_role( name="cli_or_drivers_minimal", cluster=[ "cluster:monitor/main" ], indices=[ { "names": [ "test" ], "privileges": [ "read", "indices:admin/get" ] } ], ) print(resp)
const response = await client.security.putRole({ name: "cli_or_drivers_minimal", cluster: ["cluster:monitor/main"], indices: [ { names: ["test"], privileges: ["read", "indices:admin/get"], }, ], }); console.log(response);
POST /_security/role/cli_or_drivers_minimal { "cluster": ["cluster:monitor/main"], "indices": [ { "names": ["test"], "privileges": ["read", "indices:admin/get"] } ] }
Add permissions to roles.yml
editThis example configures a role that can run SQL in JDBC querying the test
and bort
indices. Add the following to roles.yml
:
cli_or_drivers_minimal: cluster: - "cluster:monitor/main" indices: - names: test privileges: [read, "indices:admin/get"] - names: bort privileges: [read, "indices:admin/get"]