This page provides a guide to Establishing a Connection to Amazon Athena in CData Cloud, as well as information on the available resources, and a reference to the available connection properties.

Connecting to Amazon Athena

Establishing a Connection shows how to authenticate to Amazon Athena and configure any necessary connection properties to create a database in CData Cloud

Accessing Data from CData Cloud Services

Accessing data from Amazon Athena through the available standard services and CData Cloud administration is documented in further details in the CData Cloud Documentation.

Connect to Amazon Athena by selecting the corresponding icon in the Database tab. Required properties are listed under Settings. The Advanced tab lists connection properties that are not typically required.

Connecting to Amazon Athena

• DataSource: The name of the Amazon Athena data source to connect to.
• Database: The name of the Amazon Athena database to connect to.
• AWSRegion: Set this to the region where your Amazon Athena data is hosted.
• S3StagingDirectory: Set this to a folder in S3 where you would like to store the results of queries.

If Database and DataSource are not specified, the Cloud tries to list all databases from the available data sources in Amazon Athena. Setting both properties improves the performance of the Cloud.

Authenticating to Amazon Athena

Obtain AWS Keys

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

1. Sign into the AWS Management console with the credentials for your root account.
2. Select your account name or number.
3. In the menu that displays, select My Security Credentials.
4. To manage or create root account access keys, click Continue to Security Credentials and expand the "Access Keys" section.

Root Credentials

To authenticate using account root credentials, set these configuration parameters:

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

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

Temporary Credentials

To authenticate using temporary credentials, specify the following:

• AuthScheme: TemporaryCredentials.
• AWSAccessKey: The access key of the IAM user to assume the role for.
• AWSSecretKey: The secret key of the IAM user to assume the role for.
• AWSSessionToken: Your AWS session token, provided with your temporary credentials. For details, see AWS Identity and Access Management User Guide.

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

To authenticate using both temporary credentials and an IAM role, set all the parameters described above, and specify these additional parameters:

• AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This prompts the Cloud to retrieve credentials for the specified role.
• AWSExternalId (optional): Only required if you are assuming a role in another AWS account.

EC2 Instances

Set AuthScheme to AwsEC2Roles.

If you are using the Cloud from an EC2 Instance and have an IAM Role assigned to the instance, you can use the IAM Role to authenticate. Since the Cloud automatically obtains your IAM Role credentials and authenticates with them, it is not necessary to specify AWSAccessKey and AWSSecretKey.

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

• AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This will cause the Cloud to attempt to retrieve credentials for the specified role.
• AWSExternalId (optional): Only required if you are assuming a role in another AWS account.

IMDSv2 Support

The Amazon Athena Cloud now supports IMDSv2. Unlike IMDSv1, the new version requires an authentication token. Endpoints and response are the same in both versions.

In IMDSv2, the Amazon Athena Cloud first attempts to retrieve the IMDSv2 metadata token and then uses it to call AWS metadata endpoints. If it is unable to retrieve the token, the Cloud reverts to IMDSv1.

AWS IAM Roles

Set AuthScheme to AwsIAMRoles.

In many situations, it may be preferable to use an IAM role for authentication instead of the direct security credentials of an AWS root user. If you are specifying the AWSAccessKey and AWSSecretKey of an AWS root user, you may not use roles.

To authenticate as an AWS role, set these properties:

• AWSAccessKey: The access key of the IAM user to assume the role for.
• AWSSecretKey: The secret key of the IAM user to assume the role for.
• AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This will cause the Cloud to attempt to retrieve credentials for the specified role.
• AWSExternalId (optional): Only required if you are assuming a role in another AWS account.

ADFS

To connect to ADFS, set the AuthScheme to ADFS, and set these properties:

• User: The ADFS user.
• Password: The ADFS user's password.
• SSOLoginURL: The SSO provider's login url.

Example connection string:

AuthScheme=ADFS; AWSRegion=Ireland; Database=sampledb; [email protected]; Password=CH8WerW121235647iCa6; SSOLoginURL='https://adfs.domain.com'; AWSRoleArn=arn:aws:iam::1234:role/ADFS_SSO; AWSPrincipalArn=arn:aws:iam::1234:saml-provider/ADFSProvider; S3StagingDirectory=s3://athena/staging;

ADFS Integrated

The ADFS Integrated flow indicates you are connecting with the currently logged in Windows user credentials. To use the ADFS Integrated flow, do not specify the User and Password, but otherwise follow the same steps in the ADFS guide above.

Okta

To connect to Okta, set the AuthScheme to Okta, and set these properties:

• User: The Okta user.
• Password: The Okta user's password.
• SSOLoginURL: The SSO provider's login URL.

If you are using a trusted application or proxy that overrides the Okta client request OR configuring MFA, you must use combinations of SSOProperties to authenticate using Okta. Set any of the following, as applicable:

• APIToken: When authenticating a user via a trusted application or proxy that overrides the Okta client request context, set this to the API Token the customer created from the Okta organization.
• MFAType: If you have configured the MFA flow, set this to one of the following supported types: OktaVerify, Email, or SMS.
• MFAPassCode: If you have configured the MFA flow, set this to a valid passcode.
  If you set this to empty or an invalid value, the Cloud issues a one-time password challenge to your device or email. After the passcode is received, reopen the connection where the retrieved one-time password value is set to the MFAPassCode connection property.
