Skip to content

Athena Authentication

Athena queries do not run inside Qualytics — they run inside your AWS account, against the Athena service, the Glue catalog, and the S3 bucket where Athena writes query results. Every API call the AWS Athena JDBC driver (v3) sends to AWS carries an IAM identity, and AWS uses that identity to decide whether the call is allowed.

The Authentication section of the connection form is where you tell Qualytics which IAM identity to use. You have two options.

Access Key

With Access Key authentication, you create an IAM user in your AWS account and give Qualytics its credentials — an Access Key ID and a Secret Access Key. Every query Qualytics runs uses these credentials, so the IAM user behind them needs permissions for Athena, Glue, and the query-results S3 bucket (see Athena Permissions for the exact list).

This is the simplest setup. It works well when:

  • You are testing Athena or running it in a development environment.
  • Your security policy allows storing static AWS credentials.
  • You do not need cross-account access.

The trade-off is that the credentials are static. You are responsible for changing them when they expire or get leaked, and you must update them in both AWS and Qualytics each time.

IAM Role

AWS-only

IAM Role authentication is available only on AWS and local Qualytics deployments. On Azure and GCP deployments, the Type selector and the IAM Role fields are not exposed in the connection form — only Access Key authentication is offered there.

With IAM Role authentication, you do not share any static credentials with Qualytics. Instead, you create an IAM role in your AWS account and let Qualytics assume it. When Qualytics needs to run a query, it asks AWS STS for temporary credentials for that role, then uses them to call Athena. AWS issues a fresh set of credentials roughly once an hour, and Qualytics requests new ones automatically before the current ones expire.

This is the recommended option for production. It works well when:

  • Your security policy disallows storing static AWS credentials.
  • Your data lives in a different AWS account from Qualytics.
  • You want every connection logged and auditable in AWS CloudTrail.

How the assume-role flow works

When Qualytics connects to Athena using IAM Role authentication:

  1. Qualytics's AWS identity (the dataplane's base role) calls sts:AssumeRole against the role ARN you entered in the connection form.
  2. AWS checks the role's trust policy to confirm the calling identity is allowed to assume the role. If you supplied an External ID, AWS also checks that it matches the one in the trust policy.
  3. If the checks pass, AWS returns temporary credentials valid for the role's session duration (typically 1 hour).
  4. The Athena JDBC driver uses those temporary credentials to call Athena, Glue, and S3 — all inside your account, with the permissions attached to the role.
  5. Qualytics caches the credentials until just before they expire, then requests a fresh set automatically. You do not need to manage refresh.

Each AssumeRole call appears in your CloudTrail logs under the session name qualytics-athena-<id>, where <id> identifies the connection.

The base role (the dataplane identity that calls sts:AssumeRole) and the target role (the role you enter in the connection form) are described in detail in IAM Role Authentication, including who provisions each one for Managed vs Self-Hosted deployments.

About the External ID

The External ID is an extra security check on top of the trust policy. When you require an External ID in your role's trust policy, only AssumeRole calls that pass the matching value succeed. Even if Qualytics's own identity were ever misused, an attacker still could not assume your role without also knowing your External ID.

In Qualytics, the External ID is optional — supply it only if your trust policy requires one. AWS strongly recommends using an External ID whenever you grant a third party (such as Qualytics) the ability to assume a role in your account.

Host requirement

Warning

The connection's Host must be the canonical Athena endpoint for your region (athena.<region>.amazonaws.com). VPC endpoint URLs (vpce-…) and custom Route 53 / private DNS aliases are not supported.

Both the UI form (Host field) and the API (connection.host) take this full hostname. Substitute <region> for the AWS region where your Athena workgroup runs (e.g., athena.us-east-1.amazonaws.com).

Setting up IAM Role authentication

For the full setup — trust policies, base role provisioning per deployment type, and the Athena/Glue/S3 permissions you attach to the target role — see IAM Role Authentication.