# Connect to Amazon Athena with ODBC and JDBC drivers To explore and visualize your data with business intelligence tools, download, install, and configure an ODBC (Open Database Connectivity) or JDBC (Java Database Connectivity) driver. **Topics** + [Connect to Athena with JDBC](connect-with-jdbc.md) + [Connect to Athena with ODBC](connect-with-odbc.md) + [Use trusted identity propagation with drivers](using-trusted-identity-propagation.md) See also the following AWS Knowledge Center and AWS Big Data Blog topics: + [How can I use my IAM role credentials or switch to another IAM role when connecting to Athena using the JDBC driver?](https://aws.amazon.com/premiumsupport/knowledge-center/athena-iam-jdbc-driver/) + [Setting up trust between ADFS and AWS and using Active Directory credentials to connect to Amazon Athena with ODBC driver](https://aws.amazon.com/blogs/big-data/setting-up-trust-between-adfs-and-aws-and-using-active-directory-credentials-to-connect-to-amazon-athena-with-odbc-driver/) # Connect to Amazon Athena with JDBC Connect to Athena with JDBC Amazon Athena offers two JDBC drivers, versions 2.x and 3.x. The Athena JDBC 3.x driver is the new generation driver offering better performance and compatibility. The JDBC 3.x driver supports reading query results directly from Amazon S3, which improves the performance of applications that consume large query results. The new driver also has fewer third-party dependencies, which makes integration with BI tools and custom applications easier. In most cases, you can use the new driver with no or minimal changes to existing configuration. + To download the JDBC 3.x driver, see [Athena JDBC 3.x driver](jdbc-v3-driver.md). + To download the JDBC 2.x driver, see [Athena JDBC 2.x driver](jdbc-v2.md). **Topics** + [ # Athena JDBC 3.x driver ](jdbc-v3-driver.md) + [ # Athena JDBC 2.x driver ](jdbc-v2.md) # Athena JDBC 3.x driver JDBC 3.x You can use the Athena JDBC driver to connect to Amazon Athena from many third-party SQL client tools and from custom applications. ## System Requirements + Java 8 (or higher) runtime environment + At least 20 MB of available disk space ## Considerations and limitations Following are some considerations and limitations for the Athena JDBC 3.x driver. + **Logging** – The 3.x driver uses [SLF4J](https://www.slf4j.org/manual.html), which is an abstraction layer that enables the use of any one of several logging systems at runtime. + **Encryption** – When using the Amazon S3 fetcher with the `CSE_KMS` encryption option, the Amazon S3 client can't decrypt results stored in an Amazon S3 bucket. If you require `CSE_KMS` encryption, you can continue to use the streaming fetcher. Support for `CSE_KMS` encryption with the Amazon S3 fetcher is planned. ## JDBC 3.x driver download This section contains download and license information for the JDBC 3.x driver. **Important** When you use the JDBC 3.x driver, be sure to note the following requirements: **Open port 444** – Keep port 444, which Athena uses to stream query results, open to outbound traffic. When you use a PrivateLink endpoint to connect to Athena, ensure that the security group attached to the PrivateLink endpoint is open to inbound traffic on port 444. **athena:GetQueryResultsStream policy** – Add the `athena:GetQueryResultsStream` policy action to the IAM principals that use the JDBC driver. This policy action is not exposed directly with the API. It is used only with the ODBC and JDBC drivers as part of streaming results support. For an example policy, see [AWS managed policy: AWSQuicksightAthenaAccess](security-iam-awsmanpol.md#awsquicksightathenaaccess-managed-policy). To download the Amazon Athena 3.x JDBC driver, visit the following links. ### JDBC driver uber jar The following download packages the driver and all its dependencies in the same `.jar` file. This download is commonly used for third-party SQL clients. [3.7.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.7.0/athena-jdbc-3.7.0-with-dependencies.jar) ### JDBC driver lean jar The following download is a `.zip` file that contains the lean `.jar` for the driver and separate `.jar` files for the driver's dependencies. This download is commonly used for custom applications that might have dependencies that conflict with the dependencies that the driver uses. This download is useful if you want to choose which of the driver dependencies to include with the lean jar, and which to exclude if your custom application already contains one or more of them. [3.7.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.7.0/athena-jdbc-3.7.0-lean-jar-and-separate-dependencies-jars.zip) ### License The following link contains the license agreement for the JDBC 3.x driver. [License](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.7.0/LICENSE.txt) ## Trusted identity propagation with JDBC You can now connect to Amazon Athena using JDBC drivers with single sign-on capabilities through AWS Identity and Access Management Identity Center. When you access Athena from tools like PowerBI, Tableau, or DBeaver, your identity and permissions automatically propagate to Athena through IAM Identity Center. For more information, see [Use Trusted identity propagation with Amazon Athena drivers](using-trusted-identity-propagation.md). **Topics** + [ ## System Requirements ](#jdbc-v3-driver-system-requirements) + [ ## Considerations and limitations ](#jdbc-v3-driver-considerations-and-limitations) + [ ## JDBC 3.x driver download ](#jdbc-v3-driver-download) + [ ## Trusted identity propagation with JDBC ](#jdbc-v3-driver-trusted-identity) + [ # Get started with the JDBC 3.x driver ](jdbc-v3-driver-getting-started.md) + [ # Amazon Athena JDBC 3.x connection parameters ](jdbc-v3-driver-connection-parameters.md) + [ # Other JDBC 3.x configuration ](jdbc-v3-driver-other-configuration.md) + [ # Amazon Athena JDBC 3.x release notes ](jdbc-v3-driver-release-notes.md) + [ # Previous versions of the Athena JDBC 3.x driver ](jdbc-v3-driver-previous-versions.md) # Get started with the JDBC 3.x driver Get started Use the information in this section to get started with the Amazon Athena JDBC 3.x driver. **Topics** + [ ## Installation Instructions ](#jdbc-v3-driver-installation-instructions) + [ ## Running the driver ](#jdbc-v3-driver-running-the-driver) + [ ## Configuring the driver ](#jdbc-v3-driver-configuring-the-driver) + [ ## Upgrading from the Athena JDBC v2 driver ](#jdbc-v3-driver-upgrading-from-the-athena-jdbc-v2-driver-to-v3) ## Installation Instructions You can use the JDBC 3.x driver in custom application or from a third-party SQL client. ### In a custom application Download the `.zip` file that contains the driver jar and its dependencies. Each dependency has its own `.jar` file. Add the driver jar as a dependency in your custom application. Selectively add the dependencies of the driver jar based on whether you have already added those dependencies to your application from another source. ### In a third-party SQL client Download the driver uber jar file and add it to the third-party SQL client following the instructions for that client. ## Running the driver To run the driver, you can use a custom application or a third-party SQL client. ### In a custom application Use the JDBC interface to interact with the JDBC driver from a program. The following code shows a sample custom Java application. ``` public static void main(String args[]) throws SQLException { Properties connectionParameters = new Properties(); connectionParameters.setProperty("Workgroup", "primary"); connectionParameters.setProperty("Region", "us-east-2"); connectionParameters.setProperty("Catalog", "AwsDataCatalog"); connectionParameters.setProperty("Database","sampledatabase"); connectionParameters.setProperty("OutputLocation","s3://amzn-s3-demo-bucket"); connectionParameters.setProperty("CredentialsProvider","DefaultChain"); String url = "jdbc:athena://"; AthenaDriver driver = new AthenaDriver(); Connection connection = driver.connect(url, connectionParameters); Statement statement = connection.createStatement(); String query = "SELECT * from sample_table LIMIT 10"; ResultSet resultSet = statement.executeQuery(query); printResults(resultSet); // A custom-defined method for iterating over a // result set and printing its contents } ``` ### In a third-party SQL client Follow the documentation for the SQL client that you are using. Typically, you use the SQL client's graphical user interface to enter and submit the query, and the query results are displayed in the same interface. ## Configuring the driver You can use connection parameters to configure the Amazon Athena JDBC driver. For supported connection parameters, see [Amazon Athena JDBC 3.x connection parameters](jdbc-v3-driver-connection-parameters.md). ### In a custom application To set the connection parameters for the JDBC driver in a custom application, do one of the following: + Add the parameter names and their values to a `Properties` object. When you call `Connection#connect`, pass that object along with the URL. For an example, see the sample Java application in [Running the driver](#jdbc-v3-driver-running-the-driver). + In the connection string (the URL), use the following format to add the parameter names and their values directly after the protocol prefix. ``` =; ``` Use a semi-colon at the end of each parameter name/parameter value pair, and leave no white space after the semicolon, as in the following example. ``` String url = "jdbc:athena://WorkGroup=primary;Region=us-east-1;...;";AthenaDriver driver = new AthenaDriver();Connection connection = driver.connect(url, null); ``` **Note** If a parameter is specified both in the connection string and in the `Properties` object, the value in the connection string takes precedence. Specifying the same parameter in both places is not recommended. + Add the parameter values as arguments to the methods of `AthenaDataSource`, as in the following example. ``` AthenaDataSource dataSource = new AthenaDataSource(); dataSource.setWorkGroup("primary"); dataSource.setRegion("us-east-2"); ... Connection connection = dataSource.getConnection(); ... ``` ### In a third-party SQL client Follow the instructions of the SQL client that you are using. Typically, the client provides a graphical user interface to input the parameter names and their values. ## Upgrading from the Athena JDBC v2 driver Most of the JDBC version 3 connection parameters are backwards-compatible with the version 2 (Simba) JDBC driver. This means that a version 2 connection string can be reused with version 3 of the driver. However, some connection parameters have changed. These changes are described here. When you upgrade to the version 3 JDBC driver, update your existing configuration if necessary. ### Driver class Some BI tools ask you to provide the driver class from the JDBC driver `.jar` file. Most tools find this class automatically. The fully qualified name of the class in the version 3 driver is `com.amazon.athena.jdbc.AthenaDriver`. In the version 2 driver, the class was `com.simba.athena.jdbc.Driver`. ### Connection string The version 3 driver uses `jdbc:athena://` for the protocol at the beginning of the JDBC connection string URL. The version 3 driver also supports the version 2 protocol `jdbc:awsathena://`, but the use of the version 2 protocol is deprecated. To avoid undefined behaviors, version 3 does not accept connection strings that start with `jdbc:awsathena://` if version 2 (or any other driver that accepts connection strings that start with `jdbc:awsathena://`) has been registered with the [DriverManager](https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html) class. ### Credentials providers The version 2 driver uses fully qualified names to identify different credentials providers (for example, `com.simba.athena.amazonaws.auth.DefaultAWSCredentialsProviderChain`. The version 3 driver uses shorter names (for example, `DefaultChain`). The new names are described in the corresponding sections for each credentials provider. Custom credentials providers written for the version 2 driver need to be modified for the version 3 driver to implement the [AwsCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/AwsCredentialsProvider.html) interface from the new AWS SDK for Java instead of the [AWSCredentialsProvider](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSCredentialsProvider.html) interface from the previous AWS SDK for Java. The `PropertiesFileCredentialsProvider` is not supported in the JDBC 3.x driver. The provider was used in the JDBC 2.x driver but belongs to the previous version of the AWS SDK for Java which is approaching end of support. To achieve the same functionality in the JDBC 3.x driver, use the [AWS configuration profile credentials](jdbc-v3-driver-aws-configuration-profile-credentials.md) provider instead. ### Log level The following table shows the differences in the `LogLevel` parameters in the JDBC version 2 and version 3 drivers. **** | JDBC driver version | Parameter name | Parameter type | Default value | Possible values | Connection string example | | --- | --- | --- | --- | --- | --- | | v2 | LogLevel | Optional | 0 | 0-6 | LogLevel=6; | | v3 | LogLevel | Optional | TRACE | OFF, ERROR, WARN, INFO, DEBUG, TRACE | LogLevel=INFO; | ### Query ID retrieval In the version 2 driver, you unwrap a `Statement` instance to `com.interfaces.core.IStatementQueryInfoProvider`, an interface that has two methods: `#getPReparedQueryId` and `#getQueryId`. You can use these methods to obtain the query execution ID of a query that has run. In the version 3 driver, you unwrap `Statement`, `PreparedStatement`, and `ResultSet` instances to the `com.amazon.athena.jdbc.AthenaResultSet` interface. The interface has one method: `#getQueryExecutionId`. # Amazon Athena JDBC 3.x connection parameters JDBC 3.x connection parameters Supported connection parameters are divided here into three sections: [Basic connection parameters](jdbc-v3-driver-basic-connection-parameters.md), [Advanced connection parameters](jdbc-v3-driver-advanced-connection-parameters.md), and [Authentication connection parameters](jdbc-v3-driver-authentication-connection-parameters.md). The Advanced connection parameters and Authentication connection parameters sections have subsections that group related parameters together. **Topics** + [ # Basic connection parameters ](jdbc-v3-driver-basic-connection-parameters.md) + [ # Advanced connection parameters ](jdbc-v3-driver-advanced-connection-parameters.md) + [ # Authentication connection parameters ](jdbc-v3-driver-authentication-connection-parameters.md) # Basic connection parameters Basic The following sections describe the basic connection parameters for the JDBC 3.x driver. ## Region The AWS Region where queries will be run. For a list of regions, see [Amazon Athena endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/athena.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | Region | AwsRegion (deprecated) | Mandatory (but if not provided, will be searched using the [DefaultAwsRegionProviderChain](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/regions/providers/DefaultAwsRegionProviderChain.html)) | none | ## Catalog The catalog that contains the databases and the tables that will be accessed with the driver. For information about catalogs, see [DataCatalog](https://docs.aws.amazon.com/athena/latest/APIReference/API_DataCatalog.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | Catalog | none | Optional | AwsDataCatalog | ## Database The database where queries will run. Tables that are not explicitly qualified with a database name are resolved to this database. For information about databases, see [Database](https://docs.aws.amazon.com/athena/latest/APIReference/API_Database.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | Database | Schema | Optional | default | ## Workgroup The workgroup in which queries will run. For information about workgroups, see [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | WorkGroup | none | Optional | primary | ## Output location The location in Amazon S3 where query results will be stored. For information about output location, see [ResultConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultConfiguration.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | OutputLocation | S3OutputLocation (deprecated) | Mandatory (unless the workgroup specifies an output location) | none | # Advanced connection parameters Advanced The following sections describe the advanced connection parameters for the JDBC 3.x driver. **Topics** + [ ## Result encryption parameters ](#jdbc-v3-driver-result-encryption-parameters) + [ ## Result fetching parameters ](#jdbc-v3-driver-result-fetching-parameters) + [ ## Result configuration parameters ](#jdbc-v3-driver-result-config) + [ ## Query result reuse parameters ](#jdbc-v3-driver-query-result-reuse-parameters) + [ ## Query execution polling parameters ](#jdbc-v3-driver-query-execution-polling-parameters) + [ ## Endpoint override parameters ](#jdbc-v3-driver-endpoint-override-parameters) + [ ## Proxy configuration parameters ](#jdbc-v3-driver-proxy-configuration-parameters) + [ ## Logging parameters ](#jdbc-v3-driver-logging-parameters) + [ ## Application name ](#jdbc-v3-driver-application-name) + [ ## Connection test ](#jdbc-v3-driver-connection-test) + [ ## Number of retries ](#jdbc-v3-driver-number-of-retries) + [ ## Network timeout ](#jdbc-v3-driver-networktimeoutmillis) ## Result encryption parameters Note the following points: + The AWS KMS Key must be specified when `EncryptionOption` is `SSE_KMS` or `CSE_KMS`. + The AWS KMS Key cannot be specified when `EncryptionOption` is not specified or when `EncryptionOption` is `SSE_S3`. ### Encryption option The type of encryption to be used for query results as they are stored in Amazon S3. For information about query result encryption, see [EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html) in the *Amazon Athena API Reference*. **** | Parameter name | Alias | Parameter type | Default value | Possible values | | --- | --- | --- | --- | --- | | EncryptionOption | S3OutputEncOption (deprecated) | Optional | none | SSE\$1S3, SSE\$1KMS, CSE\$1KMS | ### KMS Key The KMS key ARN or ID, if `SSE_KMS` or `CSE_KMS` is chosen as the encryption option. For more information, see [EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html) in the *Amazon Athena API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | KmsKey | S3OutputEncKMSKey (deprecated) | Optional | none | ## Result fetching parameters ### Result fetcher The fetcher that will be used to download query results. The default result fetcher, `auto`, downloads query results directly from Amazon S3 without using the Athena APIs. When direct S3 download is not possible, like when query results are encrypted with the `CSE_KMS` option, it automatically falls back to use the `GetQueryResultsStream` API. Using the `auto` fetcher is recommended in most situations. If your IAM policies, or S3 bucket policies use the [s3:CalledVia](security-iam-athena-calledvia.md) condition to limit access to S3 objects requests from Athena, the `auto` fetcher first attempts to download the results from S3 and then falls back to use the `GetQueryResultsStream` API. In this situation, you can set the ResultFetcher to `GetQueryResultsStream` to avoid an extra API call. **** | Parameter name | Alias | Parameter type | Default value | Possible values | | --- | --- | --- | --- | --- | | ResultFetcher | none | Optional | auto | auto, S3, GetQueryResults, GetQueryResultsStream | ### Fetch size The value of this parameter is used as the minimum for internal buffers and as the target page size when fetching results. The value 0 (zero) means that the driver should use its defaults as described below. The maximum value is 1,000,000. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | FetchSize | RowsToFetchPerBlock (deprecated) | Optional | 0 | + The `GetQueryResults` fetcher will always use a page size of 1,000, which is the maximum value supported by the API call. When the fetch size is higher than 1,000, multiple successive API calls are made to fill the buffer above the minimum. + The `GetQueryResultsStream` fetcher will use the configured fetch size as the page size, or 10,000 by default. + The `S3` fetcher will use the configured fetch size as the page size, or 10,000 by default. ## Result configuration parameters ### Expected bucket owner The account ID of the expected s3 bucket owner. If the account ID that you provide does not match the actual owner of the bucket, the request fails. For more information about verifying s3 bucket owner, see [Verifying bucket ownership](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-owner-condition.html#bucket-owner-condition-use). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | ExpectedBucketOwner | none | Optional | none | ### Acl option Indicates that an Amazon S3 canned ACL should be set to control ownership of stored query results. For more information about `AclOption`, see [AclConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_AclConfiguration.html). **** | Parameter name | Alias | Parameter type | Default value | Possible values | | --- | --- | --- | --- | --- | | AclOption | none | Optional | none | BUCKET\$1OWNER\$1FULL\$1CONTROL | ## Query result reuse parameters ### Enable result reuse Specifies whether previous results for the same query can be reused when a query is run. For information about query result reuse, see [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | EnableResultReuseByAge | none | Optional | FALSE | ### Result reuse max age The maximum age, in minutes, of a previous query result that Athena should consider for reuse. For information about result reuse max age, see [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | MaxResultReuseAgeInMinutes | none | Optional | 60 | ## Query execution polling parameters ### Minimum query execution polling interval The minimum time, in milliseconds, to wait before polling Athena for the query execution status. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | MinQueryExecutionPollingIntervalMillis | MinQueryExecutionPollingInterval (deprecated) | Optional | 100 | ### Maximum query execution polling interval The maximum time, in milliseconds, to wait before polling Athena for the query execution status. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | MaxQueryExecutionPollingIntervalMillis | MaxQueryExecutionPollingInterval (deprecated) | Optional | 5000 | ### Query execution polling interval multiplier The factor for increasing the polling period. By default, polling will begin with the value for `MinQueryExecutionPollingIntervalMillis` and double with each poll until it reaches the value for `MaxQueryExecutionPollingIntervalMillis`. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | QueryExecutionPollingIntervalMultiplier | none | Optional | 2 | ## Endpoint override parameters ### Athena endpoint override The endpoint that the driver will use to make API calls to Athena. Note the following points: + If the `https://` or `http://` protocols are not specified in the provided URL, the driver inserts the `https://` prefix. + If this parameter is not specified, the driver uses a default endpoint. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | AthenaEndpoint | EndpointOverride (deprecated) | Optional | none | ### Athena streaming service endpoint override The endpoint that the driver will use to download query results when it uses the Athena streaming service. The Athena streaming service is available on port 444. Note the following points: + If the `https://` or `http://` protocols are not specified in the provided URL, the driver inserts the `https://` prefix. + If a port is not specified in the provided URL, the driver inserts the streaming service port 444. + If the `AthenaStreamingEndpoint` parameter is not specified, the driver uses the `AthenaEndpoint` override. If neither the `AthenaStreamingEndpoint` nor the `AthenaEndpoint` override is specified, the driver uses a default streaming endpoint. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | AthenaStreamingEndpoint | StreamingEndpointOverride (deprecated) | Optional | none | ### LakeFormation endpoint override The endpoint that the driver will use for the Lake Formation service when using the AWS Lake Formation [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) API to retrieve temporary credentials. If this parameter is not specified, the driver uses a default Lake Formation endpoint. Note the following points: + If the `https://` or `http://` protocols are not specified in the provided URL, the driver inserts the `https://` prefix. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | LakeFormationEndpoint | LfEndpointOverride (deprecated) | Optional | none | ### S3 endpoint override The endpoint that the driver will use to download query results when it uses the Amazon S3 fetcher. If this parameter is not specified, the driver uses a default Amazon S3 endpoint. Note the following points: + If the `https://` or `http://` protocols are not specified in the provided URL, the driver inserts the `https://` prefix. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | S3Endpoint | None | Optional | none | ### STS endpoint override The endpoint that the driver will use for the AWS STS service when using the AWS STS [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) API to retrieve temporary credentials. If this parameter is not specified, the driver uses a default AWS STS endpoint. Note the following points: + If the `https://` or `http://` protocols are not specified in the provided URL, the driver inserts the `https://` prefix. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | StsEndpoint | StsEndpointOverride(deprecated) | Optional | none | ### SSO OIDC endpoint override The endpoint that the driver will use when using `ClientConfiguration.endpointOverride` to override the default HTTP endpoint for SSO OIDC client. For more information, see [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | SSOOIDCEndpointOverride | | Optional | none | ### SSO Admin endpoint override The endpoint that the driver will use when using `ClientConfiguration.endpointOverride` to override the default HTTP endpoint for SSO Admin client. For more information, see [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | SSOAdminEndpointOverride | | Optional | none | ## Proxy configuration parameters ### Proxy host The URL of the proxy host. Use this parameter if you require Athena requests to go through a proxy. **Note** Make sure to include the protocol `https://` or `http://` at the beginning of the URL for `ProxyHost`. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | ProxyHost | none | Optional | none | ### Proxy port The port to be used on the proxy host. Use this parameter if you require Athena requests to go through a proxy. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | ProxyPort | none | Optional | none | ### Proxy username The username to authenticate on the proxy server. Use this parameter if you require Athena requests to go through a proxy. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | ProxyUsername | ProxyUID (deprecated) | Optional | none | ### Proxy password The password to authenticate on the proxy server. Use this parameter if you require Athena requests to go through a proxy. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | ProxyPassword | ProxyPWD (deprecated) | Optional | none | ### Proxy-exempt hosts A set of host names that the driver connects to without using a proxy when proxying is enabled (that is, when the `ProxyHost` and `ProxyPort` connection parameters are set). The hosts should be separated by the pipe (`|`) character (for example, `host1.com|host2.com`). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | ProxyExemptHosts | NonProxyHosts | Optional | none | ### Proxy enabled for identity providers Specifies whether a proxy should be used when the driver connects to an identity provider. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | ProxyEnabledForIdP | UseProxyForIdP | Optional | FALSE | ## Logging parameters This section describes parameters related to logging. ### Log level Specifies the level for the driver logging. Nothing is logged unless the `LogPath` parameter is also set. **Note** We recommend setting only the `LogPath` parameter unless you have special requirements. Setting only the `LogPath` parameter enables logging and uses the default `TRACE` log level. The `TRACE` log level provides the most detailed logging. **** | Parameter name | Alias | Parameter type | Default value | Possible values | | --- | --- | --- | --- | --- | | LogLevel | none | Optional | TRACE | OFF, ERROR, WARN, INFO, DEBUG, TRACE | ### Log path The path to a directory on the computer that runs the driver where driver logs will be stored. A log file with a unique name will be created within the specified directory. If set, enables driver logging. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | LogPath | none | Optional | none | ## Application name The name of the application that uses the driver. If a value for this parameter is specified, the value is included in the user agent string of the API calls that the driver makes to Athena. **Note** You can also set the application name by calling `setApplicationName` on the `DataSource` object. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | ApplicationName | none | Optional | none | ## Connection test If set to `TRUE`, the driver performs a connection test each time a JDBC connection is created, even if a query is not executed on the connection. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | ConnectionTest | none | Optional | TRUE | **Note** A connection test submits a `SELECT 1` query to Athena to verify that the connection has been configured correctly. This means that two files will be stored in Amazon S3 (the result set and metadata), and additional charges can apply in accordance with the [Amazon Athena pricing](https://aws.amazon.com/athena/pricing) policy. ## Number of retries The maximum number of times the driver should resend a retriable request to Athena. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | NumRetries | MaxErrorRetry (deprecated) | Optional | none | ## Network timeout The network timeout controls the amount of time that the driver waits for a network connection to be established. This includes the time it takes to send API requests. In rare circumstances, it may be useful to change the network timeout. For example, you might want to increase the timeout for long garbage collection pauses. Setting this connection parameter is equivalent to using the `setNetworkTimeout` method on a `Connection` object. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | NetworkTimeoutMillis | none | Optional | none | # Authentication connection parameters Authentication The Athena JDBC 3.x driver supports several authentication methods. The connection parameters that are required depend on the authentication method that you use. **Topics** + [IAM](jdbc-v3-driver-iam-credentials.md) + [Default](jdbc-v3-driver-default-credentials.md) + [AWS configuration profile](jdbc-v3-driver-aws-configuration-profile-credentials.md) + [Instance profile](jdbc-v3-driver-instance-profile-credentials.md) + [Custom](jdbc-v3-driver-custom-credentials.md) + [JWT](jdbc-v3-driver-jwt-credentials.md) + [JWT trusted identity propagation](jdbc-v3-driver-jwt-tip-credentials.md) + [Browser trusted identity propagation](jdbc-v3-driver-browser-oidc-tip-credentials.md) + [Azure AD](jdbc-v3-driver-azure-ad-credentials.md) + [Okta](jdbc-v3-driver-okta-credentials.md) + [Ping](jdbc-v3-driver-ping-credentials.md) + [AD FS](jdbc-v3-driver-adfs-credentials.md) + [Browser Azure AD](jdbc-v3-driver-browser-azure-ad-credentials.md) + [Browser SAML](jdbc-v3-driver-browser-saml-credentials.md) + [DataZone IdC](jdbc-v3-driver-datazone-idc.md) + [DataZone IAM](jdbc-v3-driver-datazone-iamcp.md) # IAM credentials IAM You can use your IAM credentials with the JDBC driver to connect to Amazon Athena by setting the following connection parameters. ## User Your AWS access key ID. For information about access keys, see [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html) in the *IAM User Guide*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | User | AccessKeyId | Required | none | ## Password Your AWS secret key ID. For information about access keys, see [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html) in the *IAM User Guide*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | Password | SecretAccessKey | Optional | none | ## Session token If you use temporary AWS credentials, you must specify a session token. For information about temporary credentials, see [Temporary security credentials in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) in the *IAM User Guide*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | SessionToken | none | Optional | none | # Default credentials Default You can use the default credentials that you configure on your client system to connect to Amazon Athena by setting the following connection parameters. For information about using default credentials, see [Using the Default Credential Provider Chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default) in the *AWS SDK for Java Developer Guide*. ## Credentials provider The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `DefaultChain`. **** | Parameter name | Alias | Parameter type | Default value | Value to use | | --- | --- | --- | --- | --- | | CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | DefaultChain | # AWS configuration profile credentials AWS configuration profile You can use credentials stored in an AWS configuration profile by setting the following connection parameters. AWS configuration profiles are typically stored in files in the `~/.aws` directory). For information about AWS configuration profiles, see [Use profiles](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-profiles.html) in the *AWS SDK for Java Developer Guide*. ## Credentials provider The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `ProfileCredentials`. **** | Parameter name | Alias | Parameter type | Default value | Value to use | | --- | --- | --- | --- | --- | | CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | ProfileCredentials | ## Profile name The name of the AWS configuration profile whose credentials should be used to authenticate the request to Athena. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | ProfileName | none | Required | none | **Note** The profile name can also be specified as the value of the `CredentialsProviderArguments` parameter, although this use is deprecated. # Instance profile credentials Instance profile This authentication type is used on Amazon EC2 instances. An *instance profile* is a profile attached to an Amazon EC2 instance. Using an instance profile credentials provider delegates the management of AWS credentials to the Amazon EC2 Instance Metadata Service. This removes the need for developers to store credentials permanently on the Amazon EC2 instance or worry about rotating or managing temporary credentials. ## Credentials provider The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `InstanceProfile`. **** | Parameter name | Alias | Parameter type | Default value | Value to use | | --- | --- | --- | --- | --- | | CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | InstanceProfile | # Custom credentials Custom You can use this authentication type to provide your own credentials by using a Java class that implements the [AwsCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/AwsCredentialsProvider.html) interface. ## Credentials provider The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to the fully qualified class name of the custom class that implements the [AwsCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/AwsCredentialsProvider.html) interface. At runtime, that class must be on the Java class path of the application that uses the JDBC driver. **** | Parameter name | Alias | Parameter type | Default value | Value to use | | --- | --- | --- | --- | --- | | CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | The fully qualified class name of the custom implementation of AwsCredentialsProvider | ## Credentials provider arguments A comma-separated list of string arguments for the custom credentials provider constructor. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | CredentialsProviderArguments | AwsCredentialsProviderArguments (deprecated) | Optional | none | # JWT credentials JWT With this authentication type, you can use a JSON web token (JWT) obtained from an external identity provider as a connection parameter to authenticate with Athena. The external credentials provider must already be federated with AWS. ## Credentials provider The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `JWT`. **** | Parameter name | Alias | Parameter type | Default value | Value to use | | --- | --- | --- | --- | --- | | CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | JWT | ## JWT web identity token The JWT token obtained from an external federated identity provider. This token will be used to authenticate with Athena. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | JwtWebIdentityToken | web\$1identity\$1token (deprecated) | Required | none | ## JWT role ARN The Amazon Resource Name (ARN) of the role to assume. For information about assuming roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | JwtRoleArn | role\$1arn (deprecated) | Required | none | ## JWT role session name The name of the session when you use JWT credentials for authentication. The name can be any name that you choose. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | JwtRoleSessionName | role\$1session\$1name (deprecated) | Required | none | ## Role session duration The duration, in seconds, of the role session. For more information, see [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | RoleSessionDuration | Duration (deprecated) | Optional | 3600 | # JWT with identity center integration JWT trusted identity propagation This authentication type allows you to use a JSON web token (JWT) obtained from an external identity provider as a connection parameter to authenticate with Athena. You can use this plugin, to enable support for corporate identities via trusted identity propagation. For more information on how to use trusted identity propagation with drivers, see [Use Trusted identity propagation with Amazon Athena drivers](using-trusted-identity-propagation.md). You can also [configure and deploy resources using CloudFormation](using-trusted-identity-propagation-cloudformation.md). With trusted identity propagation, identity context is added to an IAM role to identify the user requesting access to AWS resources. For information on enabling and using trusted identity propagation, see [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html). ## Credentials provider The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `JWT_TIP`. **** | Parameter name | Alias | Parameter type | Default value | Value to use | | --- | --- | --- | --- | --- | | CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | JWT\$1TIP | ## JWT web identity token The JWT token obtained from an external federated identity provider. This token will be used to authenticate with Athena. Token Caching is enabled by default and allows the same Identity Center access token to be used across driver connections. We recommend to provide a fresh JWT token upon "Testing Connection" as the exchanged token is present only during driver instance is active. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | JwtWebIdentityToken | web\$1identity\$1token (deprecated) | Required | none | ## WorkgroupArn The Amazon Resource Name (ARN) of the Amazon Athena workgroup. For more information about workgroups, see [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | WorkGroupArn | none | Required | primary | ## JWT application role ARN The ARN of the role to assume. This role is used for JWT exchange, getting IAM Identity Center customer managed application ARN through workgroup tags, and getting access role ARN. For more information about assuming roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | ApplicationRoleArn | none | Required | none | ## JWT role session name The name of the session when authenticating with JWT credentials. It can be any name of your choice. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | JwtRoleSessionName | role\$1session\$1name (deprecated) | Required | none | ## Role session duration The duration, in seconds, of the role session. For more information, see [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | RoleSessionDuration | Duration (deprecated) | Optional | 3600 | ## JWT access role ARN The ARN of the role to assume. This is the role assumed by the Athena service to make calls on the behalf of you. For more information about assuming roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | AccessRoleArn | none | Optional | none | ## IAM Identity Center customer managed application ARN The ARN of IAM Identity Center customer managed application. For more information, see [customer managed applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | CustomerIdcApplicationArn | none | Optional | none | # Browser based with identity center integration Browser trusted identity propagation This authentication type allows you to fetch a new JSON web token (JWT) from an external identity provider and authenticate with Athena. You can use this plugin, to enable support for corporate identities via trusted identity propagation. For more information on how to use trusted identity propagation with drivers, see [Use Trusted identity propagation with Amazon Athena drivers](using-trusted-identity-propagation.md). You can also [configure and deploy resources using CloudFormation](using-trusted-identity-propagation-cloudformation.md). With trusted identity propagation, identity context is added to an IAM role to identify the user requesting access to AWS resources. For information on enabling and using trusted identity propagation, see [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html). **Note** The plugin is specifically designed for single-user desktop environments. In shared environments like Windows Server, system administrators are responsible for establishing and maintaining security boundaries between users. ## Credentials provider The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `BrowserOidcTip`. **** | Parameter name | Alias | Parameter type | Default value | Value to use | | --- | --- | --- | --- | --- | | CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | BrowserOidcTip | ## Idp well known configuration URL The IDP Well Known Configuration URL is the endpoint that provides OpenID Connect configuration details for your identity provider. This URL typically ends with `.well-known/openid-configuration` and contains essential metadata about the authentication endpoints, supported features, and token signing keys. For example, if you're using *Okta*, the URL might look like `https://your-domain.okta.com/.well-known/openid-configuration`. For troubleshooting: If you receive connection errors, verify that this URL is accessible from your network and returns valid *OpenID Connect* configuration JSON. The URL must be reachable by the client where the driver is installed and should be provided by your identity provider administrator. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | IdpWellKnownConfigurationUrl | none | Required | none | ## Client identifier The client identifier issued to the application by the OpenID Connect provider. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | OidcClientId | none | Required | none | ## WorkgroupArn The Amazon Resource Name (ARN) of the Amazon Athena workgroup that contains the trusted identity propagation configuration tags. For more information about workgroups, see [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html). **Note** This parameter is different from the `Workgroup` parameter that specifies where queries will run. You must set both parameters: `WorkgroupArn` - Points to the workgroup containing the trusted identity propagation configuration tags `Workgroup` - Specifies the workgroup where queries will execute While these typically reference the same workgroup, both parameters must be set explicitly for proper operation. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | WorkGroupArn | none | Required | primary | ## JWT application role ARN The ARN of the role that will be assumed in the JWT exchange. This role is used for JWT exchange, getting IAM Identity Center customer managed application ARN through workgroup tags, and getting access role ARN. For more information about assuming roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | ApplicationRoleArn | none | Required | none | ## JWT role session name A name for the IAM session. It can be anything you like, but typically you pass the name or identifier that's associated with the user who is using your application. That way, the temporary security credentials that your application will use are associated with that user. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | JwtRoleSessionName | role\$1session\$1name (deprecated) | Required | none | ## Client secret The clientSecret is a confidential key issued by your identity provider that is used to authenticate your application (client). While this parameter is optional and may not be required for all authentication flows, it provides an additional layer of security when used. If your IDP configuration requires a client secret, you must include this parameter with the value provided by your identity provider administrator. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | OidcClientSecret | none | Optional | none | ## Scope The scope specifies what level of access your application is requesting from the identity provider. You must include `openid` in the scope to receive an ID token containing essential user identity claims. Your scope may need to include additional permissions like `email` or `profile`, depending on which user claims your identity provider (such as *Microsoft Entra ID*) is configured to include in the ID token. These claims are essential for proper *Trusted Identity Propagation* mapping. If user identity mapping fails, verify that your scope includes all necessary permissions and your identity provider is configured to include the required claims in the ID token. These claims must match your *Trusted Token Issuer* mapping configuration in IAM Identity Center. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | Scope | none | Optional | openid email offline\$1access | ## Role session duration The duration, in seconds, of the role session. For more information, see [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | RoleSessionDuration | Duration (deprecated) | Optional | 3600 | ## JWT access role ARN The ARN of the role that Athena assumes to make calls on the behalf of you. For more information about assuming roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | AccessRoleArn | none | Optional | none | ## IAM Identity Center customer managed application ARN The ARN of IAM Identity Center customer managed application. For more information, see [customer managed applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | CustomerIdcApplicationArn | none | Optional | none | ## Identity provider port number The local port number to use for the OAuth 2.0 callback server. This is used as redirect\$1uri and you will need to allowlist this in your IDP application. The default generated redirect\$1uri is: http://localhost:7890/athena **Warning** In shared environments like Windows Terminal Servers or Remote Desktop Services, the loopback port (default: 7890) is shared among all users on the same machine. System administrators can mitigate potential port hijacking risks by: Configuring different port numbers for different user groups Using Windows security policies to restrict port access Implementing network isolation between user sessions If these security controls cannot be implemented, we recommend using the [JWT trusted identity propagation](jdbc-v3-driver-jwt-tip-credentials.md) plugin instead, which doesn't require a loopback port. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | IdpPortNumber | none | Optional | 7890 | ## Identity provider response timeout The timeout in seconds to wait for the OAuth 2.0 callback response. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | IdpResponseTimeout | none | Optional | 120 | ## Enable token caching The EnableTokenCaching parameter determines whether the driver caches the authentication token between conections. Setting EnableTokenCaching to true reduces authentication prompts and improves user experience, but should be used cautiously. This setting is best suited for single-user desktop environments. In shared environments like Windows Server, it's recommended to keep this disabled to prevent potential token sharing between users with similar connection strings. For enterprise deployments using tools like Tableau Server, we recommend using the [JWT trusted identity propagation](jdbc-v3-driver-jwt-tip-credentials.md) plugin instead of this authentication method. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | EnableTokenCaching | none | Optional | FALSE | # Azure AD credentials Azure AD A SAML-based authentication mechanism that enables authentication to Athena using the Azure AD identity provider. This method assumes that a federation has already been set up between Athena and Azure AD. **Note** Some of the parameter names in this section have aliases. The aliases are functional equivalents of the parameter names and have been provided for backward compatibility with the JDBC 2.x driver. Because the parameter names have been improved to follow a clearer, more consistent naming convention, we recommend that you use them instead of the aliases, which have been deprecated. ## Credentials provider The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `AzureAD`. **** | Parameter name | Alias | Parameter type | Default value | Value to use | | --- | --- | --- | --- | --- | | CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | AzureAD | ## User The email address of the Azure AD user to use for authentication with Azure AD. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | User | UID (deprecated) | Required | none | ## Password The password for the Azure AD user. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | Password | PWD (deprecated) | Required | none | ## Azure AD tenant ID The tenant ID of your Azure AD application. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | AzureAdTenantId | tenant\$1id (deprecated) | Required | none | ## Azure AD client ID The client ID of your Azure AD application. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | AzureAdClientId | client\$1id (deprecated) | Required | none | ## Azure AD client secret The client secret of your Azure AD application. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | AzureAdClientSecret | client\$1secret (deprecated) | Required | none | ## Preferred role The Amazon Resource Name (ARN) of the role to assume. For information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | PreferredRole | preferred\$1role (deprecated) | Optional | none | ## Role session duration The duration, in seconds, of the role session. For more information, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | RoleSessionDuration | Duration (deprecated) | Optional | 3600 | ## Lake Formation enabled Specifies whether to use the [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API action to retrieve temporary IAM credentials instead of the [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API action. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | LakeFormationEnabled | none | Optional | FALSE | # Okta credentials Okta A SAML-based authentication mechanism that enables authentication to Athena using the Okta identity provider. This method assumes that a federation has already been set up between Athena and Okta. ## Credentials provider The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `Okta`. **** | Parameter name | Alias | Parameter type | Default value | Value to use | | --- | --- | --- | --- | --- | | CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | Okta | ## User The email address of the Okta user to use for authentication with Okta. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | User | UID (deprecated) | Required | none | ## Password The password for the Okta user. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | Password | PWD (deprecated) | Required | none | ## Okta host name The URL for your Okta organization. You can extract the `idp_host` parameter from the **Embed Link** URL in your Okta application. For steps, see [Retrieve ODBC configuration information from Okta](odbc-okta-plugin.md#odbc-okta-plugin-retrieve-odbc-configuration-information-from-okta). The first segment after `https://`, up to and including `okta.com`, is your IdP host (for example, `trial-1234567.okta.com` for a URL that starts with `https://trial-1234567.okta.com`). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | OktaHostName | IdP\$1Host (deprecated) | Required | none | ## Okta application ID The two-part identifier for your application. You can extract the application ID from the **Embed Link** URL in your Okta application. For steps, see [Retrieve ODBC configuration information from Okta](odbc-okta-plugin.md#odbc-okta-plugin-retrieve-odbc-configuration-information-from-okta). The application ID is the last two segments of the URL, including the forward slash in the middle. The segments are two 20-character strings with a mix of numbers and upper and lowercase letters (for example, `Abc1de2fghi3J45kL678/abc1defghij2klmNo3p4`). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | OktaAppId | App\$1ID (deprecated) | Required | none | ## Okta application name The name of your Okta application. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | OktaAppName | App\$1Name (deprecated) | Required | none | ## Okta MFA type If you have set up Okta to require multi-factor authentication (MFA), you need to specify the Okta MFA type and additional parameters depending on the second factor that you want to use. Okta MFA type is the second authentication factor type (after the password) to use to authenticate with Okta. Supported second factors include push notifications delivered through the Okta Verify app and temporary one-time passwords (TOTPs) generated by Okta Verify, Google Authenticator, or sent through SMS. Individual organization security policies determine whether or not MFA is required for user login. **** | Parameter name | Alias | Parameter type | Default value | Possible values | | --- | --- | --- | --- | --- | | OktaMfaType | okta\$1mfa\$1type (deprecated) | Required, if Okta is set up to require MFA | none | oktaverifywithpush, oktaverifywithtotp, googleauthenticator, smsauthentication | ## Okta phone number The phone number to which Okta will send a temporary one-time password using SMS when the `smsauthentication` MFA type is chosen. The phone number must be a US or Canadian phone number. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | OktaPhoneNumber | okta\$1phone\$1number (deprecated) | Required, if OktaMfaType is smsauthentication | none | ## Okta MFA wait time The duration, in seconds, to wait for the user to acknowledge a push notification from Okta before the driver throws a timeout exception. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | OktaMfaWaitTime | okta\$1mfa\$1wait\$1time (deprecated) | Optional | 60 | ## Preferred role The Amazon Resource Name (ARN) of the role to assume. For information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | PreferredRole | preferred\$1role (deprecated) | Optional | none | ## Role session duration The duration, in seconds, of the role session. For more information, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | RoleSessionDuration | Duration (deprecated) | Optional | 3600 | ## Lake Formation enabled Specifies whether to use the [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API action to retrieve temporary IAM credentials instead of the [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API action. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | LakeFormationEnabled | none | Optional | FALSE | # Ping credentials Ping A SAML-based authentication mechanism that enables authentication to Athena using the Ping Federate identity provider. This method assumes that a federation has already been set up between Athena and Ping Federate. ## Credentials provider The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `Ping`. **** | Parameter name | Alias | Parameter type | Default value | Value to use | | --- | --- | --- | --- | --- | | CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | Ping | ## User The email address of the Ping Federate user to use for authentication with Ping Federate. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | User | UID (deprecated) | Required | none | ## Password The password for the Ping Federate user. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | Password | PWD (deprecated) | Required | none | ## PingHostName The address for your Ping server. To find your address, visit the following URL and view the **SSO Application Endpoint** field. ``` https://your-pf-host-#:9999/pingfederate/your-pf-app#/spConnections ``` **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | PingHostName | IdP\$1Host (deprecated) | Required | none | ## PingPortNumber The port number to use to connect to your IdP host. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | PingPortNumber | IdP\$1Port (deprecated) | Required | none | ## PingPartnerSpId The service provider address. To find the service provider address, visit the following URL and view the **SSO Application Endpoint** field. ``` https://your-pf-host-#:9999/pingfederate/your-pf-app#/spConnections ``` **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | PingPartnerSpId | Partner\$1SPID (deprecated) | Required | none | ## Preferred role The Amazon Resource Name (ARN) of the role to assume. For information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | PreferredRole | preferred\$1role (deprecated) | Optional | none | ## Role session duration The duration, in seconds, of the role session. For more information, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | RoleSessionDuration | Duration (deprecated) | Optional | 3600 | ## Lake Formation enabled Specifies whether to use the [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API action to retrieve temporary IAM credentials instead of the [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API action. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | LakeFormationEnabled | none | Optional | FALSE | # AD FS credentials AD FS A SAML-based authentication mechanism that enables authentication to Athena using Microsoft Active Directory Federation Services (AD FS). This method assumes that the user has already set up a federation between Athena and AD FS. ## Credentials provider The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `ADFS`. **** | Parameter name | Alias | Parameter type | Default value | Value to use | | --- | --- | --- | --- | --- | | CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | ADFS | ## User The email address of the AD FS user to use for authentication with AD FS. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | User | UID (deprecated) | Required for form-based authentication. Optional for Windows Integrated Authentication. | none | ## Password The password for the AD FS user. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | Password | PWD (deprecated) | Required for form-based authentication. Optional for Windows Integrated Authentication. | none | ## ADFS host name The address for your AD FS server. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | AdfsHostName | IdP\$1Host (deprecated) | Required | none | ## ADFS port number The port number to use to connect to your AD FS server. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | AdfsPortNumber | IdP\$1Port (deprecated) | Required | none | ## ADFS relying party The trusted relying party. Use this parameter to override the AD FS relying party endpoint URL. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | AdfsRelyingParty | LoginToRP (deprecated) | Optional | urn:amazon:webservices | ## ADFS WIA enabled Boolean. Use this parameter to enable Windows Integrated Authentication (WIA) with AD FS. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | AdfsWiaEnabled | none | Optional | FALSE | ## Preferred role The Amazon Resource Name (ARN) of the role to assume. For information about ARN roles, see [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | PreferredRole | preferred\$1role (deprecated) | Optional | none | ## Role session duration The duration, in seconds, of the role session. For more information, see [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | RoleSessionDuration | Duration (deprecated) | Optional | 3600 | ## Lake Formation enabled Specifies whether to use the [https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API action to retrieve temporary IAM credentials instead of the [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API action. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | LakeFormationEnabled | none | Optional | FALSE | # Browser Azure AD credentials Browser Azure AD Browser Azure AD is a SAML-based authentication mechanism that works with the Azure AD identity provider and supports multi-factor authentication. Unlike the standard Azure AD authentication mechanism, this mechanism does not require a user name, password, or client secret in the connection parameters. Like the standard Azure AD authentication mechanism, Browser Azure AD also assumes the user has already set up federation between Athena and Azure AD. ## Credentials provider The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `BrowserAzureAD`. **** | Parameter name | Alias | Parameter type | Default value | Value to use | | --- | --- | --- | --- | --- | | CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | BrowserAzureAD | ## Azure AD tenant ID The tenant ID of your Azure AD application **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | AzureAdTenantId | tenant\$1id (deprecated) | Required | none | ## Azure AD client ID The client ID of your Azure AD application **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | AzureAdClientId | client\$1id (deprecated) | Required | none | ## Identity provider response timeout The duration, in seconds, before the driver stops waiting for the SAML response from Azure AD. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | IdpResponseTimeout | idp\$1response\$1timeout (deprecated) | Optional | 120 | ## Preferred role The Amazon Resource Name (ARN) of the role to assume. For information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | PreferredRole | preferred\$1role (deprecated) | Optional | none | ## Role session duration The duration, in seconds, of the role session. For more information, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | RoleSessionDuration | Duration (deprecated) | Optional | 3600 | ## Lake Formation enabled Specifies whether to use the [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API action to retrieve temporary IAM credentials instead of the [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API action. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | LakeFormationEnabled | none | Optional | FALSE | # Browser SAML credentials Browser SAML Browser SAML is a generic authentication plugin that can work with SAML-based identity providers and supports multi-factor authentication. ## Credentials provider The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `BrowserSaml`. **** | Parameter name | Alias | Parameter type | Default value | Value to use | | --- | --- | --- | --- | --- | | CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | BrowserSaml | ## Single sign-on login URL The single sign-on URL for your application on the SAML-based identity provider. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | SsoLoginUrl | login\$1url (deprecated) | Required | none | ## Listen port The port number that is used to listen for the SAML response. This value should match the URL with which you configured the SAML-based identity provider (for example, `http://localhost:7890/athena`). **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | ListenPort | listen\$1port (deprecated) | Optional | 7890 | ## Identity provider response timeout The duration, in seconds, before the driver stops waiting for the SAML response from Azure AD. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | IdpResponseTimeout | idp\$1response\$1timeout (deprecated) | Optional | 120 | ## Preferred role The Amazon Resource Name (ARN) of the role to assume. For information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | PreferredRole | preferred\$1role (deprecated) | Optional | none | ## Role session duration The duration, in seconds, of the role session. For more information, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | RoleSessionDuration | Duration (deprecated) | Optional | 3600 | ## Lake Formation enabled Specifies whether to use the [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API action to retrieve temporary IAM credentials instead of the [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API action. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | LakeFormationEnabled | none | Optional | FALSE | # DataZone IdC Credentials Provider DataZone IdC An authentication mechanism that enables connecting to DataZone-governed data in Athena using IAM Identity Center. ## Credentials provider The credentials provider that will be used to authenticate requests to AWS. Set the value of this parameter to `DataZoneIdc`. Note that the `AWSCredentialsProviderClass` alias is deprecated; use the `CredentialsProvider` parameter name instead. **** | Parameter name | Alias | Parameter type | Default value | Value to use | | --- | --- | --- | --- | --- | | CredentialsProvider | AWSCredentialsProviderClass (deprecated) | Required | none | DataZoneIdc | ## DataZone domain identifier Identifier of the DataZone domain to use. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | DataZoneDomainId | none | Required | none | ## DataZone environment identifier Identifier of the DataZone environment to use. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | DataZoneEnvironmentId | none | Required | none | ## DataZone domain region The AWS Region where your DataZone domain is provisioned. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | DataZoneDomainRegion | none | Required | none | ## Region The AWS Region where your DataZone environment and Athena workgroup are provisioned. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | Region | none | Required | none | ## IAM Identity Center issuer URL The issuer URL of the IAM Identity Center instance that the DataZone domain uses. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | IdentityCenterIssuerUrl | none | Required | none | ## DataZone endpoint override The DataZone API endpoint to be used instead of the default for the provided AWS Region. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | DataZoneEndpointOverride | none | Optional | none | ## Enable token caching When enabled, allows the same IAM Identity Center access token to be used across driver connections. This prevents SQL tools that create multiple driver connections from launching multiple browser windows. If you enable this parameter, we recommend that you close the SQL tool immediately after using it to clear the token cache and require re-authentication. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | EnableTokenCaching | none | Optional | FALSE | ## Listen port The port number that listens for the IAM Identity Center response. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | ListenPort | none | Optional | 8000 | ## Identity provider response time out The duration, in seconds, before the driver stops waiting for the response from IAM Identity Center. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | IdpResponseTimeout | none | Optional | 120 | # DataZone IAM Credentials Provider DataZone IAM An authentication mechanism that uses IAM credentials to connect to DataZone-governed data in Athena. ## DataZone domain identifier Identifier of the DataZone domain to use. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | DataZoneDomainId | none | Required | none | ## DataZone environment identifier Identifier of the DataZone environment to use. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | DataZoneEnvironmentId | none | Required | none | ## DataZone domain region The AWS Region where your DataZone domain is provisioned. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | DataZoneDomainRegion | none | Required | none | ## DataZone endpoint override The DataZone API endpoint to use instead of the endpoint default for the provided AWS Region. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | DataZoneEndpointOverride | none | Optional | none | ## User Your AWS access key ID. For more information about access keys, see [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html) in the *IAM User Guide*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | User | AccessKeyId | Optional | none | ## Password Your AWS secret key ID. For more information about access keys, see [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html) in the *IAM User Guide*. **** | Parameter name | Alias | Parameter type | Default value | | --- | --- | --- | --- | | Password | SecretAccessKey | Optional | none | # Other JDBC 3.x configuration The following sections describe some additional configuration settings for the JDBC 3.x driver. ## Network timeout The network timeout controls the amount of time in milliseconds that the driver waits for a network connection to be established. This includes the time it takes to send API requests. After this time, the driver throws a timeout exception. In rare circumstances, it may be useful to change the network timeout. For example, you might want to increase the timeout for long garbage collection pauses. To set it, call the `setNetworkTimeout` method on a JDBC `Connection` object. This value can be changed during the lifecycle of the JDBC connection. For more information, see [setNetworkTimeout](https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html#setNetworkTimeout-java.util.concurrent.Executor-int-) in the Oracle JDBC API documentation. Using the `setNetworkTimeout` method is equivalent to setting the [Network timeout](jdbc-v3-driver-advanced-connection-parameters.md#jdbc-v3-driver-networktimeoutmillis) connection parameter. The following example sets the network timeout to 5000 milliseconds. ``` ... AthenaDriver driver = new AthenaDriver(); Connection connection = driver.connect(url, connectionParameters); connection.setNetworkTimeout(null, 5000); ... ``` ## Query timeout The amount of time, in seconds, the driver will wait for a query to complete on Athena after a query has been submitted. After this time, the driver attempts to cancel the submitted query and throws a timeout exception. The query timeout cannot be set as a connection parameter. To set it, call the `setQueryTimeout` method on a JDBC `Statement` object. This value can be changed during the lifecycle of a JDBC statement. The default value of this parameter is `0` (zero). A value of `0` means that queries can run until they complete (subject to [Service Quotas](service-limits.md)). The following example sets the query timeout to 5 seconds. ``` ... AthenaDriver driver = new AthenaDriver(); Connection connection = driver.connect(url, connectionParameters); Statement statement = connection.createStatement(); statement.setQueryTimeout(5); ... ``` # Amazon Athena JDBC 3.x release notes JDBC 3.x release notes These release notes provide details of improvements and fixes in the Amazon Athena JDBC 3.x driver. ## 3.7.0 Released 2025-11-21 ### Improvements + **Browser OIDC Trusted identity propagation authentication plugin** – Added a new authentication plugin that enables seamless browser-based authentication with OpenID Connect (OIDC) identity providers. This plugin handles the complete OAuth 2.0 flow through your default browser, automatically fetches the JSON Web Token (JWT), and integrates with trusted identity propagation. Designed specifically for single-user desktop environments, it provides a more streamlined authentication experience compared to manual JWT handling. For more information about trusted identity propagation, see [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html). ### Fixes + **Enhanced timestamp precision support** – The driver now fully supports millisecond and nanosecond precision in timestamp values returned from Athena queries through the `getTimestamp()` method. + **Improved complex type handling** – Fixed issues with parsing nested data types (arrays, structs, and maps) in both `DatabaseMetaData#getColumns` and general metadata operations, ensuring accurate type information for complex data structures. + **Enhanced error logging** – Improved logging for S3 metadata fetch failures, providing clearer error messages and better diagnostic information. ## 3.6.0 Released 2025-09-10 ### Improvements + **JWT Trusted identity propagation authentication plugin** – Added a new authentication plugin to support JWT trusted identity propagation integration with JDBC drivers. This authentication type allows you to use a JSON web token (JWT) obtained from an external identity provider as a connection parameter to authenticate with Athena. With trusted identity propagation, identity context is added to an IAM role to identify the user requesting access to AWS resources. For information on enabling and using trusted identity propagation, see [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html). + **Custom SSO OIDC and SSO admin endpoints support** – Added support for custom SSO OIDC and SSO Admin endpoints in the JDBC driver. This enhancement allows you to specify your own endpoints for SSO services when running JDBC behind VPCs. + **AWS SDK version update** – We have updated the AWS SDK version used in the driver to 2.32.16 and have updated the project dependencies for release 3.6.0. ## 3.5.1 Released 2025-07-17 ### Improvements + **Logging capabilities** – Enhanced S3 fetch logging by elevating log level to `INFO` and adding metrics for row counts, offsets, and object length. Implemented connection lifecycle tracking and optimized overall logging performance. + **Special characters handling** – Improved handling of special characters for `LIKE` patterns in schema and catalog names. + **Connection state management** – Improved connection state management to prevent potential errors by preventing API calls after connection closure and adding safety checks for query operations during shutdown. ### Fixes + **DDL query metadata** – Fixed `NoSuchKeyFound` issue with DDL query metadata handling. ## 3.5.0 Released 2025-03-18 ### Improvements + **Result configuration parameters** – Added support for two new connection parameters `ExpectedBucketOwner` and `AclOption`. For more information, see [Result configuration parameters](jdbc-v3-driver-advanced-connection-parameters.md#jdbc-v3-driver-result-config). + **AWS SDK version** – The AWS SDK version used in the driver has been updated to 2.30.22. ## 3.4.0 Released 2025-02-18 ### Improvements + **Result Fetcher** – The driver now automatically selects the fastest method to download query results. This removes the need to manually configure the fetcher in most situations. For more information, see [Result fetching parameters](jdbc-v3-driver-advanced-connection-parameters.md#jdbc-v3-driver-result-fetching-parameters). ### Fixes + **ResultSet** – The driver now handles iterating over the result sets of DDL statements that don't produce result objects on S3. It also returns an empty `ResultSet` object instead of null when `GetQueryResultsStream` returns a completely empty page. + **ResultsStream** – The result streaming has been optimized by removing unnecessary calls to count the number of rows in internal buffers. + **getTables** – The `GetTables` call has been optimized by handling table types based on `ListTableMetadata` and `GetTableMetadata` responses. ## 3.3.0 Released 2024-10-30 ### Improvements + **DataZone authentication** – Added support for the DataZone authentication plugins `DataZoneIdC` and `DataZoneIAM`. For more information, see [DataZone IdC Credentials Provider](jdbc-v3-driver-datazone-idc.md) and [DataZone IAM Credentials Provider](jdbc-v3-driver-datazone-iamcp.md). + **Network timeout** – The network timeout can now be set using the `NetworkTimeoutMillis` connection parameter. Previously it could be set only on the `Connection` object itself. For more information, see [Network timeout](jdbc-v3-driver-other-configuration.md#jdbc-v3-driver-network-timeout). ### Fixes + **S3 empty object handling** – The driver now handles empty objects in the S3 fetcher instead of throwing an Amazon S3 Range Not Satisfiable exception. + **Logging** – The driver no longer logs the message Items requested for query execution [...], but subscription is cancelled after consuming query results. + **Empty parameter strings** – The driver now handles empty strings present in a connection parameter as if the parameter were not present. This resolves issues that occurred when some BI tools inadvertently passed empty strings that caused unintended authentication attempts. ## 3.2.2 Released 2024-07-29 ### Improvements + **Data type mapping** – Improved the compliance with the JDBC spec by changing how the driver maps the `tinyint`, `smallint`, `row`, and `struct` data types to Java objects. + **AWS SDK version update** – The AWS SDK version used in the driver has been updated to 2.26.23. ### Fixes + **Comments** – Fixed an issue with line comments at the end of a statement. + **Database listing** – Fixed an issue in which listing databases could enter an infinite loop when the last page returned by the paginated `ListDatabases` API was empty. ## 3.2.1 Released 2024-07-03 ### Improvements + **JWT credentials provider** – Added support for user-specified session durations. For more information, see [Role session duration](jdbc-v3-driver-jwt-credentials.md#jdbc-v3-driver-jwt-role-session-duration). ### Fixes + **Thread pool** – Created one `ThreadPoolExecutor` per connection for asynchronous tasks to avoid using the `ForkJoin` pool. + **Credential providers** – The proxy host is now parsed to get the scheme and host when the HTTP client is configured for external IdPs. + **Default credentials provider** – Ensured the default credentials provider can't be closed by client code. + **getColumns** – Fixed an `ORDINAL_COLUMN` column property issue in the `DatabaseMetaData#getColumns` method. + **ResultSet** – Added support for `Infinity`, `-Infinity`, and `NaN` to `ResultSet.` Fixed a discrepancy between the column type returned from catalog operations and the result set of a completed query. ## 3.2.0 Released 2024-04-26 ### Improvements + **Catalog operation performance** – Performance has been improved for catalog operations that do not use wildcard characters. + **Minimum polling interval change** – The minimum polling interval default has been modified to reduce the number of API calls the driver makes to Athena. Query completions are still detected as soon as possible. + **BI tool discoverability** – The driver has been made more easily discoverable for business intelligence tools. + **Data type mapping** – Data type mapping to the Athena `binary`, `array`, and `struct` DDL data types has been improved. + **AWS SDK version** – The AWS SDK version used in the driver has been updated to 2.25.34. ### Fixes + **Federated catalog table listings** – Fixed an issue that caused federated catalogs to return an empty list of tables. + **getSchemas** – Fixed an issue that caused the JDBC [DatabaseMetaData\$1getSchemas](https://docs.oracle.com/javase/8/docs/api/java/sql/DatabaseMetaData.html#getSchemas--) method to fetch databases only from the default catalog instead of from all catalogs. + **getColumns** – Fixed an issue that caused a null catalog to be returned when the JDBC [DatabaseMetaData\$1getColumns](https://docs.oracle.com/javase/8/docs/api/java/sql/DatabaseMetaData.html#getColumns-java.lang.String-java.lang.String-java.lang.String-java.lang.String-) method was called with a null catalog name. ## 3.1.0 Released 2024-02-15 ### Improvements + Support added for Microsoft Active Directory Federation Services (AD FS) Windows Integrated Authentication and form-based authentication. + For backwards compatibility with version 2.x, the `awsathena` JDBC sub-protocol is now accepted but produces a deprecation warning. Use the `athena` JDBC sub-protocol instead. + `AwsDataCatalog` is now the default for the catalog parameter, and `default` is the default for the database parameter. These changes ensure that correct values for the current catalog and database are returned instead of null. + In conformance with the JDBC specification, `IS_AUTOINCREMENT` and `IS_GENERATEDCOLUMN` now return an empty string instead of `NO`. + The Athena `int` data type now maps to the same JDBC type as Athena `integer` instead of to `other`. + When the column metadata from Athena does not contain the optional `precision` and `scale` fields, the driver now returns zero for the corresponding values in a `ResultSet` column. + The AWS SDK version has been updated to 2.21.39. ### Fixes + Fixed an issue with `GetQueryResultsStream` that caused an exception to occur when plain text results from Athena had a column count inconsistent with the column count in Athena result metadata. ## 3.0.0 Released 2023-11-16 The Athena JDBC 3.x driver is the new generation driver offering better performance and compatibility. The JDBC 3.x driver supports reading query results directly from Amazon S3, which improves the performance of applications that consume large query results. The new driver also has fewer third-party dependencies, which makes integration with BI tools and custom applications easier. # Previous versions of the Athena JDBC 3.x driver Previous versions We highly recommended that you use the [latest version](jdbc-v3-driver.md) of the JDBC 3.x driver. The latest version of the driver contains the most recent improvements and fixes. Use an older version only if your application experiences incompatibilities with the latest version. ## JDBC driver uber jar The following download packages the driver and all its dependencies in the same `.jar` file. This download is commonly used for third-party SQL clients. + [3.6.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.6.0/athena-jdbc-3.6.0-with-dependencies.jar) + [3.5.1 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.5.1/athena-jdbc-3.5.1-with-dependencies.jar) + [3.5.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.5.0/athena-jdbc-3.5.0-with-dependencies.jar) + [3.4.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.4.0/athena-jdbc-3.4.0-with-dependencies.jar) + [3.3.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.3.0/athena-jdbc-3.3.0-with-dependencies.jar) + [3.2.2 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.2/athena-jdbc-3.2.2-with-dependencies.jar) + [3.2.1 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.1/athena-jdbc-3.2.1-with-dependencies.jar) + [3.2.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.0/athena-jdbc-3.2.0-with-dependencies.jar) + [3.1.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.1.0/athena-jdbc-3.1.0-with-dependencies.jar) + [3.0.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.0.0/athena-jdbc-3.0.0-with-dependencies.jar) ## JDBC driver lean jar The following download is a `.zip` file that contains the lean `.jar` for the driver and separate `.jar` files for the driver's dependencies. This download is commonly used for custom applications that might have dependencies that conflict with the dependencies that the driver uses. This download is useful if you want to choose which of the driver dependencies to include with the lean jar, and which to exclude if your custom application already contains one or more of them. + [3.6.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.6.0/athena-jdbc-3.6.0-lean-jar-and-separate-dependencies-jars.zip) + [3.5.1 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.5.1/athena-jdbc-3.5.1-lean-jar-and-separate-dependencies-jars.zip) + [3.5.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.5.0/athena-jdbc-3.5.0-lean-jar-and-separate-dependencies-jars.zip) + [3.4.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.4.0/athena-jdbc-3.4.0-lean-jar-and-separate-dependencies-jars.zip) + [3.3.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.3.0/athena-jdbc-3.3.0-lean-jar-and-separate-dependencies-jars.zip) + [3.2.2 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.2/athena-jdbc-3.2.2-lean-jar-and-separate-dependencies-jars.zip) + [3.2.1 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.1/athena-jdbc-3.2.1-lean-jar-and-separate-dependencies-jars.zip) + [3.2.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.0/athena-jdbc-3.2.0-lean-jar-and-separate-dependencies-jars.zip) + [3.1.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.1.0/athena-jdbc-3.1.0-lean-jar-and-separate-dependencies-jars.zip) + [3.0.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.0.0/athena-jdbc-3.0.0-lean-jar-and-separate-dependencies-jars.zip) # Athena JDBC 2.x driver JDBC 2.x You can use a JDBC connection to connect Athena to business intelligence tools and other applications, such as [SQL workbench](http://www.sql-workbench.eu/downloads.html). To do this, use the Amazon S3 links on this page to download, install, and configure the Athena JDBC 2.x driver. For information about building the JDBC connection URL, see the downloadable [JDBC driver installation and configuration guide](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/docs/Simba+Amazon+Athena+JDBC+Connector+Install+and+Configuration+Guide.pdf). For permissions information, see [Control access through JDBC and ODBC connections](policy-actions.md). To submit feedback regarding the JDBC driver, email [athena-feedback@amazon.com](mailto:athena-feedback@amazon.com). Starting with version 2.0.24, two versions of the driver are available: one that includes the AWS SDK, and one that does not. **Important** When you use the JDBC driver, be sure to note the following requirements: **Open port 444** – Keep port 444, which Athena uses to stream query results, open to outbound traffic. When you use a PrivateLink endpoint to connect to Athena, ensure that the security group attached to the PrivateLink endpoint is open to inbound traffic on port 444. If port 444 is blocked, you may receive the error message [Simba][AthenaJDBC](100123) An error has occurred. Exception during column initialization. **athena:GetQueryResultsStream policy** – Add the `athena:GetQueryResultsStream` policy action to the IAM principals that use the JDBC driver. This policy action is not exposed directly with the API. It is used only with the ODBC and JDBC drivers as part of streaming results support. For an example policy, see [AWS managed policy: AWSQuicksightAthenaAccess](security-iam-awsmanpol.md#awsquicksightathenaaccess-managed-policy). **Using the JDBC driver for multiple data catalogs** – To use the JDBC driver for multiple data catalogs with Athena (for example, when using an [external Hive metastore](connect-to-data-source-hive.md) or [federated queries](federated-queries.md)), include `MetadataRetrievalMethod=ProxyAPI` in your JDBC connection string. **4.1 drivers** – Starting in 2023, driver support for JDBC version 4.1 is discontinued. No further updates will be released. If you are using a JDBC 4.1 driver, migration to the 4.2 driver is highly recommended. ## JDBC 2.x driver with AWS SDK The JDBC driver version 2.2.2 complies with the JDBC API 4.2 data standard and requires JDK 8.0 or later. For information about checking the version of Java Runtime Environment (JRE) that you use, see the Java [documentation](https://www.java.com/en/download/help/version_manual.html). Use the following link to download the JDBC 4.2 driver `.jar` file. + [AthenaJDBC42-2.2.2.1000.jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/AthenaJDBC42-2.2.2.1000.jar) The following `.zip` file download contains the `.jar` file for JDBC 4.2 and includes the AWS SDK and the accompanying documentation, release notes, licenses, and agreements. + [SimbaAthenaJDBC-2.2.2.1000.zip](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/SimbaAthenaJDBC-2.2.2.1000.zip) ## JDBC 2.x driver without AWS SDK The JDBC driver version 2.2.2 complies with the JDBC API 4.2 data standard and requires JDK 8.0 or later. For information about checking the version of Java Runtime Environment (JRE) that you use, see the Java [documentation](https://www.java.com/en/download/help/version_manual.html). Use the following link to download the JDBC 4.2 driver `.jar` file without the AWS SDK. + [AthenaJDBC42-2.2.2.1001.jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1001/AthenaJDBC42-2.2.2.1001.jar) The following `.zip` file download contains the `.jar` file for JDBC 4.2 and the accompanying documentation, release notes, licenses, and agreements. It does not include the AWS SDK. + [SimbaAthenaJDBC-2.2.2.1001.zip](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1001/SimbaAthenaJDBC-2.2.2.1001.zip) ## JDBC 2.x driver release notes, license agreement, and notices After you download the version you need, read the release notes, and review the License Agreement and Notices. + [Release notes](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/docs/release-notes.txt) + [License agreement](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/docs/LICENSE.txt) + [Notices](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/docs/NOTICES.txt) + [Third-party licenses](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/docs/third-party-licenses.txt) ## JDBC 2.x driver documentation Download the following documentation for the driver: + [JDBC driver installation and configuration guide](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/docs/Simba+Amazon+Athena+JDBC+Connector+Install+and+Configuration+Guide.pdf). Use this guide to install and configure the driver. + [JDBC driver migration guide](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/docs/Simba+Amazon+Athena+JDBC+Connector+Migration+Guide.pdf). Use this guide to migrate from previous versions to the current version. # Connect to Amazon Athena with ODBC Connect to Athena with ODBC Amazon Athena offers two ODBC drivers, versions 1.x and 2.x. The Athena ODBC 2.x driver is a new alternative that supports Linux, macOS ARM, macOS Intel, and Windows 64-bit systems. The Athena 2.x driver supports all authentication plugins that the 1.x ODBC driver supports, and almost all connection parameters are backward-compatible. + To download the ODBC 2.x driver, see [Amazon Athena ODBC 2.x](odbc-v2-driver.md). + To download the ODBC 1.x driver, see [Athena ODBC 1.x driver](connect-with-odbc-driver-and-documentation-download-links.md). **Topics** + [ # Amazon Athena ODBC 2.x ](odbc-v2-driver.md) + [ # Athena ODBC 1.x driver ](connect-with-odbc-driver-and-documentation-download-links.md) + [ # Use the Amazon Athena Power BI connector ](connect-with-odbc-and-power-bi.md) # Amazon Athena ODBC 2.x ODBC 2.x You can use an ODBC connection to connect to Amazon Athena from many third-party SQL client tools and applications. You set up the ODBC connection on your client computer. ## Considerations and limitations For information on migrating from the Athena ODBC 1.x driver to the Athena 2.x ODBC driver, see [Migrate to the ODBC 2.x driver](odbc-v2-driver-migrating.md). ## ODBC 2.x driver download To download the Amazon Athena 2.x ODBC driver, visit the links on this page. **Important** When you use the ODBC 2.x driver, be sure to note the following requirements: **Open port 444** – Keep port 444, which Athena uses to stream query results, open to outbound traffic. When you use a PrivateLink endpoint to connect to Athena, ensure that the security group attached to the PrivateLink endpoint is open to inbound traffic on port 444. **athena:GetQueryResultsStream policy** – Add the `athena:GetQueryResultsStream` policy action to the IAM principals that use the ODBC driver. This policy action is not exposed directly with the API. It is used only with the ODBC and JDBC drivers as part of streaming results support. For an example policy, see [AWS managed policy: AWSQuicksightAthenaAccess](security-iam-awsmanpol.md#awsquicksightathenaaccess-managed-policy). **Important** **Security update:** Version 2.1.0.0 includes security enhancements to authentication, query processing, and transport security components. We recommend upgrading to this version to benefit from these improvements. For details, see the [Amazon Athena ODBC 2.x release notes](odbc-v2-driver-release-notes.md). ### Linux | Driver version | Download link | | --- | --- | | ODBC 2.1.0.0 for Linux 64-bit | [Linux 64 bit ODBC driver 2.1.0.0](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Linux/AmazonAthenaODBC-2.1.0.0.rpm) | ### macOS (ARM) | Driver version | Download link | | --- | --- | | ODBC 2.1.0.0 for macOS 64-bit (ARM) | [macOS 64 bit ODBC driver 2.1.0.0 (ARM)](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Mac/arm/AmazonAthenaODBC-2.1.0.0_arm.pkg) | ### macOS (Intel) | Driver version | Download link | | --- | --- | | ODBC 2.1.0.0 for macOS 64-bit (Intel) | [macOS 64 bit ODBC driver 2.1.0.0 (Intel)](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Mac/Intel/AmazonAthenaODBC-2.1.0.0_x86.pkg) | ### Windows | Driver version | Download link | | --- | --- | | ODBC 2.1.0.0 for Windows 64-bit | [Windows 64 bit ODBC driver 2.1.0.0](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Windows/AmazonAthenaODBC-2.1.0.0.msi) | ### Licenses + [AWS license](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/LICENSE.txt) + [Third party license](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/THIRD_PARTY_LICENSES.txt) ## Trusted identity propagation with ODBC You can now connect to Amazon Athena using ODBC drivers with single sign-on capabilities through AWS Identity and Access Management Identity Center. When you access Athena from tools like PowerBI, Tableau, or DBeaver, your identity and permissions automatically propagate to Athena through IAM Identity Center. For more information, see [Use Trusted identity propagation with Amazon Athena drivers](using-trusted-identity-propagation.md). **Topics** + [ ## Considerations and limitations ](#odbc-v2-driver-considerations-limitations) + [ ## ODBC 2.x driver download ](#odbc-v2-driver-download) + [ ## Trusted identity propagation with ODBC ](#odbc-v2-driver-trusted-identity) + [ # Get started with the ODBC 2.x driver ](odbc-v2-driver-getting-started.md) + [ # Athena ODBC 2.x connection parameters ](odbc-v2-driver-connection-parameters.md) + [ # Migrate to the ODBC 2.x driver ](odbc-v2-driver-migrating.md) + [ # Troubleshoot the ODBC 2.x driver ](odbc-v2-driver-troubleshooting.md) + [ # Amazon Athena ODBC 2.x release notes ](odbc-v2-driver-release-notes.md) # Get started with the ODBC 2.x driver Get started with ODBC 2.x Use the information in this section to get started with the Amazon Athena ODBC 2.x driver. The driver is supported on the Windows, Linux, and macOS operating systems. **Topics** + [ # Windows ](odbc-v2-driver-getting-started-windows.md) + [ # Linux ](odbc-v2-driver-getting-started-linux.md) + [ # macOS ](odbc-v2-driver-getting-started-macos.md) # Windows Windows If you want to use a Windows client computer to access Amazon Athena, the Amazon Athena ODBC driver is required. ## Windows system requirements Install the Amazon Athena ODBC driver on client computers that will access Amazon Athena databases directly instead of using a web browser. The Windows system you use must meet the following requirements: + You have administrator rights + One of the following operating systems: + Windows 11, 10, or 8.1 + Windows Server 2019, 2016, or 2012 + Supported processor architecture : x86\$164 (64-bit) + At least 100 MB of available disk space + [Microsoft Visual C\$1\$1 Redistributable for Visual Studio](https://visualstudio.microsoft.com/downloads/#microsoft-visual-c-redistributable-for-visual-studio-2022) for 64-bit Windows is installed. ## Installing the Amazon Athena ODBC driver **To download and install the Amazon Athena ODBC driver for Windows** 1. [Download](odbc-v2-driver.md#odbc-v2-driver-download) the `AmazonAthenaODBC-2.x.x.x.msi` installation file. 1. Launch the installation file, and then choose **Next**. 1. To accept the terms of the license agreement, select the check box, and then choose **Next**. 1. To change the installation location, choose **Browse**, browse to the desired folder, and then choose **OK**. 1. To accept the installation location, choose **Next**. 1. Choose **Install**. 1. When the installation completes, choose **Finish**. ## Ways to set driver configuration options To control the behavior of the Amazon Athena ODBC driver in Windows, you can set driver configuration options in the following ways: + In the **ODBC Data Source Administrator** program when you configure a data source name (DSN). + By adding or changing Windows registry keys in the following location: ``` HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\YOUR_DSN_NAME ``` + By setting driver options in the connection string when you connect programmatically. ## Configuring a data source name on Windows After you download and install the ODBC driver, you must add a data source name (DSN) entry to the client computer or Amazon EC2 instance. SQL client tools use this data source to connect to and query Amazon Athena. **To create a system DSN entry** 1. From the Windows **Start** menu, right-click **ODBC Data Sources (64 bit)**, and then choose **More**, **Run as administrator**. 1. In the **ODBC Data Source Administrator**, choose the **Drivers** tab. 1. In the **Name** column, verify that **Amazon Athena ODBC (x64)** is present. 1. Do one of the following: + To configure the driver for all users on the computer, choose the **System DSN** tab. Because applications that use a different account to load data might not be able to detect user DSNs from another account, we recommend the system DSN configuration option. **Note** Using the **System DSN** option requires administrative privileges. + To configure the driver for your user account only, choose the **User DSN** tab. 1. Choose **Add**. The **Create New Data Source** dialog box opens. 1. Choose **Amazon Athena ODBC (x64)**, and then choose **Finish**. 1. In the **Amazon Athena ODBC Configuration** dialog box, enter the following information. For detailed information about these options, see [Main ODBC 2.x connection parameters](odbc-v2-driver-main-connection-parameters.md). + For **Data Source Name**, enter a name that you want to use to identify the data source. + For **Description**, enter a description to help you identify the data source. + For **Region**, enter the name of the AWS Region that you will use Athena in (for example, ** us-west-1**). + For **Catalog**, enter the name of the Amazon Athena catalog. The default is **AwsDataCatalog**, which is used by AWS Glue. + For **Database**, enter the name of the Amazon Athena database. The default is **default**. + For **Workgroup**, enter the name of the Amazon Athena workgroup. The default is **primary**. + For **S3 Output Location**, enter the location in Amazon S3 where the query results will be stored (for example, **s3://amzn-s3-demo-bucket/**). + (Optional) For **Encryption Options**, choose an encryption option. The default is `NOT_SET`. + (Optional) For **KMS Key**, choose an encryption KMS key if required. 1. To specify configuration options for IAM authentication, choose **Authentication Options.** 1. Enter the following information: + For **Authentication Type**, choose **IAM Credentials**. This is the default. For more information about available authentication types, see [Authentication options](odbc-v2-driver-authentication-options.md). + For **Username**, enter a user name. + For **Password**, enter a password. + For **Session Token**, enter a session token if you want to use temporary AWS credentials. For information about temporary credentials, see [Using temporary credentials with AWS resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html) in the *IAM User Guide*. 1. Choose **OK**. 1. At the bottom of the **Amazon Athena ODBC Configuration** dialog box, choose **Test**. If the client computer connects successfully to Amazon Athena, the **Connection test** box reports **Connection successful**. If not, the box reports **Connection failed** with corresponding error information. 1. Choose **OK** to close the connection test. The data source that you created now appears in the list of data source names. ## Using a DSN-less connection on Windows You can use a DSN-less connection to connect to a database without a Data Source Name (DSN). The following example shows a connection string for the Amazon Athena ODBC (x64) ODBC driver that connects to Amazon Athena. ``` DRIVER={Amazon Athena ODBC (x64)};Catalog=AwsDataCatalog;AwsRegion=us-west-1;Schema=test_schema;S3OutputLocation= s3://amzn-s3-demo-bucket/;AuthenticationType=IAM Credentials;UID=YOUR_UID;PWD=YOUR_PWD; ``` # Linux Linux If you want use a Linux client computer to access Amazon Athena, the Amazon Athena ODBC driver is required. ## Linux system requirements Each Linux client computer where you install the driver must meet the following requirements. + You have root access. + Use one of the following Linux distributions: + Red Hat Enterprise Linux (RHEL) 7 or 8 + CentOS 7 or 8. + Have 100 MB of disk space available. + Use version 2.3.1 or later of [unixODBC](https://www.unixodbc.org/). + Use version 2.26 or later of the [GNU C Library](https://www.gnu.org/software/libc/) (glibc). ## Installing the ODBC data connector on Linux Use the following procedure to install the Amazon Athena ODBC driver on a Linux operating system. **To install the Amazon Athena ODBC driver on Linux** 1. Enter one of the following commands: ``` sudo rpm -Uvh AmazonAthenaODBC-2.X.Y.Z.rpm ``` or ``` sudo yum --nogpgcheck localinstall AmazonAthenaODBC-2.X.Y.Z.rpm ``` 1. After the installation finishes, enter one of the following commands to verify that the driver is installed: + ``` yum list | grep amazon-athena-odbc-driver ``` Output: ``` amazon-athena-odbc-driver.x86_64 2.0.2.1-1.amzn2int installed ``` + ``` rpm -qa | grep amazon ``` Output: ``` amazon-athena-odbc-driver-2.0.2.1-1.amzn2int.x86_64 ``` ## Configuring a data source name on Linux After the driver is installed, you can find example `.odbc.ini` and `.odbcinst.ini` files in the following location: + `/opt/athena/odbc/ini/`. Use the `.ini` files in this location as examples for configuring the Amazon Athena ODBC driver and data source name (DSN). **Note** By default, ODBC driver managers use the hidden configuration files `.odbc.ini` and `.odbcinst.ini`, which are located in the home directory. To specify the path to the `.odbc.ini` and `.odbcinst.ini` files using unixODBC, perform the following steps. **To specify ODBC `.ini` file locations using unixODBC** 1. Set `ODBCINI` to the full path and file name of the `odbc.ini` file, as in the following example. ``` export ODBCINI=/opt/athena/odbc/ini/odbc.ini ``` 1. Set `ODBCSYSINI` to the full path of the directory that contains the `odbcinst.ini` file, as in the following example. ``` export ODBCSYSINI=/opt/athena/odbc/ini ``` 1. Enter the following command to verify that you are using the unixODBC driver manager and the correct `odbc*.ini` files: ``` username % odbcinst -j ``` Sample output ``` unixODBC 2.3.1 DRIVERS............: /opt/athena/odbc/ini/odbcinst.ini SYSTEM DATA SOURCES: /opt/athena/odbc/ini/odbc.ini FILE DATA SOURCES..: /opt/athena/odbc/ini/ODBCDataSources USER DATA SOURCES..: /opt/athena/odbc/ini/odbc.ini SQLULEN Size.......: 8 SQLLEN Size........: 8 SQLSETPOSIROW Size.: 8 ``` 1. If you want to use a data source name (DSN) to connect to your data store, configure the `odbc.ini` file to define data source names (DSNs). Set the properties in the `odbc.ini` file to create a DSN that specifies the connection information for your data store, as in the following example. ``` [ODBC Data Sources] athena_odbc_test=Amazon Athena ODBC (x64) [ATHENA_WIDE_SETTINGS] # Special DSN-name to signal driver about logging configuration. LogLevel=0 # To enable ODBC driver logs, set this to 1. UseAwsLogger=0 # To enable AWS-SDK logs, set this to 1. LogPath=/opt/athena/odbc/logs/ # Path to store the log files. Permissions to the location are required. [athena_odbc_test] Driver=/opt/athena/odbc/lib/libathena-odbc.so AwsRegion=us-west-1 Workgroup=primary Catalog=AwsDataCatalog Schema=default AuthenticationType=IAM Credentials UID= PWD= S3OutputLocation=s3://amzn-s3-demo-bucket/ ``` 1. Configure the `odbcinst.ini` file, as in the following example. ``` [ODBC Drivers] Amazon Athena ODBC (x64)=Installed [Amazon Athena ODBC (x64)] Driver=/opt/athena/odbc/lib/libathena-odbc.so Setup=/opt/athena/odbc/lib/libathena-odbc.so ``` 1. After you install and configure the Amazon Athena ODBC driver, use the unixODBC `isql` command-line tool to verify the connection, as in the following example. ``` username % isql -v "athena_odbc_test" +---------------------------------------+ | Connected! | | | | sql-statement | | help [tablename] | | quit | | | +---------------------------------------+ SQL> ``` ## Verify the ODBC driver signature **Important** We recommend verifying the Athena ODBC driver RPM signature before installing it on your machine. Follow these steps to verify the signature of the Athena ODBC driver RPM package: 1. **Prepare the templates** Prepare the commands with appropriate public key, RPM signature, and the corresponding access link to the RPM scripts hosted in Amazon S3 buckets. You must download the following to your device. + [Athena ODBC driver](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Linux/AmazonAthenaODBC-2.1.0.0.rpm) + [Public Key](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Linux/public_key.pem) + [Athena ODBC RPM signature](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Linux/signature.bin) 1. Download the Athena ODBC driver, public key, and Athena ODBC RPM signature to your device. 1. Run the following command to verify ODBC driver signature: ``` openssl dgst -sha256 -verify public_key.pem -signature signature.bin AmazonAthenaODBC-2.1.0.0.rpm ``` If verification passes, you will see a message similar to `Verified OK`. This means you can now proceed to install the Athena ODBC driver. If it fails with a message `Verification Failure`, it means that the signature on RPM has been tampered. Ensure that all the three files mentioned in step 1 are present, the paths are correctly specified ,and the files haven't been modified since download and then retry the verification process. # macOS macOS If you want to use a macOS client computer to access Amazon Athena, the Amazon Athena ODBC driver is required. ## macOS system requirements Each macOS computer where you install the driver must meet the following requirements. + Use macOS version 14 or later. + Have 100 MB of disk space available. + Use version 3.52.16 or later of [iODBC](https://www.iodbc.org/dataspace/doc/iodbc/wiki/iodbcWiki/WelcomeVisitors). ## Installing the ODBC data connector on macOS Use the following procedure to download and install the Amazon Athena ODBC driver for macOS operating systems. **To download and install the Amazon Athena ODBC driver for macOS** 1. Download the `.pkg` package file. 1. Double-click the `.pkg` file. 1. Follow the steps in the wizard to install the driver. 1. On the **License Agreement** page, press **Continue**, and then choose **Agree**. 1. Choose **Install**. 1. When the installation completes, choose **Finish**. 1. Enter the following command to verify that the driver is installed: ``` > pkgutil --pkgs | grep athenaodbc ``` Depending on your system, the output can look like one of the following. ``` com.amazon.athenaodbc-x86_64.Config com.amazon.athenaodbc-x86_64.Driver ``` or ``` com.amazon.athenaodbc-arm64.Config com.amazon.athenaodbc-arm64.Driver ``` ## Configuring a data source name on macOS After the driver is installed, you can find example `.odbc.ini` and `.odbcinst.ini` files in the following locations: + Intel processor computers: `/opt/athena/odbc/x86_64/ini/` + ARM processor computers: `/opt/athena/odbc/arm64/ini/` Use the `.ini` files in this location as examples for configuring the Amazon Athena ODBC driver and data source name (DSN). **Note** By default, ODBC driver managers use the hidden configuration files `.odbc.ini` and `.odbcinst.ini`, which are located in the home directory. To specify the path to the `.odbc.ini` and `.odbcinst.ini` files using the iODBC driver manager, perform the following steps. **To specify ODBC `.ini` file locations using iODBC driver manager** 1. Set `ODBCINI` to the full path and file name of the `odbc.ini` file. + For macOS computers that have Intel processors, use the following syntax. ``` export ODBCINI=/opt/athena/odbc/x86_64/ini/odbc.ini ``` + For macOS computers that have ARM processors, use the following syntax. ``` export ODBCINI=/opt/athena/odbc/arm64/ini/odbc.ini ``` 1. Set `ODBCSYSINI` to the full path and file name of the `odbcinst.ini` file. + For macOS computers that have Intel processors, use the following syntax. ``` export ODBCSYSINI=/opt/athena/odbc/x86_64/ini/odbcinst.ini ``` + For macOS computers that have ARM processors, use the following syntax. ``` export ODBCSYSINI=/opt/athena/odbc/arm64/ini/odbcinst.ini ``` 1. If you want to use a data source name (DSN) to connect to your data store, configure the `odbc.ini` file to define data source names (DSNs). Set the properties in the `odbc.ini` file to create a DSN that specifies the connection information for your data store, as in the following example. ``` [ODBC Data Sources] athena_odbc_test=Amazon Athena ODBC (x64) [ATHENA_WIDE_SETTINGS] # Special DSN-name to signal driver about logging configuration. LogLevel=0 # set to 1 to enable ODBC driver logs UseAwsLogger=0 # set to 1 to enable AWS-SDK logs LogPath=/opt/athena/odbc/logs/ # Path to store the log files. Permissions to the location are required. [athena_odbc_test] Description=Amazon Athena ODBC (x64) # For ARM: Driver=/opt/athena/odbc/arm64/lib/libathena-odbc-arm64.dylib # For Intel: # Driver=/opt/athena/odbc/x86_64/lib/libathena-odbc-x86_64.dylib AwsRegion=us-west-1 Workgroup=primary Catalog=AwsDataCatalog Schema=default AuthenticationType=IAM Credentials UID= PWD= S3OutputLocation=s3://amzn-s3-demo-bucket/ ``` 1. Configure the `odbcinst.ini` file, as in the following example. ``` [ODBC Drivers] Amazon Athena ODBC (x64)=Installed [Amazon Athena ODBC (x64)] # For ARM: Driver=/opt/athena/odbc/arm64/lib/libathena-odbc-arm64.dylib Setup=/opt/athena/odbc/arm64/lib/libathena-odbc-arm64.dylib # For Intel: # Driver=/opt/athena/odbc/x86_64/lib/libathena-odbc-x86_64.dylib # Setup=/opt/athena/odbc/x86_64/lib/libathena-odbc-x86_64.dylib ``` 1. After you install and configure the Amazon Athena ODBC driver, use the `iodbctest` command-line tool to verify the connection, as in the following example. ``` username@ % iodbctest iODBC Demonstration program This program shows an interactive SQL processor Driver Manager: 03.52.1623.0502 Enter ODBC connect string (? shows list): ? DSN | Driver ------------------------------------------------------------------------------ athena_odbc_test | Amazon Athena ODBC (x64) Enter ODBC connect string (? shows list): DSN=athena_odbc_test; Driver: 2.0.2.1 (Amazon Athena ODBC Driver) SQL> ``` # Athena ODBC 2.x connection parameters ODBC 2.x connection parameters The **Amazon Athena ODBC Configuration** dialog box options include **Authentication Options**, **Advanced Options**, **Logging Options**, **Endpoint Overrides** and **Proxy Options**. For detailed information about each, visit the corresponding links. + [Main ODBC 2.x connection parameters](odbc-v2-driver-main-connection-parameters.md) + [Authentication options](odbc-v2-driver-authentication-options.md) + [Advanced options](odbc-v2-driver-advanced-options.md) + [Logging options](odbc-v2-driver-logging-options.md) + [Endpoint overrides](odbc-v2-driver-endpoint-overrides.md) + [Proxy options](odbc-v2-driver-proxy-options.md) # Main ODBC 2.x connection parameters Main parameters The following sections describe each of the main connection parameters. ## Data source name Specifies the name of your data source. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | DSN | Optional for DSN-less connection types | none | DSN=AmazonAthenaOdbcUsWest1; | ## Description Contains description of your data source. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | Description | Optional | none | Description=Connection to Amazon Athena us-west-1; | ## Catalog Specifies the data catalog name. For more information about catalogs, see [DataCatalog](https://docs.aws.amazon.com/athena/latest/APIReference/API_DataCatalog.html) in the Amazon Athena API Reference. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | Catalog | Optional | AwsDataCatalog | Catalog=AwsDataCatalog; | ## Region Specifies the AWS Region. For information about AWS Regions, see [Regions and Availability Zones](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AwsRegion | Mandatory | none | AwsRegion=us-west-1; | ## Database Specifies the database name. For more information about databases, see [Database](https://docs.aws.amazon.com/athena/latest/APIReference/API_Database.html) in the *Amazon Athena API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | Schema | Optional | default | Schema=default; | ## Workgroup Specifies the workgroup name. For more information about workgroups, see [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html) in the *Amazon Athena API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | Workgroup | Optional | primary | Workgroup=primary; | ## Output location Specifies the location in Amazon S3 where query results are stored. For more information about output location, see [ResultConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultConfiguration.html) in the *Amazon Athena API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | S3OutputLocation | Mandatory | none | S3OutputLocation=s3://amzn-s3-demo-bucket/; | ## Encryption options **Dialog parameter name**: Encryption options Specifies encryption option. For more information about encryption options, see [EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html) in the *Amazon Athena API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Possible values** | **Connection string example** | | --- | --- | --- | --- | --- | | S3OutputEncOption | Optional | none | NOT\$1SET, SSE\$1S3, SSE\$1KMS, CSE\$1KMS | S3OutputEncOption=SSE\$1S3; | ## KMS key Specifies a KMS key for encryption. For more information about encryption configuration for KMS Keys, see [EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html) in the *Amazon Athena API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | S3OutputEncKMSKey | Optional | none | S3OutputEncKMSKey=your\$1key; | ## Connection test ODBC Data Source Administrator provides a **Test** option that you can use to test your ODBC 2.x connection to Amazon Athena. For steps, see [Configuring a data source name on Windows](odbc-v2-driver-getting-started-windows.md#odbc-v2-driver-configuring-dsn-on-windows). When you test a connection, the ODBC driver calls the [GetWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetWorkGroup.html) Athena API action. The call uses the authentication type and corresponding credentials provider that you specified to retrieve the credentials. There is no charge for the connection test when you use the ODBC 2.x driver. The test does not generate query results in your Amazon S3 bucket. # Authentication options Authentication You can connect to Amazon Athena using the following authentication types. For all types, the connection string name is `AuthenticationType`, the parameter type is `Required`, and the default value is `IAM Credentials`. For information about the parameters for each authentication type, visit the corresponding link. For common authentication parameters, see [Common authentication parameters](odbc-v2-driver-common-authentication-parameters.md). **** | Authentication type | Connection string example | | --- | --- | | [IAM credentials](odbc-v2-driver-iam-credentials.md) | AuthenticationType=IAM Credentials; | | [IAM profile](odbc-v2-driver-iam-profile.md) | AuthenticationType=IAM Profile; | | [AD FS](odbc-v2-driver-ad-fs.md) | AuthenticationType=ADFS; | | [Azure AD](odbc-v2-driver-azure-ad.md) | AuthenticationType=AzureAD; | | [Browser Azure AD](odbc-v2-driver-browser-azure-ad.md) | AuthenticationType=BrowserAzureAD; | | [Browser SAML](odbc-v2-driver-browser-saml.md) | AuthenticationType=BrowserSAML; | | [Browser SSO OIDC](odbc-v2-driver-browser-sso-oidc.md) | AuthenticationType=BrowserSSOOIDC; | | [Default credentials](odbc-v2-driver-default-credentials.md) | AuthenticationType=Default Credentials; | | [External credentials](odbc-v2-driver-external-credentials.md) | AuthenticationType=External Credentials; | | [Instance profile](odbc-v2-driver-instance-profile.md) | AuthenticationType=Instance Profile; | | [JWT](odbc-v2-driver-jwt.md) | AuthenticationType=JWT; | | [JWT Trusted identity propagation credentials provider](odbc-v2-driver-jwt-tip.md) | AuthenticationType=JWT\$1TIP; | | [Browser trusted identity propagation credentials](odbc-v2-driver-browser-oidc-tip.md) | AuthenticationType=BrowserOidcTip; | | [Okta](odbc-v2-driver-okta.md) | AuthenticationType=Okta; | | [Ping](odbc-v2-driver-ping.md) | AuthenticationType=Ping; | # IAM credentials You can use your IAM credentials to connect to Amazon Athena with the ODBC driver using the connection string parameters described in this section. ## Authentication type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | IAM Credentials | AuthenticationType=IAM Credentials; | ## User ID Your AWS Access Key ID. For more information about access keys, see [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html)in the *IAM User Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | UID | Required | none | UID=AKIAIOSFODNN7EXAMPLE; | ## Password Your AWS secret key id. For more information about access keys, see [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html)in the *IAM User Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | PWD | Required | none | PWD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKE; | ## Session token If you use temporary AWS credentials, you must specify a session token. For information about temporary credentials, see [Temporary security credentials in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) in the *IAM User Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | SessionToken | Optional | none | SessionToken=AQoDYXdzEJr...; | # IAM profile You can configure a named profile to connect to Amazon Athena using the ODBC driver. You can use a named profile with one of the following credential sources: + `Ec2InstanceMetadata` – Retrieves credentials from the Amazon EC2 Instance Metadata Service (IMDS). Use this when running on an Amazon EC2 instance. + `EcsContainer` – Retrieves credentials from the Amazon ECS Task Role endpoint. Use this when running in an Amazon ECS container. + `Environment` – Retrieves credentials from environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`). Set the `credential_source` parameter in your AWS profile configuration to the appropriate value for your environment. If you want to use a custom credentials provider in a named profile, specify a value for the `plugin_name` parameter in your profile configuration. ## Authentication type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | IAM Credentials | AuthenticationType=IAM Profile; | ## AWS profile The profile name to use for your ODBC connection. For more information about profiles, see [Using named profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles) in the *AWS Command Line Interface User Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AWSProfile | Required | none | AWSProfile=default; | ## Preferred role The Amazon Resource Name (ARN) of the role to assume. The preferred role parameter is used when the custom credentials provider is specified by the `plugin_name` parameter in your profile configuration. For more information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | preferred\$1role | Optional | none | preferred\$1role=arn:aws:IAM::123456789012:id/user1; | ## Session duration The duration, in seconds, of the role session. For more information about session duration, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. The session duration parameter is used when the custom credentials provider is specified by the `plugin_name` parameter in your profile configuration. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | duration | Optional | 900 | duration=900; | ## Plugin name Specifies the name of a custom credentials provider used in a named profile. This parameter can take the same values as those in the **Authentication Type** field of the ODBC Data Source Administrator, but is used only by `AWSProfile` configuration. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | plugin\$1name | Optional | none | plugin\$1name=AzureAD; | # AD FS AD FS is a SAML based authentication plugin that works with the Active Directory Federation Service (AD FS) identity provider. The plugin supports [Integrated Windows authentication](https://learn.microsoft.com/en-us/aspnet/web-api/overview/security/integrated-windows-authentication) and form-based authentication. If you use Integrated Windows Authentication, you can omit the user name and password. For information about configuring AD FS and Athena, see [Configure federated access to Amazon Athena for Microsoft AD FS users using an ODBC client](odbc-adfs-saml.md). ## Authentication type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | IAM Credentials | AuthenticationType=ADFS; | ## User ID Your user name for connecting to the AD FS server. For Integrated Windows Authentication, you can omit the user name. If your AD FS setup requires a user name, you must provide it in the connection parameter. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | UID | Optional for windows integrated authentication | none | UID=domain\$1username; | ## Password Your password for connecting to the AD FS server. Like the user name field, you can omit the user name if you use Integrated Windows Authentication. If your AD FS setup requires a password, you must provide it in the connection parameter. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | PWD | Optional for windows integrated authentication | none | PWD=password\$13EXAMPLE; | ## Preferred role The Amazon Resource Name (ARN) of the role to assume. If your SAML assertion has multiple roles, you can specify this parameter to choose the role to be assumed. This role should present in the SAML assertion. For more information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | preferred\$1role | Optional | none | preferred\$1role=arn:aws:IAM::123456789012:id/user1; | ## Session duration The duration, in seconds, of the role session. For more information about session duration, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | duration | Optional | 900 | duration=900; | ## IdP host The name of the AD FS service host. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | idp\$1host | Require | none | idp\$1host=.; | ## IdP port The port to use to connect to the AD FS host. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | idp\$1port | Required | none | idp\$1port=443; | ## LoginToRP The trusted relying party. Use this parameter to override the AD FS relying party endpoint URL. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | LoginToRP | Optional | urn:amazon:webservices | LoginToRP=trustedparty; | # Azure AD Azure AD is a SAML-based authentication plugin that works with Azure AD identity provider. This plugin does not support multifactor authentication (MFA). If you require MFA support, consider using the `BrowserAzureAD` plugin instead. ## Authentication Type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | IAM Credentials | AuthenticationType=AzureAD; | ## User ID Your user name for connecting to Azure AD. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | UID | Required | none | UID=jane.doe@example.com; | ## Password Your password for connecting to Azure AD. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | PWD | Required | none | PWD=password\$13EXAMPLE; | ## Preferred role The Amazon Resource Name (ARN) of the role to assume. For information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | preferred\$1role | Optional | none | preferred\$1role=arn:aws:iam::123456789012:id/user1; | ## Session duration The duration, in seconds, of the role session. For more information, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | duration | Optional | 900 | duration=900; | ## Tenant ID Specifies your application tenant ID. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | idp\$1tenant | Required | none | idp\$1tenant=123zz112z-z12d-1z1f-11zz-f111aa111234; | ## Client ID Specifies your application client ID. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | client\$1id | Required | none | client\$1id=9178ac27-a1bc-1a2b-1a2b-a123abcd1234; | ## Client secret Specifies your client secret. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | client\$1secret | Required | none | client\$1secret=zG12q\$1.xzG1xxxZ1wX1.\$1ZzXXX1XxkHZizeT1zzZ; | # Browser Azure AD Browser Azure AD is a SAML based authentication plugin that works with Azure AD identity provider and supports multi-factor authentication. Unlike the standard Azure AD plugin, this plugin does not require a user name, password, or client secret in the connection parameters. **Note** **v2.1.0.0 security update:** Starting in v2.1.0.0, the BrowserAzureAD plugin includes PKCE (Proof Key for Code Exchange) in the OAuth 2.0 authorization flow. This prevents authorization code interception attacks on shared systems. No configuration changes are required. ## Authentication Type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | IAM Credentials | AuthenticationType=BrowserAzureAD; | ## Preferred role The Amazon Resource Name (ARN) of the role to assume. If your SAML assertion has multiple roles, you can specify this parameter to choose the role to be assumed. The role specified should be present in the SAML assertion. For more information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | preferred\$1role | Optional | none | preferred\$1role=arn:aws:IAM::123456789012:id/user1; | ## Session duration The duration, in seconds, of the role session. For more information about session duration, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | duration | Optional | 900 | duration=900; | ## Tenant ID Specifies your application tenant ID. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | idp\$1tenant | Required | none | idp\$1tenant=123zz112z-z12d-1z1f-11zz-f111aa111234; | ## Client ID Specifies your application client ID. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | client\$1id | Required | none | client\$1id=9178ac27-a1bc-1a2b-1a2b-a123abcd1234; | ## Timeout The duration, in seconds, before the plugin stops waiting for the SAML response from Azure AD. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | timeout | Optional | 120 | timeout=90; | ## Enable Azure file cache Enables a temporary credentials cache. This connection parameter enables temporary credentials to be cached and reused between multiple processes. Use this option to reduce the number of opened browser windows when you use BI tools such as Microsoft Power BI. **Note** Starting in v2.1.0.0, cached credentials are stored as plaintext JSON in the `user-profile/.athena-odbc/` directory with file permissions restricted to the owning user, consistent with how the AWS CLI protects locally stored credentials. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | browser\$1azure\$1cache | Optional | 1 | browser\$1azure\$1cache=0; | # Browser SAML Browser SAML is a generic authentication plugin that can work with SAML based identity providers and support multi-factor authentication. For detailed configuration information, see [Configure single sign-on using ODBC, SAML 2.0, and the Okta Identity Provider](okta-saml-sso.md). **Note** **v2.1.0.0 security update:** Starting in v2.1.0.0, the BrowserSAML plugin includes CSRF protection via RelayState validation. The driver generates a random state token, includes it as a RelayState parameter in the login URL, and validates it against the received response before accepting SAML assertions. ## Authentication type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | IAM Credentials | AuthenticationType=BrowserSAML; | ## Preferred role The Amazon Resource Name (ARN) of the role to assume. If your SAML assertion has multiple roles, you can specify this parameter to choose the role to be assumed. This role should be present in the SAML assertion. For more information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | preferred\$1role | Optional | none | preferred\$1role=arn:aws:IAM::123456789012:id/user1; | ## Session duration The duration, in seconds, of the role session. For more information, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | duration | Optional | 900 | duration=900; | ## Login URL The single sign-on URL that is displayed for your application. **Important** Starting in v2.1.0.0, the login URL must use HTTP or HTTPS protocol with a valid authority. The driver validates the URL format before initiating the authentication flow. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | login\$1url | Required | none | login\$1url=https://trial-1234567.okta.com/app/trial-1234567\$1oktabrowsersaml\$11/zzz4izzzAzDFBzZz1234/sso/saml; | ## Listen port The port number that is used to listen for the SAML response. This value should match the IAM Identity Center URL that you configured the IdP with (for example, `http://localhost:7890/athena`). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | listen\$1port | Optional | 7890 | listen\$1port=7890; | ## Timeout The duration, in seconds, before the plugin stops waiting for the SAML response from the identity provider. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | timeout | Optional | 120 | timeout=90; | # Browser SSO OIDC Browser SSO OIDC is an authentication plugin that works with AWS IAM Identity Center. For information on enabling and using IAM Identity Center, see [Step 1: Enable IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/get-started-enable-identity-center.html) in the *AWS IAM Identity Center User Guide*. **Note** **v2.1.0.0 security update:** Starting in version 2.1.0.0, the BrowserSSOOIDC plugin uses Authorization Code with PKCE instead of Device Code Authorization for improved security. This change eliminates the device code display step and provides faster authentication. A new `listen_port` parameter (default 7890) is used for the OAuth 2.0 callback server. You may need to allowlist this port on your network. The default scope has changed to `sso:account:access`. ## Authentication type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | IAM Credentials | AuthenticationType=BrowserSSOOIDC; | ## IAM Identity Center Start URL The URL for the AWS access portal. The IAM Identity Center [RegisterClient](https://docs.aws.amazon.com/singlesignon/latest/OIDCAPIReference/API_RegisterClient.html) API action uses this value for the `issuerUrl` parameter. **To copy the AWS access portal URL** 1. Sign in to the AWS Management Console and open the AWS IAM Identity Center console at [https://console.aws.amazon.com/singlesignon/](https://console.aws.amazon.com/singlesignon/). 1. In the navigation pane, choose **Settings**. 1. On the **Settings** page, under **Identity source**, choose the clipboard icon for **AWS access portal URL**. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | sso\$1oidc\$1start\$1url | Required | none | sso\$1oidc\$1start\$1url=https://app\$1id.awsapps.com/start; | ## IAM Identity Center Region The AWS Region where your SSO is configured. The `SSOOIDCClient` and `SSOClient` AWS SDK clients use this value for the `region` parameter. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | sso\$1oidc\$1region | Required | none | sso\$1oidc\$1region=us-east-1; | ## Scopes The list of scopes that are defined by the client. Upon authorization, this list restricts permissions when an access token is granted. The IAM Identity Center [RegisterClient](https://docs.aws.amazon.com/singlesignon/latest/OIDCAPIReference/API_RegisterClient.html) API action uses this value for the `scopes` parameter. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | sso\$1oidc\$1scopes | Optional | sso:account:access | sso\$1oidc\$1scopes=sso:account:access; | ## Account ID The identifier for the AWS account that is assigned to the user. The IAM Identity Center [GetRoleCredentials](https://docs.aws.amazon.com/singlesignon/latest/PortalAPIReference/API_GetRoleCredentials.html) API uses this value for the `accountId` parameter. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | sso\$1oidc\$1account\$1id | Required | none | sso\$1oidc\$1account\$1id=123456789123; | ## Role name The friendly name of the role that is assigned to the user. The name that you specify for this permission set appears in the AWS access portal as an available role. The IAM Identity Center [GetRoleCredentials](https://docs.aws.amazon.com/singlesignon/latest/PortalAPIReference/API_GetRoleCredentials.html) API action uses this value for the `roleName` parameter. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | sso\$1oidc\$1role\$1name | Required | none | sso\$1oidc\$1role\$1name=AthenaReadAccess; | ## Timeout The number of seconds the polling SSO API should check for the access token. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | sso\$1oidc\$1timeout | Optional | 120 | sso\$1oidc\$1timeout=60; | ## Listen port The local port number to use for the OAuth 2.0 callback server. This is used as the redirect URI and you may need to allowlist this port on your network. The default generated redirect URI is: `http://localhost:7890/athena`. This parameter was added in v2.1.0.0 as part of the migration from Device Code to Authorization Code with PKCE. **Warning** In shared environments like Windows Terminal Servers or Remote Desktop Services, the loopback port (default: 7890) is shared among all users on the same machine. System administrators can mitigate potential port hijacking risks by: Configuring different port numbers for different user groups Using Windows security policies to restrict port access Implementing network isolation between user sessions **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | listen\$1port | Optional | 7890 | listen\$1port=8080; | ## Enable file cache Enables a temporary credentials cache. This connection parameter enables temporary credentials to be cached and reused between multiple processes. Use this option to reduce the number of opened browser windows when you use BI tools such as Microsoft Power BI. **Note** Starting in v2.1.0.0, cached credentials are stored as plaintext JSON in the `user-profile/.athena-odbc/` directory with file permissions restricted to the owning user, consistent with how the AWS CLI protects locally stored credentials. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | sso\$1oidc\$1cache | Optional | 1 | sso\$1oidc\$1cache=0; | # Default credentials You can use the default credentials that you configure on your client system to connect to Amazon Athena. For information about using default credentials, see [Using the Default Credential Provider Chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default) in the *AWS SDK for Java Developer Guide*. ## Authentication type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | IAM Credentials | AuthenticationType=Default Credentials; | # External credentials External credentials is a generic authentication plugin that you can use to connect to any external SAML based identity provider. To use the plugin, you pass an executable file that returns a SAML response. ## Authentication type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | IAM Credentials | AuthenticationType=External Credentials; | ## Executable path The path to the executable that has the logic of your custom SAML-based credential provider. The output of the executable must be the parsed SAML response from the identity provider. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | ExecutablePath | Required | none | ExecutablePath=C:\$1Users\$1user\$1name\$1external\$1credential.exe | ## Argument list The list of arguments that you want to pass to the executable. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | ArgumentList | Optional | none | ArgumentList=arg1 arg2 arg3 | # Instance profile This authentication type is used on EC2 instances and is delivered through the Amazon EC2 metadata service. ## Authentication type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | IAM Credentials | AuthenticationType=Instance Profile; | # JWT The JWT (JSON Web Token) plugin provides an interface that uses JSON Web Tokens to assume an Amazon IAM role. The configuration depends on the identity provider. For information about configuring federation for Google Cloud and AWS, see [Configure workload identity federation with AWS or Azure](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds) in the Google Cloud documentation. ## Authentication type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | IAM Credentials | AuthenticationType=JWT; | ## Preferred role The Amazon Resource Name (ARN) of the role to assume. For more information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | preferred\$1role | Optional | none | preferred\$1role=arn:aws:IAM::123456789012:id/user1; | ## Session duration The duration, in seconds, of the role session. For more information about session duration, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | duration | Optional | 900 | duration=900; | ## JSON web token The JSON web token that is used to retrieve IAM temporary credentials using the [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) AWS STS API action. For information about generating JSON web tokens for Google Cloud Platform (GCP) users, see [Using JWT OAuth tokens](https://cloud.google.com/apigee/docs/api-platform/security/oauth/using-jwt-oauth) in the Google Cloud documentation. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | web\$1identity\$1token | Required | none | web\$1identity\$1token=eyJhbGc...; | ## Role session name A name for the session. A common technique is to use the name or identifier of the user of your application as the role session name. This conveniently associates the temporary security credentials that your application uses with the corresponding user. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | role\$1session\$1name | Required | none | role\$1session\$1name=familiarname; | # JWT Trusted identity propagation credentials provider JWT trusted identity propagation This authentication type allows you to use a JSON web token (JWT) obtained from an external identity provider as a connection parameter to authenticate with Athena. You can use this plugin, to enable support for corporate identities via trusted identity propagation. With trusted identity propagation, identity context is added to an IAM role to identify the user requesting access to AWS resources. For information on enabling and using trusted identity propagation, see [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html). ## Authentication type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | IAM Credentials | AuthenticationType=JWT\$1TIP; | ## JWT web identity token The JWT token obtained from an external federated identity provider. This token will be used to authenticate with Athena. Token caching is enabled by default and allows the same Identity Center access token to be used across driver connections. We recommend to provide a fresh JWT token upon "Testing Connection" as the exchanged token is present only during the duration driver instance is active. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | web\$1identity\$1token | Required | none | web\$1identity\$1token=eyJhbGc...; | ## Workgroup Arn The Amazon Resource Name (ARN) of the Amazon Athena workgroup. For more information about workgroups, see [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | WorkGroupArn | Required | none | WorkgroupArn=arn:aws:athena:us-west-2:111122223333:workgroup/primary | ## JWT application role ARN The ARN of the role to assume. This role is used for JWT exchange, getting IAM Identity Center Customer Managed application ARN through workgroup tags, and getting Access Role ARN. For more information about assuming roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | ApplicationRoleArn | Required | none | ApplicationRoleArn=arn:aws:iam::111122223333:role/applicationRole; | ## Role session name A name for the session. It can be anything you like, but typically you pass the name or identifier that's associated with the user who is using your application. That way, the temporary security credentials that your application will use are associated with that user. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | role\$1session\$1name | Required | none | role\$1session\$1name=familiarname; | ## Session duration The duration, in seconds, of the role session. For more information about session duration, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | duration | Optional | 3600 | duration=900; | ## JWT access role ARN The ARN of the role to assume. This is the role that Athena assumes to make calls on your behalf. For more information about assuming roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AccessRoleArn | Optional | none | AccessRoleArn=arn:aws:iam::111122223333:role/accessRole; | ## IAM Identity Center customer managed application ARN The ARN of IAM Identity Center customer managed IDC application. For more information about Customer Managed Applications, see [customer managed applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | CustomerIdcApplicationArn | Optional | none | CustomerIdcApplicationArn=arn:aws:sso::111122223333:application/ssoins-111122223333/apl-111122223333 | ## Enable file cache Enables a temporary credentials cache. This connection parameter allows you to cache temporary credentials and reuse it between multiple processes. Use this option to reduce the number of web identity tokens when you use BI tools such as Microsoft Power BI. By default, the driver uses `%USERPROFILE%` in Windows and `HOME` path to write the file caches. Ensure that you provide read and write access for the path present in these two environment variables, for a better experience. **Note** Starting in v2.1.0.0, cached credentials are stored as plaintext JSON in the `user-profile/.athena-odbc/` directory with file permissions restricted to the owning user, consistent with how the AWS CLI protects locally stored credentials. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | JwtTipFileCache | Optional | 0 | JwtTipFileCache=1; | # Browser trusted identity propagation credentials Browser trusted identity propagation This authentication type allows you to fetch a new JSON web token (JWT) from an external identity provider and authenticate with Athena. You can use this plugin, to enable support for corporate identities via trusted identity propagation. For more information on how to use trusted identity propagation with drivers, see [Use Trusted identity propagation with Amazon Athena drivers](using-trusted-identity-propagation.md). You can also [configure and deploy resources using CloudFormation](using-trusted-identity-propagation-cloudformation.md). With trusted identity propagation, identity context is added to an IAM role to identify the user requesting access to AWS resources. For information on enabling and using trusted identity propagation, see [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html). **Note** The plugin is specifically designed for single-user desktop environments. In shared environments like Windows Server, system administrators are responsible for establishing and maintaining security boundaries between users. ## Authentication type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | none | AuthenticationType=BrowserOidcTip; | ## IDP well known configuration URL The IDP Well Known Configuration URL is the endpoint that provides OpenID Connect configuration details for your identity provider. This URL typically ends with `.well-known/openid-configuration` and contains essential metadata about the authentication endpoints, supported features, and token signing keys. For example, if you're using *Okta*, the URL might look like `https://your-domain.okta.com/.well-known/openid-configuration`. For troubleshooting: If you receive connection errors, verify that this URL is accessible from your network and returns valid *OpenID Connect* configuration JSON. The URL must be reachable by the client where the driver is installed and should be provided by your identity provider administrator. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | IdpWellKnownConfigurationUrl | Required | none | IdpWellKnownConfigurationUrl=https:///.well-known/openid-configuration; | ## Client Identifier The client identifier issued to the application by the OpenID Connect provider. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | client\$1id | Required | none | client\$1id=00001111-aaaa-2222-bbbb-3333cccc4444; | ## Workgroup ARN The Amazon Resource Name (ARN) of the Amazon Athena workgroup that contains the trusted identity propagation configuration tags. For more information about workgroups, see [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html). **Note** This parameter is different from the `Workgroup` parameter that specifies where queries will run. You must set both parameters: `WorkgroupArn` - Points to the workgroup containing the trusted identity propagation configuration tags `Workgroup` - Specifies the workgroup where queries will execute While these typically reference the same workgroup, both parameters must be set explicitly for proper operation. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | WorkGroupArn | Required | none | WorkgroupArn=arn:aws:athena:us-west-2:111122223333:workgroup/primary | ## JWT application role ARN The ARN of the role that will be assumed in the JWT exchange. This role is used for JWT exchange, getting IAM Identity Center customer managed application ARN through workgroup tags, and getting access role ARN. For more information about assuming roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | ApplicationRoleArn | Required | none | ApplicationRoleArn=arn:aws:iam::111122223333:role/applicationRole; | ## Role session name A name for the IAM session. It can be anything you like, but typically you pass the name or identifier that's associated with the user who is using your application. That way, the temporary security credentials that your application will use are associated with that user. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | role\$1session\$1name | Required | none | role\$1session\$1name=familiarname; | ## Client secret The client secret is a confidential key issued by your identity provider that is used to authenticate your application. While this parameter is optional and may not be required for all authentication flows, it provides an additional layer of security when used. If your IDP configuration requires a client secret, you must include this parameter with the value provided by your identity provider administrator. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | client\$1secret | Optional | none | client\$1secret=s0m3R@nd0mS3cr3tV@lu3Th@tS3cur3lyPr0t3ct5Th3Cl13nt;\$1 | ## Scope The scope specifies what level of access your application is requesting from the identity provider. You must include `openid` in the scope to receive an ID token containing essential user identity claims. Your scope may need to include additional permissions like `email` or `profile`, depending on which user claims your identity provider (such as *Microsoft Entra ID*) is configured to include in the ID token. These claims are essential for proper *Trusted Identity Propagation* mapping. If user identity mapping fails, verify that your scope includes all necessary permissions and your identity provider is configured to include the required claims in the ID token. These claims must match your *Trusted Token Issuer* mapping configuration in IAM Identity Center. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | Scope | Optional | openid email offline\$1access | Scope=openid email; | ## Session duration The duration, in seconds, of the role session. For more information, see [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | duration | Optional | 3600 | duration=900; | ## JWT access role ARN The ARN of the role that Athena assumes to make calls on the behalf of you. For more information about assuming roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AccessRoleArn | Optional | none | AccessRoleArn=arn:aws:iam::111122223333:role/accessRole; | ## IAM Identity Center customer managed application ARN The ARN of IAM Identity Center customer managed IDC application. For more information about Customer Managed Applications, see [customer managed applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | CustomerIdcApplicationArn | Optional | none | CustomerIdcApplicationArn=arn:aws:sso::111122223333:application/ssoins-111122223333/apl-111122223333; | ## Identity provider port number The local port number to use for the OAuth 2.0 callback server. This is used as redirect\$1uri and you will need to allowlist this in your IDP application. The default generated redirect\$1uri is: http://localhost:7890/athena **Warning** In shared environments like Windows Terminal Servers or Remote Desktop Services, the loopback port (default: 7890) is shared among all users on the same machine. System administrators can mitigate potential port hijacking risks by: Configuring different port numbers for different user groups Using Windows security policies to restrict port access Implementing network isolation between user sessions If these security controls cannot be implemented, we recommend using the [JWT trusted identity propagation](odbc-v2-driver-jwt-tip.md) plugin instead, which doesn't require a loopback port. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | listen\$1port | Optional | 7890 | listen\$1port=8080; | ## Identity provider response timeout The timeout in seconds to wait for the OAuth 2.0 callback response. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | IdpResponseTimeout | Optional | 120 | IdpResponseTimeout=140; | ## Enable file cache The JwtTipFileCache parameter determines whether the driver caches the authentication token between connections. Setting JwtTipFileCache to true reduces authentication prompts and improves user experience, but should be used cautiously. This setting is best suited for single-user desktop environments. In shared environments like Windows Server, it's recommended to keep this disabled to prevent potential token sharing between users with similar connection strings. For enterprise deployments using tools like PowerBI Server, we recommend using the [JWT trusted identity propagation](odbc-v2-driver-jwt-tip.md) plugin instead of this authentication method. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | JwtTipFileCache | Optional | 0 | JwtTipFileCache=1; | # Okta Okta is a SAML-based authentication plugin that works with the Okta identity provider. For information about configuring federation for Okta and Amazon Athena, see [Configure SSO for ODBC using the Okta plugin and Okta Identity Provider](odbc-okta-plugin.md). ## Authentication Type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | IAM Credentials | AuthenticationType=Okta; | ## User ID Your Okta user name. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | UID | Required | none | UID=jane.doe@org.com; | ## Password Your Okta user password. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | PWD | Required | none | PWD=oktauserpasswordexample; | ## Preferred role The Amazon Resource Name (ARN) of the role to assume. For more information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | preferred\$1role | Optional | none | preferred\$1role=arn:aws:IAM::123456789012:id/user1; | ## Session duration The duration, in seconds, of the role session. For more information, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | duration | Optional | 900 | duration=900; | ## IdP host The URL for your Okta organization. You can extract the `idp_host` parameter from the **Embed Link** URL in your Okta application. For steps, see [Retrieve ODBC configuration information from Okta](odbc-okta-plugin.md#odbc-okta-plugin-retrieve-odbc-configuration-information-from-okta). The first segment after `https://`, up to and including `okta.com` is your IdP host (for example, `http://trial-1234567.okta.com`). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | idp\$1host | Required | None | idp\$1host=dev-99999999.okta.com; | ## IdP port The port number to use to connect to your IdP host. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | idp\$1port | Required | None | idp\$1port=443; | ## Okta app ID The two-part identifier for your application. You can extract the `app_id` parameter from the **Embed Link** URL in your Okta application. For steps, see [Retrieve ODBC configuration information from Okta](odbc-okta-plugin.md#odbc-okta-plugin-retrieve-odbc-configuration-information-from-okta). The application ID is the last two segments of the URL, including the forward slash in the middle. The segments are two 20-character strings with a mix of numbers and upper and lowercase letters (for example, `Abc1de2fghi3J45kL678/abc1defghij2klmNo3p4`). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | app\$1id | Required | None | app\$1id=0oa25kx8ze9A3example/alnexamplea0piaWa0g7; | ## Okta app name The name of the Okta application. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | app\$1name | Required | None | app\$1name=amazon\$1aws\$1redshift; | ## Okta wait time Specifies the duration in seconds to wait for the multifactor authentication (MFA) code. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | okta\$1mfa\$1wait\$1time | Optional | 10 | okta\$1mfa\$1wait\$1time=20; | ## Okta MFA type The MFA factor type. Supported types are Google Authenticator, SMS (Okta), Okta Verify with Push, and Okta Verify with TOTP. Individual organization security policies determine whether or not MFA is required for user login. **** | **Connection string name** | **Parameter type** | **Default value** | **Possible values** | **Connection string example** | | --- | --- | --- | --- | --- | | okta\$1mfa\$1type | Optional | None | googleauthenticator, smsauthentication, oktaverifywithpush, oktaverifywithtotp | okta\$1mfa\$1type=oktaverifywithpush; | ## Okta phone number The phone number to use with AWS SMS authentication. This parameter is required only for multifactor enrollment. If your mobile number is already enrolled, or if AWS SMS authentication is not used by the security policy, you can ignore this field. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | okta\$1mfa\$1phone\$1number | Required for MFA enrollment, optional otherwise | None | okta\$1mfa\$1phone\$1number=19991234567; | ## Enable Okta file cache Enables a temporary credentials cache. This connection parameter enables temporary credentials to be cached and reused between the multiple processes opened by BI applications. Use this option to avoid the Okta API throttling limit. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | okta\$1cache | Optional | 0 | okta\$1cache=1; | # Ping Ping is a SAML based plugin that works with the [PingFederate](https://www.pingidentity.com/en/platform/capabilities/authentication-authority/pingfederate.html) identity provider. ## Authentication type **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | AuthenticationType | Required | IAM Credentials | AuthenticationType=Ping; | ## User ID The user name for the PingFederate server. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | UID | Required | none | UID=pingusername@domain.com; | ## Password The password for the PingFederate server. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | PWD | Required | none | PWD=pingpassword; | ## Preferred role The Amazon Resource Name (ARN) of the role to assume. If your SAML assertion has multiple roles, you can specify this parameter to choose the role to be assumed. This role should be present in the SAML assertion. For more information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | preferred\$1role | Optional | none | preferred\$1role=arn:aws:iam::123456789012:id/user1; | ## Session duration The duration, in seconds, of the role session. For more information about session duration, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the *AWS Security Token Service API Reference*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | duration | Optional | 900 | duration=900; | ## IdP host The address for your Ping server. To find your address, visit the following URL and view the **SSO Application Endpoint** field. ``` https://your-pf-host-#:9999/pingfederate/your-pf-app#/spConnections ``` **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | idp\$1host | Required | none | idp\$1host=ec2-1-83-65-12.compute-1.amazonaws.com; | ## IdP port The port number to use to connect to your IdP host. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | idp\$1port | Required | None | idp\$1port=443; | ## Partner SPID The service provider address. To find the service provider address, visit the following URL and view the **SSO Application Endpoint** field. ``` https://your-pf-host-#:9999/pingfederate/your-pf-app#/spConnections ``` **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | partner\$1spid | Required | None | partner\$1spid=https://us-east-1.signin.aws.amazon.com/platform/saml/<...>; | ## Ping URI param Passes a URI argument for an authentication request to Ping. Use this parameter to bypass the Lake Formation single role limitation. Configure Ping to recognize the passed parameter, and verify that the role passed exists in the list of roles assigned to the user. Then, send a single role in the SAML assertion. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | ping\$1uri\$1param | Optional | None | ping\$1uri\$1param=role=my\$1iam\$1role; | # Common authentication parameters Common auth parameters The parameters in this section are common to the authentication types as noted. ## Use Proxy for IdP Enables communication between the driver and the IdP through the proxy. This option is available for the following authentication plugins: + AD FS + Azure AD + Browser Azure AD + Browser SSO OIDC + JWT trusted identity propagation + JWT + JWT trusted identity propagation + Browser trusted identity propagation + Okta + Ping **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | UseProxyForIdP | Optional | 0 | UseProxyForIdP=1; | ## Use Lake Formation Uses the [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API action to retrieve temporary IAM credentials instead of the [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API action. This option is available for the Azure AD, Browser Azure AD, Browser SAML, Okta, Ping, and AD FS authentication plugins. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | LakeformationEnabled | Optional | 0 | LakeformationEnabled=1; | ## SSL insecure (IdP) Disables SSL when communicating with the IdP. This option is available for the Azure AD, Browser Azure AD, Okta, Ping, and AD FS authentication plugins. **Important** **Breaking change in v2.1.0.0:** The default behavior for SSL certificate validation when connecting to identity providers has changed. In versions before 2.1.0.0, SSL validation was disabled by default. Starting in v2.1.0.0, SSL validation is enabled by default for all IdP connections. The driver also enforces TLS 1.2 as the minimum TLS version. If you use a local identity provider without a valid SSL certificate (for testing purposes only), set `SSL_Insecure=1` in your connection string. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | SSL\$1Insecure | Optional | 0 | SSL\$1Insecure=1; | # Endpoint overrides Endpoints ## Athena endpoint override The `endpointOverride ClientConfiguration` class uses this value override the default HTTP endpoint for the Amazon Athena client. For more information, see [AWS Client configuration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html) in the *AWS SDK for C\$1\$1 Developer Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | EndpointOverride | Optional | none | EndpointOverride=athena.us-west-2.amazonaws.com; | ## Athena streaming endpoint override The `ClientConfiguration.endpointOverride` method uses this value to override the default HTTP endpoint for the Amazon Athena streaming client. For more information, [AWS Client configuration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html) in the *AWS SDK for C\$1\$1 Developer Guide*. The Athena Streaming service is available through port 444. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | StreamingEndpointOverride | Optional | none | StreamingEndpointOverride=athena.us-west-1.amazonaws.com:444; | ## AWS STS endpoint override The `ClientConfiguration.endpointOverride` method uses this value to override the default HTTP endpoint for the AWS STS client. For more information, see [AWS Client configuration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html) in the *AWS SDK for C\$1\$1 Developer Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | StsEndpointOverride | Optional | none | StsEndpointOverride=sts.us-west-1.amazonaws.com; | ## Lake Formation endpoint override The `ClientConfiguration.endpointOverride` method uses this value to override the default HTTP endpoint for the Lake Formation client. For more information, see [AWS Client configuration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html) in the *AWS SDK for C\$1\$1 Developer Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | LakeFormationEndpointOverride | Optional | none | LakeFormationEndpointOverride=lakeformation.us-west-1.amazonaws.com; | ## SSO endpoint override The `ClientConfiguration.endpointOverride` method uses this value to override the default HTTP endpoint for the SSO client. For more information, see [AWS Client configuration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html) in the *AWS SDK for C\$1\$1 Developer Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | SSOEndpointOverride | Optional | none | SSOEndpointOverride=portal.sso.us-east-2.amazonaws.com; | ## SSO OIDC endpoint override The `ClientConfiguration.endpointOverride` method uses this value to override the default HTTP endpoint for the SSO OIDC client. For more information, see [AWS Client configuration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html) in the *AWS SDK for C\$1\$1 Developer Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | SSOOIDCEndpointOverride | Optional | none | SSOOIDCEndpointOverride=oidc.us-east-2.amazonaws.com | ## SSO Admin endpoint override The `ClientConfiguration.endpointOverride` method uses this value to override the default HTTP endpoint for SSO Admin client. For more information, see [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | SSOAdminEndpointOverride | Optional | none | SSOAdminEndpointOverride=sso.us-east-2.amazonaws.com | ## S3 endpoint override The `ClientConfiguration.endpointOverride` method uses this value to override the default HTTP endpoint for S3 client. The endpoint that the driver will use to download query results when it uses the Amazon S3 fetcher. If this parameter is not specified, the driver uses a default Amazon S3 endpoint. For more information, see [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | S3EndpointOverride | Optional | none | S3EndpointOverride=s3.us-east-2.amazonaws.com | # Advanced options Advanced ## Fetch size The maximum number of results (rows) to return in this request. For parameter information, see [GetQuery MaxResults](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetQueryResults.html#athena-GetQueryResults-request-MaxResults). For the streaming API, the maximum value is 10000000. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | RowsToFetchPerBlock | Optional | `1000` for non-streaming `20000` for streaming | RowsToFetchPerBlock=20000; | ## Result fetcher The default result fetcher downloads query results directly from Amazon S3 without going through the Athena API operations. When it detects situations where direct S3 download is not possible, it automatically falls back to using the `GetQueryResultsStream` API operation. For example, this happens when query results are encrypted with the `CSE_KMS` option. Using the `auto` fetcher is recommended in most situations. However, if your IAM policies, or S3 bucket policies use the `s3:CalledVia` condition to limit access to S3 objects to requests from Athena, the auto fetcher first attempts to download the results from S3 and then falls back to using the `GetQueryResultsStream`. In this situation, you might want to set the `ResultFetcher` to `GetQueryResultsStream` to avoid an extra API call. **Note** The driver still recognizes the Enable streaming API (`UseResultsetStreaming=1;`) and Enable S3 fetcher (`EnableS3Fetcher=1;`) parameters. However, we encourage you to use `ResultFetcher` parameter for better experience. **** | **Connection string name** | **Parameter type** | **Default value** | **Possible values** | **Connection string example** | | --- | --- | --- | --- | --- | | ResultFetcher | Optional | auto | auto, S3, GetQueryResults, GetQueryResultsStream | ResultFetcher=auto | ## Enable result reuse Specifies if previous query results can be reused when the query is run. For parameter information, see ResultReuseByAgeConfiguration. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | EnableResultReuse | Optional | 0 | EnableResultReuse=1; | ## Result reuse maximum age Specifies, in minutes, the maximum age of a previous query result that Athena should consider for reuse. For parameter information, see [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | ReusedResultMaxAgeInMinutes | Optional | 60 | ReusedResultMaxAgeInMinutes=90; | ## Use multiple S3 threads Fetches data from Amazon S3 using multiple threads. When this option is enabled, the result file stored in the Amazon S3 bucket is fetched in parallel using multiple threads. Enable this option only if you have good network bandwidth. For example, in our measurements on an EC2 [c5.2xlarge](https://aws.amazon.com/ec2/instance-types/c5/) instance, a single-threaded S3 client reached 1 Gbps, while multiple-threaded S3 clients reached 4 Gbps of network throughput. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | UseMultipleS3Threads | Optional | 0 | UseMultipleS3Threads=1; | ## Use single catalog and schema By default, the ODBC driver queries Athena to get the list of available catalogs and schemas. This option forces the driver to use the catalog and schema specified by the ODBC Data Source Administrator configuration dialog box or connection parameters. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | UseSingleCatalogAndSchema | Optional | 0 | UseSingleCatalogAndSchema=1; | ## Use query to list tables For `LAMBDA` catalog types, enables the ODBC driver to submit a [SHOW TABLES](show-tables.md) query to get a list of available tables. This setting is the default. If this parameter is set to 0, the ODBC driver uses the Athena [ListTableMetadata](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListTableMetadata.html) API to get a list of available tables. Note that, for `LAMBDA` catalog types, using `ListTableMetadata` leads to performance regression. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | UseQueryToListTables | Optional | 1 | UseQueryToListTables=1; | ## Use WCHAR for string types By default, the ODBC driver uses `SQL_CHAR` and `SQL_VARCHAR` for Athena the string data types `char`, `varchar`, `string`, `array`, `map<>`, `struct<>`, and `row`. Setting this parameter to `1` forces the driver to use `SQL_WCHAR` and `SQL_WVARCHAR` for string data types. Wide character and wide variable character types are used to ensure that characters from different languages can be stored and retrieved correctly. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | UseWCharForStringTypes | Optional | 0 | UseWCharForStringTypes=1; | ## Query external catalogs Specifies if the driver needs to query external catalogs from Athena. For more information, see [Migrate to the ODBC 2.x driver](odbc-v2-driver-migrating.md). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | QueryExternalCatalogs | Optional | 0 | QueryExternalCatalogs=1; | ## Verify SSL Controls whether to verify SSL certificates when you use the AWS SDK. This value is passed to `ClientConfiguration.verifySSL` parameter. For more information, see [AWS Client configuration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html) in the *AWS SDK for C\$1\$1 Developer Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | VerifySSL | Optional | 1 | VerifySSL=0; | ## S3 result block size Specifies, in bytes, the size of the block to download for a single Amazon S3 [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) API request. The default value is 67108864 (64 MB). The minimum and maximum values allowed are 10485760 (10 MB) and 2146435072 (about 2 GB). **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | S3ResultBlockSize | Optional | 67108864 | S3ResultBlockSize=268435456; | ## String column length Specifies the column length for columns with the `string` data type. Because Athena uses the [Apache Hive string data type](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Types#LanguageManualTypes-StringsstringStrings), which does not have defined precision, the default length reported by Athena is 2147483647 (`INT_MAX`). Because BI tools usually pre-allocate memory for columns, this can lead to high memory consumption. To avoid this, the Athena ODBC driver limits the reported precision for columns of the `string` data type and exposes the `StringColumnLength` connection parameter so that the default value can be changed. **** | Connection string name | Parameter type | Default value | Connection string example | | --- | --- | --- | --- | | StringColumnLength | Optional | 255 | StringColumnLength=65535; | ## Complex type column length Specifies the column length for columns with complex data types like `map`, `struct`, and `array`. Like [StringColumnLength](#odbc-v2-driver-advanced-options-string-column-length), Athena reports 0 precision for columns with complex data types. The Athena ODBC driver sets the default precision for columns with complex data types and exposes the `ComplexTypeColumnLength` connection parameter so that the default value can be changed. **** | Connection string name | Parameter type | Default value | Connection string example | | --- | --- | --- | --- | | ComplexTypeColumnLength | Optional | 65535 | ComplexTypeColumnLength=123456; | ## Trusted CA certificate Instructs the HTTP client where to find your SSL certificate trust store. This value is passed to the `ClientConfiguration.caFile` parameter. For more information, see [AWS Client configuration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html) in the *AWS SDK for C\$1\$1 Developer Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | TrustedCerts | Optional | %INSTALL\$1PATH%/bin | TrustedCerts=C:\$1\$1Program Files\$1\$1Amazon Athena ODBC Driver\$1\$1bin\$1\$1cacert.pem; | ## Min poll period Specifies the minimum value in milliseconds to wait before polling Athena for query execution status. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | MinQueryExecutionPollingInterval | Optional | 100 | MinQueryExecutionPollingInterval=200; | ## Max poll period Specifies the maximum value in milliseconds to wait before polling Athena for the query execution status. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | MaxQueryExecutionPollingInterval | Optional | 60000 | MaxQueryExecutionPollingInterval=1000; | ## Poll multiplier Specifies the factor for increasing the poll period. By default, polling begins with the value of min poll period and doubles with each poll until it reaches the value of max poll period. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | QueryExecutionPollingIntervalMultiplier | Optional | 2 | QueryExecutionPollingIntervalMultiplier=2; | ## Max poll duration Specifies the maximum value in milliseconds that a driver can poll Athena for query execution status. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | MaxPollDuration | Optional | 1800000 | MaxPollDuration=1800000; | ## Connection timeout The amount of time (in milliseconds) that the HTTP connection waits to establish a connection. This value is set for `ClientConfiguration.connectTimeoutMs` Athena client. If not specified, the curl default value is used. For information about connection parameters, see [Client Configuration](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/section-client-configuration.html) in the *AWS SDK for Java Developer Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | ConnectionTimeout | Optional | 0 | ConnectionTimeout=2000; | ## Request timeout Specifies the socket read timeout for HTTP clients. This value is set for the `ClientConfiguration.requestTimeoutMs` parameter of the Athena client. For parameter information, see [Client Configuration](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/section-client-configuration.html) in the *AWS SDK for Java Developer Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | RequestTimeout | Optional | 10000 | RequestTimeout=30000; | # Proxy options Proxy ## Proxy host If you require users to go through a proxy, use this parameter to set the proxy host. This parameter corresponds to the `ClientConfiguration.proxyHost` parameter in the AWS SDK. For more information, see [AWS Client configuration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html) in the *AWS SDK for C\$1\$1 Developer Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | ProxyHost | Optional | none | ProxyHost=127.0.0.1; | ## Proxy port Use this parameter to set the proxy port. This parameter corresponds to the `ClientConfiguration.proxyPort` parameter in the AWS SDK. For more information, see [AWS Client configuration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html) in the *AWS SDK for C\$1\$1 Developer Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | ProxyPort | Optional | none | ProxyPort=8888; | ## Proxy user name Use this parameter to set the proxy user name. This parameter corresponds to the `ClientConfiguration.proxyUserName` parameter in the AWS SDK. For more information, see [AWS Client configuration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html) in the *AWS SDK for C\$1\$1 Developer Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | ProxyUID | Optional | none | ProxyUID=username; | ## Proxy password Use this parameter to set the proxy password. This parameter corresponds to the `ClientConfiguration.proxyPassword` parameter in the AWS SDK. For more information, see [AWS Client configuration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html) in the *AWS SDK for C\$1\$1 Developer Guide*. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | ProxyPWD | Optional | none | ProxyPWD=password; | ## Non proxy host Use this optional parameter to specify a host that the driver connects to without using a proxy. This parameter corresponds to the `ClientConfiguration.nonProxyHosts` parameter in the AWS SDK. For more information, see [AWS Client configuration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html) in the *AWS SDK for C\$1\$1 Developer Guide*. The `NonProxyHost` connection parameter is passed to the `CURLOPT_NOPROXY` curl option. For information about the `CURLOPT_NOPROXY` format, see [CURLOPT\$1NOPROXY](https://curl.se/libcurl/c/CURLOPT_NOPROXY.html) in the curl documentation. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | NonProxyHost | Optional | none | NonProxyHost=.amazonaws.com,localhost,.example.net,.example.com; | ## Use proxy Enables user traffic through the specified proxy. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | UseProxy | Optional | none | UseProxy=1; | # Logging options Logging **Warning** **Security:** When logging is enabled at verbose levels (DEBUG or TRACE), the AWS SDK used by the driver may log sensitive information such as authentication tokens and credentials in plaintext. Use verbose logging only for troubleshooting, and ensure log files are stored securely and deleted after use. Do not enable verbose logging in production environments. Administrator rights are required to modify the settings described here. To make the changes, you can use the ODBC Data Source Administrator **Logging Options** dialog box or modify the Windows registry directly. ## Log level This option enables ODBC driver logs with different levels of detail. In Windows, you can use the registry or a dialog box to configure logging. The option is located in the following registry path: ``` Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Amazon Athena\ODBC\Driver ``` The following log levels are available: + `OFF` - Logging is disabled + `ERROR` - Only error messages are logged + `WARN` - Warning messages and errors are logged + `INFO` - Informational messages, warnings, and errors are logged + `DEBUG` - Detailed debug information plus all lower level messages are logged + `TRACE` - Most detailed level of logging, includes all messages **Note** Each log level includes all messages from the levels below it. Higher log levels may impact performance and generate larger log files. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | LogLevel | Optional | OFF | LogLevel=INFO; | ## Log path Specifies path to the file where the ODBC driver logs are stored. You can use the registry or a dialog box to set this value. The option is located in the following registry path: ``` Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Amazon Athena\ODBC\Driver ``` **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | LogPath | Optional | none | LogPath=C:\$1Users\$1username\$1projects\$1internal\$1trunk\$1; | ## Use AWS Logger Specifies if AWS SDK logging is enabled. Specify 1 to enable, 0 to disable. **** | **Connection string name** | **Parameter type** | **Default value** | **Connection string example** | | --- | --- | --- | --- | | UseAwsLogger | Optional | 0 | UseAwsLogger=0; | **Note** Logs may log sensitive information when `UseAwsLogger` is enabled and `LogLevel` is set to `DEBUG` or `TRACE`. `UseAwsLogger` is recommended only for troubleshooting purposes. # Migrate to the ODBC 2.x driver Migrate to ODBC 2.x Because most Athena ODBC 2.x connection parameters are backwardly compatible with the ODBC 1.x driver, you can reuse most of your existing connection string with the Athena ODBC 2.x driver. However, the following connection parameters require modifications. ## Log level While the current ODBC driver provides a range of available logging options, starting from `LOG_OFF (0)` to `LOG_TRACE (6)`, the Amazon Athena ODBC 2.x driver initially had only two values: 0 (disabled) and 1 (enabled). Starting with version 2.0.6.0, the driver now supports more granular logging levels with enhanced logging capabilities: + `OFF` - Logging is disabled + `ERROR` - Only error messages are logged + `WARN` - Warning messages and errors are logged + `INFO` - Informational messages, warnings, and errors are logged + `DEBUG` - Detailed debug information plus all lower level messages are logged + `TRACE` - Most detailed level of logging, includes all messages For more information about logging the ODBC 2.x driver, see [Logging options](odbc-v2-driver-logging-options.md). **** | | ODBC 1.x driver | ODBC 2.x driver | | --- | --- | --- | | Connection string name | LogLevel | LogLevel | | Parameter type | Optional | Optional | | Default value | 0 | OFF | | Possible values | 0-6 | For versions before 2.0.6.0: `0,1` For version 2.0.6.0 and later: `OFF`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE` | | Connection string example | LogLevel=6; | LogLevel=INFO; | **Note** In version 2.0.6.0 and later, the logging framework has been optimized to reduce operational delays and excessive log file generation, while providing more detailed diagnostic information through these granular log levels. Each level includes all messages from the levels below it. ## MetadataRetrievalMethod The current ODBC driver provides several options for retrieving the metadata from Athena. The Amazon Athena ODBC driver deprecates the `MetadataRetrievalMethod` and always uses the Amazon Athena API to extract metadata. Athena introduces the flag `QueryExternalCatalogs` for querying external catalogs. To query external catalogs with the current ODBC driver, set `MetadataRetrievalMethod` to `ProxyAPI`. To query external catalogs with the Athena ODBC driver, set `QueryExternalCatalogs` to `1`. **** | | ODBC 1.x driver | ODBC 2.x driver | | --- | --- | --- | | Connection string name | MetadataRetrievalMethod | QueryExternalCatalogs | | Parameter type | Optional | Optional | | Default value | Auto | 0 | | Possible values | Auto, AWS Glue, ProxyAPI, Query | 0,1 | | Connection string example | MetadataRetrievalMethod=ProxyAPI; | QueryExternalCatalogs=1; | ## Connection test When you test an ODBC 1.x driver connection, the driver runs a `SELECT 1` query that generates two files in your Amazon S3 bucket: one for the result set, and one for the metadata. The test connection is charged according to the [Amazon Athena Pricing](https://aws.amazon.com/athena/pricing/) policy. When you test an ODBC 2.x driver connection, the driver calls the [GetWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetWorkGroup.html) Athena API action. The call uses the authentication type and corresponding credentials provider that you specified to retrieve the credentials. There is no charge for the connection test when you use the ODBC 2.x driver, and the test does not generate query results in your Amazon S3 bucket. # Troubleshoot the ODBC 2.x driver Troubleshoot ODBC 2.x If you encounter issues with the Amazon Athena ODBC driver, you can contact Support (in the AWS Management Console, choose **Support**, **Support Center**). Be sure to include the following information, and provide any additional details that will help the support team understand your use case. + **Description** – (Required) A description that includes detailed information about your use case and the difference between the expected and observed behavior. Include any information that can help support engineers navigate the issue easily. If the issue is intermittent, specify the dates, timestamps, or interval points at which the issue occurred. + **Version information** – (Required) Information about the driver version, the operating system, and the applications that you used. For example, "ODBC driver version 1.2.3, Windows 10 (x64), Power BI." + **Log files** – (Required) The minimum number of ODBC driver log files that are required to understand the issue. For information about logging options for the ODBC 2.x driver, see [Logging options](odbc-v2-driver-logging-options.md). + **Connection string** – (Required) Your ODBC connection string or a screen shot of the dialog box that shows the connection parameters that you used. For information about connection parameters, see [Athena ODBC 2.x connection parameters](odbc-v2-driver-connection-parameters.md). + **Issue steps** – (Optional) If possible, include steps or a standalone program that can help reproduce the issue. + **Query error information** – (Optional) If you have errors that involve DML or DDL queries, include the following information: + A full or simplified version of the failed DML or DDL query. + The account ID and AWS Region used, and the query execution ID. + **SAML errors** – (Optional) If you have an issue related to authentication with SAML assertion, include the following information: + The identity provider and authentication plugin that was used. + An example with the SAML token. # Amazon Athena ODBC 2.x release notes ODBC 2.x release notes These release notes provide details of enhancements, features, known issues, and workflow changes in the Amazon Athena ODBC 2.x driver. ## 2.1.0.0 Released 2026-03-20 The Amazon Athena The Amazon Athena ODBC v2.1.0.0 driver includes security improvements. This release enhances authentication flows, query processing, and transport security. We recommend upgrading to this version as soon as possible. ### Breaking changes + **SSL certificate validation enabled by default** – The driver now enforces SSL certificate verification when connecting to identity providers. If you use a local identity provider without a valid SSL certificate, you must explicitly set `SSL_Insecure=1` in your connection string. For more information, see [SSL insecure (IdP)](odbc-v2-driver-common-authentication-parameters.md#odbc-v2-driver-common-authentication-parameters-ssl-insecure-idp). + **TLS 1.2 minimum enforced** – The driver no longer accepts TLS 1.0 or TLS 1.1 connections to identity providers. All IdP connections now require TLS 1.2 or later. + **BrowserSSOOIDC authentication flow updated** – The BrowserSSOOIDC plugin now uses Authorization Code with PKCE instead of Device Code Authorization. A new optional parameter `listen_port` (default 7890) is available for the OAuth 2.0 callback server. You may need to allowlist this port on your network. The default scope has changed to `sso:account:access`. For more information, see [Browser SSO OIDC](odbc-v2-driver-browser-sso-oidc.md). ### Improvements + **BrowserSSOOIDC** – Migrated from Device Code flow to Authorization Code with PKCE for improved security. + **BrowserAzureAD** – Added PKCE (Proof Key for Code Exchange) to the OAuth 2.0 authorization flow to prevent authorization code interception attacks. + **BrowserSAML** – Added RelayState CSRF protection to prevent SAML token injection attacks. + **Credentials cache** – Starting in v2.1.0.0, cached credentials are stored as plaintext JSON in the `user-profile/.athena-odbc/` directory with file permissions restricted to the owning user, consistent with how the AWS CLI protects locally stored credentials. + **IAM Profile** – Added support for `EcsContainer` and `Environment` credential sources in addition to the existing `Ec2InstanceMetadata`. + **Connection string parser** – Implemented proper ODBC `}}` escape handling. + **Catalog queries** – Added SQL identifier escaping for schema names and table patterns. + **ODBC pattern matching** – Replaced regex-based matching with direct ODBC LIKE wildcard matcher. + **XML parsing** – Added recursion depth limit (100 levels) and size limit (1MB) for SAML tokens. + **ADFS authentication** – Added response size limit (200KB) for ADFS server responses. ### Fixes + Fixed improper neutralization of special elements in authentication components that could allow code execution or authentication flow redirection via crafted connection parameters. Affects BrowserSSOOIDC, BrowserAzureAD, and BrowserSAML plugins. + Fixed improper neutralization of special elements in query processing components that could allow denial of service or SQL injection via crafted table metadata. + Fixed improper certificate validation when connecting to identity providers. + Fixed missing authentication security controls in browser-based authentication flows, including PKCE for OAuth, CSRF protection for SAML, secure credential caching, and exclusive callback port binding. + Fixed uncontrolled resource consumption in parsing components that could allow denial of service via crafted input patterns, unbounded server responses, or deeply nested XML payloads. + Fixed an issue where `SQLColumns` and `SQLTables` returned no results when using `UseSingleCatalogAndSchema=1` with cross-account federated catalogs in Power BI Import mode. To download the new ODBC v2 driver, see [ODBC 2.x driver download](odbc-v2-driver.md#odbc-v2-driver-download). For connection information, see [Amazon Athena ODBC 2.x](odbc-v2-driver.md). ## 2.0.6.0 Released 2025-11-21 ### Improvements + **Browser Trusted Identity Propagation authentication plugin** – Added a new authentication plugin to support browser-based OpenID Connect (OIDC) authentication with trusted identity propagation. This plugin provides a seamless authentication experience by handling the complete OAuth 2.0 flow through your default browser, automatically fetching the JSON Web Token (JWT), and integrating with trusted identity propagation. The plugin is specifically designed for single-user desktop environments. For information on enabling and using trusted identity propagation, see [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html). + **Enhanced logging framework** – Significantly improved the driver's logging mechanism by: + Introducing more granular log levels beyond basic 0/1 options + Removing redundant log statements + Optimizing the logging framework to include diagnostically relevant information + Addressing performance issues that were causing operational delays + Reducing excessive log file generation when logging is enabled ### Fixes + **Result fetcher optimization** – Fixed an issue where fetch size parameter limitations were incorrectly applied to both streaming and non-streaming result fetchers. The limitation is now correctly applied only to non-streaming result fetchers. To download the new ODBC v2 driver, see [ODBC 2.x driver download](odbc-v2-driver.md#odbc-v2-driver-download). For connection information, see [Amazon Athena ODBC 2.x](odbc-v2-driver.md). ## 2.0.5.1 Released 2025-10-13 ### Fixes The Amazon Athena ODBC v2.0.5.1 driver contains the following fixes to browser-based authentication plugins. + Implemented validation for login URL and schema checking. + Improved browser launch mechanism on Linux to utilize system APIs, resulting in improved stability and security. To download the new ODBC v2 driver, see [ODBC 2.x driver download](odbc-v2-driver.md#odbc-v2-driver-download). For connection information, see [Amazon Athena ODBC 2.x](odbc-v2-driver.md). ## 2.0.5.0 Released 2025-09-10 ### Improvements + **JWT Trusted Identity Provider (TIP) authentication plugin** – Added a new authentication plugin to support JWT Trusted Identity Provider (TIP) integration with ODBC drivers. This authentication type allows you to use a JSON web token (JWT) obtained from an external identity provider as a connection parameter to authenticate with Athena. With TIP, identity context is added to an IAM role to identify the user requesting access to AWS resources. For information on enabling and using TIP, see [What is Trusted Identity Propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html). + **Custom SSO admin endpoints support** – Added support for custom SSO Admin endpoints in the ODBC driver. This enhancement allows you to specify your own endpoints for SSO services when running ODBC behind VPCs. + **AWS SDK version update** – We have updated the AWS SDK version used in the driver to 2.32.16 and have updated the project dependencies for release 2.0.5.0. ## 2.0.4.0 Released 2025-06-17 The Amazon Athena ODBC v2.0.4.0 driver contains the following improvements and fixes. ### Improvements + **Result Fetcher** – The driver now automatically selects the method to download query results. This removes the need to manually configure the fetcher in most situations. For more information, see [Result fetcher](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-result-fetcher). + Curl Library has been updated to 8.12.1. ### Fixes + Fixed proxy configuration for IAM profile when connecting to STS. The fix allows IAM Profile to be used for successful authentication. + Read all additional configuration options for IAM profile with authentication plugins. This includes `UseProxyForIdP`, `SSL_Insecure`, `LakeformationEnabled`, and `LoginToRP` to resolve misconfigurations for the affected plugins. + Fixed round function by allowing it to take in an optional 2nd parameter. It successfully processes queries containing the escape syntax. + Fixed column size for `TIME WITH TIME ZONE` and `TIMESTAMP WITH TIME ZONE` data types. Values with timestamp and timezone data type will not get truncated. To download the new ODBC v2 driver, see [ODBC 2.x driver download](odbc-v2-driver.md#odbc-v2-driver-download). For connection information, see [Amazon Athena ODBC 2.x](odbc-v2-driver.md). ## 2.0.3.0 Released 2024-04-08 The Amazon Athena ODBC v2.0.3.0 driver contains the following improvements and fixes. ### Improvements + Added MFA support for the Okta authentication plugin on Linux and Mac platforms. + Both the `athena-odbc.dll` library and the `AmazonAthenaODBC-2.x.x.x.msi` installer for Windows are now signed. + Updated the CA certificate `cacert.pem` file that is installed with the driver. + Improved the time required to list tables under Lambda catalogs. For `LAMBDA` catalog types, the ODBC driver can now submit a [SHOW TABLES](show-tables.md) query to get a list of available tables. For more information, see [Use query to list tables](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-use-query-to-list-tables). + Introduced the `UseWCharForStringTypes` connection parameter to report string data types using `SQL_WCHAR` and `SQL_WVARCHAR`. For more information, see [Use WCHAR for string types](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-use-wchar-for-string-types). ### Fixes + Fixed a registry corruption warning that occurred when the Get-OdbcDsn PowerShell tool was used. + Updated the parsing logic to handle comments at the start of query strings. + Date and timestamp data types now allow zero in the year field. To download the new ODBC v2 driver, see [ODBC 2.x driver download](odbc-v2-driver.md#odbc-v2-driver-download). For connection information, see [Amazon Athena ODBC 2.x](odbc-v2-driver.md). ## 2.0.2.2 Released 2024-02-13 The Amazon Athena ODBC v2.0.2.2 driver contains the following improvements and fixes. ### Improvements + Added two connection parameters, `StringColumnLength` and `ComplexTypeColumnLength`, that you can use to change the default column length for string and complex data types. For more information, see [String column length](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-string-column-length) and [Complex type column length](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-complex-type-column-length). + Support has been added for the Linux and macOS (Intel and ARM) operating systems. For more information, see [Linux](odbc-v2-driver-getting-started-linux.md) and [macOS](odbc-v2-driver-getting-started-macos.md). + AWS-SDK-CPP has been updated to the 1.11.245 tag version. + The curl library has been updated to the 8.6.0 version. ### Fixes + Resolved an issue that cause incorrect values to be reported in result-set metadata for string-like data types in the precision column. To download the ODBC v2 driver, see [ODBC 2.x driver download](odbc-v2-driver.md#odbc-v2-driver-download). For connection information, see [Amazon Athena ODBC 2.x](odbc-v2-driver.md). ## 2.0.2.1 Released 2023-12-07 The Amazon Athena ODBC v2.0.2.1 driver contains the following improvements and fixes. ### Improvements + Improved ODBC driver thread safety for all interfaces. + When logging is enabled, datetime values are now recorded with millisecond precision. + During authentication with the [Browser SSO OIDC](odbc-v2-driver-browser-sso-oidc.md) plugin, the terminal now opens to display the device code to the user. ### Fixes + Resolved a memory release issue that occurred when parsing results from the streaming API. + Requests for the interfaces `SQLTablePrivileges()`, `SQLSpecialColumns()`, `SQLProcedureColumns()`, and `SQLProcedures()` now return empty result sets. To download the ODBC v2 driver, see [ODBC 2.x driver download](odbc-v2-driver.md#odbc-v2-driver-download). For connection information, see [Amazon Athena ODBC 2.x](odbc-v2-driver.md). ## 2.0.2.0 Released 2023-10-17 The Amazon Athena ODBC v2.0.2.0 driver contains the following improvements and fixes. ### Improvements + File cache feature added for the Browser Azure AD, Browser SSO OIDC, and Okta browser-based authentication plugins. BI Tools like Power BI and browser-based plugins use multiple browser windows. The new file cache connection parameter enables temporary credentials to be cached and reused between the multiple processes opened by BI applications. + Applications can now query information about the result set after a statement is prepared. + Default connection and request timeouts have been increased for use with slower client networks. For more information, see [Connection timeout](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-connection-timeout) and [Request timeout](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-request-timeout). + Endpoint overrides have been added for SSO and SSO OIDC. For more information, see [Endpoint overrides](odbc-v2-driver-endpoint-overrides.md). + Added a connection parameter to pass a URI argument for an authentication request to Ping. You can use this parameter to bypass the Lake Formation single role limitation. For more information, see [Ping URI param](odbc-v2-driver-ping.md#odbc-v2-driver-ping-uri-param). ### Fixes + Fixed an integer overflow issue that occurred when using the row-based binding mechanism. + Removed timeout from the list of required connection parameters for the Browser SSO OIDC authentication plugin. + Added missing interfaces for `SQLStatistics()`, `SQLPrimaryKeys()`, `SQLForeignKeys()`, and `SQLColumnPrivileges()`, and added the ability to return empty result sets upon request. To download the new ODBC v2 driver, see [ODBC 2.x driver download](odbc-v2-driver.md#odbc-v2-driver-download). For connection information, see [Amazon Athena ODBC 2.x](odbc-v2-driver.md). ## 2.0.1.1 Released 2023-08-10 The Amazon Athena ODBC v2.0.1.1 driver contains the following improvements and fixes. ### Improvements + Added URI logging to the Okta authentication plugin. + Added the preferred role parameter to the external credentials provider plugin. + Adding handling for the profile prefix in the profile name of AWS configuration file. ### Fixes + Corrected a AWS Region use issue that occurred when working with Lake Formation and AWS STS clients. + Restored missing partition keys to the list of table columns. + Added the missing `BrowserSSOOIDC` authentication type to the AWS profile. To download the new ODBC v2 driver, see [ODBC 2.x driver download](odbc-v2-driver.md#odbc-v2-driver-download). ## 2.0.1.0 Released 2023-06-29 Amazon Athena releases the ODBC v2.0.1.0 driver. Athena has released a new ODBC driver that improves the experience of connecting to, querying, and visualizing data from compatible SQL development and business intelligence applications. The latest version of the Athena ODBC driver supports the features of the existing driver and is straightforward to upgrade. The new version includes support for authenticating users through [AWS IAM Identity Center](https://aws.amazon.com/iam/identity-center/). It also offers the option to read query results from Amazon S3, which can make query results available to you sooner. For more information, see [Amazon Athena ODBC 2.x](odbc-v2-driver.md). # Athena ODBC 1.x driver ODBC 1.x You can use an ODBC connection to connect to Athena from third-party SQL client tools and applications. Use the links on this page to download the Amazon Athena 1.x ODBC driver License Agreement, ODBC drivers, and ODBC documentation. For information about the ODBC connection string, see the ODBC Driver Installation and Configuration Guide PDF file, downloadable from this page. For permissions information, see [Control access through JDBC and ODBC connections](policy-actions.md). **Important** When you use the ODBC 1.x driver, be sure to note the following requirements: **Open port 444** – Keep port 444, which Athena uses to stream query results, open to outbound traffic. When you use a PrivateLink endpoint to connect to Athena, ensure that the security group attached to the PrivateLink endpoint is open to inbound traffic on port 444. **athena:GetQueryResultsStream policy** – Add the `athena:GetQueryResultsStream` policy action to the IAM principals that use the ODBC driver. This policy action is not exposed directly with the API. It is used only with the ODBC and JDBC drivers as part of streaming results support. For an example policy, see [AWS managed policy: AWSQuicksightAthenaAccess](security-iam-awsmanpol.md#awsquicksightathenaaccess-managed-policy). ## Windows | Driver version | Download link | | --- | --- | | ODBC 1.2.3.1000 for Windows 32-bit | [Windows 32 bit ODBC driver 1.2.3.1000](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/SimbaAthenaODBC_1.2.3.1000/Windows/SimbaAthena_1.2.3.1000_32-bit.msi) | | ODBC 1.2.3.1000 for Windows 64-bit | [Windows 64 bit ODBC driver 1.2.3.1000](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/SimbaAthenaODBC_1.2.3.1000/Windows/SimbaAthena_1.2.3.1000_64-bit.msi) | ## Linux | Driver version | Download link | | --- | --- | | ODBC 1.2.3.1000 for Linux 32-bit | [Linux 32 bit ODBC driver 1.2.3.1000](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/SimbaAthenaODBC_1.2.3.1000/Linux/simbaathena-1.2.3.1000-1.el7.i686.rpm) | | ODBC 1.2.3.1000 for Linux 64-bit | [Linux 64 bit ODBC driver 1.2.3.1000](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/SimbaAthenaODBC_1.2.3.1000/Linux/simbaathena-1.2.3.1000-1.el7.x86_64.rpm) | ## OSX | Driver version | Download link | | --- | --- | | ODBC 1.2.3.1000 for OSX | [OSX ODBC driver 1.2.3.1000](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/SimbaAthenaODBC_1.2.3.1000/OSX/SimbaAthena_1.2.3.1000.dmg) | ## Documentation | Content | Documentation link | | --- | --- | | Amazon Athena ODBC driver license agreement | [License agreement](https://downloads.athena.us-east-1.amazonaws.com/agreement/ODBC/Amazon+Athena+ODBC+Driver+License+Agreement.pdf) | | Documentation for ODBC 1.2.3.1000 | [ODBC driver installation and configuration guide version 1.2.3.1000](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/SimbaAthenaODBC_1.2.3.1000/docs/Simba+Amazon+Athena+ODBC+Connector+Install+and+Configuration+Guide.pdf) | | Release Notes for ODBC 1.2.3.1000 | [ODBC driver release notes version 1.2.3.1000](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/SimbaAthenaODBC_1.2.3.1000/docs/release-notes.txt) | ## ODBC driver notes **Connecting Without Using a Proxy** If you want to specify certain hosts that the driver connects to without using a proxy, you can use the optional `NonProxyHost` property in your ODBC connection string. The `NonProxyHost` property specifies a comma-separated list of hosts that the connector can access without going through the proxy server when a proxy connection is enabled, as in the following example: ``` .amazonaws.com,localhost,.example.net,.example.com ``` The `NonProxyHost` connection parameter is passed to the `CURLOPT_NOPROXY` curl option. For information about the `CURLOPT_NOPROXY` format, see [CURLOPT\$1NOPROXY](https://curl.se/libcurl/c/CURLOPT_NOPROXY.html) in the curl documentation. # Configure federated access to Amazon Athena for Microsoft AD FS users using an ODBC client AD FS access using ODBC To set up federated access to Amazon Athena for Microsoft Active Directory Federation Services (AD FS) users using an ODBC client, you first establish trust between AD FS and your AWS account. With this trust in place, your AD users can [federate](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml.html#CreatingSAML-configuring-IdP) into AWS using their AD credentials and assume permissions of an [AWS Identity and Access Management](https://aws.amazon.com/iam/) (IAM) role to access AWS resources such as the Athena API. To create this trust, you add AD FS as a SAML provider to your AWS account and create an IAM role that federated users can assume. On the AD FS side, you add AWS as a relying party and write SAML claim rules to send the right user attributes to AWS for authorization (specifically, Athena and Amazon S3). Configuring AD FS access to Athena involves the following major steps: [1. Setting up an IAM SAML provider and role](#odbc-adfs-saml-setting-up-an-iam-saml-provider-and-role) [2. Configuring AD FS](#odbc-adfs-saml-configuring-ad-fs) [3. Creating Active Directory users and groups](#odbc-adfs-saml-creating-active-directory-users-and-groups) [4. Configuring the AD FS ODBC connection to Athena](#odbc-adfs-saml-configuring-the-ad-fs-odbc-connection-to-athena) ## 1. Setting up an IAM SAML provider and role In this section, you add AD FS as a SAML provider to your AWS account and create an IAM role that your federated users can assume. **To set up a SAML provider** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Identity providers**. 1. Choose **Add provider**. 1. For **Provider type**, choose **SAML**. ![\[Choose SAML.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-1.png) 1. For **Provider name**, enter **adfs-saml-provider**. 1. In a browser, enter the following address to download the federation XML file for your AD FS server. To perform this step, your browser must have access to the AD FS server. ``` https://adfs-server-name/federationmetadata/2007-06/federationmetadata.xml ``` 1. In the IAM console, for **Metadata document**, choose **Choose file**, and then upload the federation metadata file to AWS. 1. To finish, choose **Add provider**. Next, you create the IAM role that your federated users can assume. **To create an IAM role for federated users** 1. In the IAM console navigation pane, choose **Roles**. 1. Choose **Create role**. 1. For **Trusted entity type**, choose **SAML 2.0 federation**. 1. For **SAML 2.0-based provider**, choose the **adfs-saml-provider** provider that you created. 1. Choose **Allow programmatic and AWS Management Console access**, and then choose **Next**. ![\[Choosing SAML as the trusted entity type.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-2.png) 1. On the **Add permissions** page, filter for the IAM permissions policies that you require for this role, and then select the corresponding check boxes. This tutorial attaches the `AmazonAthenaFullAccess` and `AmazonS3FullAccess` policies. ![\[Attaching the Athena full access policy to the role.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-3.png) ![\[Attaching the Amazon S3 full access policy to the role.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-4.png) 1. Choose **Next**. 1. On the **Name, review, and create** page, for **Role name**, enter a name for the role. This tutorial uses the name **adfs-data-access**. In **Step 1: Select trusted entities**, the **Principal** field should be automatically populated with `"Federated:" "arn:aws:iam::account_id:saml-provider/adfs-saml-provider"`. The `Condition` field should contain `"SAML:aud"` and `"https://signin.aws.amazon.com/saml"`. ![\[Trusted entities JSON.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-5.png) **Step 2: Add permissions** shows the policies that you have attached to the role. ![\[List of policies attached to the role.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-6.png) 1. Choose **Create role**. A banner message confirms creation of the role. 1. On the **Roles** page, choose the name of the role that you just created. The summary page for the role shows the policies that have been attached. ![\[Summary page for the role.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-7.png) ## 2. Configuring AD FS Now you are ready to add AWS as a relying party and write SAML claim rules so that you can send the right user attributes to AWS for authorization. SAML-based federation has two participant parties: the IdP (Active Directory) and the relying party (AWS), which is the service or application that uses authentication from the IdP. To configure AD FS, you first add a relying party trust, then you configure SAML claim rules for the relying party. AD FS uses claim rules to form a SAML assertion that is sent to a relying party. The SAML assertion states that the information about the AD user is true, and that it has authenticated the user. ### Adding a relying party trust To add a relying party trust in AD FS, you use the AD FS server manager. **To add a relying party trust in AD FS** 1. Sign in to the AD FS server. 1. On the **Start** menu, open **Server Manager**. 1. Choose **Tools**, and then choose **AD FS Management**. ![\[Choose Tools, AD FS Management.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-8.png) 1. In the navigation pane, under **Trust Relationships**, choose **Relying Party Trusts**. 1. Under **Actions**, choose **Add Relying Party Trust**. ![\[Choose Add Relying Party Trust.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-9.png) 1. On the **Add Relying Party Trust Wizard** page, choose **Start**. ![\[Choose Start.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-10.png) 1. On the **Select Data Source** screen, select the option **Import data about the relying party published online or on a local network**. 1. For **Federation metadata address (host name or URL)**, enter the URL ** https://signin.aws.amazon.com/static/saml-metadata.xml** 1. Choose **Next.** ![\[Configuring the data source.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-11.png) 1. On the **Specify Display Name** page, for **Display name**, enter a display name for your relying party, and then choose **Next**. ![\[Enter a display name for the relying party.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-12.png) 1. On the **Configure Multi-factor Authentication Now** page, this tutorial selects **I do not want to configure multi-factor authentication for this relying party trust at this time**. For increased security, we recommend that you configure multi-factor authentication to help protect your AWS resources. Because it uses a sample dataset, this tutorial doesn't enable multi-factor authentication. ![\[Configuring multi-factor authentication.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-13.png) 1. Choose **Next**. 1. On the **Choose Issuance Authorization Rules** page, select **Permit all users to access this relying party**. This option allows all users in Active Directory to use AD FS with AWS as a relying party. You should consider your security requirements and adjust this configuration accordingly. ![\[Configuring user access to the relying party.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-14.png) 1. Choose **Next**. 1. On the **Ready to Add Trust** page, choose **Next** to add the relying party trust to the AD FS configuration database. ![\[Choose Next.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-15.png) 1. On the **Finish** page, choose **Close**. ![\[Choose Close.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-16.png) ### Configuring SAML claim rules for the relying party In this task, you create two sets of claim rules. The first set, rules 1–4, contains AD FS claim rules that are required to assume an IAM role based on AD group membership. These are the same rules that you create if you want to establish federated access to the [AWS Management Console](http://aws.amazon.com/console). The second set, rules 5–6, are claim rules required for Athena access control. **To create AD FS claim rules** 1. In the AD FS Management console navigation pane, choose **Trust Relationships**, **Relying Party Trusts**. 1. Find the relying party that you created in the previous section. 1. Right-click the relying party and choose **Edit Claim Rules**, or choose **Edit Claim Rules** from the **Actions** menu. ![\[Choose Edit Claim Rules.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-17.png) 1. Choose **Add Rule.** 1. On the **Configure Rule** page of the Add Transform Claim Rule Wizard, enter the following information to create claim rule 1, and then choose **Finish**. + For **Claim Rule name**, enter **NameID**. + For **Rule template**, use **Transform an Incoming Claim**. + For **Incoming claim type**, choose **Windows account name**. + For **Outgoing claim type**, choose **Name ID**. + For **Outgoing name ID format**, choose **Persistent Identifier**. + Select **Pass through all claim values**. ![\[Create the first claim rule.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-18.png) 1. Choose **Add Rule**, and then enter the following information to create claim rule 2, and then choose **Finish**. + For **Claim rule name**, enter **RoleSessionName**. + For **Rule template**, use **Send LDAP Attribute as Claims**. + For **Attribute store**, choose **Active Directory**. + For **Mapping of LDAP attributes to outgoing claim types**, add the attribute **E-Mail-Addresses**. For the **Outgoing Claim Type**, enter ** https://aws.amazon.com/SAML/Attributes/RoleSessionName**. ![\[Create the second claim rule.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-19.png) 1. Choose **Add Rule**, and then enter the following information to create claim rule 3, and then choose **Finish**. + For **Claim rule name**, enter **Get AD Groups**. + For **Rule template**, use **Send Claims Using a Custom Rule**. + For **Custom rule**, enter the following code: ``` c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]=> add(store = "Active Directory", types = ("http://temp/variable"), query = ";tokenGroups;{0}", param = c.Value); ``` ![\[Create the third claim rule.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-20.png) 1. Choose **Add Rule**. Enter the following information to create claim rule 4, and then choose **Finish**. + For **Claim rule name**, enter **Role**. + For **Rule template**, use **Send Claims Using a Custom Rule**. + For **Custom rule**, enter the following code with your account number and name of the SAML provider that you created earlier: ``` c:[Type == "http://temp/variable", Value =~ "(?i)^aws-"]=> issue(Type = "https://aws.amazon.com/SAML/Attributes/Role", Value = RegExReplace(c.Value, "aws-", "arn:aws:iam::AWS_ACCOUNT_NUMBER:saml-provider/adfs-saml-provider,arn:aws:iam:: AWS_ACCOUNT_NUMBER:role/")); ``` ![\[Create the fourth claim rule.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-21.png) ## 3. Creating Active Directory users and groups Now you are ready to create AD users that will access Athena, and AD groups to place them in so that you can control levels of access by group. After you create AD groups that categorize patterns of data access, you add your users to those groups. **To create AD users for access to Athena** 1. On the Server Manager dashboard, choose **Tools**, and then choose **Active Directory Users and Computers**. ![\[Choose Tools, Active Directory Users and Computers.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-22.png) 1. In the navigation pane, choose **Users**. 1. On the **Active Directory Users and Computers** tool bar, choose the **Create user** option. ![\[Choose Create user.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-23.png) 1. In the **New Object – User** dialog box, for **First name**, **Last name**, and **Full name**, enter a name. This tutorial uses **Jane Doe**. ![\[Enter a user name.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-24.png) 1. Choose **Next**. 1. For **Password**, enter a password, and then retype to confirm. For simplicity, this tutorial deselects **User must change password at next sign on**. In real-world scenarios, you should require newly created users to change their password. ![\[Enter a password.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-25.png) 1. Choose **Next**. 1. Choose **Finish.** ![\[Choose Finish.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-26.png) 1. In **Active Directory Users and Computers**, choose the user name. 1. In the **Properties** dialog box for the user, for **E-mail**, enter an email address. This tutorial uses **jane@example.com**. ![\[Enter an email address.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-27.png) 1. Choose **OK**. ### Create AD groups to represent data access patterns You can create AD groups whose members assume the `adfs-data-access` IAM role when they log in to AWS. The following example creates an AD group called aws-adfs-data-access. **To create an AD group** 1. On the Server Manager Dashboard, from the **Tools** menu, choose **Active Directory Users and Computers.** 1. On the tool bar, choose the **Create new group** option. ![\[Choose Create new group.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-28.png) 1. In the **New Object - Group** dialog box, enter the following information: + For **Group name**, enter **aws-adfs-data-access**. + For **Group scope**, select **Global**. + For **Group type**, select **Security**. ![\[Creating a global security group in AD.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-29.png) 1. Choose **OK**. ### Add AD users to appropriate groups Now that you have created both an AD user and an AD group, you can add the user to the group. **To add an AD user to an AD group** 1. On the Server Manager Dashboard, on the **Tools** menu, choose **Active Directory Users and Computers**. 1. For **First name** and **Last name**, choose a user (for example, **Jane Doe**). 1. In the **Properties** dialog box for the user, on the **Member Of** tab, choose **Add**. ![\[Choose Add.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-30.png) 1. Add one or more AD FS groups according to your requirements. This tutorial adds the **aws-adfs-data-access** group. 1. In the **Select Groups** dialog box, for **Enter the object names to select**, enter the name of the AD FS group that you created (for example, **aws-adfs-data-access**), and then choose **Check Names**. ![\[Choose Check Names.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-31.png) 1. Choose **OK**. In the **Properties** dialog box for the user, the name of the AD group appears in the **Member of** list. ![\[AD group added to user properties.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-32.png) 1. Choose **Apply**, then choose **OK**. ## 4. Configuring the AD FS ODBC connection to Athena After you have created your AD users and groups, you are ready to use the ODBC Data Sources program in Windows to configure your Athena ODBC connection for AD FS. **To configure the AD FS ODBC connection to Athena** 1. Install the ODBC driver for Athena. For download links, see [Connect to Amazon Athena with ODBC](connect-with-odbc.md). 1. In Windows, choose **Start**, **ODBC Data Sources**. 1. In the **ODBC Data Source Administrator** program, choose **Add**. ![\[Choose Add to add an ODBC data source.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-33.png) 1. In the **Create New Data Source** dialog box, choose **Simba Athena ODBC Driver**, and then choose **Finish**. ![\[Choose Simba Athena ODBC Driver.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-34.png) 1. In the **Simba Athena ODBC Driver DSN Setup** dialog box, enter the following values: + For **Data Source Name,** enter a name for your data source (for example, ** Athena-odbc-test**). + For **Description**, enter a description for your data source. + For **AWS Region**, enter the AWS Region that you are using (for example, ** us-west-1**). + For **S3 Output Location**, enter the Amazon S3 path where you want your output to be stored. ![\[Entering values for Simba Athena ODBC Driver DSN Setup.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-35.png) 1. Choose **Authentication Options**. 1. In the **Authentication Options** dialog box, specify the following values: + For **Authentication Type**, choose **ADFS**. + For **User,** enter the user's email address (for example, **jane@example.com**). + For **Password**, enter the user's ADFS password. + For **IdP Host**, enter the AD FS server name (for example, **adfs.example.com**). + For **IdP Port**, use the default value **443**. + Select the **SSL Insecure** option. ![\[Configuring authentication options.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-adfs-saml-37.png) 1. Choose **OK** to close **Authentication Options**. 1. Choose **Test** to test the connection, or **OK** to finish. # Configure SSO for ODBC using the Okta plugin and Okta Identity Provider SSO for ODBC and Okta This page describes how to configure the Amazon Athena ODBC driver and Okta plugin to add single sign-on (SSO) capability using the Okta identity provider. ## Prerequisites Completing the steps in this tutorial requires the following: + Amazon Athena ODBC driver. For download links, see [Connect to Amazon Athena with ODBC](connect-with-odbc.md). + An IAM Role that you want to use with SAML. For more information, see [Creating a role for SAML 2.0 federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html) in the *IAM User Guide*. + An Okta account. For information, visit [Okta.com](https://www.okta.com/). ## Creating an app integration in Okta First, use the Okta dashboard to create and configure a SAML 2.0 app for single sign-on to Athena. You can use an existing Redshift application in Okta to configure access to Athena. **To create an app integration in Okta** 1. Log in to the admin page for your account on [Okta.com](https://www.okta.com/). 1. In the navigation panel, choose **Applications**, **Applications.** 1. On the **Applications** page, choose **Browse App Catalog.** 1. On the **Browse App Integration Catalog** page, in the **Use Case** section, choose **All Integrations**. 1. In the search box, enter **Amazon Web Services Redshift**, and then choose **Amazon Web Services Redshift SAML**. 1. Choose **Add Integration**. ![\[Choose Add integration.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-1.png) 1. In the **General Settings Required** section, for **Application label**, enter a name for the application. This tutorial uses the name **Athena-ODBC-Okta.** ![\[Enter a name for the Okta application.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-2.png) 1. Choose **Done**. 1. On the page for your Okta application (for example, **Athena-ODBC-Okta**), choose **Sign On**. ![\[Choose the Sign On tab.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-3.png) 1. In the **Settings** section, choose **Edit**. ![\[Choose Edit.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-4.png) 1. In the **Advanced Sign-on Settings** section, configure the following values. + For **IdP ARN and Role ARN**, enter your AWS IDP ARN and Role ARN as comma-separated values. For information about the IAM role format, see [Configuring SAML assertions for the authentication response](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html) in the *IAM User Guide*. + For **Session Duration**, enter a value between 900 and 43200 seconds. This tutorial uses the default of 3600 (1 hour). ![\[Enter advanced sign-on settings.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-5.png) The **DbUser Format**, **AutoCreate**, and **Allowed DBGroups** settings aren't used by Athena. You don't have to configure them. 1. Choose **Save**. ## Retrieve ODBC configuration information from Okta Now that you created the Okta application, you're ready to retrieve the application's ID and IdP host URL. You will require these later when you configure ODBC for connection to Athena. **To retrieve configuration information for ODBC from Okta** 1. Choose the **General** tab of your Okta application, and then scroll down to the **App Embed Link** section. ![\[The embed link URL of the Okta application.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-6.png) Your **Embed Link** URL is in the following format: ``` https://trial-1234567.okta.com/home/amazon_aws_redshift/Abc1de2fghi3J45kL678/abc1defghij2klmNo3p4 ``` 1. From your **Embed Link** URL, extract and save the following pieces: + The first segment after `https://`, up to and including `okta.com` (for example, **trial-1234567.okta.com**). This is your IdP host. + The last two segments of the URL, including the forward slash in the middle. The segments are two 20-character strings with a mix of numbers and upper and lowercase letters (for example, **Abc1de2fghi3J45kL678/abc1defghij2klmNo3p4**). This is your application ID. ## Add a user to the Okta application Now you're ready to add a user to your Okta application. **To add a user to the Okta application** 1. In the left navigation pane, choose **Directory**, and then choose **People**. 1. Choose **Add person**. ![\[Choose Add person.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-7.png) 1. In the **Add Person** dialog box, enter the following information. + Enter values for **First name** and **Last name**. This tutorial uses **test user**. + Enter values for **Username** and **Primary email**. This tutorial uses **test@amazon.com** for both. Your security requirements for passwords might vary. ![\[Enter user credentials.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-8.png) 1. Choose **Save**. Now you're ready to assign the user that you created to your application. **To assign the user to your application:** 1. In the navigation pane, choose **Applications**, **Applications**, and then choose the name of your application (for example, **Athena-ODBC-Okta**). 1. Choose **Assign,** and then choose **Assign to People**. ![\[Choose Assign to People.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-9.png) 1. Choose the **Assign** option for your user, and then choose **Done**. ![\[Choose Assign, and then choose Done.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-10.png) 1. At the prompt, choose **Save and Go Back**. The dialog box shows the user's status as **Assigned**. 1. Choose **Done**. 1. Choose the **Sign On** tab. 1. Scroll down to the **SAML Signing Certificates** section. 1. Choose **Actions**. 1. Open the context (right-click) menu for **View IdP metadata**, and then choose the browser option to save the file. 1. Save the file with an `.xml` extension. ![\[Saving IdP metadata to a local XML file.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-11.png) ## Create an AWS SAML Identity Provider and Role Now you are ready to upload the metadata XML file to the IAM console in AWS. You will use this file to create an AWS SAML identity provider and role. Use an AWS Services administrator account to perform these steps. **To create a SAML identity provider and role in AWS** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/IAM/](https://console.aws.amazon.com/IAM/). 1. In the navigation pane, choose **Identity providers**, and then choose **Add provider**. ![\[Choose Add provider.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-12.png) 1. On the **Add an Identity provider** page, for **Configure provider**, enter the following information. + For **Provider type**, choose **SAML**. + For **Provider name**, enter a name for your provider (for example, ** AthenaODBCOkta**). + For **Metadata document**, use the **Choose file** option to upload the identity provider (IdP) metadata XML file that you downloaded. ![\[Enter information for the identity provider.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-13.png) 1. Choose **Add provider**. ### Creating an IAM role for Athena and Amazon S3 access Now you are ready to create an IAM role for Athena and Amazon S3 access. You will assign this role to your user. That way, you can provide the user with single sign-on access to Athena. **To create an IAM role for your user** 1. In the IAM console navigation pane, choose **Roles**, and then choose **Create role**. ![\[Choose Create role.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-14.png) 1. On the **Create role** page, choose the following options: + For **Select type of trusted entity**, choose **SAML 2.0 Federation.** + For **SAML 2.0–based provider**, choose the SAML identity provider that you created (for example, **AthenaODBCOkta**). + Select **Allow programmatic and AWS Management Console access**. ![\[Choose options on the Create role page.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-15.png) 1. Choose **Next**. 1. On the **Add Permissions** page, for **Filter policies**, enter **AthenaFull**, and then press ENTER. 1. Select the `AmazonAthenaFullAccess` managed policy, and then choose **Next**. ![\[Choose the AmazonAthenaFullAccess managed policy.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-16.png) 1. On the **Name, review, and create** page, for **Role name**, enter a name for the role (for example, **Athena-ODBC-OktaRole**), and then choose **Create role**. ## Configuring the Okta ODBC connection to Athena Now you're ready to configure the Okta ODBC connection to Athena using the ODBC Data Sources program in Windows. **To configure your Okta ODBC connection to Athena** 1. In Windows, launch the **ODBC Data Sources** program. 1. In the **ODBC Data Source Administrator** program, choose **Add**. ![\[Choose Add.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-17.png) 1. Choose **Simba Athena ODBC Driver**, and then choose **Finish**. ![\[Choose the Athena ODBC driver.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-18.png) 1. In the **Simba Athena ODBC Driver DSN Setup** dialog, enter the values described. + For **Data Source Name,** enter a name for your data source (for example, **Athena ODBC 64**). + For **Description**, enter a description for your data source. + For **AWS Region**, enter the AWS Region that you're using (for example, **us-west-1**). + For **S3 Output Location**, enter the Amazon S3 path where you want your output to be stored. ![\[Enter values for the data source name setup.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-19.png) 1. Choose **Authentication Options**. 1. In the **Authentication Options** dialog box, choose or enter the following values. + For **Authentication Type**, choose **Okta**. + For **User**, enter your Okta user name. + For **Password**, enter your Okta password. + For **IdP Host**, enter the value that you recorded earlier (for example, **trial-1234567.okta.com**). + For **IdP Port**, enter **443**. + For **App ID**, enter the value that you recorded earlier (the last two segments of your Okta embed link). + For **Okta App Name**, enter **amazon\$1aws\$1redshift**. ![\[Enter the authentication options.\]](http://docs.aws.amazon.com/athena/latest/ug/images/odbc-okta-plugin-20.png) 1. Choose **OK**. 1. Choose **Test** to test the connection or **OK** to finish. # Configure single sign-on using ODBC, SAML 2.0, and the Okta Identity Provider SSO using ODBC, SAML 2.0, and Okta To connect to data sources, you can use Amazon Athena with identity providers (IdPs) like PingOne, Okta, OneLogin, and others. Starting with Athena ODBC driver version 1.1.13 and Athena JDBC driver version 2.0.25, a browser SAML plugin is included that you can configure to work with any SAML 2.0 provider. This topic shows you how to configure the Amazon Athena ODBC driver and the browser-based SAML plugin to add single sign-on (SSO) capability using the Okta identity provider. ## Prerequisites Completing the steps in this tutorial requires the following: + Athena ODBC driver version 1.1.13 or later. Versions 1.1.13 and later include browser SAML support. For download links, see [Connecting to Amazon Athena with ODBC](https://docs.aws.amazon.com/athena/latest/ug/connect-with-odbc.html). + An IAM Role that you want to use with SAML. For more information, see [Creating a role for SAML 2.0 federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html) in the *IAM User Guide*. + An Okta account. For information, visit [okta.com](https://www.okta.com/). ## Creating an app integration in Okta First, use the Okta dashboard to create and configure a SAML 2.0 app for single sign-on to Athena. **To use the Okta dashboard to set up single sign-on for Athena** 1. Login to the Okta admin page on `okta.com`. 1. In the navigation pane, choose **Applications**, **Applications**. 1. On the **Applications** page, choose **Create App Integration**. ![\[Choose Create App Integration.\]](http://docs.aws.amazon.com/athena/latest/ug/images/okta-saml-sso-1.png) 1. In the **Create a new app integration** dialog box, for **Sign-in method**, select **SAML 2.0**, and then choose **Next**. ![\[Choose SAML 2.0\]](http://docs.aws.amazon.com/athena/latest/ug/images/okta-saml-sso-2.png) 1. On the **Create SAML Integration** page, in the **General Settings** section, enter a name for the application. This tutorial uses the name **Athena SSO**. ![\[Enter a name for the Okta application.\]](http://docs.aws.amazon.com/athena/latest/ug/images/okta-saml-sso-3.png) 1. Choose **Next**. 1. On the **Configure SAML** page, in the **SAML Settings** section, enter the following values: + For **Single sign on URL**, enter **http://localhost:7890/athena** + For **Audience URI**, enter **urn:amazon:webservices** ![\[Enter SAML settings.\]](http://docs.aws.amazon.com/athena/latest/ug/images/okta-saml-sso-4.png) 1. For **Attribute Statements (optional)**, enter the following two name/value pairs. These are required mapping attributes. + For **Name**, enter the following URL: **https://aws.amazon.com/SAML/Attributes/Role** For **Value**, enter the name of your IAM role. For information about the IAM role format, see [Configuring SAML assertions for the authentication response](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html) in the *IAM User Guide*. + For **Name**, enter the following URL: **https://aws.amazon.com/SAML/Attributes/RoleSessionName** For **Value**, enter **user.email**. ![\[Enter SAML attributes for Athena.\]](http://docs.aws.amazon.com/athena/latest/ug/images/okta-saml-sso-5.png) 1. Choose **Next**, and then choose **Finish**. When Okta creates the application, it also creates your login URL, which you will retrieve next. ## Getting the login URL from the Okta dashboard Now that your application has been created, you can obtain its login URL and other metadata from the Okta dashboard. **To get the login URL from the Okta dashboard** 1. In the Okta navigation pane, choose **Applications**, **Applications**. 1. Choose the application for which you want to find the login URL (for example, **AthenaSSO**). 1. On the page for your application, choose **Sign On**. ![\[Choose Sign On.\]](http://docs.aws.amazon.com/athena/latest/ug/images/okta-saml-sso-6.png) 1. Choose **View Setup Instructions**. ![\[Choose View Setup Instructions.\]](http://docs.aws.amazon.com/athena/latest/ug/images/okta-saml-sso-7.png) 1. On the **How to Configure SAML 2.0 for Athena SSO** page, find the URL for **Identity Provider Issuer**. Some places in the Okta dashboard refer to this URL as the **SAML issuer ID**. ![\[The value for Identity Provider Issuer.\]](http://docs.aws.amazon.com/athena/latest/ug/images/okta-saml-sso-8.png) 1. Copy or store the value for **Identity Provider Single Sign-On URL**. In the next section, when you configure the ODBC connection, you will provide this value as the **Login URL** connection parameter for the browser SAML plugin. ## Configuring the browser SAML ODBC connection to Athena Now you are ready to configure the browser SAML connection to Athena using the ODBC Data Sources program in Windows. **To configure the browser SAML ODBC connection to Athena** 1. In Windows, launch the **ODBC Data Sources** program. 1. In the **ODBC Data Source Administrator** program, choose **Add**. ![\[Choose Add.\]](http://docs.aws.amazon.com/athena/latest/ug/images/okta-saml-sso-9.png) 1. Choose **Simba Athena ODBC Driver**, and then choose **Finish**. ![\[Choose Simba Athena Driver\]](http://docs.aws.amazon.com/athena/latest/ug/images/okta-saml-sso-10.png) 1. In the **Simba Athena ODBC Driver DSN Setup** dialog, enter the values described. ![\[Enter the DSN setup values.\]](http://docs.aws.amazon.com/athena/latest/ug/images/okta-saml-sso-11.png) + For **Data Source Name,** enter a name for your data source (for example, **Athena ODBC 64**). + For **Description**, enter a description for your data source. + For **AWS Region**, enter the AWS Region that you are using (for example, **us-west-1**). + For **S3 Output Location**, enter the Amazon S3 path where you want your output to be stored. 1. Choose **Authentication Options**. 1. In the **Authentication Options** dialog box, choose or enter the following values. ![\[Enter authentication options.\]](http://docs.aws.amazon.com/athena/latest/ug/images/okta-saml-sso-12.png) + For **Authentication Type**, choose **BrowserSAML**. + For **Login URL**, enter the **Identity Provider Single Sign-On URL** that you obtained from the Okta dashboard. + For **Listen Port**, enter **7890**. + For **Timeout (sec)**, enter a connection timeout value in seconds. 1. Choose **OK** to close **Authentication Options**. 1. Choose **Test** to test the connection, or **OK** to finish. # Use the Amazon Athena Power BI connector Use the Power BI connector On Windows operating systems, you can use the Microsoft Power BI connector for Amazon Athena to analyze data from Amazon Athena in Microsoft Power BI Desktop. For information about Power BI, see [Microsoft power BI](https://powerbi.microsoft.com/). After you publish content to the Power BI service, you can use the July 2021 or later release of [Power BI gateway](https://powerbi.microsoft.com/gateway/) to keep the content up to date through on-demand or scheduled refreshes. ## Prerequisites Before you begin, make sure that your environment meets the following requirements. The Amazon Athena ODBC driver is required. + [AWS account](https://aws.amazon.com/) + [Permissions to use Athena](policy-actions.md) + [Amazon Athena ODBC driver](connect-with-odbc.md) + [Power BI desktop](https://powerbi.microsoft.com/en-us/desktop/) ## Capabilities supported + **Import** – Selected tables and columns are imported into Power BI Desktop for querying. + **DirectQuery** – No data is imported or copied into Power BI Desktop. Power BI Desktop queries the underlying data source directly. + **Power BI gateway** – An on-premises data gateway in your AWS account that works like a bridge between the Microsoft Power BI Service and Athena. The gateway is required to see your data on the Microsoft Power BI Service. ## Connect to Amazon Athena To connect Power BI desktop to your Amazon Athena data, perform the following steps. **To connect to Athena data from power BI desktop** 1. Launch Power BI Desktop. 1. Do one of the following: + Choose **File**, **Get Data** + From the **Home** ribbon, choose **Get Data**. 1. In the search box, enter **Athena**. 1. Select **Amazon Athena**, and then choose **Connect**. ![\[Choose the Amazon Athena connector\]](http://docs.aws.amazon.com/athena/latest/ug/images/connect-with-odbc-and-power-bi-1.png) 1. On the **Amazon Athena** connection page, enter the following information. + For **DSN**, enter the name of the ODBC DSN that you want to use. For instructions on configuring your DSN, see the [ODBC driver documentation](connect-with-odbc-driver-and-documentation-download-links.md#connect-with-odbc-driver-documentation). + For **Data Connectivity mode**, choose a mode that is appropriate for your use case, following these general guidelines: + For smaller datasets, choose **Import**. When using Import mode, Power BI works with Athena to import the contents of the entire dataset for use in your visualizations. + For larger datasets, choose **DirectQuery**. In DirectQuery mode, no data is downloaded to your workstation. While you create or interact with a visualization, Microsoft Power BI works with Athena to dynamically query the underlying data source so that you're always viewing current data. For more information about DirectQuery, see [Use DirectQuery in power BI desktop](https://docs.microsoft.com/power-bi/connect-data/desktop-use-directquery) in the Microsoft documentation. ![\[Enter your data connectivity information\]](http://docs.aws.amazon.com/athena/latest/ug/images/connect-with-odbc-and-power-bi-2.png) 1. Choose **OK**. 1. At the prompt to configure data source authentication, choose either **Use Data Source Configuration** or **AAD Authentication**, and then choose **Connect**. ![\[Choose a data source authentication method\]](http://docs.aws.amazon.com/athena/latest/ug/images/connect-with-odbc-and-power-bi-3.png) Your data catalog, databases, and tables appear in the **Navigator** dialog box. ![\[The Navigator displays your data\]](http://docs.aws.amazon.com/athena/latest/ug/images/connect-with-odbc-and-power-bi-4.png) 1. In the **Display Options** pane, select the check box for the dataset that you want to use. 1. If you want to transform the dataset before you import it, go to the bottom of the dialog box and choose **Transform Data**. This opens the Power Query Editor so that you can filter and refine the set of data you want to use. 1. Choose **Load**. After the load is complete, you can create visualizations like the one in the following image. If you selected **DirectQuery** as the import mode, Power BI issues a query to Athena for the visualization that you requested. ![\[A sample data visualization\]](http://docs.aws.amazon.com/athena/latest/ug/images/connect-with-odbc-and-power-bi-5.png) ## Setting up an on-premises gateway You can publish dashboards and datasets to the Power BI service so that other users can interact with them through web, mobile, and embedded apps. To see your data in the Microsoft Power BI Service, you install the Microsoft Power BI on-premises data gateway in your AWS account. The gateway works like a bridge between the Microsoft Power BI Service and Athena. **To download, install, and test an on-premises data gateway** 1. Visit the [Microsoft power BI gateway download](https://powerbi.microsoft.com/en-us/gateway/) page and choose either personal mode or standard mode. Personal mode is useful for testing the Athena connector locally. Standard mode is appropriate in a multiuser production setting. 1. To install an on-premises gateway (either personal or standard mode), see [Install an on-premises data gateway](https://docs.microsoft.com/en-us/data-integration/gateway/service-gateway-install) in the Microsoft documentation. 1. To test the gateway, follow the steps in [Use custom data connectors with the on-premises data gateway](https://docs.microsoft.com/en-us/power-bi/connect-data/service-gateway-custom-connectors) in the Microsoft documentation. For more information about on-premises data gateways, see the following Microsoft resources. + [What is an on-premises data gateway?](https://docs.microsoft.com/en-us/power-bi/connect-data/service-gateway-onprem) + [Guidance for deploying a data gateway for power BI](https://docs.microsoft.com/en-us/power-bi/connect-data/service-gateway-deployment-guidance) For an example of configuring Power BI Gateway for use with Athena, see the AWS Big Data Blog article [Creating dashboards quickly on Microsoft power BI using amazon Athena](https://aws.amazon.com/blogs/big-data/creating-dashboards-quickly-on-microsoft-power-bi-using-amazon-athena/). # Use Trusted identity propagation with Amazon Athena drivers Use trusted identity propagation with drivers Trusted identity propagation provides a new authentication option for organizations that want to centralize data permissions management and authorize requests based on their IdP identity across service boundaries. With IAM Identity Center, you can configure an existing IdP to manage users and groups and use AWS Lake Formation to define fine-grained access control permissions on catalog resources for these IdP identities. Athena supports identity propagation when querying data to audit data access by IdP identities to help your organization meet their regulatory and compliance requirements. You can now connect to Athena using Java Database Connectivity (JDBC) or Open Database Connectivity (ODBC) drivers with single sign-on capabilities through IAM Identity Center. When you access Athena from tools like PowerBI, Tableau, or DBeaver, your identity and permissions automatically propagate to Athena through IAM Identity Center. This means your individual data access permissions are enforced directly when querying data, without requiring separate authentication steps or credential management. For administrators, this feature centralizes access control through IAM Identity Center and Lake Formation, ensuring consistent permission enforcement across all supported analysis tools connecting to Athena. To get started, ensure your organization has configured IAM Identity Center as your identity source and set up the appropriate data access permissions for your users. **Topics** + [ ## Key definitions ](#using-trusted-identity-propagation-key-definitions) + [ ## Considerations ](#using-trusted-identity-propagation-considerations) + [ ## Prerequisites ](#using-trusted-identity-propagation-prerequisites) + [ # Connect Athena to IAM Identity Center ](using-trusted-identity-propagation-setup.md) + [ # Configure and deploy resources using AWS CloudFormation ](using-trusted-identity-propagation-cloudformation.md) ## Key definitions 1. **Application Role** – Role to exchange tokens, retrieve workgroup and customer managed AWS IAM Identity Center application ARN. 1. **Access Role** – Role to use with Athena drivers for running customer workflows with Identity enhanced credentials. This means this role is needed to access downstream services. 1. **Customer Managed Application** – The AWS IAM Identity Center Application. For more information, see [Customer Managed Application](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html). ## Considerations 1. This feature only works for regions where Athena is generally available with trusted identity propagation. For more information on availability, see [Considerations and Limitations](https://docs.aws.amazon.com/athena/latest/ug/workgroups-identity-center.html). 1. The JDBC and ODBC drivers support trusted identity propagation with IAM-enabled workgroups. 1. You can use both JDBC and ODBC either as standalone drivers or with any BI or SQL tool with trusted identity propagation using this authentication plugin. ## Prerequisites 1. You must have an AWS IAM Identity Center instance enabled. For more information, see [What is IAM Identity Center?](https://docs.aws.amazon.com/singlesignon/latest/userguide/identity-center-instances.html) for more information. 1. You must have a working external identity provider and the users or groups must be present in AWS IAM Identity Center. You can provision your users or groups automatically either manually or with SCIM. For more information, see [Provisioning an external identity provider into IAM Identity Center using SCIM](https://docs.aws.amazon.com/singlesignon/latest/userguide/provision-automatically.html). 1. You must grant Lake Formation Permissions to users or groups for catalogs, databases, and tables. For more information, see [Use Athena to query data with Lake Formation](https://docs.aws.amazon.com/athena/latest/ug/security-athena-lake-formation.html). 1. You must have a working BI tool or SQL client to run Athena queries using the JDBC or ODBC driver. # Connect Athena to IAM Identity Center The following section lists the process of connecting Athena to IAM Identity Center. ## Setup trusted token issuer Follow [Setting up a trusted token issuer](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) guide to setup trusted token issuer. This will create an AWS IAM Identity Center. **Note** For **Provider type**, choose **OpenID Connect**. For **Provider URL**, enter the issuer URL from your Identity provider. For **Audience**, specify the client ID issued by the Identity provider for your app. Copy the Application Resource Name (ARN) for AWS IAM Identity provider. For more information, see [Identity providers and federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html). ## Setup IAM roles ### Setup IAM application role 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. On the left navigation, choose **Roles** and then choose **Create role**. 1. For **Trusted entity type**, choose **Custom trust policy** as following: 1. For **Federated Principal**, add the ARN for AWS IAM identity provider that you copied during trusted token issuer setup. 1. For policy condition, add the audience from your external federated identity provider. 1. Add the following inline policy to grant access to the user for [CreateTokenWithIAM](https://docs.aws.amazon.com/singlesignon/latest/OIDCAPIReference/API_CreateTokenWithIAM.html), [ListTagsForResource](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListTagsForResource.html), and [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) permissions. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "athena:ListTags*", "sso:ListTags*" ], "Resource": "*" } ] } ``` ------ **Note** `CreateTokenWithIam` permissions are given in customer managed IAM Identity Center application. 1. Copy the ARN for application role. ### Setup IAM access role 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. On the left navigation, choose **Roles** and then choose **Create role**. 1. For **Trusted entity type**, choose **Custom trust policy** as following: 1. For **Federated Principal**, add the ARN for AWS IAM Identity Center copied during trusted token issuer setup. 1. For **AWS Principal**, add the ARN for AWS IAM application role copied during IAM application role setup. 1. Add the following **inline policy** to grant access for driver workflows: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "athena:StartQueryExecution", "athena:GetQueryExecution", "athena:GetQueryResults", "athena:ListWorkGroups", "athena:ListDataCatalogs", "athena:ListDatabases", "athena:ListTableMetadata" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:GetObject", "s3:PutObject" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "glue:GetDatabase", "glue:GetDatabases", "glue:CreateTable", "glue:GetTable", "glue:GetTables", "glue:UpdateTable", "glue:DeleteTable", "glue:BatchDeleteTable", "glue:GetTableVersion", "glue:GetTableVersions", "glue:DeleteTableVersion", "glue:BatchDeleteTableVersion", "glue:CreatePartition", "glue:BatchCreatePartition", "glue:GetPartition", "glue:GetPartitions", "glue:BatchGetPartition", "glue:UpdatePartition", "glue:DeletePartition", "glue:BatchDeletePartition" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "lakeformation:GetDataAccess" ], "Resource": "*" } ] } ``` ------ 1. Copy the ARN for access role. ## Configure AWS IAM Identity Center customer managed application To configure a customer managed application, follow the steps in [Set up customer managed OAuth 2.0 applications for trusted identity propagation](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-trusted-identity-propagation-set-up-your-own-app-OAuth2.html) with the following considerations for Athena. + For **Tags**, add the following key-value pair: + **Key** – **AthenaDriverOidcAppArn** + **Value** – **AccessRoleARN** that was copied during IAM Access Role setup. + When [specifying application credentials](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-trusted-identity-propagation-set-up-your-own-app-OAuth2.html#customermanagedapps-trusted-identity-propagation-set-up-your-own-app-OAuth2-specify-application-credentials), add the ARN for AWS IAM application role that you copied during IAM application role setup. + For **Applications that can receive requests**, choose **AWS-Lake-Formation-AWS-Glue-Data-Catalog-**. + For **Access scopes to apply**, select **lakeformation:query** for IAM-enabled workgroups, or **lakeformation:query**, **athena:workgroup:read\$1write**, and **s3:access\$1grants:read\$1write** for Identity Center-enabled workgroups. ## Configure workgroup association 1. In the Athena console navigation pane, choose **Workgroups**. 1. Choose a workgroup from the list and open the **Tags** tab. 1. Choose **Manage tags** and enter the following: 1. **Key** – `AthenaDriverOidcAppArn` 1. **Value** – ARN for AWS IAM Identity Center application. 1. Choose **Save**. Once administrators complete the one-time setup, they can distribute essential connection details to their users. Users need these five mandatory parameters to run SQL workloads: 1. **ApplicationRoleARN** – The ARN of the application role 1. **JwtWebIdentityToken** – The JWT token for identity verification 1. **WorkgroupARN** – The ARN of the Athena workgroup 1. **JwtRoleSessionName** – The session name for JWT role 1. **CredentialsProvider** – The credentials provider configuration **Note** We've simplified the connection string configuration through strategic tagging. By properly tagging both the Athena workgroup and AWS IAM Identity Center customer managed application, administrators eliminate the need for users to provide `AccessRoleArn` and `CustomerIdcApplicationArn`. The plugin handles this automatically by using the application role to locate necessary tags and retrieve corresponding ARN values for its workflow. Administrators can still make users provide `AccessRoleArn` or `CustomerIdcApplicationArn` in the connection string by adjusting the application role permissions as needed. ## Run queries using trusted identity propagation enabled Athena drivers Download the latest version of driver that you want to use. For more information on JDBC installation, see [Get started with the JDBC 3.x driver](jdbc-v3-driver-getting-started.md). You can choose to install ODBC drivers based on the supported platform. For more information, see [Get started with the ODBC 2.x driver](odbc-v2-driver-getting-started.md). Based on the driver that you want to use, provide the parameters listed in: + [JDBC auth plugin connection parameters](jdbc-v3-driver-jwt-tip-credentials.md) + [ODBC auth plugin connection parameters](odbc-v2-driver-jwt-tip.md) **Note** Trusted identity propagation with drivers is only available after version 3.6.0 in JDBC and version 2.0.5.0 in ODBC. ## Use Athena drivers and trusted identity propagation with DBeaver 1. Download the latest JDBC jar with dependencies from Athena. For more information, see [Athena JDBC 3.x driver](jdbc-v3-driver.md). 1. Open the DBeaver application on your computer. 1. Navigate to the **Database** menu at the top of the screen, and then choose **Driver Manager**. 1. Choose **New** and then **Libraries**. 1. Add the latest driver and choose **Find class**. This will give you a file path like `com.amazon.athena.jdbc.AthenaDriver`. 1. Open **Settings** tab and provide the following fields 1. **Driver name** – Athena JDBC trusted identity propagation 1. **Class name** – `com.amazon.athena.jdbc.AthenaDriver` 1. Select the option **No authentication**. 1. Choose **Connect to a database** and find Athena JDBC trusted identity propagation. This will take you to the JDBC URL. For more information, see [Configuring the driver](jdbc-v3-driver-getting-started.md#jdbc-v3-driver-configuring-the-driver). 1. Provide the following details 1. **Workgroup** – The workgroup in which you want to run queries. For information about workgroups, see [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html). 1. **Region** – The AWS Region where the queries will be run. For a list of regions, see [Amazon Athena endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/athena.html). 1. **OutputLocation** – The location in Amazon S3 where you want to store the query results. For information about output location, see [ResultConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultConfiguration.html). 1. **CredentialsProvider** – Enter `JWT_TIP`. 1. **ApplicationRoleArn** – The ARN of the role to enable `AssumeRoleWithWebIdentity`. For more information about ARN roles, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the AWS Security Token Service API reference. 1. **WorkgroupArn** – The ARN of the workgroup in which queries will run. It must be the same workgroup as provided in the **Workgroup** field . For information about workgroups, see [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html). 1. **JwtRoleSessionName** – The name of the session when you use JWT credentials for authentication. It can be any name of your choice. 1. **JwtWebIdentityToken** – The JWT token obtained from an external federated identity provider. This token is used to authenticate with Athena. ``` jdbc:athena://Workgroup=;Region=;OutputLocation=;CredentialsProvider=JWT_TIP;ApplicationRoleArn=;WorkgroupArn=;JwtRoleSessionName=JDBC_TIP_SESSION;JwtWebIdentityToken=; ``` 1. Choose **OK** and close the window. DBeaver will start loading your metadata after this step and you should start seeing your catalogs, databases, and tables getting populated. **Note** If JTI claim is present in the token and you choose **Test connection** before choosing **OK**, it prevents the same JTI from being reused for token exchanges. For more information, see [Prerequisites and considerations for trusted token issuers](https://docs.aws.amazon.com/singlesignon/latest/userguide/using-apps-with-trusted-token-issuer.html#trusted-token-issuer-prerequisites). To handle this, JDBC implements an in-memory cache, whose lifecycle is dependent on the main driver instance. For ODBC, a [file cache](odbc-v2-driver-jwt-tip.md#odbc-v2-driver-jwt-tip-file-cache) is optionally present that enables temporary credentials to be cached and reused to reduce the number of web identity tokens used during session lifecycle. 1. Open **SQL query editor** and start running your queries. See [Cloudtrail logs](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html) to verify the propagated identity of the user. # Configure and deploy resources using AWS CloudFormation You can configure and deploy resources using CloudFormation templates to start using Trusted Identity Propagation with Athena drivers as following. 1. Download an CloudFormation template to set up the IAM Identity Center customer managed application and access roles along with workgroup and IAM Identity Center application tags. You can download it from this [CloudFormation template link](https://downloads.athena.us-east-1.amazonaws.com/drivers/CFNTemplate/AthenaDriversTrustedIdentityPropagationCFNTemplate.yaml). 1. Run the `create-stack` AWS CLI command to deploy the CloudFormation stack that will provision the configured resources as following. ``` aws cloudformation create-stack \ --stack-name my-stack \ --template-url URL_of_the_file_that_contains_the_template_body \ --parameters file://params.json ``` 1. To view the status of the resources provisioning, navigate to the CloudFormation console. After the cluster creation completes, view the new IAM Identity Center application in Identity Center console. You can view the IAM roles in the IAM console. The tags will be associated in Workgroup as well as IAM Identity Center application. 1. Using the created roles and application, you can use the Athena drivers immediately. To use JDBC driver, see [JDBC auth plugin connection parameters](jdbc-v3-driver-jwt-tip-credentials.md). To use ODBC driver, see [ODBC auth plugin connection parameters](odbc-v2-driver-jwt-tip.md).