Using the Okta Credentials Provider

You can configure the connector to authenticate the connection using the Okta credentials provider, which obtains credentials from the Okta 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 Okta service. For more information, see Specifying Okta Information in the Connection URL.
  • Refers to an AWS profile that specifies information about the Okta service. For more information, see Specifying Okta 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 Okta 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 Okta Information in the Connection URL

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

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

  • In your connection URL, set the following properties:
    PropertyValue

    IdP_Host

    The host name of the Okta service that you are using to authenticate the connection.

    The host name cannot include any slashes (/).

    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 Okta credentials provider.

    App_ID

    The Okta-provided unique ID associated with your Athena application.

    App_Name

    (Optional) The name of the Okta application that you use to authenticate the connection to Athena.

    User

    As an alternative, you can configure this property using the alias UID.

    The email address that you use to access the Okta 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

    The Amazon Resource Name (ARN) of the role that you want to assume when authenticated through Okta.

    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.
    okta_mfa_type

    The factor type when using Okta MFA authentication, from the following list:

    • oktaverifywithtotp
    • oktaverifywithpush
    • SmsAuthentication
    • GoogleAuthenticator
    okta_mfa_wait_timeThe MFA timeout value, in seconds.
    okta_phone_numberThe phone number used to receive a one-time password for SMS Authentication.

    Example of connection URL with Okta:

    jdbc:awsathena://AwsRegion=us-east-1;S3OutputLocation=s3://test;AwsCredentialsProviderClass=com.simba.athena.iamsupport.plugin.OktaCredentialsProvider;UID=jsmith@acme.com;PWD=simba12345;idp_host=123456.okta.com;app_id=45L3MDWLKM4EDMWR34M;ssl_insecure=true;

    Example of connection URL with Okta MFA:

    jdbc:awsathena://AwsRegion=us-east-1;S3OutputLocation=s3://test;AwsCredentialsProviderClass=com.simba.athena.iamsupport.plugin.OktaCredentialsProvider;UID=jsmith@acme.com;PWD=simba12345;idp_host=123456.okta.com;app_id=45L3MDWLKM4EDMWR34M;ssl_insecure=true;okta_mfa_type=GoogleAuthenticator;

    When you connect to Athena, the connector retrieves temporary credentials from Okta. 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 Okta 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 Okta service is hosted, and your credentials for accessing the Okta 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 Okta information is also specified directly in your connection URL, those settings take precedence over the Okta 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 Okta 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.
    PropertyValue

    IdP_Host

    The host name of the Okta service that you are using to authenticate the connection.

    The host name cannot include any slashes (/).

    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 Okta credentials provider.

    App_ID

    The Okta-provided unique ID associated with your Athena application.

    App_Name

    (Optional) The name of the Okta application that you use to authenticate the connection to Athena .

    User

    As an alternative, you can configure this property using the alias UID.

    The email address that you use to access the Okta server.

    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.

    preferred_role

    The Amazon Resource Name (ARN) of the role that you want to assume when authenticated through Okta.

    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-okta that specifies all the required Okta service information:

    [plug-in-creds-okta]

    plugin_name=com.simba.athena.iamsupport.plugin.OktaCredentialsProvider

    idp_host=123456.okta.com

    app_id=45L3MDWLKM4EDMWR34M

    uid=jsmith@acme.com

    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-okta;ssl_insecure=true;

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