Options for providing IAM credentials - Amazon Redshift
Using a configuration profileJDBC and ODBC options for providing IAM credentialsJDBC and ODBC options for creating database user credentialsCredentials provider plugins

Options for providing IAM credentials

To provide IAM credentials for a JDBC or ODBC connection, choose one of the following options.

  • AWS profile

    As an alternative to providing credentials values in the form of JDBC or ODBC settings, you can put the values in a named profile. For more information, see Using a configuration profile.

  • IAM credentials

    Provide values for AccessKeyID, SecretAccessKey, and, optionally, SessionToken in the form of JDBC or ODBC settings. SessionToken is required only for an IAM role with temporary credentials. For more information, see JDBC and ODBC options for providing IAM credentials.

  • Identity provider federation

    When you use identity provider federation to enable users from an identity provider to authenticate to Amazon Redshift, specify the name of a credential provider plugin. For more information, see Credentials provider plugins.

    The Amazon Redshift JDBC and ODBC drivers include plugins for the following SAML-based identity federation credential providers:

    • Microsoft Active Identity Federation Services (AD FS)

    • PingOne

    • Okta

    • Microsoft Azure Active Directory (Azure AD)

    You can provide the plugin name and related values in the form of JDBC or ODBC settings or by using a profile. For more information, see Options for JDBC driver version 2.1 configuration.

For more information, see Step 5: Configure a JDBC or ODBC connection to use IAM credentials.

Using a configuration profile

You can supply the IAM credentials options and GetClusterCredentials options as settings in named profiles in your AWS configuration file. To provide the profile name, use the Profile JDBC option. The configuration is stored in a file named config or a file named credentials in a folder named .aws in your home directory.

For a SAML-based credential provider plugin included with an Amazon Redshift JDBC or ODBC driver, you can use the settings described just preceding in Credentials provider plugins. If plugin_name isn't used, the other options are ignored.

The following example shows the ~/.aws/credentials file with two profiles.