• MFARememberDevice: True by default. Okta supports remembering devices when MFA is required. If remembering devices is allowed according to the configured authentication policies, the Cloud sends a device token to extend MFA authentication lifetime. If you do not want MFA to be remembered, set this variable to False.

Example connection string:

AuthScheme=Okta; AWSRegion=Ireland; Database=sampledb; [email protected]; Password=CH8WerW121235647iCa6; SSOLoginURL='https://cdata-us.okta.com/home/amazon_aws/0oa35m8arsAL5f5NrE6NdA356/272'; SSOProperties='ApiToken=01230GGG2ceAnm_tPAf4MhiMELXZ0L0N1pAYrO1VR-hGQSf;'; AWSRoleArn=arn:aws:iam::1234:role/Okta_SSO; AWSPrincipalARN=arn:aws:iam::1234:saml-provider/OktaProvider; S3StagingDirectory=s3://athena/staging;

To connect to PingFederate, set AuthScheme to PingFederate, and set these properties:

• User: The PingFederate user.
• Password: The PingFederate user's password.
• SSOLoginURL: The SSO provider's login url.
• AWSRoleARN (optional): If you have multiple role ARNs, specify the one you want to use for authorization.
• AWSPrincipalARN (optional): If you have multiple principal ARNs, specify the one you want to use for authorization.
• SSOExchangeUrl: The Partner Service Identifier URI configured in your PingFederate server instance under: SP Connections > SP Connection > WS-Trust > Protocol Settings. This should uniquely identify a PingFederate SP Connection, so it is a good idea to set it to your AWS SSO ACS URL. You can find it under AWS SSO > Settings > View Details next to the Authentication field.
• SSOProperties (optional): Authscheme=Basic if you want to include your username and password as an authorization header in requests to Amazon S3.

To enable mutual SSL authentication for SSOLoginURL, the WS-Trust STS endpoint, configure these SSOProperties:

• SSLClientCert
• SSLClientCertType
• SSLClientCertSubject
• SSLClientCertPassword

Example connection string:

authScheme=pingfederate;SSOLoginURL=https://mycustomserver.com:9033/idp/sts.wst;SSOExchangeUrl=https://us-east-1.signin.aws.amazon.com/platform/saml/acs/764ef411-xxxxxx;user=admin;password=PassValue;AWSPrincipalARN=arn:aws:iam::215338515180:saml-provider/pingFederate;AWSRoleArn=arn:aws:iam::215338515180:role/SSOTest2;AWSRegion=Ireland;S3StagingDirectory=s3://somedirectory/staging;Database=athenadatabase;

Multi-Factor Authentication (MFA)

For users and roles that require multi-factor authentication, specify the following:

• AuthScheme: AwsMFA.
• CredentialsLocation: The location of the settings file where MFA credentials are saved. See the Credentials File Location page under Connection String Options for more information.
• MFASerialNumber: The serial number of the MFA device if one is being used.
• MFAToken: The temporary token available from your MFA device.

• AWSAccessKey: The access key of the IAM user for whom MFA will be issued.
• AWSSecretKey: The secret key of the IAM user whom MFA will be issued.

• AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This will cause the Cloud to attempt to retrieve credentials for the specified role using MFA.
• AWSExternalId (optional): Only required if you are assuming a role in another AWS account.

Note: If you want to control the duration of the temporary credentials, set the TemporaryTokenDuration property (default: 3600 seconds).

Credentials Files

You can use a credentials file to authenticate. Any configurations related to AccessKey/SecretKey authentication, temporary credentials, role authentication, or MFA can be used. To do so, set the following properties to authenticate:

• AuthScheme: AwsCredentialsFile.
• AWSCredentialsFile: The location of your credentials file.
• AWSCredentialsFileProfile (optional): The name of the profile you would like to use from the specified credentials file. If not specified, the default profile is used.

AWS Cognito Credentials

If you want to use the Cloud with a user registered in a User Pool in AWS Cognito, set the following properties to authenticate:

• AuthScheme: Set this to AwsCognitoSrp (recommended). You can also use AwsCognitoBasic.
• AWSCognitoRegion: Set this to the region of the User Pool.
• AWSUserPoolId: Set this to the User Pool Id.
• AWSUserPoolClientAppId: Set this to the User Pool Client App Id.
• AWSUserPoolClientAppSecret: Set this to the User Pool Client Secret.
• AWSIdentityPoolId: Set this to the Identity Pool Id of the Identity Pool that is linked with the User Pool.
• User: Set this to the username of the user registered in the User Pool.
• Password: Set this to the password of the user registered in the User Pool.

Azure Active Directory/Microsoft Entra ID

This configuration uses 2.0 On-Behalf-Of flow (Microsoft identity platform and OAuth 2.0 On-Behalf-Of flow ), which requires two Microsoft Entra applications:

• the "Amazon Athena" application used for single sign-on
• a separate "connector" application with user_impersonation permission on the "Amazon Athena" application

You must follow the steps outlined in Microsoft's AWS Single-Account Access documentation to create the SSO application and set Microsoft Entra ID as the SAML IdP for an AWS single-account app.

To create an application with user_impersonation permission on the SSO application, follow these steps:

