Establishing a Connection

Creating a JDBC Data Source

You can create a JDBC data source to connect from your Java application. Creating a JDBC data source based on the CData JDBC Driver for Elasticsearch consists of three basic steps:

Add the driver JAR file to the classpath. The JAR file is located in the lib subfolder of the installation directory. Note that the .lic file must be located in the same folder as the JAR file.

Provide the driver class. For example:

cdata.jdbc.elasticsearch.ElasticsearchDriver

Provide the JDBC URL. For example:
```
jdbc:elasticsearch:Server=127.0.0.1;Port=9200;

or

jdbc:cdata:elasticsearch:Server=127.0.0.1;Port=9200;
```
The second format above can be used whenever there is a conflict in your application between drivers using the same URL format to ensure you are using the CData driver. The URL must start with either "jdbc:elasticsearch:" or "jdbc:cdata:elasticsearch:" and can include any of the connection properties in name-value pairs separated with semicolons.

Connecting to Elasticsearch Service

Set the following to connect to data:

Server should be set to the IP Address or domain of the Elasticsearch instance. The Server could also be set to a comma-delimited list of node addresses or hostnames from a single cluster.
```
Server=https://01.02.03.04 
  OR 
Server=https://01.01.01.01:1234,https://02.02.02.02:5678
```
Port should be set to the configured port for the Elasticsearch instance. If you include a port in a node specification for the Server property, that included port will take precedence over the specification for Port for that node only.

The driver uses X-Pack Security for authentication and TLS/SSL encryption. You can prefix the server value with "https://" to connect using TLS/SSL.

Connecting to Amazon OpenSearch Service

Set the following to connect to data:

Server should be set to the Endpoint URL for the Amazon ES instance.
Port should be set to 443.
AWSRegion should be set to the Amazon AWS region where the Elasticsearch instance is being hosted (the driver will attempt to automatically identify the region based on the Server value).

The driver uses X-Pack Security for authentication and TLS/SSL encryption.

Note: Requests are signed using AWS Signature Version 4.

Authenticating to Elasticsearch

In addition to standard connection properties, select one of the below authentication methods to authenticate.

Obtain AWS Keys

To obtain the credentials for an IAM user, follow the steps below:

Sign into the IAM console.
In the navigation pane, select Users.
To create or manage the access keys for a user, select the user and then go to the Security Credentials tab.

To obtain the credentials for your AWS root account, follow the steps below:

Sign into the AWS Management console with the credentials for your root account.
Select your account name or number and select My Security Credentials in the menu that is displayed.
Click Continue to Security Credentials and expand the "Access Keys" section to manage or create root account access keys.

Standard Authentication

Set the AuthScheme to Basic, and set User and Password properties and/or use PKI (public key infrastructure) to authenticate. Once the driver is connected, X-Pack performs user authentication and grants role permissions based on the realms you have configured.

To use PKI, set the SSLClientCert, SSLClientCertType, SSLClientCertSubject, and SSLClientCertPassword properties.

Note: TLS/SSL and client authentication must be enabled on X-Pack to use PKI.

Securing Elasticsearch Connections

To enable TLS/SSL in the driver, prefix the Server value with 'https://'.

Root Credentials

To authenticate using account root credentials, set the following:

AuthScheme: Set this to AwsRootKeys.
AWSAccessKey: The access key associated with the AWS root account.
AWSSecretKey: The secret key associated with the AWS root account.

Note: Use of this authentication scheme is discouraged by Amazon for anything but simple tests. The account root credentials have the full permissions of the user, making this the least secure authentication method.

Temporary Credentials

To authenticate using temporary credentials, specify the following:

AuthScheme: Set this to TemporaryCredentials.
AWSAccessKey: The access key of the IAM user to assume the role for.
AWSSecretKey: The secret key of the IAM user to assume the role for.
AWSSessionToken: Your AWS session token. This will have been provided alongside your temporary credentials. See AWS Identity and Access Management User Guide for more info.

The driver can now request resources using the same permissions provided by long-term credentials (such as IAM user credentials) for the lifespan of the temporary credentials.

If you are also using an IAM role to authenticate, you must additionally specify the following:

AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This will cause the driver to attempt to retrieve credentials for the specified role.
AWSExternalId: Only if required when you assume a role in another account.

AWS IAM Roles

In many situations it may be preferable to use an IAM role for authentication instead of the direct security credentials of an AWS root user.

To authenticate as an AWS role, set the following:

AuthScheme: Set this to AwsIAMRoles.
AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This will cause the driver to attempt to retrieve credentials for the specified role.
AWSExternalId: Only if required when you assume a role in another account.
AWSAccessKey: The access key of the IAM user to assume the role for.
AWSSecretKey: The secret key of the IAM user to assume the role for.

Note: Roles may not be used when specifying the AWSAccessKey and AWSSecretKey of an AWS root user.

Kerberos

Please see Using Kerberos for details on how to authenticate with Kerberos.

API Key

To authenticate using APIKey set the following:

AuthScheme: Set this to APIKey.
APIKey: Set this to APIKey returned from Elasticsearch.
APIKeyId: Set this to the Id returned alongside APIKey.