OCF Connector for Amazon Athena: SSO with Compose

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

For Amazon Athena, Alation supports SSO with a SAML 2.0-compliant IdP and AWS IAM for Compose, dynamic sampling and profiling, query forms, and data upload.

If you have multiple Athena data sources, SSO authentication should be configured for each specific data source. Multiple data sources can use one and the same AuthService configuration object if authentication goes through the same authentication application in the same IdP.

Note

This configuration requires access to the backend of the Alation server. For Alation Cloud Service instances, create a support ticket with Alation requesting the configuration of SSO for Compose.

To configure SSO authentication for Compose:

1. Create an authentication application for Alation in your IdP: Compose SSO for AWS Data Sources: Create an Authentication Application.

2. Create an authentication object for the AWS IAM plug-in of AuthService. You can either create it on the backend of the Alation server or in the Alation user interface.

   • Backend: Compose SSO with AWS Sources: Configure AWS IAM Plug-in

   • User interface: Authentication Configuration Methods for External Systems

3. Get your Amazon Athena data source ID. The data source ID can be obtained from the URL of the Data Source Catalog page: How to Find Data Source ID.

4. Configure Compose to use the IAM plug-in authentication object. This configuration is performed on the backend of the Alation server.

To configure Compose to use the IAM plug-in authentication object:

1. Use SSH to connect to the Alation host.

2. Enter the Alation shell, and then enter the Django shell:

   sudo /etc/init.d/alation shell
   alation_django_shell
   

3. From the Django shell, run the code given below, substituting the placeholder values <ds_id> and <config_name> with your real values. As the result, the configuration object of the AuthService IAM plug-in with config_name = <config_name> will apply to a Compose connection to Athena when the connection URI contains the AwsCredentialsProviderClass=com.example.CustomSessionCredentialsProvider parameter.

   • <ds_id>—Data source ID

   • <config_name>—config_name value of the configuration object in the AWS IAM plug-in of the AuthService that has been created for your IdP.

   AuthServiceConfiguration.objects.create(
       ds_id=<ds_id>,
       method_name='aws_iam',
       config_name='<config_name>',
       jdbc_config={
           'auth_obj_to_jdbc_param_map':{
               'AWSCredentialsProviderArguments': '{AWSAccessKey},{AWSSecretKey},{AWSSessionToken}'
           },
           'jdbc_uri_enabler_patterns': [
               'AwsCredentialsProviderClass\\=com\\.example\\.CustomSessionCredentialsProvider'
           ],
           'jdbc_uri_to_auth_service_args_map': {
               'role': [
                   'preferred_role=(arn:aws:iam::[^:]+:role/[^;]+)'
                 ]
           },
           'require_strict_jdbc_uri_to_auth_service_args_map': False
       })
   

4. (Optional) Run the command below to check that the Compose configuration object has been created for your Amazon Athena data source, substituting the placeholder values <ds_id> and <config_name> with real values. The command will output the number of Compose configurations that exist for a data source, the aws_iam AuthService method and the specific AuthService config_name:

   AuthServiceConfiguration.objects.filter(ds_id=<ds_id>, method_name='aws_iam', config_name='<config_name>').count()
   

Important

We recommend creating one Compose configuration that uses the same config_name per data source.

5. Exit the Django shell: exit.

6. Exit the Alation shell: exit.

Configure the Amazon Athena Data Source Settings

Next, complete the configuration in the Alation user interface:

1. Log in to the Alation user interface as a Server Admin or a Data Source Admin for your Amazon Athena data source.

2. Open the Settings > Compose page of the Amazon Athena data source.

3. Create a new Compose connection or edit the default one. To create a new connection, click +Add on the right of the Compose connections section and specify a title for the connection and the URL.

   • Give the connection a meaningful name so that it can be recognized by users in the list of connections in Compose.

   • Add the following parameter to the URI (required to enable authentication redirection from Compose to the IdP):

     AwsCredentialsProviderClass=com.example.CustomSessionCredentialsProvider**
     

   Format:

   awsathena://<your_AWS_URL>:443;S3OutputLocation=s3://<your S3 location>;AwsCredentialsProviderClass=com.example.CustomSessionCredentialsProvider
   

   Example:

   awsathena://athena.us-east-1.amazonaws.com:443;S3OutputLocation=s3://user-s3-location;AwsCredentialsProviderClass=com.example.CustomSessionCredentialsProvider
   

Note

If SSO is the only type of authentication that users are allowed to use in Compose, edit the default Compose connection by adding the AwsCredentialsProviderClass=com.example.CustomSessionCredentialsProvider parameter.

After this configuration is done, users will be able to create and use SSO-enabled connections in Compose. They will connect to Amazon Athena with the AWS role returned in the SAML assertion response from the IdP. If a user is assigned multiple roles and they would like to connect with a specific role only, they will be able to select one of their roles before login. See How to Specify an IAM Role for Connection below for more information.

Test the Configuration

Test Connection in Compose

You can test with a user account that exists in the IdP and has access to Amazon Athena.

For steps to log in Compose using an SSO-enabled connection, see Authenticate to AWS Data Sources with SSO.

If the token request fails, the UI will display an error and connection will not be established. See Troubleshoot SSO Authentication with AWS Data Sources.

Test Dynamic Profiling

This test applies if dynamic profiling is enabled for your Amazon Athena data source:

1. Go to the Alation catalog and open the catalog page of a column.

2. Click Run Profile. The Connection Settings dialog should pop up.

3. Select the SSO-enabled connection from the list of connections.

4. If there is currently no active STS token, a new browser tab should open where you will be redirected to the identity provider login page.

5. Enter your credentials.

6. Upon authentication, the tab will close and you will be able to profile the column.

Test Data Upload

Similarly, you can test the data upload.

1. Go the the Amazon Athena data source page in the catalog.

2. On the upper right, click More, and then click Upload Data.

3. Try to test-upload a table.

How to Specify an IAM Role for Connection

AWS STS allows authenticated users to assume a role and returns temporary credentials that can be used to establish a connection to Amazon Athena.

If the SAML assertion response returns multiple roles for a user, they will be able to select one of their roles from the list roles when they are connecting to the data source:

Note that the role selection can be disabled: Disable Role Selection for SSO-Enabled Data Sources. When role selection is disabled, the driver will assume the first role from the list returned in the SAML response from the IdP unless the preferred_role parameter is included into the URI.

The Compose connection URI for Amazon Athena can include a preferred_role URI parameter that accepts the value of the AWS role ARN. The preferred_role parameter can be specified by a Server Admin who creates a Compose connection in the data source settings or can be specified by a Compose user who creates a new database connection in Compose.

Format:

awsathena://<your_AWS_URL>:443;S3OutputLocation=s3://<your S3 location>;AwsCredentialsProviderClass=com.example.CustomSessionCredentialsProvider;preferred_role=<role_ARN>

Note

The preferred_role parameter is an Alation-specific parameter and is not the same as the preferred_role property of the Simba JDBC driver for Amazon Athena. This parameter is used by Compose to pass the AWS role ARN to Alation AuthService.

The role ARN specified in preferred_role must be listed in SAML assertion associated with the authorization request handled by AuthService. If not, AuthService will issue an error. The Role a user specifies in the connection URI must match the role received in the SAML response from the IdP.