1. Sign into the Microsoft Entra admin center as at least a Cloud Application Administrator.
2. Navigate to Identity > Applications > App registrations.
3. Click New application at the top of the page.
4. Enter a name and select supported account types as desired.
5. Select Web in the Redirect URI dropdown, and enter http://localhost:33333.
6. Select Register.
7. In the "Overview" section, you can see your OAuthClientId (Application ID).
8. Select API permissions > Add a permission.
9. Select the API of your SSO application by specifying its name or Application Id in the "APIs my organization uses" tab.
10. Select user_impersonation from the available list of Permissions.
11. Select Add permissions.
12. Select Certificates & secrets.
13. Select New client secret.
14. Optionally, enter a description and change the default Expires value, then select Add.
15. Save your client secret (the Value field of the OAuth secret that is displayed).

• OAuthClientId: The application Id of the connector application, listed in the Overview section of the application registration.
• OAuthClientSecret : The client secret value of the connector application. Azure AD displays this when you create a new client secret.
• CallbackURL: Set this to the redirect URI of the connector application. For example: https://localhost:33333.
• InitiateOAuth: GETANDREFRESH.

Use the following SSOProperties to authenticate to AzureAD:

• Resource: The application Id URI of the Amazon Athena application, listed in the Overview section of the application registration. In most cases this is the URL of your custom Amazon Athena domain.
• AzureTenant: The Id of the Azure AD tenant where the applications are registered.

The following is an example connection string:

AuthScheme=AzureAD;InitiateOAuth=GETANDREFRESH;OAuthClientId=3ea1c786-d527-4399-8c3b-2e3696ae4b48;OauthClientSecret=xxx;CallbackUrl=https://localhost:33333;SSOProperties='Resource=https://signin.aws.amazon.com/saml;AzureTenant=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

Customizing Amazon Athena Behavior

Follow the steps below to configure the Cloud defaults for querying Amazon Athena.

Using QueryPassthrough

Amazon Athena supports a set of queries that are not specified in the regular SQL-92 standard; to execute these queries simply set QueryPassthrough to true. This will pass the query directly to Amazon Athena without parsing it internally.

Flattening Nested Objects and Arrays

The Cloud is capable of flattening array elements and object properties into columns. See the pages for FlattenArrays and FlattenObjects for more information.

Encrypting Query Results to S3

Set EncryptionKey and EncryptionType if you would like to encrypt the result set stored in S3 after query execution.

To encrypt results stored in S3, follow the steps below:

1. Navigate to Amazon Athena Console.
2. Click Settings.
3. Enable the Encrypt Query Results option.
4. Select the Encryption type and set EncryptionType when you connect.
5. If you selected SSE-KMS or CSE-KMS, set both EncryptionType and EncryptionKey: select an encryption key in the menu or click Create KMS Key.

Cleaning Query Results

Amazon Athena stores the results of every query you execute in CSV files in S3StagingDirectory; these can quickly rack up a lot of space in Amazon S3. You can use CleanQueryResults, enabled by default, to clean these files for every query executed.

Note that this behavior will add a minor performance hit when you disconnect the last connection in a process.

Using Athena's Query Caching

You configure QueryCachingLevel to modify the usage of the query results stored in S3StagingDirectory; note that you have to keep the connection open to benefit from this feature. This is especially helpful when executing a certain query multiple times. This means Amazon Athena will not scan the same data again and simply use the results from the previous execution. These results are cleaned in the amount of seconds specified in QueryTolerance.

Note that failing to properly disconnect the connection when QueryCachingLevel is set to Cloud may lead to a large amount of saved queries in Athena. For most use cases setting QueryCachingLevel to Local should be enough.

Fine Tuning Performance

You can use the PageSize property to optimize use of your provisioned throughput, based on the size of your items and Amazon Athena's 1000MB page size. Set this property to the number of items to return.

Generally, a smaller page size reduces spikes in throughput that cause throttling. A smaller page size also inserts pauses between requests. This interval evens out the distribution of requests and allows more requests to be successful by avoiding throttling.

We recommend using predefined roles for services rather than creating custom IAM policies, but it if you want to create custom polices, use the roles described in the table below. Note that the specific policies required by the Amazon Athena driver are subject to change in future releases. Amazon Athena requires at a minimum the following permissions:

"arn:aws:athena:us-east-1:987654321098:datacatalog/*"

            "Resource": [
                "arn:aws:glue:region123:111111111111:table/*/*",
                "arn:aws:glue:region123:111111111111:database/*",
                "arn:aws:glue:region123:111111111111:catalog"
            ]
			

Federated Queries

    {
        "Effect": "Allow",
        "Action": [
            "lambda:InvokeFunction"
        ],
        "Resource": [
            "arn:aws:lambda:us-east-1:987654321098:function:cloudwatchtest1"
        ]
    }
 

Customizing the SSL Configuration

By default, the Cloud attempts to negotiate SSL/TLS by checking the server's certificate against the system's trusted certificate store.

To specify another certificate, see the SSLServerCert property for the available formats to do so.

Connecting Through a Firewall or Proxy

HTTP Proxies

To connect through the Windows system proxy, you do not need to set any additional connection properties. To connect to other proxies, set ProxyAutoDetect to false.

In addition, to authenticate to an HTTP proxy, set ProxyAuthScheme, ProxyUser, and ProxyPassword, in addition to ProxyServer and ProxyPort.

Other Proxies

Set the following properties:

• To use a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort.
• To tunnel the connection, set FirewallType to TUNNEL.
• To authenticate, specify FirewallUser and FirewallPassword.
• To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.

Stored Procedures

System Tables

CData Cloud - Amazon Athena Data Model

The Cloud dynamically extracts all relevant schema information from Amazon Athena via the REST API.

Discovering Schemas

By default, all Amazon Athena entities will be exposed as views. However, the Cloud is also capable of dividing object types into the following types from the Amazon Athena API :

