Using the Ping Credentials Provider

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

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

Important:

• If any information is included in both places, the information specified directly in the connection URL takes precedence over the information in the profile.
• If the connection URL refers to an AWS profile, then the AWSCredentialsProviderClass property must be specified in the profile instead of the connection URL.

When the connector connects to Athena, it retrieves temporary credentials from the Ping 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 Ping Information in the Connection URL

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

If your connection URL also specifies an AWS profile that contains some Ping information, then the settings specified directly in the URL take precedence over the Ping 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 Ping information in the connection URL:

• In your connection URL, set the following properties:

  Property	Value
  IdP_Host	The host name of the PingFederate 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 PingFederate service host uses to listen for requests.
  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 Ping credentials provider.
  Partner_SPID	The partner SPID (service provider ID) value to use when authenticating the connection using the PingFederate service.
  User As an alternative, you can configure this property using the alias UID.	The name that you use to access the PingFederate server.
  Password As an alternative, you can configure this property using the alias PWD.	The password corresponding to your user name specified in the User or UID property.
  preferred_role	(Optional) The Amazon Resource Name (ARN) of the role that you want to assume when authenticated through PingFederate.
  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.

Example of a connection URL with Ping:

jdbc:awsathena://AwsRegion=us-east-1;S3OutputLocation=s3://test;AwsCredentialsProviderClass=com.simba.athena.iamsupport.plugin.PingCredentialsProvider;UID=[e-mail];PWD=simba12345;idp_host=123456.ping.com;idp_port=12345;partner_spid=45L3MDWLKM4EDMWR34M;ssl_insecure=true;

When you connect to Athena, the connector retrieves temporary credentials from Ping. 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 Ping Information in an AWS Profile

In your AWS credentials file, define a profile that specifies information such as the host of the server where the PingFederate service is hosted, and your credentials for accessing the PingFederate 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 Ping information is also specified directly in your connection URL, those settings take precedence over the Ping information in the profile.

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 Ping 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
   IdP_Host	The host name of the PingFederate 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 PingFederate service host uses to listen for requests.
   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 Ping credentials provider.
   Partner_SPID	The partner SPID (service provider ID) value to use when authenticating the connection using the PingFederate service.
   User As an alternative, you can configure this property using the alias UID.	The name that you use to access the PingFederate server.
   Password As an alternative, you can configure this property using the alias PWD.	The password corresponding to your user name specified in the User or UID property.
   preferred_role	(Optional) The Amazon Resource Name (ARN) of the role that you want to assume when authenticated through PingFederate.
   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-ping that specifies all the required PingFederate service information:

[plug-in-creds-ping]
plugin_name=com.simba.athena.iamsupport.plugin.PingCredentialsProvider
idp_host=123456.ping.com
idp_port=12345
partner_spid=45L3MDWLKM4EDMWR34M
uid=[e-mail]
pwd=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-athena-output-us-east-1/;profile=plug-in-creds-ping;ssl_insecure=true;

When you connect to Athena, the connector checks the AWS credentials file for the specified profile, and then uses the Ping information given in the profile to retrieve temporary credentials from Ping. 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.