Using the AWSCredentialsProvider Interface

You can configure the connector to authenticate the connection using a class that implements the AWSCredentialsProvider interface. For detailed information about this interface, see the Amazon AWS documentation for Interface AWSCredentialsProvider: http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSCredentialsProvider.html.

To configure authentication using the AWSCredentialsProvider interface:

  1. Set the AwsCredentialsProviderClass property to a fully qualified class name that implements the AWSCredentialsProvider interface. This class can be an implementation from the AWS SDK, or a custom implementation.

    Note: The AWS SDK is shaded and packaged in the connector JAR file. However, if your project has its own AWS SDK dependency, it is recommended that you use that class implementation instead of the one that is shaded in the connector. The shaded AWS SDK is intended to be used internally by the connector, and might not be optimal for other use cases.

  2. If necessary, set the AwsCredentialsProviderArguments property to a comma-separated list of String arguments for the constructor of the AwsCredentialsProviderClass.

    Be aware of the following restrictions:

    • The connector only supports String arguments for the constructor parameters.
    • Multiple arguments must be separated by a comma (,).
    • Surrounding spaces are not included in the parsed arguments.
    • To escape a single character, use a backslash (\) before that character. To indicate a backslash in an argument, use two backslashes (\\).
    • To escape all commas in an argument, enclose the argument in quotation marks ("). To indicate a quotation mark in a quoted argument, use a backslash (\) before that quotation mark.

For more detailed instructions about how to configure authentication using various implementations of the AWSCredentialsProvider interface, see the following:

For code examples that demonstrate how to use each type of credentials provider in a Java application, see Examples: Using the Connector in a Java Application.

Using DefaultAWSCredentialsProviderChain

To configure authentication using DefaultAWSCredentialsProviderChain:

  1. Set the AwsCredentialsProviderClass property to com.simba.athena.amazonaws.auth.DefaultAWSCredentialsProviderChain.
  2. Do not set the AwsCredentialsProviderArguments property.

    The arguments are taken from one of the locations in the default credentials provider chain. For detailed information about configuring default credentials, see "Using the Default Credential Provider Chain" in the AWS SDK for Java Developer Guide: http://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default.

For a code example that demonstrates how to use the DefaultAWSCredentialsProviderChain in a Java application, see Example: DefaultAWSCredentialsProviderChain.

Using PropertiesFileCredentialsProvider

To configure authentication using PropertiesFileCredentialsProvider:

  1. Create a text file called athenaCredentials.props. This file should contain the following text:

    accessKey = [AccessKey]

    secretKey = [SecretKey]

    The variables are defined as follows:

    • [AccessKey] is the access key provided by your AWS account.
    • [SecretKey] is the secret key provided by your AWS account.
  2. Set the AwsCredentialsProviderClass property to com.simba.athena.amazonaws.auth.PropertiesFileCredentialsProvider.
  3. Set the AwsCredentialsProviderArguments property to the full path and name of the athenaCredentials.props file. For example, "/Users/skroob/athenaCredentials.props".

For a code example that demonstrates how to use the PropertiesFileCredentialsProvider in a Java application, see Example: PropertiesFileCredentialsProvider.

Using InstanceProfileCredentialsProvider

To configure authentication using InstanceProfileCredentialsProvider:

  1. Set the AwsCredentialsProviderClass property to com.simba.athena.amazonaws.auth.InstanceProfileCredentialsProvider.
  2. Do not set the AwsCredentialsProviderArguments property.

    The arguments are provided by the EC2 instance profile for the instance on which you are running your application. For more detailed information about configuring InstanceProfileCredentialsProvider, see "IAM Roles for Amazon EC2" in the Amazon Elastic Compute Cloud User Guide for Linux Instances: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html.

    3. For examples of a few different ways that profiles can be used, see the following:

    For a code example that demonstrates how to use the InstanceProfileCredentialsProvider in a Java application, see Example: InstanceProfileCredentialsProvider.

Example: Using a Profile to Provide a Session Token

This example demonstrates how to authenticate a connection to Athena using a profile that provides a session token. A session token grants temporary access to the Athena service. An access key and secret key must be provided along with the token.

First, define a profile that specifies the access key, secret key, and session token. For example:

[simba_session]

aws_access_key_id=[YourAccessKey]

aws_secret_access_key=[YourSecretKey]

aws_session_token=[YourSessionToken]

Then, to connect to Athena using that profile, set the following properties in your connection URL:

  • Set the AwsCredentialsProviderClass property to com.simba.athena.amazonaws.auth.profile.ProfileCredentialsProvider.
  • Set the AwsCredentialsProviderArguments property to the name of the profile that you want to use. In this case, simba_session.

For example:

jdbc:awsathena://AwsRegion=us-east-1;S3OutputLocation=s3://my-athena-resultbucket/test/;AwsCredentialsProviderClass=com.simba.athena.amazonaws.auth.profile.ProfileCredentialsProvider;AwsCredentialsProviderArguments=simba_session;

Example: Using a Profile to Switch Roles

You can define a profile that refers to another existing profile, and then include an additional role setting. When you use this profile to authenticate your connection, the connector uses all the settings defined in the referenced profile as well as the role that has been additionally specified. By switching between these profiles, you can alternate between your roles without having to update the profile definition each time.

For an example that demonstrates how to configure profiles this way, see "Example Scenario: Switch to a Production Role" in the AWS Identity and Access Management documentation: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-cli.html#switch-role-cli-scenario-prod-env.

Based on this AWS example, which involves defining a main profile named default and a role switch profile named prodaccess, in order to switch roles when using the Simba Amazon Athena JDBC Connector, all you would need to do is update the AwsCredentialsProviderArguments setting in your connection URL. For example:

  • To use the ProductionAccessRole role:

    jdbc:awsathena://AwsRegion=us-east-1;S3OutputLocation=s3://my-athena-resultbucket/test/;AwsCredentialsProviderClass=com.simba.athena.amazonaws.auth.profile.ProfileCredentialsProvider;AwsCredentialsProviderArguments=prodaccess;

  • Or, to access Athena without using the ProductionAccessRole role:

    jdbc:awsathena://AwsRegion=us-east-1;S3OutputLocation=s3://my-athena-resultbucket/test/;AwsCredentialsProviderClass=com.simba.athena.amazonaws.auth.profile.ProfileCredentialsProvider;AwsCredentialsProviderArguments=default;

Using a Custom Credentials Provider

This example shows a custom credentials provider, CustomSessionsCredentialsProvider, that uses an access and secret key in addition to a session token. CustomSessionsCredentialsProvider is shown for example only and is not included in the connector. You must create custom providers before you can use them.

For an example of using a custom credentials provider to obtain credentials from an identity provider, see Using a Custom Credentials Provider for an Identity Provider.

To configure authentication using a custom credentials provider:

  1. Create a credentials provider called CustomSessionsCredentialsProvider that uses an access key, secret key, and session token for authentication.
  2. In the connection URL, set the AwsCredentialsProviderClass property to com.example.CustomSessionCredentialsProvider.
  3. Set the AwsCredentialsProviderArguments property to "My_Access_Key, My_Secret_Key, My_Token".
  4. Generate My_Access_Key, My_Secret_Key and My_Token using AWS Security Token Service. For detailed instructions, see "Temporary Security Credentials" in the AWS Identity and Access Management User Guide: http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html.

For code examples that demonstrate how to create and use the CustomSessionCredentialsProvider in a Java application, see Example: CustomSessionCredentialsProvider.

To use a custom credential provider in an application that has a graphical user interface (GUI), start by exporting the implementation as a JAR file. Then, using the options in the application, include that JAR file along with the connector JAR files.