• TABLE
• VIEW

You can enable this functionality by setting MetadataDiscoveryMethod to Glue. This method will require you to also add the necessary IAM profiles for the user.

Alternatively, you can use the Athena discovery method, though this method is slower.

• MetadataDiscoveryMethod: Set this to Athena.
• IncludeTableTypes: Set this to True.

Note that while the Cloud can break Amazon Athena objects into these types, they are all considered to be read-only. Reconnect to load any changes in the metadata, such as added or removed columns or changes in data type.

Stored procedures are function-like interfaces that extend the functionality of the Cloud beyond simple SELECT/INSERT operations with Amazon Athena.

Stored procedures accept a list of parameters, perform their intended function, and then return any relevant response data from Amazon Athena, along with an indication of whether the procedure succeeded or failed.

CData Cloud - Amazon Athena Stored Procedures

You can query the system tables described in this section to access schema information, information on data source functionality, and batch operation statistics.

Schema Tables

The following tables return database metadata for Amazon Athena:

• sys_catalogs: Lists the available databases.
• sys_schemas: Lists the available schemas.
• sys_tables: Lists the available tables and views.
• sys_tablecolumns: Describes the columns of the available tables and views.
• sys_procedures: Describes the available stored procedures.
• sys_procedureparameters: Describes stored procedure parameters.
• sys_keycolumns: Describes the primary and foreign keys.
• sys_indexes: Describes the available indexes.

Data Source Tables

The following tables return information about how to connect to and query the data source:

• sys_connection_props: Returns information on the available connection properties.
• sys_sqlinfo: Describes the SELECT queries that the Cloud can offload to the data source.

Query Information Tables

The following table returns query statistics for data modification queries, including batch operations::

• sys_identity: Returns information about batch operations or single updates.

Lists the available databases.

The following query retrieves all databases determined by the connection string:

SELECT * FROM sys_catalogs

Columns

Lists the available schemas.

The following query retrieves all available schemas:

          SELECT * FROM sys_schemas
          

Columns

Lists the available tables.

The following query retrieves the available tables and views:

          SELECT * FROM sys_tables
          

Columns

Describes the columns of the available tables and views.

The following query returns the columns and data types for the [AwsDataCatalog].[sampledb].Customers table:

SELECT ColumnName, DataTypeName FROM sys_tablecolumns WHERE TableName='Customers' AND CatalogName='AwsDataCatalog' AND SchemaName='sampledb'

Columns

Lists the available stored procedures.

The following query retrieves the available stored procedures:

          SELECT * FROM sys_procedures
          

Columns

Describes stored procedure parameters.

The following query returns information about all of the input parameters for the SelectEntries stored procedure:

SELECT * FROM sys_procedureparameters WHERE ProcedureName='SelectEntries' AND Direction=1 OR Direction=2

Columns

Describes the primary and foreign keys.

The following query retrieves the primary key for the [AwsDataCatalog].[sampledb].Customers table:

         SELECT * FROM sys_keycolumns WHERE IsKey='True' AND TableName='Customers' AND CatalogName='AwsDataCatalog' AND SchemaName='sampledb'
          

Columns

Describes the foreign keys.

The following query retrieves all foreign keys which refer to other tables:

         SELECT * FROM sys_foreignkeys WHERE ForeignKeyType = 'FOREIGNKEY_TYPE_IMPORT'
          

Columns

Describes the primary keys.

The following query retrieves the primary keys from all tables and views:

         SELECT * FROM sys_primarykeys
          

Columns

Describes the available indexes. By filtering on indexes, you can write more selective queries with faster query response times.

The following query retrieves all indexes that are not primary keys:

          SELECT * FROM sys_indexes WHERE IsPrimary='false'
          

Columns

Returns information on the available connection properties and those set in the connection string.

When querying this table, the config connection string should be used:

jdbc:cdata:amazonathena:config:

This connection string enables you to query this table without a valid connection.

The following query retrieves all connection properties that have been set in the connection string or set through a default value:

SELECT * FROM sys_connection_props WHERE Value <> ''

Columns

Describes the SELECT query processing that the Cloud can offload to the data source.

See SQL Compliance for SQL syntax details.

Discovering the Data Source's SELECT Capabilities

Below is an example data set of SQL capabilities. Some aspects of SELECT functionality are returned in a comma-separated list if supported; otherwise, the column contains NO.

The following query retrieves the operators that can be used in the WHERE clause:

SELECT * FROM sys_sqlinfo WHERE Name = 'SUPPORTED_OPERATORS'

Columns

Returns information about attempted modifications.

The following query retrieves the Ids of the modified rows in a batch operation:

         SELECT * FROM sys_identity
          

Columns

The connection string properties are the various options that can be used to establish a connection. This section provides a complete list of the options you can configure in the connection string for this provider. Click the links for further details.

Authentication

Connection

AWS Authentication

SSO

OAuth

SSL

Logging

Schema

Miscellaneous

This section provides a complete list of the Authentication properties you can configure in the connection string for this provider.

Your Athena VPC Endpoint. It will override the default athena.{region}.amazonaws.com endpoint.

Data Type

string

Default Value

""

Remarks

Your Athena VPC Endpoint. It will override the default athena.{region}.amazonaws.com endpoint.

Specifies the location Amazon Athena will use to store the results of a query.

Data Type

string

Default Value

""

Remarks

