Using the Post-SAML Workflow Hook

In some cases, after retrieving credentials through a SAML workflow, you may need to modify the credentials before they can actually be used to authenticate your connection to Athena. For example, if you retrieve temporary credentials from an AD FS provider, and these credentials are not associated with an IAM role that has permission to access Athena, you must exchange them for more specialized AWS credentials before you can authenticate the connection. The connector provides a post-SAML workflow hook that enables you to go through such processes.

To exchange the temporary credentials from AD FS for more specialized AWS credentials, do the following:

  1. Extend the default AD FS credentials provider class. The FQCN of this class is:

    com.simba.athena.iamsupport.plugin.AdfsCredentialsProvider

  2. Override the performPostSAMLAction() method with the post-SAML workflow hook. For details, see below.

    Note: For a complete implementation example, see Example: Implementing a Custom Credentials Provider that uses the Post-SAML Workflow Hook.

    To override the performPostSAMLAction() method, use a post-SAML workflow hook that includes your AD FS user name, the temporary credentials returned by the AD FS service, and a SAML assertion that determines how these credentials are exchanged for AWS credentials.

The function signature of the hook is as follows:

/** Perform custom actions after the temporary credentials are available. *

* @param username - Your AD FS user name.

* @param samlAssertion - The Base64-encoded SAML assertion.

* @param credentials - The temporary credentials from the AssumeRoleWithSAML request.

* @return - The CredentialsHolder wrapper object containing the AWS credentials. */

@Override

protected CredentialsHolder performPostSAMLAction(

String username,

String samlAssertion,

CredentialsHolder credentials) throws SdkClientException

Important:

It is recommended that you specify @Override, as this enables the build to return an error if a class mismatch occurs.

This implementation causes the following to occur:

  1. The AD FS credentials provider class obtains the following:
    • The SAML assertion from the AD FS provider.
    • The temporary credentials with the AssumeRoleWithSAML API from STS.
  2. The specified AD FS user name, SAML assertion, and temporary credentials are passed into the performPostSAMLAction() method.
  3. The method returns a CredentialsHolder wrapper object containing your AWS credentials for authenticating your connection to Athena.
    Note:

    If the method returns NULL, this indicates that your credentials were not exchanged. This can occur if you pass in credentials that do not need to be exchanged and can be used immediately for authentication. If NULL is being returned unexpectedly, make sure that the post-SAML workflow hook is implemented properly and that the correct parameter values are being passed in.

  4. The connector authenticates the connection to Athena using the credentials returned by the implementation.

The FQCN of the CredentialsHolder is:

com.simba.athena.iamsupport.model.CredentialsHolder

The CredentialsHolder can optionally include an expiration date for the returned credentials. If the expiration date is not included, then the function signature is as follows:

/** Creates a new instance of the CredentialsHolder.

* @param credentials - The AWS credentials.

* @param expiration - The expiration date.

* @return - The CredentialsHolder.

*/public static CredentialsHolder newInstance(AWSCredentials credentials)

If the expiration date is included, then the function signature is as follows:

/** Creates a new instance of the CredentialsHolder.

* @param credentials - The AWS credentials.

* @param expiration - The expiration date.

* @return - The CredentialsHolder.

*/public static CredentialsHolder newInstance(AWSCredentials credentials, Date expiration)