Amazon Athena
User Guide

Enabling Federated Access to Athena API

This section discusses federated access that allows a user or client application in your organization to call Athena API operations. In this case, your organization's users don't have direct access to Athena. Instead, you manage user credentials outside of AWS in Microsoft Active Directory. Active Directory supports SAML 2.0 (Security Assertion Markup Language 2.0).

In this case, to authenticate users, use the JDBC or ODBC driver with SAML.2.0 support that accesses Active Directory Federation Services (AD FS) 3.0 and enables a client application to call Athena API operations.

For more information about SAML 2.0 support in AWS, see About SAML 2.0 Federation in the IAM User Guide.

Note

Federated access to Athena API is supported for a particular type of identity provider (IdP), the Active Directory Federation Service (AD FS 3.0), which is part of Windows Server. Access is established through the versions of JDBC or ODBC drivers that support SAML 2.0. For information, see Using Athena with the JDBC Driver and Connecting to Amazon Athena with ODBC.

Before You Begin

Before you begin, complete the following prerequisites:

Architecture Diagram

The following diagram illustrates this process.


                The diagram of the federated access to Athena API.

In this diagram:

  1. A user in your organization uses a client application with the JDBC or ODBC driver to request authentication from your organization's IdP. The IdP is AD FS 3.0.

  2. The IdP authenticates the user against Active Directory, which is your organization's Identity Store.

  3. The IdP constructs a SAML assertion with information about the user and sends the assertion to the client application via the JDBC or ODBC driver.

  4. The JDBC or ODBC driver calls the AWS Security Token Service AssumeRoleWithSAML API operation, passing it the following parameters:

    • The ARN of the SAML provider

    • The ARN of the role to assume

    • The SAML assertion from the IdP

    For more information, see AssumeRoleWithSAML, in the AWS Security Token Service API Reference.

  5. The API response to the client application via the JDBC or ODBC driver includes temporary security credentials.

  6. The client application uses the temporary security credentials to call Athena API operations, allowing your users to access Athena API operations.

Procedure: SAML-based Federated Access to Athena API

In this procedure, actions take place either on the side of your organization, or within AWS. The procedure provides steps that establish trust between your organization's IdP and your AWS account to enable SAML-based federated access to the AWS Athena API operation.

To enable federated access to the Athena API:

  1. In your organization, register AWS as a service provider (SP) in your IdP. This process is known as relying party trust. For more information, see Configuring your SAML 2.0 IdP with Relying Party Trust in the IAM User Guide. As part of this task, perform these steps:

    1. Obtain the sample SAML metadata document from this URL: https://signin.aws.amazon.com/static/saml-metadata.xml.

    2. In your organization's IdP (AD FS), generate an equivalent metadata XML file that describes your IdP as an identity provider to AWS. Your metadata file must include the issuer name, creation date, expiration date, and keys that AWS uses to validate authentication responses (assertions) from your organization.

  2. In the IAM console, create a SAML identity provider entity. For more information, see Creating SAML Identity Providers in the IAM User Guide. As part of this step, do the following:

    1. Open the IAM console at https://console.aws.amazon.com/iam/.

    2. Upload the SAML metadata document produced by the IdP (AD FS) in Step 1 in this procedure.

  3. In the IAM console, create one or more IAM roles for your IdP. For more information, see Creating a Role for a Third-Party Identity Provider (Federation) in the IAM User Guide. As part of this step, do the following:

    • In the role's permission policy, list actions that users from your organization are allowed to do in AWS.

    • In the role's trust policy, set the SAML provider entity that you created in Step 2 of this procedure as the principal.

    This establishes a trust relationship between your organization and AWS.

  4. In your organization's IdP (AD FS), define assertions that map users or groups in your organization to the IAM roles. The mapping of users and groups to the IAM roles is also known as a claim rule. Note that different users and groups in your organization might map to different IAM roles.

    For information about configuring the mapping in AD FS, see the blog post: Enabling Federation to AWS Using Windows Active Directory, ADFS, and SAML 2.0.

  5. Install and configure the JDBC or ODBC driver with SAML 2.0 support. For information, see Using Athena with the JDBC Driver and Connecting to Amazon Athena with ODBC.

  6. Specify the connection string from your application to the JDBC or ODBC driver. For information about the connection string that your application should use, see the topic "Using the Active Directory Federation Services (ADFS) Credentials Provider" in the JDBC Driver Installation and Configuration Guide, or a similar topic in the ODBC Driver Installation and Configuration Guide.

    The high-level summary of configuring the connection string to the drivers is as follows:

    • In the AwsCredentialsProviderClass configuration, set the com.simba.athena.iamsupport.plugin.AdfsCredentialsProvider to indicate that you want to use SAML 2.0 based authentication via AD FS IdP.

    • For idp_host, provide the host name of the AD FS IdP server.

    • For idp_port, provide the port number that the AD FS IdP listens on for the SAML assertion request.

    • For UID and PWD, provide the AD domain user credentials. When using the driver on Windows, if UID and PWD are not provided, the driver attempts to obtain the user credentials of the user logged in to the Windows machine.

    • Optionally, set ssl_insecure to true. In this case, the driver does not check the authenticity of the SSL certificate for the AD FS IdP server. Setting to true is needed if the AD FS IdP’s SSL certificate has not been configured to be trusted by the driver.

    • To enable mapping of an Active Directory domain user or group to one or more IAM roles (as mentioned in step 4 of this procedure), in the preferred_role for the JDBC or ODBC connection, specify the IAM role (ARN) to assume for the driver connection. Specifying the preferred_role is optional, and is useful if the role is not the first role listed in the claim rule.

    As a result, the following actions occur:

    1. The JDBC or ODBC driver calls the AWS STS AssumeRoleWithSAML API, and passes it the assertions, as shown in step 4 of the architecture diagram.

    2. AWS makes sure that the request to assume the role comes from the IdP referenced in the SAML provider entity.

    3. If the request is successful, the AWS STS AssumeRoleWithSAML API operation returns a set of temporary security credentials, which your client application uses to make signed requests to Athena.

      Your application now has information about the current user and can access Athena programmatically.