Specifies the location Amazon Athena will use to store the results of a query. This folder can occupy space over the course of time and you may want to clean it manually if CleanQueryResults is not enabled.

Specifies the encryption option for query results in Athena.

Possible Values

Data Type

string

Default Value

"None"

Remarks

Specifies the encryption option for query results in Athena. This option is required if you have configured Amazon Athena to encrypt query results; Set EncryptionType and EncryptionKey if you would like to encrypt the result set stored in S3 after query execution. Note that setting these properties does not encrypt the result set in S3StagingDirectory.

To encrypt Amazon Athena query results, follow the following steps:

1. Navigate to Amazon Athena Console.
2. Click Settings.
3. Enable the Encrypt Query Results option.
4. Select the Encryption type.
5. If you selected SSE-KMS or CSE-KMS, select an encryption key in the menu or click Create KMS Key. Set EncryptionKey in addition to EncryptionType when you connect.

Specifies the encryption key when encrypting results stored in S3.

Data Type

string

Default Value

""

Remarks

Specifies the encryption key when encrypting results stored in S3. This option is required if the EncryptionType is set to SSE_KMS or CSE_KMS.

Set EncryptionType and EncryptionKey if you would like to encrypt the result set stored in S3 after query execution. Note that this does not encrypt the result set in S3StagingDirectory.

Enabling Encryption

To enable the encryption of results stored in S3, see Fine-Tuning Data Access.

Obtaining an Encryption Key

You can create a key when you enable encryption. Or, create a key in the IAM console: Click Encryption Keys, select a region, and then click Create Key. To obtain the key, sign into the AWS Management console and click Services -> IAM -> Encryption Keys -> Create Key.

The name of the Athena Data Source.

Data Type

string

Default Value

""

Remarks

The data source to connect to when querying Athena. For MetadataDiscoveryMethod=Glue, AwsDataCatalog is used as the default data source.

The name of the Athena database.

Data Type

string

Default Value

""

Remarks

The database to connect to when querying Athena.

This section provides a complete list of the Connection properties you can configure in the connection string for this provider.

The Account Id to use when retrieving metadata from Glue. Default is current account id.

Data Type

string

Default Value

""

Remarks

When the property MetadataDiscoveryMethod has been set to 'Glue' then user is able to specify a Cross Account Id which they have permissions to access, and this account will be used to retrieve metadata. See more information here: https://docs.aws.amazon.com/glue/latest/dg/cross-account-access.html

This setting specifies the threshold, in bytes, above which the provider will choose to perform a multipart upload rather than uploading everything in one request.

Data Type

string

Default Value

""

Remarks

This setting specifies the threshold, in bytes, above which the Cloud will choose to perform a multipart upload rather than uploading everything in one request.

When this property is set to true, AWSLakeFormation service will be used to retrieve temporary credentials, which enforce access policies against the user based on the configured IAM role. The service can be used when authenticating through OKTA, ADFS, AzureAD, PingFederate, while providing a SAML assertion.

Data Type

bool

Default Value

false

Remarks

When this property is set to true, AWSLakeFormation service will be used to retrieve temporary credentials, which enforce access policies against the user based on the configured IAM role. The service can be used when authenticating through OKTA, ADFS, AzureAD, PingFederate, while providing a SAML assertion.

This section provides a complete list of the AWS Authentication properties you can configure in the connection string for this provider.

The scheme used for authentication. Accepted entries are: Auto, , AwsRootKeys , AwsIAMRoles , AwsEC2Roles , AwsMFA , ADFS, Okta, PingFederate , AwsCredentialsFile , AwsCognitoBasic , AwsCognitoSrp.

Data Type

string

Default Value

"AwsRootKeys"

Remarks

Use the following options to select your authentication scheme:

• Auto: Set this to have the Cloud attempt to automatically resolve the proper authentication scheme to use based on the other connection properties specified.
• TemporaryCredentials: Set this to leverage temporary security credentials alongside a session token to connect.
• AwsRootKeys: Set this to use the root user access key and secret. Useful for quickly testing, but production use cases are encouraged to use something with narrowed permissions.
• AwsIAMRoles: Set to use IAM Roles for the connection.
• AwsEC2Roles: Set this to automatically use IAM Roles assigned to the EC2 machine the CData Cloud is currently running on.
• AwsMFA: Set to use multi factor authentication.
• Okta: Set to use a single sign on connection with OKTA as the identity provider.
• ADFS: Set to use a single sign on connection with ADFS as the identity provider.
• PingFederate: Set to use a single sign on connection with PingFederate as the identity provider.
• AwsCredentialsFile: Set to use a credential file for authentication.
• AwsCognitoSrp: Set to use Cognito based authentication. This is recommended over AwsCognitoBasic because this option does NOT send the password to the server for authentication, instead it uses the SRP protocol.
• AwsCognitoBasic: Set to use Cognito based authentication.

Your AWS account access key. This value is accessible from your AWS security credentials page.

Data Type

string

Default Value

""

Remarks

Your AWS account access key. This value is accessible from your AWS security credentials page:

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

Your AWS account secret key. This value is accessible from your AWS security credentials page.

Data Type

string

Default Value

""

Remarks

Your AWS account secret key. This value is accessible from your AWS security credentials page:

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

The Amazon Resource Name of the role to use when authenticating.

Data Type

string

Default Value

""

Remarks

