Using the Active Directory Federation Services (AD FS) Credentials Provider

You can configure the connector to authenticate the connection using the AD FS credentials provider, which obtains credentials from the AD FS identity provider. To do this, connect to Athena using a connection URL that does either of the following:

• Includes property settings that specify information about the AD FS service. For more information, see Specifying AD FS Information in the Connection URL.
• Refers to an AWS profile that specifies information about the AD FS service. For more information, see Specifying AD FS Information in an AWS Profile.

When the connector connects to Athena, it retrieves temporary credentials from the AD FS identity provider. If these credentials are associated with an IAM role that has permission to access Athena, the connector immediately uses these credentials to authenticate the connection to Athena. Otherwise, you must exchange the temporary credentials for more specialized AWS credentials, which can then be used to authenticate the connection. For post-SAML workflows such as exchanging temporary credentials for specialized ones, the connector provides a post-SAML workflow hook. For more information, see Using the Post-SAML Workflow Hook.

Specifying AD FS Information in the Connection URL

In your connection URL, set properties to specify information such as the host and port of the server where the AD FS service is hosted.

If your connection URL also specifies an AWS profile that contains some AD FS information, then the settings specified directly in the URL take precedence over the AD FS information in the profile, and the AWSCredentialsProviderClass property must be specified in the profile instead of the connection URL.

Note: Some properties can be set through aliases, as described below. If you specify both a property name and its alias, the setting associated with the property name takes precedence.

To specify AD FS information in the connection URL:

• In your connection URL, set the following properties:

  Property	Value
  AWSCredentialsProviderClass As alternatives, you can configure this property using the aliases aws_credentials_provider_class or plugin_name. If you specify both aliases, the setting associated with aws_credentials_provider_class takes precedence.	The FQCN that implements the AD FS credentials provider.
  IdP_Host	The host name of the AD FS service that you are using to authenticate the connection. The host name cannot include any slashes (/).
  IdP_Port	The number of the port that the AD FS service host uses to listen for requests. The exact port number that you need to specify may differ depending on the AD FS server configuration. If you are not sure which port to specify, contact your system administrator.
  User As an alternative, you can configure this property using the alias UID.	The user name that you use to access the AD FS server. You can include the domain name using the format [DomainName]\[UserName]. On Windows machines, if you do not provide a user name, the connector attempts to authenticate to the AD FS server using your Windows user name over the NTLM protocol.
  Password As an alternative, you can configure this property using the alias PWD.	The password corresponding to your user name that you specified in the User or UID property. On Windows machines, if you do not provide a password, the connector attempts to authenticate to the AD FS server using your Windows password over the NTLM protocol.
  preferred_role As an alternative, you can use your own relying party identifier by setting the loginToRP property and overriding the ADFS endpoint URL.	The Amazon Resource Name (ARN) of the role that you want to assume when authenticated through AD FS.
  SSL_Insecure If this is not set, the default is false.	One of the following: false if you want the connector to verify the server certificate. true if you do not want the connector to verify the server certificate.

  For example:

  jdbc:awsathena://AwsRegion=us-east-1;S3OutputLocation=s3://test;AwsCredentialsProviderClass=com.simba.athena.iamsupport.plugin.AdfsCredentialsProvider;idp_host=example.adfs.server;idp_port=443;User=HOME\jsmith;Password=simba12345;preferred_role=arn:aws:iam::123456789123:role/JSMITH;ssl_insecure=true;Duration=900;

  Note:

  Optionally, in the Duration field, type the duration of the role session in seconds.

  When you connect to Athena, the connector retrieves temporary credentials from AD FS. If these credentials are not associated with an IAM role that has permission to access Athena, then you must exchange them for more specialized AWS credentials before the connector can authenticate the connection. For information about how to complete this process, see Using the Post-SAML Workflow Hook.

Specifying AD FS Information in an AWS Profile

In your AWS credentials file, define a profile that specifies information such as the host and port of the server where the AD FS service is hosted, and your credentials for accessing the AD FS service. Then, in your connection URL, set the profile property to the name of that profile.

By default, the AWS credentials file is located in ~/.aws/credentials. You can change this default behavior by setting the AWS_CREDENTIAL_PROFILES_FILE environment variable to the full path and name of a different credentials file. For more information about profiles, see "Working with AWS Credentials" in the AWS SDK for Java Developer Guide: https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html.

If any AD FS information is also specified directly in your connection URL, those settings take precedence over the AD FS information in the profile.

To specify AD FS information in an AWS profile:

1. In your AWS credentials file, define a profile that specifies the following property settings. Start by providing the name of the profile in brackets ([ ]), and then specify each property on separate lines.

   Property	Value
   AWSCredentialsProviderClass As alternatives, you can configure this property using the aliases aws_credentials_provider_class or plugin_name. If you specify both aliases, the setting associated with aws_credentials_provider_class takes precedence.	The FQCN that implements the AD FS credentials provider.
   IdP_Host	The host name of the AD FS service that you are using to authenticate the connection. The host name cannot include any slashes (/).
   IdP_Port	The number of the port that the AD FS service host uses to listen for requests. You can specify any port that is available on your AD FS server. If you are not sure which port to specify, contact your system administrator.
   User As an alternative, you can configure this property using the alias UID.	The user name that you use to access the AD FS server. You can include the domain name using the format [DomainName]\[UserName]. On Windows machines, if you do not provide a user name, the connector attempts to authenticate to the AD FS server using your Windows user name over the NTLM protocol.
   Password As an alternative, you can configure this property using the alias PWD.	The password corresponding to your user name that you specified in the User or UID property. On Windows machines, if you do not provide a password, the connector attempts to authenticate to the AD FS server using your Windows password over the NTLM protocol.
   preferred_role	The Amazon Resource Name (ARN) of the role that you want to assume when authenticated through AD FS.
   SSL_Insecure If this is not set, the default is false.	One of the following: false if you want the connector to verify the server certificate. true if you do not want the connector to verify the server certificate.

   For example, the following is an AWS profile named plug-in-creds-lambda that specifies all the required AD FS service information:

   [plug-in-creds-lambda]

   plugin_name=com.providers.AdfsLambdaCredentialProvider

   idp_host=example.adfs.server

   idp_port=443

   preferred_role=arn:aws:iam::123456789123:role/JSMITH

   user=HOME\jsmith

   password=simba12345

2. In your connection URL, set the profile property to the name of the profile.

   For example:

   jdbc:awsathena://AwsRegion=us-east-1;S3OutputLocation=s3://test;profile=plug-in-creds-lambda;

When you connect to Athena, the connector checks the AWS credentials file for the specified profile, and then uses the AD FS information given in the profile to retrieve temporary credentials from AD FS. If these credentials are not associated with an IAM role that has permission to access Athena, then you must exchange them for more specialized AWS credentials before the connector can authenticate the connection. For information about how to complete this process, see Using the Post-SAML Workflow Hook.