For similar capabilities to Amazon Timestream for LiveAnalytics, consider Amazon Timestream for InfluxDB. It offers simplified data ingestion and single-digit millisecond query response times for real-time analytics. Learn more [here](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html).

# JDBC
<a name="JDBC"></a>

 You can use a Java Database Connectivity (JDBC) connection to connect Timestream for LiveAnalytics to your business intelligence tools and other applications, such as [SQL Workbench](https://www.sql-workbench.eu/). The Timestream for LiveAnalytics JDBC driver currently supports SSO with Okta and Microsoft Azure AD. 

**Topics**
+ [

# Configuring the JDBC driver for Timestream for LiveAnalytics
](JDBC.configuring.md)
+ [

# Connection properties
](JDBC.connection-properties.md)
+ [

# JDBC URL examples
](JDBC.url-examples.md)
+ [

# Setting up Timestream for LiveAnalytics JDBC single sign-on authentication with Okta
](JDBC.SSOwithOkta.md)
+ [

# Setting up Timestream for LiveAnalytics JDBC single sign-on authentication with Microsoft Azure AD
](JDBC.withAzureAD.md)

# Configuring the JDBC driver for Timestream for LiveAnalytics
<a name="JDBC.configuring"></a>

Follow the steps below to configure the JDBC driver. 

**Topics**
+ [

## Timestream for LiveAnalytics JDBC driver JARs
](#w2aab7c44c37b7b7)
+ [

## Timestream for LiveAnalytics JDBC driver class and URL format
](#w2aab7c44c37b7b9)
+ [

## Sample application
](#w2aab7c44c37b7c11)

## Timestream for LiveAnalytics JDBC driver JARs
<a name="w2aab7c44c37b7b7"></a>

 You can obtain the Timestream for LiveAnalytics JDBC driver via direct download or by adding the driver as a Maven dependency. 
+  *As a direct download:*. To directly download the Timestream for LiveAnalytics JDBC driver, complete the following steps:

  1. Navigate to [ https://github.com/awslabs/amazon-timestream-driver-jdbc/releases ](https://github.com/awslabs/amazon-timestream-driver-jdbc/releases) 

  1. You can use `amazon-timestream-jdbc-1.0.1-shaded.jar` directly with your business intelligence tools and applications

  1. Download `amazon-timestream-jdbc-1.0.1-javadoc.jar` to a directory of your choice.

  1. In the directory where you have downloaded `amazon-timestream-jdbc-1.0.1-javadoc.jar`, run the following command to extract the Javadoc HTML files: 

     ```
     jar -xvf amazon-timestream-jdbc-1.0.1-javadoc.jar
     ```
+  *As a Maven dependency:* To add the Timestream for LiveAnalytics JDBC driver as a Maven dependency, complete the following steps:

  1. Navigate to and open your application's `pom.xml` file in an editor of your choice.

  1. Add the JDBC driver as a dependency into your application's `pom.xml` file:

     ```
     <!-- https://mvnrepository.com/artifact/software.amazon.timestream/amazon-timestream-jdbc -->
     <dependency>
         <groupId>software.amazon.timestream</groupId>
         <artifactId>amazon-timestream-jdbc</artifactId>
         <version>1.0.1</version>
     </dependency>
     ```

## Timestream for LiveAnalytics JDBC driver class and URL format
<a name="w2aab7c44c37b7b9"></a>

 The driver class for Timestream for LiveAnalytics JDBC driver is: 

```
software.amazon.timestream.jdbc.TimestreamDriver
```

 The Timestream JDBC driver requires the following JDBC URL format: 

```
jdbc:timestream:
```

 To specify database properties through the JDBC URL, use the following URL format: 

```
jdbc:timestream://
```

## Sample application
<a name="w2aab7c44c37b7c11"></a>

To help you get started with using Timestream for LiveAnalytics with JDBC, we've created a fully functional sample application in GitHub.

1. Create a database with sample data following the instructions described [here](getting-started.db-w-sample-data.md#getting-started.db-w-sample-data.using-console).

1. Clone the GitHub repository for the [sample application for JDBC](https://github.com/awslabs/amazon-timestream-tools/tree/mainline/integrations/jdbc) following the instructions from [GitHub](https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/cloning-a-repository).

1. Follow the instructions in the [README](https://github.com/awslabs/amazon-timestream-tools/tree/mainline/integrations/jdbc/README.md) to get started with the sample application.

# Connection properties
<a name="JDBC.connection-properties"></a>

 The Timestream for LiveAnalytics JDBC driver supports the following options: 

**Topics**
+ [

## Basic authentication options
](#JDBC.connection-properties.basic-auth)
+ [

## Standard client info option
](#JDBC.connection-properties.standard-client)
+ [

## Driver configuration option
](#JDBC.connection-properties.driver-config)
+ [

## SDK option
](#JDBC.connection-properties.sdk-options)
+ [

## Endpoint configuration option
](#JDBC.connection-properties.endpoint-config)
+ [

## Credential provider options
](#JDBC.connection-properties.cred-providers)
+ [

## SAML-based authentication options for Okta
](#JDBC.connection-properties.okta)
+ [

## SAML-based authentication options for Azure AD
](#JDBC.connection-properties.azure-ad)

**Note**  
 If none of the properties are provided, the Timestream for LiveAnalytics JDBC driver will use the default credentials chain to load the credentials. 

**Note**  
 All property keys are case-sensitive. 

## Basic authentication options
<a name="JDBC.connection-properties.basic-auth"></a>

The following table describes the available Basic Authentication options.


| Option | Description | Default | 
| --- | --- | --- | 
|  AccessKeyId  |  The AWS user access key id.  |  NONE  | 
|  SecretAccessKey  |  The AWS user secret access key.  |  NONE  | 
|  SessionToken  |  The temporary session token required to access a database with multi-factor authentication (MFA) enabled.  |  NONE  | 

## Standard client info option
<a name="JDBC.connection-properties.standard-client"></a>

The following table describes the Standard Client Info Option.


| Option | Description | Default | 
| --- | --- | --- | 
|  ApplicationName  |  The name of the application currently utilizing the connection. `ApplicationName` is used for debugging purposes and will not be communicated to the Timestream for LiveAnalytics service.  |  The application name detected by the driver.  | 

## Driver configuration option
<a name="JDBC.connection-properties.driver-config"></a>

The following table describes the Driver Configuration Option.


| Option | Description | Default | 
| --- | --- | --- | 
|  EnableMetaDataPreparedStatement  |  Enables Timestream for LiveAnalytics JDBC driver to return metadata for `PreparedStatements`, but this will incur an additional cost with Timestream for LiveAnalytics when retrieving the metadata.  |  FALSE  | 
|  Region  |  The database's region.  |  us-east-1  | 

## SDK option
<a name="JDBC.connection-properties.sdk-options"></a>

The following table describes the SDK Option.


| Option | Description | Default | 
| --- | --- | --- | 
|  RequestTimeout  |  The time in milliseconds the AWS SDK will wait for a query request before timing out. Non-positive value disables request timeout.  |  0  | 
|  SocketTimeout  |  The time in milliseconds the AWS SDK will wait for data to be transferred over an open connection before timing out. Value must be non-negative. A value of `0` disables socket timeout.  |  50000  | 
|  MaxRetryCountClient  |  The maximum number of retry attempts for retryable errors with 5XX error codes in the SDK. The value must be non-negative.  |  NONE  | 
|  MaxConnections  |  The maximum number of allowed concurrently opened HTTP connections to the Timestream for LiveAnalytics service. The value must be positive.  |  50  | 

## Endpoint configuration option
<a name="JDBC.connection-properties.endpoint-config"></a>

The following table describes the Endpoint Configuration Option.


| Option | Description | Default | 
| --- | --- | --- | 
|  Endpoint  |  The endpoint for the Timestream for LiveAnalytics service.  |  NONE  | 

## Credential provider options
<a name="JDBC.connection-properties.cred-providers"></a>

The following table describes the available Credential Provider options.


| Option | Description | Default | 
| --- | --- | --- | 
|  AwsCredentialsProviderClass  |  One of `PropertiesFileCredentialsProvider` or `InstanceProfileCredentialsProvider` to use for authentication.  |  NONE  | 
|  CustomCredentialsFilePath  |  The path to a properties file containing AWS security credentials `accessKey` and `secretKey`. This is only required if `AwsCredentialsProviderClass` is specified as `PropertiesFileCredentialsProvider` .  |  NONE  | 

## SAML-based authentication options for Okta
<a name="JDBC.connection-properties.okta"></a>

The following table describes the available SAML-based authentication options for Okta.


| Option | Description | Default | 
| --- | --- | --- | 
|  IdpName  |  The Identity Provider (Idp) name to use for SAML-based authentication. One of `Okta` or `AzureAD`.  |  NONE  | 
|  IdpHost  |  The host name of the specified Idp.  |  NONE  | 
|  IdpUserName  |  The user name for the specified Idp account.  |  NONE  | 
|  IdpPassword  |  The password for the specified Idp account.  |  NONE  | 
|  OktaApplicationID  |  The unique Okta-provided ID associated with the Timestream for LiveAnalytics application. `AppId` can be found in the `entityID` field provided in the application metadata. Consider the following example: `entityID = http://www.okta.com//IdpAppID`  |  NONE  | 
|  RoleARN  |  The Amazon Resource Name (ARN) of the role that the caller is assuming.  |  NONE  | 
|  IdpARN  |  The Amazon Resource Name (ARN) of the SAML provider in IAM that describes the Idp.  |  NONE  | 

## SAML-based authentication options for Azure AD
<a name="JDBC.connection-properties.azure-ad"></a>

The following table describes the available SAML-based authentication options for Azure AD.


| Option | Description | Default | 
| --- | --- | --- | 
|  IdpName  |  The Identity Provider (Idp) name to use for SAML-based authentication. One of `Okta` or `AzureAD` .  |  NONE  | 
|  IdpHost  |  The host name of the specified Idp.  |  NONE  | 
|  IdpUserName  |  The user name for the specified Idp account.  |  NONE  | 
|  IdpPassword  |  The password for the specified Idp account.  |  NONE  | 
|  AADApplicationID  |  The unique id of the registered application on Azure AD.  |  NONE  | 
|  AADClientSecret  |  The client secret associated with the registered application on Azure AD used to authorize fetching tokens.  |  NONE  | 
|  AADTenant  |  The Azure AD Tenant ID.  |  NONE  | 
|  IdpARN  |  The Amazon Resource Name (ARN) of the SAML provider in IAM that describes the Idp.  |  NONE  | 

# JDBC URL examples
<a name="JDBC.url-examples"></a>

 This section describes how to create a JDBC connection URL, and provides examples. To specify the [optional connection properties](JDBC.connection-properties.md), use the following URL format:

```
jdbc:timestream://PropertyName1=value1;PropertyName2=value2... 
```

**Note**  
All connection properties are optional. All property keys are case-sensitive.

Below are some examples of JDBC connection URLs.

*Example with basic authentication options and region:*  

```
jdbc:timestream://AccessKeyId=<myAccessKeyId>;SecretAccessKey=<mySecretAccessKey>;SessionToken=<mySessionToken>;Region=us-east-1
```

*Example with client info, region and SDK options:*  

```
jdbc:timestream://ApplicationName=MyApp;Region=us-east-1;MaxRetryCountClient=10;MaxConnections=5000;RequestTimeout=20000
```

*Connect using the default credential provider chain with AWS credential set in environment variables:*  

```
jdbc:timestream
```

*Connect using the default credential provider chain with AWS credential set in the connection URL:*  

```
jdbc:timestream://AccessKeyId=<myAccessKeyId>;SecretAccessKey=<mySecretAccessKey>;SessionToken=<mySessionToken>
```

*Connect using the PropertiesFileCredentialsProvider as the authentication method:*  

```
jdbc:timestream://AwsCredentialsProviderClass=PropertiesFileCredentialsProvider;CustomCredentialsFilePath=<path to properties file>
```

*Connect using the InstanceProfileCredentialsProvider as the authentication method:*  

```
jdbc:timestream://AwsCredentialsProviderClass=InstanceProfileCredentialsProvider
```

*Connect using the Okta credentials as the authentication method:*  

```
jdbc:timestream://IdpName=Okta;IdpHost=<host>;IdpUserName=<name>;IdpPassword=<password>;OktaApplicationID=<id>;RoleARN=<roleARN>;IdpARN=<IdpARN>
```

*Connect using the Azure AD credentials as the authentication method:*  

```
jdbc:timestream://IdpName=AzureAD;IdpUserName=<name>;IdpPassword=<password>;AADApplicationID=<id>;AADClientSecret=<secret>;AADTenant=<tenantID>;IdpARN=<IdpARN>
```

*Connect with a specific endpoint:*  

```
jdbc:timestream://Endpoint=abc.us-east-1.amazonaws.com;Region=us-east-1
```

# Setting up Timestream for LiveAnalytics JDBC single sign-on authentication with Okta
<a name="JDBC.SSOwithOkta"></a>

 Timestream for LiveAnalytics supports Timestream for LiveAnalytics JDBC single sign-on authentication with Okta. To use Timestream for LiveAnalytics JDBC single sign-on authentication with Okta, complete each of the sections listed below. 

**Topics**
+ [

# Prerequisites
](aws-sso-with-okta-prerequisites.md)
+ [

# AWS account federation in Okta
](aws-account-federation-in-okta.md)
+ [

# Setting up Okta for SAML
](aws-setting-up-okta-for-saml.md)

# Prerequisites
<a name="aws-sso-with-okta-prerequisites"></a>

Ensure that you have met the following prerequisites before using the Timestream for LiveAnalytics JDBC single sign-on authentication with Okta:
+ [Admin permissions in AWS to create the identity provider and the roles](security-iam.md).
+  An Okta account (Go to [https://www.okta.com/login/](https://www.okta.com/login/) to create an account).
+ [Access to Amazon Timestream for LiveAnalytics](accessing.md).

Now that you have completed the Prerequisites, you may proceed to [AWS account federation in Okta](aws-account-federation-in-okta.md).

# AWS account federation in Okta
<a name="aws-account-federation-in-okta"></a>

The Timestream for LiveAnalytics JDBC driver supports AWS Account Federation in Okta. To set up AWS Account Federation in Okta, complete the following steps:

1. Sign in to the Okta Admin dashboard using the following URL:

   ```
   https://<company-domain-name>-admin.okta.com/admin/apps/active 
   ```
**Note**  
 Replace **<company-domain-name>** with your domain name. 

1. Upon successful sign-in, choose** Add Application** and search for **AWS Account Federation**.

1. Choose **Add**

1. Change the Login URL to the appropriate URL.

1. Choose **Next**

1. Choose **SAML 2.0** As the **Sign-On** method

1. Choose **Identity Provider metadata** to open the metadata XML file. Save the file locally.

1. Leave all other configuration options blank.

1. Choose **Done**

Now that you have completed AWS Account Federation in Okta, you may proceed to [Setting up Okta for SAML](aws-setting-up-okta-for-saml.md).

# Setting up Okta for SAML
<a name="aws-setting-up-okta-for-saml"></a>

1. Choose the **Sign On** tab. Choose the **View**.

1. Choose the **Setup Instructions** button in the **Settings** section.

**Finding the Okta metadata document**

1. To find the document, go to:

   ```
   https://<domain>-admin.okta.com/admin/apps/active
   ```
**Note**  
 <domain> is your unique domain name for your Okta account. 

1. Choose the **AWS Account Federation** application

1. Choose the **Sign On** tab

# Setting up Timestream for LiveAnalytics JDBC single sign-on authentication with Microsoft Azure AD
<a name="JDBC.withAzureAD"></a>

 Timestream for LiveAnalytics supports Timestream for LiveAnalytics JDBC single sign-on authentication with Microsoft Azure AD. To use Timestream for LiveAnalytics JDBC single sign-on authentication with Microsoft Azure AD, complete each of the sections listed below. 

**Topics**
+ [

# Prerequisites
](JDBC.withAzureAD.prereqs.md)
+ [

# Setting up Azure AD
](JDBC.withAzureAD.setUp.md)
+ [

# Setting up IAM Identity Provider and roles in AWS
](JDBC.withAzureAD.IAM.md)

# Prerequisites
<a name="JDBC.withAzureAD.prereqs"></a>

Ensure that you have met the following prerequisites before using the Timestream for LiveAnalytics JDBC single sign-on authentication with Microsoft Azure AD:
+ [Admin permissions in AWS to create the identity provider and the roles](security-iam.md).
+ An Azure Active Directory account (Go to [ https://azure.microsoft.com/en-ca/services/active-directory/](https://azure.microsoft.com/en-ca/services/active-directory/) to create an account)
+ [Access to Amazon Timestream for LiveAnalytics](accessing.md).

# Setting up Azure AD
<a name="JDBC.withAzureAD.setUp"></a>

1. Sign in to Azure Portal

1. Choose **Azure Active Directory** in the list of Azure services. This will redirect to the Default Directory page.

1. Choose **Enterprise Applications** under the **Manage** section on the sidebar

1. Choose **\$1 New application**.

1. Find and select **Amazon Web Services**.

1. Choose **Single Sign-On** under the **Manage** section in the sidebar

1. Choose **SAML** as the single sign-on method

1. In the Basic SAML Configuration section, enter the following URL for both the Identifier and the Reply URL:

   ```
   https://signin.aws.amazon.com/saml
   ```

1. Choose **Save**

1. Download the Federation Metadata XML in the SAML Signing Certificate section. This will be used when creating the IAM Identity Provider later

1. Return to the Default Directory page and choose **App registrations** under **Manage**.

1. Choose **Timestream for LiveAnalytics** from the **All Applications** section. The page will be redirected to the application's Overview page
**Note**  
Note the Application (client) ID and the Directory (tenant) ID. These values are required for when creating a connection.

1. Choose **Certificates and Secrets**

1. Under **Client secrets**, create a new client secret with **\$1 New client secret**.
**Note**  
Note the generated client secret, as this is required when creating a connection to Timestream for LiveAnalytics.

1. On the sidebar under **Manage**, select **API permissions**

1. In the **Configured permissions**, use **Add a permission** to grant Azure AD permission to sign in to Timestream for LiveAnalytics. Choose **Microsoft Graph** on the Request API permissions page.

1. Choose **Delegated permissions** and select the **User.Read **permission

1. Choose **Add permissions**

1. Choose **Grant admin consent for Default Directory**

# Setting up IAM Identity Provider and roles in AWS
<a name="JDBC.withAzureAD.IAM"></a>

 Complete each section below to set up IAM for Timestream for LiveAnalytics JDBC single sign-on authentication with Microsoft Azure AD: 

**Topics**
+ [

## Create a SAML Identity Provider
](#JDBC.withAzureAD.IAM.SAML)
+ [

## Create an IAM role
](#JDBC.withAzureAD.IAM.roleForIAM)
+ [

## Create an IAM policy
](#JDBC.withAzureAD.IAM.policyForIAM)
+ [

## Provisioning
](#JDBC.withAzureAD.IAM.provisioning)

## Create a SAML Identity Provider
<a name="JDBC.withAzureAD.IAM.SAML"></a>

To create a SAML Identity Provider for the Timestream for LiveAnalytics JDBC single sign-on authentication with Microsoft Azure AD, complete the following steps:

1. Sign in to the AWS Management Console

1. Choose **Services** and select **IAM** under Security, Identity, & Compliance

1. Choose **Identity providers** under Access management

1. Choose **Create Provider** and choose **SAML** as the provider type. Enter the **Provider Name**. This example will use AzureADProvider.

1. Upload the previously downloaded Federation Metadata XML file

1. Choose **Next**, then choose **Create**.

1. Upon completion, the page will be redirected back to the Identity providers page

## Create an IAM role
<a name="JDBC.withAzureAD.IAM.roleForIAM"></a>

To create an IAM role for the Timestream for LiveAnalytics JDBC single sign-on authentication with Microsoft Azure AD, complete the following steps:

1. On the sidebar select **Roles** under Access management

1. Choose Create role

1. Choose **SAML 2.0 federation** as the trusted entity

1. Choose the **Azure AD provider**

1. Choose **Allow programmatic and AWS Management Console access**

1. Choose **Next: Permissions**

1. Attach permissions policies or continue to Next:Tags

1. Add optional tags or continue to Next:Review

1. Enter a Role name. This example will use AzureSAMLRole

1. Provide a role description

1. Choose **Create Role** to complete

## Create an IAM policy
<a name="JDBC.withAzureAD.IAM.policyForIAM"></a>

To create an IAM policy for the Timestream for LiveAnalytics JDBC single sign-on authentication with Microsoft Azure AD complete the following steps:

1. On the sidebar, choose **Policies** under Access management

1. Choose **Create policy** and select the **JSON** tab

1. Add the following policy

------
#### [ JSON ]

****  

   ```
   {
   "Version":"2012-10-17",		 	 	 
   "Statement": [
       {
             "Effect": "Allow",
             "Action": [
                    "iam:ListRoles",
                    "iam:ListAccountAliases"
              ],
              "Resource": "*"
         }
   ]
   }
   ```

------

1. Choose **Create policy**

1. Enter a policy name. This example will use TimestreamAccessPolicy.

1. Choose **Create Policy**

1. On the sidebar, choose **Roles** under Access management. 

1.  Choose the previously created **Azure AD role** and choose **Attach policies** under Permissions.

1. Select the previously created access policy.

## Provisioning
<a name="JDBC.withAzureAD.IAM.provisioning"></a>

To provision the identity provider for Timestream for LiveAnalytics JDBC single sign-on authentication with Microsoft Azure AD, complete the following steps:

1. Go back to Azure Portal

1. Choose **Azure Active Directory** in the list of Azure services. This will redirect to the Default Directory page

1. Choose **Enterprise Applications** under the Manage section on the sidebar

1. Choose **Provisioning**

1. Choose **Automatic mode** for the Provisioning Method

1. Under Admin Credentials, enter your **AwsAccessKeyID** for clientsecret, and **SecretAccessKey** for Secret Token

1. Set the **Provisioning Status** to **On**

1. Choose **save**. This allows Azure AD to load the necessary IAM Roles

1. Once the Current cycle status is completed, choose **Users and groups** on the sidebar

1. Choose **\$1 Add user**

1. Choose the Azure AD user to provide access to Timestream for LiveAnalytics

1. Choose the IAM Azure AD role and the corresponding Azure Identity Provider created in AWS

1. Choose **Assign**