When authenticating outside of AWS, it is common to use a Role for authentication instead of your direct AWS account credentials. Entering the AWSRoleARN will cause the CData Cloud to perform a role based authentication instead of using the AWSAccessKey and AWSSecretKey directly. The AWSAccessKey and AWSSecretKey must still be specified to perform this authentication. You cannot use the credentials of an AWS root user when setting RoleARN. The AWSAccessKey and AWSSecretKey must be those of an IAM user.

The ARN of the SAML Identity provider in your AWS account.

Data Type

string

Default Value

""

Remarks

The ARN of the SAML Identity provider in your AWS account.

The hosting region for your Amazon Web Services.

Possible Values

Data Type

string

Default Value

"NORTHERNVIRGINIA"

Remarks

The hosting region for your Amazon Web Services. Available values are OHIO, NORTHERNVIRGINIA, NORTHERNCALIFORNIA, OREGON, CAPETOWN, HONGKONG, JAKARTA, MUMBAI, OSAKA, SEOUL, SINGAPORE, SYDNEY, TOKYO, CENTRAL, BEIJING, NINGXIA, FRANKFURT, IRELAND, LONDON, MILAN, PARIS, STOCKHOLM, ZURICH, BAHRAIN, UAE, SAOPAULO, GOVCLOUDEAST, and GOVCLOUDWEST.

Your AWS session token.

Data Type

string

Default Value

""

Remarks

Your AWS session token. This value can be retrieved in different ways. See this link for more info.

A unique identifier that might be required when you assume a role in another account.

Data Type

string

Default Value

""

Remarks

A unique identifier that might be required when you assume a role in another account.

The serial number of the MFA device if one is being used.

Data Type

string

Default Value

""

Remarks

You can find the device for an IAM user by going to the AWS Management Console and viewing the user's security credentials. For virtual devices, this is actually an Amazon Resource Name (such as arn:aws:iam::123456789012:mfa/user).

The temporary token available from your MFA device.

Data Type

string

Default Value

""

Remarks

If MFA is required, this value will be used along with the MFASerialNumber to retrieve temporary credentials to login. The temporary credentials available from AWS will only last up to 1 hour by default (see TemporaryTokenDuration). Once the time is up, the connection must be updated to specify a new MFA token so that new credentials may be obtained.

The amount of time (in seconds) a temporary token will last.

Data Type

string

Default Value

"3600"

Remarks

Temporary tokens are used with both MFA and Role based authentication. Temporary tokens will eventually time out, at which time a new temporary token must be obtained. For situations where MFA is not used, this is not a big deal. The CData Cloud will internally request a new temporary token once the temporary token has expired.

However, for MFA required connection, a new MFAToken must be specified in the connection to retrieve a new temporary token. This is a more intrusive issue since it requires an update to the connection by the user. The maximum and minimum that can be specified will depend largely on the connection being used.

For Role based authentication, the minimum duration is 900 seconds (15 minutes) while the maximum if 3600 (1 hour). Even if MFA is used with role based authentication, 3600 is still the maximum.

For MFA authentication by itself (using an IAM User or root user), the minimum is 900 seconds (15 minutes), the maximum is 129600 (36 hours).

The hosting region for AWS Cognito.

Possible Values

Data Type

string

Default Value

"NORTHERNVIRGINIA"

Remarks

The hosting region for AWS Cognito. Available values are OHIO, NORTHERNVIRGINIA, NORTHERNCALIFORNIA, OREGON, CAPETOWN, HONGKONG, MUMBAI, OSAKA, SEOUL, SINGAPORE, SYDNEY, TOKYO, CENTRAL, BEIJING, NINGXIA, FRANKFURT, IRELAND, LONDON, MILAN, PARIS, STOCKHOLM, BAHRAIN, SAOPAULO, GOVCLOUDEAST, and GOVCLOUDWEST.

The User Pool Id.

Data Type

string

Default Value

""

Remarks

You can find this in AWS Cognito -> Manage User Pools -> select your user pool -> General settings -> Pool Id.

The User Pool Client App Id.

Data Type

string

Default Value

""

Remarks

You can find this in AWS Cognito -> Manage Identity Pools -> select your user pool -> General settings -> App clients -> App client Id.

Optional. The User Pool Client App Secret.

Data Type

string

Default Value

""

Remarks

You can find this in AWS Cognito -> Manage Identity Pools -> select your user pool -> General settings -> App clients -> App client secret.

The Identity Pool Id.

Data Type

string

Default Value

""

Remarks

You can find this in AWS Cognito -> Manage Identity Pools -> select your identity pool -> Edit identity pool -> Identity Pool Id

This section provides a complete list of the SSO properties you can configure in the connection string for this provider.

The IDP user used to authenticate the IDP via SSO.

Data Type

string

Default Value

""

Remarks

Together with Password, this field is used to authenticate in SSO connections against the Amazon Athena server.

The password used to authenticate the IDP user via SSO.

Data Type

string

Default Value

""

Remarks

The User and Password are together used in SSO connections to authenticate with the server.

The identity provider's login URL.

Data Type

string

Default Value

""

Remarks

The identity provider's login URL.

Additional properties required to connect to the identity provider in a semicolon-separated list.

Data Type

string

Default Value

""

Remarks

Additional properties required to connect to the identity provider in a semicolon-separated list. SSOProperties is used in conjunction with the the AWSRoleARN and AWSPrincipalARN. The following section provides an example using the OKTA identity provider.

ADFS

To connect to ADFS, set the AuthScheme to ADFS, and set these properties:

• User: The ADFS user.
• Password: The ADFS user's password.
• SSOLoginURL: The SSO provider's login url.