[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[user2]
aws_access_key_id=AKIAI44QH8DHBEXAMPLE
aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
session_token=AQoDYXdzEPT//////////wEXAMPLEtc764bNrC9SAPBSM22wDOk4x4HIZ8j4FZTwdQWLWsKWHGBuFqwAeMicRXmxfpSPfIeoIYRqTflfKD8YUuwthAx7mSEI/qkPpKPi/kMcGd
QrmGdeehM4IC1NtBmUpp2wUE8phUZampKsburEDy0KPkyQDYwT7WZ0wq5VSXDvp75YU
9HFvlRd8Tx6q6fE8YQcHNVXAkiY9q6d+xo0rKwT38xVqr7ZD0u0iPPkUL64lIZbqBAz
+scqKmlzm8FDrypNC9Yjc8fPOLn9FX9KSYvKTr4rvx3iSIlTJabIQwj2ICCR/oLxBA==

To use the credentials for the user2 example, specify Profile=user2 in the JDBC URL.

For more information on using profiles, see Configuration and credential file settings in the AWS Command Line Interface User Guide.

For more information on using profiles for the JDBC driver, see Specifying profiles.

For more information on using profiles for the ODBC driver, see Authentication methods.

JDBC and ODBC options for providing IAM credentials

The following table lists the JDBC and ODBC options for providing IAM credentials.

Option

 Description

Iam

 For use only in an ODBC connection string. Set to 1 to use IAM authentication.

AccessKeyID

SecretAccessKey

SessionToken

 The access key ID and secret access key for the IAM role or user configured for IAM database authentication. SessionToken is required only for an IAM role with temporary credentials. SessionToken isn't used for a user. For more information, see Temporary Security Credentials.
plugin_name The fully qualified name of a class that implements a credentials provider. The Amazon Redshift JDBC driver includes SAML-based credential provider plugins. If you provide plugin_name, you can also provide other related options. For more information, see Credentials provider plugins.

Profile

The name of a profile in an AWS credentials or config file that contains values for the JDBC connection options. For more information, see Using a configuration profile.

JDBC and ODBC options for creating database user credentials

To use the Amazon Redshift JDBC or ODBC driver to create database user credentials, provide the database user name as a JDBC or ODBC option. Optionally, you can have the driver create a new database user if one doesn't exist, and you can specify a list of database user groups the user joins at login.

If you use an identity provider (IdP), work with your IdP administrator to determine the correct values for these options. Your IdP administrator can also configure your IdP to provide these options, in which case you don't need to provide them as JDBC or ODBC options. For more information, see Step 2: Configure SAML assertions for your IdP.

Note

If you use an IAM policy variable ${redshift:DbUser}, as described in Resource policies for GetClusterCredentials the value for DbUser is replaced with the value retrieved by the API operation's request context. The Amazon Redshift drivers use the value for the DbUser variable provided by the connection URL, rather than the value supplied as a SAML attribute.

To help secure this configuration, we recommend that you use a condition in an IAM policy to validate the DbUser value with the RoleSessionName. You can find examples of how to set a condition using an IAM policy in Example policy for using GetClusterCredentials.

The following table lists the options for creating database user credentials.

Option

 Description
DbUser

The name of a database user. If a user named DbUser exists in the database, the temporary user credentials have the same permissions as the existing user. If DbUser doesn't exist in the database and AutoCreate is true, a new user named DbUser is created. Optionally, disable the password for an existing user. For more information, see ALTER_USER
AutoCreate

Specify true to create a database user with the name specified for DbUser if one does not exist. The default is false.
DbGroups A comma-delimited list of the names of one or more existing database groups the database user joins for the current session. By default, the new user is added only to PUBLIC.

Credentials provider plugins

Amazon Redshift uses credentials provider plugins for single sign-on authentication.

To support single sign-on authentication, Amazon Redshift provides the Azure AD plugin for Microsoft Azure Active Directory. For information on how to configure this plugin, see Setting up JDBC or ODBC single sign-on authentication.

Multi-factor authentication

To support multi-factor authentication (MFA), Amazon Redshift provides browser-based plugins. Use the browser SAML plugin for Okta, PingOne, and the browser Azure AD plugin for Microsoft Azure Active Directory.

With the browser SAML plugin, OAuth authentication flows like this:

OAuth workflows for how the plugin, local server, web browser, and endpoint work together to authenticate a user with SAML authentication.

  1. A user tries to log in.

  2. The plugin launches a local server to listen to incoming connections on the localhost.

  3. The plugin launches a web browser to request a SAML response over HTTPS from the specified single sign-on login URL federated identity provider endpoint.

  4. The web browser follows the link and prompts the user to enter credentials.

  5. After the user authenticates and grants consent, the federated identity provider endpoint returns a SAML response over HTTPS to the URI indicated by redirect_uri.

  6. The web browser moves the response message with the SAML response to the indicated redirect_uri.

  7. The local server accepts the incoming connection and the plugin retrieves the SAML response and passes it to Amazon Redshift.

With the browser Azure AD plugin, SAML authentication flows like this:

Azure workflows for how the plugin, local server, web browser, and endpoint work together to authenticate a user with SAML authentication.

  1. A user tries to log in.

  2. The plugin launches a local server to listen to incoming connections on the localhost.

  3. The plugin launches a web browser to request an authorization code from the Azure AD oauth2/authorize endpoint.

  4. The web browser follows the generated link over HTTPS and prompts the user to enter credentials. The link is generated using configuration properties, such as tenant and client_id.

  5. After the user authenticates and grants consent, the Azure AD oauth2/authorize endpoint returns and sends a response over HTTPS with the authorization code to the indicated redirect_uri.

  6. The web browser moves the response message with the SAML response to the indicated redirect_uri.

  7. The local server accepts the incoming connection and the plugin requests and retrieves the authorization code and sends a POST request to the Azure AD oauth2/token endpoint.

  8. The Azure AD oauth2/token endpoint returns a response with an access token to the indicated redirect_uri.

  9. The plugin retrieves the SAML response and passes it to Amazon Redshift.

See the following sections:

Plugin options

To use a SAML-based credentials provider plugin, specify the following options using JDBC or ODBC options or in a named profile. If plugin_name isn't specified, the other options are ignored.

Option

 Description
plugin_name

For JDBC, the class name that implements a credentials provider. Specify one of the following:

  • For Active Directory Federation Services

    com.amazon.redshift.plugin.AdfsCredentialsProvider

  • For Okta

    com.amazon.redshift.plugin.OktaCredentialsProvider

  • For PingFederate

    com.amazon.redshift.plugin.PingCredentialsProvider

  • For Microsoft Azure Active Directory

    com.amazon.redshift.plugin.AzureCredentialsProvider

  • For SAML MFA

    com.amazon.redshift.plugin.BrowserSamlCredentialsProvider

  • For Microsoft Azure Active Directory single sign-on with MFA

    com.amazon.redshift.plugin.BrowserAzureCredentialsProvider

For ODBC, specify one of the following:

  • For Active Directory Federation Services: adfs

  • For Okta: okta

  • For PingFederate: ping

  • For Microsoft Azure Active Directory: azure

  • For SAML MFA: browser saml

  • For Microsoft Azure Active Directory single sign-on with MFA: browser azure ad
idp_host The name of the corporate identity provider host. This name should not include any slashes (‘/’). For an Okta identity provider, the value for idp_host should end with .okta.com.

idp_port

The port used by the identity provider. The default is 443. This port is ignored for Okta.

preferred_role

A role Amazon Resource Name (ARN) from the AttributeValue elements for the Role attribute in the SAML assertion. To find the appropriate value for the preferred role, work with your IdP administrator. For more information, see Step 2: Configure SAML assertions for your IdP.

user

A corporate user name, including the domain when applicable. For example, for Active Directory, the domain name is required in the format domain\username.
password

The corporate user's password. We recommend not using this option. Instead, use your SQL client to supply the password.

app_id

An ID for an Okta application. Used only with Okta. The value for app_id follows amazon_aws in the Okta application embed link. To get this value, work with your IdP administrator. The following is an example of an application embed link: https://example.okta.com/home/amazon_aws/0oa2hylwrpM8UGehd1t7/272

idp_tenant

 A tenant used for Azure AD. Used only with Azure.

client_id

A client ID for the Amazon Redshift enterprise application in Azure AD. Used only with Azure.