# Connect to Amazon 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
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
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
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
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
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
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
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
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
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
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
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
## 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
## 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 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
**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
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
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
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
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
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
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
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
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/).