Example connection string:

AuthScheme=ADFS; AWSRegion=Ireland; Database=sampledb; [email protected]; Password=CH8WerW121235647iCa6; SSOLoginURL='https://adfs.domain.com'; AWSRoleArn=arn:aws:iam::1234:role/ADFS_SSO; AWSPrincipalArn=arn:aws:iam::1234:saml-provider/ADFSProvider; S3StagingDirectory=s3://athena/staging;

ADFS Integrated

The ADFS Integrated flow indicates you are connecting with the currently logged in Windows user credentials. To use the ADFS Integrated flow, do not specify the User and Password, but otherwise follow the same steps in the ADFS guide above.

Okta

To connect to Okta, set the AuthScheme to Okta, and set these properties:

• User: The Okta user.
• Password: The Okta user's password.
• SSOLoginURL: The SSO provider's login URL.

If you are using a trusted application or proxy that overrides the Okta client request OR configuring MFA, you must use combinations of SSOProperties to authenticate using Okta. Set any of the following, as applicable:

• APIToken: When authenticating a user via a trusted application or proxy that overrides the Okta client request context, set this to the API Token the customer created from the Okta organization.
• MFAType: If you have configured the MFA flow, set this to one of the following supported types: OktaVerify, Email, or SMS.
• MFAPassCode: If you have configured the MFA flow, set this to a valid passcode.
  If you set this to empty or an invalid value, the Cloud issues a one-time password challenge to your device or email. After the passcode is received, reopen the connection where the retrieved one-time password value is set to the MFAPassCode connection property.
• MFARememberDevice: True by default. Okta supports remembering devices when MFA is required. If remembering devices is allowed according to the configured authentication policies, the Cloud sends a device token to extend MFA authentication lifetime. If you do not want MFA to be remembered, set this variable to False.

Example connection string:

AuthScheme=Okta; AWSRegion=Ireland; Database=sampledb; [email protected]; Password=CH8WerW121235647iCa6; SSOLoginURL='https://cdata-us.okta.com/home/amazon_aws/0oa35m8arsAL5f5NrE6NdA356/272'; SSOProperties='ApiToken=01230GGG2ceAnm_tPAf4MhiMELXZ0L0N1pAYrO1VR-hGQSf;'; AWSRoleArn=arn:aws:iam::1234:role/Okta_SSO; AWSPrincipalARN=arn:aws:iam::1234:saml-provider/OktaProvider; S3StagingDirectory=s3://athena/staging;

The URL used for consuming the SAML response and exchanging it for service specific credentials.

Data Type

string

Default Value

""

Remarks

The CData Cloud will use the URL specified here to consume a SAML response and exchange it for service specific credentials. The retrieved credentials are the final piece during the SSO connection that are used to communicate with Amazon Athena.

This section provides a complete list of the OAuth properties you can configure in the connection string for this provider.

The client Id assigned when you register your application with an OAuth authorization server.

Data Type

string

Default Value

""

Remarks

As part of registering an OAuth application, you will receive the OAuthClientId value, sometimes also called a consumer key, and a client secret, the OAuthClientSecret.

The client secret assigned when you register your application with an OAuth authorization server.

Data Type

string

Default Value

""

Remarks

As part of registering an OAuth application, you will receive the OAuthClientId, also called a consumer key. You will also receive a client secret, also called a consumer secret. Set the client secret in the OAuthClientSecret property.

This section provides a complete list of the SSL properties you can configure in the connection string for this provider.

The certificate to be accepted from the server when connecting using TLS/SSL.

Data Type

string

Default Value

""

Remarks

If using a TLS/SSL connection, this property can be used to specify the TLS/SSL certificate to be accepted from the server. Any other certificate that is not trusted by the machine is rejected.

This property can take the following forms:

If not specified, any certificate trusted by the machine is accepted.

Use '*' to signify to accept all certificates. Note that this is not recommended due to security concerns.

This section provides a complete list of the Logging properties you can configure in the connection string for this provider.

The verbosity level that determines the amount of detail included in the log file.

Data Type

string

Default Value

"1"

Remarks

The verbosity level determines the amount of detail that the Cloud reports to the Logfile. Verbosity levels from 1 to 5 are supported. These are detailed in the Logging page.

This section provides a complete list of the Schema properties you can configure in the connection string for this provider.

This property restricts the schemas reported to a subset of the available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC.

Data Type

string

Default Value

""

Remarks

Listing the schemas from databases can be expensive. Providing a list of schemas in the connection string improves the performance.

By default, arrays are returned as strings of JSON. The FlattenArrays property can be used to flatten the elements of arrays into columns of their own. Set FlattenArrays to the number of elements you want to return from arrays.

Data Type

int

Default Value

0

Remarks

By default, arrays are returned as strings of JSON. The FlattenArrays property can be used to flatten the elements of arrays into columns of their own. This is only recommended for arrays that are expected to be short.

Set FlattenArrays to the number of elements you want to return from arrays. The specified elements are returned as columns. The zero-based index is concatenated to the column name. Other elements are ignored.

For example, you can return an arbitrary number of elements from an array of strings:

["FLOW-MATIC","LISP","COBOL"]

Setting FlattenArrays to -1 will flatten all the elements of arrays.

Set FlattenObjects to true to flatten object properties into columns of their own. Otherwise, objects nested in arrays are returned as strings of JSON.

Data Type

bool

Default Value

false

Remarks

Set FlattenObjects to true to flatten object properties into columns of their own. Otherwise, objects nested in arrays are returned as strings of JSON. To generate the column name, the Cloud concatenates the property name onto the object name with a dot.

For example, you can flatten the nested objects below at connection time:

[
     { "grade": "A", "score": 2 },
     { "grade": "A", "score": 6 },
     { "grade": "A", "score": 10 },
     { "grade": "A", "score": 9 },
     { "grade": "B", "score": 14 }
]

This section provides a complete list of the Miscellaneous properties you can configure in the connection string for this provider.

Amazon Athena produces cache files with every query, in the folder specified in S3StagingDirectory . CleanQueryResults specifies whether these files should be deleted once the connection is closed.

Data Type

bool

Default Value

true

Remarks

Amazon Athena stores the results of every query you execute as a CSV file in S3StagingDirectory. These CSV files can quickly rack up a lot of space in Amazon S3.

You can use CleanQueryResults, enabled by default, to clean these files for every query executed. Note that this behavior will add a minor performance hit when you disconnect the last connection in a process.

See Also

See Fine-Tuning Data Access for more information on configuring Athena's query caching.

A boolean indicating if FIPS URLs should be enabled.

Data Type

bool

Default Value

false

Remarks

FIPS or Federal Information Processing Standard are seperate endpoints in Amazon that may be required for certain government organizations. Set EnableFIPSMode to true to switch to using these endpoints. See more information here: https://aws.amazon.com/compliance/fips/.

The maximum column size.

Data Type

int

Default Value

255

Remarks

Some tools restrain the largest size of a column or the total size of all the columns selected. You can set the MaximumColumnSize to overcome these schema-based restrictions. The Cloud will not report any column to be larger than the MaximumColumnSize.

Set a MaximumColumnSize of zero to eliminate limits on column size, as shown in the following example:

Limits the number of rows returned when no aggregation or GROUP BY is used in the query. This takes precedence over LIMIT clauses.

Data Type

int

Default Value

-1

Remarks

Limits the number of rows returned when no aggregation or GROUP BY is used in the query. This takes precedence over LIMIT clauses.

The number of results to return per page of data retrieved from Amazon Athena.

Data Type

string

Default Value

"1000"

Remarks

The number of results to return per page of data retrieved from Amazon Athena. The maximum allowed value is 1000. See Fine-Tuning Data Access for more information on settings this property to avoid request throttling.

This determines the polling interval in milliseconds to check whether the result is ready to be retrieved.

Data Type

string

Default Value

"100"

Remarks

This property determines how long to wait between checking whether or not the query's results are ready. Very large resultsets or complex queries may take longer to process, and a low polling interval may result in many unnecessary requests being made to check the query status.

This property indicates whether or not to include pseudo columns as columns to the table.

Data Type

string

Default Value

""

Remarks

This setting is particularly helpful in Entity Framework, which does not allow you to set a value for a pseudo column unless it is a table column. The value of this connection setting is of the format "Table1=Column1, Table1=Column2, Table2=Column3". You can use the "*" character to include all tables and all columns; for example, "*=*".

Indicates whether to read the empty values as empty or as null.

Data Type

bool

Default Value

false

Remarks

Indicates whether to read the empty values as empty or as null.

Modifies the usage of query results stored in S3StagingDirectory . Cached queries will not be scanned again by Amazon Athena until the amount of seconds specified in QueryTolerance has passed.

Possible Values

Data Type

string

Default Value

"Local"

Remarks

Modifies the usage of query results stored in S3StagingDirectory. Cached queries will not be scanned again by Amazon Athena until the amount of seconds specified in QueryTolerance has passed. The casing of the queries must match exactly to trigger the behavior, which is explained below:

The timeout in seconds for requests issued by the provider to download large result sets.

Data Type

int

Default Value

1800

Remarks

If the QueryTimeout property is set to 0, operations will not time out; instead, they will run until they complete successfully or encounter an error condition. This property is distinct from Timeout which applies to individual HTTP operations while QueryTimeout applies to execution time of the operation as a whole.

If QueryTimeout expires and the request has not finished being processed, the Cloud raises an error condition.

Specifies the amount of time in seconds queries cache for if QueryCachingLevel is not set to None.

Data Type

string

Default Value

"600"

Remarks

Specifies the amount of time in seconds queries will cache for if QueryCachingLevel is not set to None. Values lower than 1 are not accepted.

Whether or not to expose the _S3Path column for the Amazon Athena tables.

Data Type

bool

Default Value

false

Remarks

The _S3Path column refers to the Amazon Athena's $path column, which returns the path of the source Amazon S3 file for each row in the output.

The Cloud will expose the _S3Path column for each table, only if this connection property is set to TRUE.

Specifies the number of header rows to skip for SELECT queries.

Data Type

string

Default Value

""

Remarks

Specifies the number of header rows to skip for SELECT queries. This most commonly used for Athena tables that point towards a CSV data source. If the CSV data source has headers, set SkipHeaderLineCount to 1.

If you have used AWS Glue to generate tables in Athena you can find this in the "skip.header.line.count" table property.

The value in seconds until the timeout error is thrown, canceling the operation.

Data Type

int

Default Value

60

Remarks

If Timeout = 0, operations do not time out. The operations run until they complete successfully or until they encounter an error condition.

If Timeout expires and the operation is not yet complete, the Cloud throws an exception.

Work group of the executed queries.

Data Type

string

Default Value

""

Remarks

Work group of the executed queries.