Amazon Redshift will no longer support the creation of new Python UDFs starting Patch 198. Existing Python UDFs will continue to function until June 30, 2026. For more information, see the [ blog post ](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/). # Using IAM authentication to generate database user credentials You can generate temporary database credentials based on permissions granted through an AWS Identity and Access Management (IAM) permissions policy to manage the access that your users have to your Amazon Redshift database. Commonly, Amazon Redshift database users log in to the database by providing a database user name and password. However, you don't have to maintain user names and passwords in your Amazon Redshift database. As an alternative, you can configure your system to permit users to create user credentials and log in to the database based on their IAM credentials. Amazon Redshift provides the [GetClusterCredentials](https://docs.aws.amazon.com/redshift/latest/APIReference/API_GetClusterCredentials.html) API operation to generate temporary database user credentials. You can configure your SQL client with Amazon Redshift JDBC or ODBC drivers that manage the process of calling the `GetClusterCredentials` operation. They do so by retrieving the database user credentials, and establishing a connection between your SQL client and your Amazon Redshift database. You can also use your database application to programmatically call the `GetClusterCredentials` operation, retrieve database user credentials, and connect to the database. If you already manage user identities outside AWS, you can use an identity provider (IdP) compliant with Security Assertion Markup Language (SAML) 2.0 to manage access to Amazon Redshift resources. You configure your IdP to permit your federated users access to an IAM role. With that IAM role, you can generate temporary database credentials and log in to Amazon Redshift databases. Your SQL client needs permission to call the `GetClusterCredentials` operation for you. You manage those permissions by creating an IAM role and attaching an IAM permissions policy that grants or restricts access to the `GetClusterCredentials` operation and related actions. As a best practice, we recommend attaching permissions policies to an IAM role and then assigning it to users and groups as needed. For more information, see [Identity and access management in Amazon Redshift](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html). The policy also grants or restricts access to specific resources, such as Amazon Redshift clusters, databases, database user names, and user group names. **Note** We recommend using the Amazon Redshift JDBC or ODBC drivers to manage the process of calling the `GetClusterCredentials` operation and logging on to the database. For simplicity, we assume that you are using a SQL client with the JDBC or ODBC drivers throughout this topic. For specific details and examples of using the `GetClusterCredentials` operation or the parallel `get-cluster-credentials` CLI command, see [GetClusterCredentials](https://docs.aws.amazon.com/redshift/latest/APIReference/API_GetClusterCredentials.html) and [get-cluster-credentials](https://docs.aws.amazon.com/cli/latest/reference/redshift/get-cluster-credentials.html). To manage authentication and authorization centrally, Amazon Redshift supports database authentication with IAM, enabling user authentication through enterprise federation. Instead of creating a user, you can use existing identities from AWS Directory Service, your enterprise user directory, or a web identity provider. These are known as federated users. AWS assigns a role to a federated user when access is requested through an IdP. To provide federated access to a user or client application in your organization to call Amazon Redshift API operations, you can also use the JDBC or ODBC driver with SAML 2.0 support to request authentication from your organization IdP. In this case, your organization's users don't have direct access to Amazon Redshift. For more information, see [Identity Providers and Federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html) in the *IAM User Guide*. # Creating temporary IAM credentials In this section, you can find how to configure your system to generate temporary IAM-based database user credentials and log in to your database using the new credentials. At a high level, the process flows as follows: 1. [Step 1: Create an IAM role for IAM single sign-on access](#generating-iam-credentials-sso-role) (Optional) You can authenticate users for access to an Amazon Redshift database by integrating IAM authentication and a third-party identity provider (IdP). 1. [Step 2: Configure SAML assertions for your IdP](#configuring-saml-assertions) (Optional) To use IAM authentication using an IdP, you need to define a claim rule in your IdP application that maps users or groups in your organization to the IAM role. Optionally, you can include attribute elements to set `GetClusterCredentials` parameters. 1. [Step 3: Create an IAM role with permissions to call GetClusterCredentialsWithIAM or GetClusterCredentials](#generating-iam-credentials-role-permissions) Your SQL client application assumes the user when it calls the `GetClusterCredentials` operation. If you created an IAM role for identity provider access, you can add the necessary permission to that role. 1. [Step 4: Create a database user and database groups](#generating-iam-credentials-user-and-groups) (Optional) By default, `GetClusterCredentials` returns credentials create a new user if the user name doesn't exist. You can also choose to specify user groups that users join at logon. By default, database users join the PUBLIC group. 1. [Step 5: Configure a JDBC or ODBC connection to use IAM credentials](#generating-iam-credentials-configure-jdbc-odbc) To connect to your Amazon Redshift database, you configure your SQL client to use an Amazon Redshift JDBC or ODBC driver. ## Step 1: Create an IAM role for IAM single sign-on access If you don't use an identity provider for single sign-on access, you can skip this step. If you already manage user identities outside of AWS, you can authenticate users for access to an Amazon Redshift database by integrating IAM authentication and a third-party SAML-2.0 identity provider (IdP). For more information, see [Identity Providers and Federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html) in the *IAM User Guide*. Before you can use Amazon Redshift IdP authentication, create an AWS SAML identity provider. You create an IdP in the IAM console to inform AWS about the IdP and its configuration. Doing this establishes trust between your AWS account and the IdP. For steps to create a role, see [Creating a Role for SAML 2.0 Federation (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html?icmpid=docs_iam_console) in the *IAM User Guide*. ## Step 2: Configure SAML assertions for your IdP After you create the IAM role, you define a claim rule in your IdP application to map users or groups in your organization to the IAM role. For more information, see [Configuring SAML Assertions for the Authentication Response](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html) in the *IAM User Guide*. If you choose to use the optional `GetClusterCredentials` parameters `DbUser`, `AutoCreate`, and `DbGroups`, you have two options. You can set the values for the parameters with your JDBC or ODBC connection, or you can set the values by adding SAML attribute elements to your IdP. For more information about the `DbUser`, `AutoCreate`, and `DbGroups` parameters, see [Step 5: Configure a JDBC or ODBC connection to use IAM credentials](#generating-iam-credentials-configure-jdbc-odbc). **Note** If you use an IAM policy variable `${redshift:DbUser}`, as described in [Resource policies for GetClusterCredentials](redshift-iam-access-control-identity-based.md#redshift-policy-resources.getclustercredentials-resources) 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 by using `RoleSessionName`. You can find examples of how to set a condition using an IAM policy in [Example 8: IAM policy for using GetClusterCredentials](redshift-iam-access-control-identity-based.md#redshift-policy-examples-getclustercredentials). To configure your IdP to set the `DbUser`, `AutoCreate`, and `DbGroups` parameters, include the following `Attribute` elements: + An `Attribute` element with the `Name` attribute set to "https://redshift.amazon.com/SAML/Attributes/DbUser" Set the `AttributeValue` element to the name of a user that will connect to the Amazon Redshift database. The value in the `AttributeValue` element must be lowercase, begin with a letter, contain only alphanumeric characters, underscore ('\$1'), plus sign ('\$1'), dot ('.'), at ('@'), or hyphen ('-'), and be fewer than 128 characters. Typically, the user name is a user ID (for example, bobsmith) or an email address (for example bobsmith@example.com). The value can't include a space (for example, a user's display name such as Bob Smith). ``` user-name ``` + An Attribute element with the Name attribute set to "https://redshift.amazon.com/SAML/Attributes/AutoCreate" Set the AttributeValue element to true to create a new database user if one doesn't exist. Set the AttributeValue to false to specify that the database user must exist in the Amazon Redshift database. ``` true ``` + An `Attribute` element with the `Name` attribute set to set to "https://redshift.amazon.com/SAML/Attributes/DbGroups" This element contains one or more `AttributeValue` elements. Set each `AttributeValue` element to a database group name that the `DbUser` joins for the duration of the session when connecting to the Amazon Redshift database. ``` group1 group2 group3 ``` ## Step 3: Create an IAM role with permissions to call GetClusterCredentialsWithIAM or GetClusterCredentials Your SQL client needs authorization to call the the ` GetClusterCredentialsWithIAM` or `GetClusterCredentials` operation on your behalf. To provide that authorization, you create a user or role and attach a policy that grants the necessary permissions. Both operations are available for obtaining the cluster credentials, but they differ in their authentication method. ` GetClusterCredentialsWithIAM` uses an IAM role, automatically creating a database user that maps to the role, which is beneficial for managing permissions at the IAM role level, while `GetClusterCredentials` gives credentials for a given username in the database. **To create an IAM role with permissions to call GetClusterCredentialsWithIAM** 1. Using the IAM service, create a user or role. You can also use an existing user or role. For example, if you created an IAM role for identity provider access, you can attach the necessary IAM policies to that role. 1. Attach a permission policy with permission to call the ` redshift:GetClusterCredentialsWithIAM` operation. The following policy sample shows options to allow the operation for specific cluster and database, any database in cluster, and any database in any cluster. ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "SpecificClusterAndDBName", "Effect": "Allow", "Action": "redshift:GetClusterCredentialsWithIAM", "Resource": [ "arn:aws:redshift:us-east-1:123456789012:dbname:testcluster/testdatabase" ] }, { "Sid": "SpecificClusterAndAnyDBName", "Effect": "Allow", "Action": "redshift:GetClusterCredentialsWithIAM", "Resource": "arn:aws:redshift:us-east-1:123456789012:dbname:examplecluster/*", }, { "Sid": "AnyClusterAnyDatabase", "Effect": "Allow", "Action": "redshift:GetClusterCredentialsWithIAM", "Resource": "*" } ] } ``` **To create an IAM role with permissions to call GetClusterCredentials** 1. Using the IAM service, create a user or role. You can also use an existing user or role. For example, if you created an IAM role for identity provider access, you can attach the necessary IAM policies to that role. 1. Attach a permission policy with permission to call the `redshift:GetClusterCredentials` operation. Depending on which optional parameters you specify, you can also allow or restrict additional actions and resources in your policy: + To permit your SQL client to retrieve cluster ID, AWS Region, and port, include permission to call the `redshift:DescribeClusters` operation with the Redshift cluster resource. + If you use the `AutoCreate` option, include permission to call `redshift:CreateClusterUser` with the `dbuser` resource. The following Amazon Resource Name (ARN) specifies the Amazon Redshift `dbuser`. Replace *`region`*, *`account-id`*, and *`cluster-name`* with the values for your AWS Region, account, and cluster. For *`dbuser-name`*, specify the user name to use to log in to the cluster database. ``` arn:aws:redshift:region:account-id:dbuser:cluster-name/dbuser-name ``` + (Optional) Add an ARN that specifies the Amazon Redshift `dbname` resource in the following format. Replace *`region`*, *`account-id`*, and *`cluster-name`* with the values for your AWS Region, account, and cluster. For `database-name`, specify the name of a database that the user will log in to. ``` arn:aws:redshift:region:account-id:dbname:cluster-name/database-name ``` + If you use the `DbGroups` option, include permission to call the `redshift:JoinGroup` operation with the Amazon Redshift `dbgroup` resource in the following format. Replace *`region`*, *`account-id`*, and *`cluster-name`* with the values for your AWS Region, account, and cluster. For `dbgroup-name`, specify the name of a user group that the user joins at login. ``` arn:aws:redshift:region:account-id:dbgroup:cluster-name/dbgroup-name ``` For more information and examples, see [Resource policies for GetClusterCredentials](redshift-iam-access-control-identity-based.md#redshift-policy-resources.getclustercredentials-resources). ## Step 4: Create a database user and database groups Optionally, you can create a database user that you use to log in to the cluster database. If you create temporary user credentials for an existing user, you can disable the user's password to force the user to log on with the temporary password. Alternatively, you can use the `GetClusterCredentials` Autocreate option to automatically create a new database user. You can create database user groups with the permissions you want the IAM database user to join at login. When you call the `GetClusterCredentials` operation, you can specify a list of user group names that the new user joins at login. These group memberships are valid only for sessions created using credentials generated with the given request. **To create a database user and database groups** 1. Log in to your Amazon Redshift database and create a database user using [CREATE USER](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_USER.html) or alter an existing user using [ALTER USER](https://docs.aws.amazon.com/redshift/latest/dg/r_ALTER_USER.html). 1. Optionally, specify the PASSWORD DISABLE option to prevent the user from using a password. When a user's password is disabled, the user can log on only using temporary credentials. If the password is not disabled, the user can log on either with the password or using temporary credentials. You can't disable the password for a superuser. Users need programmatic access if they want to interact with AWS outside of the AWS Management Console. The way to grant programmatic access depends on the type of user that's accessing AWS. To grant users programmatic access, choose one of the following options. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/redshift/latest/mgmt/generating-iam-credentials-steps.html) The following example creates a user with password disabled. ``` create user temp_creds_user password disable; ``` The following example disables the password for an existing user. ``` alter user temp_creds_user password disable; ``` 1. Create database user groups using [CREATE GROUP](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_GROUP.html). 1. Use the [GRANT](https://docs.aws.amazon.com/redshift/latest/dg/r_GRANT.html) command to define access privileges for the groups. ## Step 5: Configure a JDBC or ODBC connection to use IAM credentials You can configure your SQL client with an Amazon Redshift JDBC or ODBC driver. This driver manages the process of creating database user credentials and establishing a connection between your SQL client and your Amazon Redshift database. If you use an identity provider for authentication, specify the name of a credential provider plugin. The Amazon Redshift JDBC and ODBC drivers include plugins for the following SAML-based identity providers: + Active Directory Federation Services (AD FS) + PingOne + Okta + Microsoft Azure AD For the steps to set up Microsoft Azure AD as an identity provider, see [Setting up JDBC or ODBC single sign-on authentication](setup-azure-ad-identity-provider.md). **To configure a JDBC connection to use IAM credentials** 1. Download the latest Amazon Redshift JDBC driver from the [Configuring a connection for JDBC driver version 2.x for Amazon Redshift](jdbc20-install.md) page. 1. Create a JDBC URL with the IAM credentials options in one of the following formats. To use IAM authentication, add `iam:` to the Amazon Redshift JDBC URL following `jdbc:redshift:` as shown in the following example. ``` jdbc:redshift:iam:// ``` Add `cluster-name`, `region`, and `account-id`. The JDBC driver uses your IAM account information and cluster name to retrieve the cluster ID and AWS Region. To do so, your user or role must have permission to call the `redshift:DescribeClusters` operation with the specified cluster. If your user or role doesn't have permission to call the `redshift:DescribeClusters` operation, include the cluster ID, AWS Region, and port as shown in the following example. The port number is optional. ``` jdbc:redshift:iam://examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com:5439/dev ``` 1. Add JDBC options to provide IAM credentials. You use different combinations of JDBC options to provide IAM credentials. For details, see [JDBC and ODBC options for creating database user credentials](options-for-providing-iam-credentials.md#jdbc-and-odbc-options-for-database-credentials). The following URL specifies AccessKeyID and SecretAccessKey for a user. ``` jdbc:redshift:iam://examplecluster:us-west-2/dev?AccessKeyID=AKIAIOSFODNN7EXAMPLE&SecretAccessKey=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ``` The following example specifies a named profile that contains the IAM credentials. ``` jdbc:redshift:iam://examplecluster:us-west-2/dev?Profile=user2 ``` 1. Add JDBC options that the JDBC driver uses to call the `GetClusterCredentials` API operation. Don't include these options if you call the `GetClusterCredentials` API operation programmatically. The following example includes the JDBC `GetClusterCredentials` options. ``` jdbc:redshift:iam://examplecluster:us-west-2/dev?plugin_name=com.amazon.redshift.plugin.AzureCredentialsProvider&UID=user&PWD=password&idp_tenant=my_tenant&client_secret=my_secret&client_id=my_id ``` **To configure an ODBC connection to use IAM credentials** In the following procedure, you can find steps only to configure IAM authentication. For steps to use standard authentication, using a database user name and password, see [Configuring a connection for ODBC driver version 2.x for Amazon Redshift](odbc20-install.md). 1. Install and configure the latest Amazon Redshift OBDC driver for your operating system. For more information, see [Configuring a connection for ODBC driver version 2.x for Amazon Redshift](odbc20-install.md) page. **Important** The Amazon Redshift ODBC driver must be version 1.3.6.1000 or later. 1. Follow the steps for your operating system to configure connection settings. 1. On Microsoft Windows operating systems, access the Amazon Redshift ODBC Driver DSN Setup window. 1. Under **Connection Settings**, enter the following information: + **Data Source Name** + **Server** (optional) + **Port** (optional) + **Database** If your user or role has permission to call the `redshift:DescribeClusters` operation, only **Data Source Name** and **Database** are required. Amazon Redshift uses **ClusterId** and **Region** to get the server and port by calling the `DescribeCluster` operation. If your user or role doesn't have permission to call the `redshift:DescribeClusters` operation, specify **Server** and **Port**. 1. Under **Authentication**, choose a value for **Auth Type**. For each authentication type, enter values as listed following: AWS Profile Enter the following information: + **ClusterID** + **Region** + **Profile name** Enter the name of a profile in an AWS config file that contains values for the ODBC connection options. For more information, see [Using a configuration profile](options-for-providing-iam-credentials.md#using-configuration-profile). (Optional) Provide details for options that the ODBC driver uses to call the `GetClusterCredentials` API operation: + **DbUser** + **User AutoCreate** + **DbGroups** For more information, see [JDBC and ODBC options for creating database user credentials](options-for-providing-iam-credentials.md#jdbc-and-odbc-options-for-database-credentials). IAM Credentials Enter the following information: + **ClusterID** + **Region** + **AccessKeyID** and **SecretAccessKey** The access key ID and secret access key for the IAM role or user configured for IAM database authentication. + **SessionToken** **SessionToken** is required for an IAM role with temporary credentials. For more information, see [Temporary Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html). Provide details for options that the ODBC driver uses to call the `GetClusterCredentials` API operation: + **DbUser** (required) + **User AutoCreate** (optional) + **DbGroups** (optional) For more information, see [JDBC and ODBC options for creating database user credentials](options-for-providing-iam-credentials.md#jdbc-and-odbc-options-for-database-credentials). Identity Provider: AD FS For Windows Integrated Authentication with AD FS, leave **User** and **Password** empty. Provide IdP details: + **IdP Host** The name of the corporate identity provider host. This name should not include any slashes ( / ). + **IdP Port** (optional) The port used by identity provider. The default is 443. + **Preferred Role** An Amazon Resource Name (ARN) for the IAM role from the multi-valued `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](#configuring-saml-assertions). (Optional) Provide details for options that the ODBC driver uses to call the `GetClusterCredentials` API operation: + **DbUser** + **User AutoCreate** + **DbGroups** For more information, see [JDBC and ODBC options for creating database user credentials](options-for-providing-iam-credentials.md#jdbc-and-odbc-options-for-database-credentials). Identity Provider: PingFederate For **User** and **Password**, enter your IdP user name and password. Provide IdP details: + **IdP Host** The name of the corporate identity provider host. This name should not include any slashes ( / ). + **IdP Port** (optional) The port used by identity provider. The default is 443. + **Preferred Role** An Amazon Resource Name (ARN) for the IAM role from the multi-valued `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](#configuring-saml-assertions). (Optional) Provide details for options that the ODBC driver uses to call the `GetClusterCredentials` API operation: + **DbUser** + **User AutoCreate** + **DbGroups** For more information, see [JDBC and ODBC options for creating database user credentials](options-for-providing-iam-credentials.md#jdbc-and-odbc-options-for-database-credentials). Identity Provider: Okta For **User** and **Password**, enter your IdP user name and password. Provide IdP details: + **IdP Host** The name of the corporate identity provider host. This name should not include any slashes ( / ). + **IdP Port ** This value is not used by Okta. + **Preferred Role** An Amazon Resource Name (ARN) for the IAM role 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](#configuring-saml-assertions). + **Okta App ID** An ID for an Okta application. The value for App ID follows "amazon\$1aws" in the Okta application embed link. Work with your IdP administrator to get this value. (Optional) Provide details for options that the ODBC driver uses to call the `GetClusterCredentials` API operation: + **DbUser** + **User AutoCreate** + **DbGroups** For more information, see [JDBC and ODBC options for creating database user credentials](options-for-providing-iam-credentials.md#jdbc-and-odbc-options-for-database-credentials). Identity Provider: Azure AD For **User** and **Password**, enter your IdP user name and password. For **Cluster ID** and ** Region**, enter the cluster ID and AWS Region of your Amazon Redshift cluster. For **Database**, enter the database that you created for your Amazon Redshift cluster. Provide IdP details: + **IdP Tenant** The tenant used for Azure AD. + **Azure Client Secret** The client secret of the Amazon Redshift enterprise app in Azure. + **Azure Client ID** The client ID (application ID) of the Amazon Redshift enterprise app in Azure. (Optional) Provide details for options that the ODBC driver uses to call the `GetClusterCredentials` API operation: + **DbUser** + **User AutoCreate** + **DbGroups** For more information, see [JDBC and ODBC options for creating database user credentials](options-for-providing-iam-credentials.md#jdbc-and-odbc-options-for-database-credentials). # 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](#using-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](#jdbc-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](#using-credentials-provider-plugin). 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.x configuration](jdbc20-configuration-options.md). For more information, see [Step 5: Configure a JDBC or ODBC connection to use IAM credentials](generating-iam-credentials-steps.md#generating-iam-credentials-configure-jdbc-odbc). ## 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](#using-credentials-provider-plugin). If `plugin_name` isn't used, the other options are ignored. The following example shows the \$1/.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](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) in the* AWS Command Line Interface User Guide.* For more information on using profiles for the JDBC driver, see [Specifying profiles](jdbc20-configure-authentication-ssl.md#jdbc20-aws-credentials-profiles). For more information on using profiles for the ODBC driver, see [Authentication methods](odbc20-authentication-ssl.md). ## JDBC and ODBC options for providing IAM credentials The following table lists the JDBC and ODBC options for providing IAM credentials. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/redshift/latest/mgmt/options-for-providing-iam-credentials.html) ## 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](generating-iam-credentials-steps.md#configuring-saml-assertions). **Note** If you use an IAM policy variable `${redshift:DbUser}`, as described in [Resource policies for GetClusterCredentials](redshift-iam-access-control-identity-based.md#redshift-policy-resources.getclustercredentials-resources) 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 8: IAM policy for using GetClusterCredentials](redshift-iam-access-control-identity-based.md#redshift-policy-examples-getclustercredentials). The following table lists the options for creating database user credentials. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/redshift/latest/mgmt/options-for-providing-iam-credentials.html) ## 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](setup-azure-ad-identity-provider.md). ### 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.\]](http://docs.aws.amazon.com/redshift/latest/mgmt/images/BrowserSAML_plugin.png) 1. A user tries to log in. 1. The plugin launches a local server to listen to incoming connections on the localhost. 1. 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. 1. The web browser follows the link and prompts the user to enter credentials. 1. 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`. 1. The web browser moves the response message with the SAML response to the indicated `redirect_uri`. 1. 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.\]](http://docs.aws.amazon.com/redshift/latest/mgmt/images/BrowserAzure_plugin.png) 1. A user tries to log in. 1. The plugin launches a local server to listen to incoming connections on the localhost. 1. The plugin launches a web browser to request an authorization code from the Azure AD `oauth2/authorize` endpoint. 1. 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\$1id. 1. 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`. 1. The web browser moves the response message with the SAML response to the indicated `redirect_uri`. 1. 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. 1. The Azure AD `oauth2/token` endpoint returns a response with an access token to the indicated `redirect_uri`. 1. The plugin retrieves the SAML response and passes it to Amazon Redshift. See the following sections: + Active Directory Federation Services (AD FS) For more information, see [Setting up JDBC or ODBC single sign-on authentication](setup-azure-ad-identity-provider.md). + PingOne (Ping) Ping is supported only with the predetermined PingOne IdP Adapter using Forms authentication. For more information, see [Setting up JDBC or ODBC single sign-on authentication](setup-azure-ad-identity-provider.md). + Okta Okta is supported only for the Okta-supplied application used with the AWS Management Console. For more information, see [Setting up JDBC or ODBC single sign-on authentication](setup-azure-ad-identity-provider.md). + Microsoft Azure Active Directory For more information, see [Setting up JDBC or ODBC single sign-on authentication](setup-azure-ad-identity-provider.md). ### 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. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/redshift/latest/mgmt/options-for-providing-iam-credentials.html) # Generating database credentials for an IAM identity using the Amazon Redshift CLI or API To programmatically generate temporary database user credentials, Amazon Redshift provides the [get-cluster-credentials](https://docs.aws.amazon.com/cli/latest/reference/redshift/get-cluster-credentials.html) command for the AWS Command Line Interface (AWS CLI) and the [GetClusterCredentials](https://docs.aws.amazon.com/redshift/latest/APIReference/API_GetClusterCredentials.html) API operation. Or you can configure your SQL client with Amazon Redshift JDBC or ODBC drivers that manage the process of calling the `GetClusterCredentials` operation, retrieving the database user credentials, and establishing a connection between your SQL client and your Amazon Redshift database. For more information, see [JDBC and ODBC options for creating database user credentials](options-for-providing-iam-credentials.md#jdbc-and-odbc-options-for-database-credentials). **Note** We recommend using the Amazon Redshift JDBC or ODBC drivers to generate database user credentials. In this section, you can find steps to programmatically call the `GetClusterCredentials` operation or get-cluster-credentials command, retrieve database user credentials, and connect to the database. **To generate and use temporary database credentials** 1. Create or modify a user or role with the required permissions. For more information about IAM permissions, see [Step 3: Create an IAM role with permissions to call GetClusterCredentialsWithIAM or GetClusterCredentials](generating-iam-credentials-steps.md#generating-iam-credentials-role-permissions). 1. As a user or role you authorized in the previous step, run the get-cluster-credentials CLI command or call the `GetClusterCredentials` API operation and provide the following values: + **Cluster identifier** – The name of the cluster that contains the database. + **Database user name** – The name of an existing or new database user. + If the user doesn't exist in the database and AutoCreate is true, a new user is created with PASSWORD disabled. + If the user doesn't exist, and AutoCreate is false, the request fails. + For this example, the database user name is `temp_creds_user`. + **Autocreate ** – (Optional) Create a new user if the database user name doesn't exist. + **Database name ** – (Optional) The name of the database that the user is authorized to log on to. If database name isn't specified, the user can log on to any cluster database. + **Database groups ** – (Optional) A list of existing database user groups. Upon successful login, the database user is added to the specified user groups. If no group is specified, the user has only PUBLIC permissions. The user group names must match the dbgroup resources ARNs specified in the IAM policy attached to the user or role. + **Expiration time** – (Optional) The time, in seconds, until the temporary credentials expire. You can specify a value between 900 seconds (15 minutes) and 3600 seconds (60 minutes). The default is 900 seconds. 1. Amazon Redshift verifies that the user has permission to call the `GetClusterCredentials` operation with the specified resources. 1. Amazon Redshift returns a temporary password and the database user name. The following example uses the Amazon Redshift CLI to generate temporary database credentials for an existing user named `temp_creds_user`. ``` aws redshift get-cluster-credentials --cluster-identifier examplecluster --db-user temp_creds_user --db-name exampledb --duration-seconds 3600 ``` The result is as follows. ``` { "DbUser": "IAM:temp_creds_user", "Expiration": "2016-12-08T21:12:53Z", "DbPassword": "EXAMPLEjArE3hcnQj8zt4XQj9Xtma8oxYEM8OyxpDHwXVPyJYBDm/gqX2Eeaq6P3DgTzgPg==" } ``` The following example uses the Amazon Redshift CLI with autocreate to generate temporary database credentials for a new user and add the user to the group `example_group`. ``` aws redshift get-cluster-credentials --cluster-identifier examplecluster --db-user temp_creds_user --auto-create --db-name exampledb --db-groups example_group --duration-seconds 3600 ``` The result is as follows. ``` { "DbUser": "IAMA:temp_creds_user:example_group", "Expiration": "2016-12-08T21:12:53Z", "DbPassword": "EXAMPLEjArE3hcnQj8zt4XQj9Xtma8oxYEM8OyxpDHwXVPyJYBDm/gqX2Eeaq6P3DgTzgPg==" } ``` 1. Establish a Secure Socket Layer (SSL) authentication connection with the Amazon Redshift cluster and send a login request with the user name and password from the `GetClusterCredentials` response. Include the `IAM:` or `IAMA:` prefix with the user name, for example `IAM:temp_creds_user` or `IAMA:temp_creds_user`. **Important** Configure your SQL client to require SSL. Otherwise, if your SQL client automatically tries to connect with SSL, it can fall back to non-SSL if there is any kind of failure. In that case, the first connection attempt might fail because the credentials are expired or invalid, then a second connection attempt fails because the connection is not SSL. If that occurs, the first error message might be missed. For more information about connecting to your cluster using SSL, see [Configuring security options for connections](connecting-ssl-support.md). 1. If the connection doesn't use SSL, the connection attempt fails. 1. The cluster sends an `authentication` request to the SQL client. 1. The SQL client then sends the temporary password to the cluster. 1. If the password is valid and has not expired, the cluster completes the connection. # Setting up JDBC or ODBC single sign-on authentication You can leverage external identity providers (IdPs) to authenticate and authorize users accessing your Amazon Redshift cluster, simplifying user management and enhancing security. This enables centralized user management, role-based access control, and auditing capabilities across multiple services. Common use cases include streamlining authentication for diverse user groups, enforcing consistent access policies, and meeting regulatory requirements. The following pages guide you through configuring IdP integration with your Redshift cluster. For more information about configuring AWS as a service provider for the IdP, see [Configuring Your SAML 2.0 IdP with Relying Party Trust and Adding Claims](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_relying-party.html#saml_relying-party) in the *IAM User Guide*. # AD FS This tutorial shows you how you can use AD FS as an identity provider (IdP) to access your Amazon Redshift cluster. ## Step 1: Set up AD FS and your AWS account to trust each other The following procedure describes how to set up a trust relationship. 1. Create or use an existing Amazon Redshift cluster for your AD FS users to connect to. To configure the connection, certain properties of this cluster are needed, such as the cluster identifier. For more information, see [Creating a Cluster](https://docs.aws.amazon.com/redshift/latest/mgmt/create-cluster.html). 1. Set up AD FS to control Amazon Redshift access on the Microsoft Management Console: 1. Choose **ADFS 2.0**, and then choose **Add Relying Party Trust**. On the **Add Relying Party Trust Wizard** page, choose **Start**. 1. On the **Select Data Source** page, choose **Import data about the relying party published online or on a local network**. 1. For **Federation metadata address (host name or URL)**, enter **https://signin.aws.amazon.com/saml-metadata.xml**. The metadata XML file is a standard SAML metadata document that describes AWS as a relying party. 1. On the **Specify Display Name** page, enter a value for **Display name**. 1. On the **Choose Issuance Authorization Rules** page, choose an issuance authorization rule to either permit or deny all users to access this relying party. 1. On the **Ready to Add Trust** page, review your settings. 1. On the **Finish** page, choose **Open the Edit Claim Rules dialog for this relying party trust when the wizard closes**. 1. On the context (right-click) menu, choose **Relying Party Trusts**. 1. For your relying party, open the context (right-click) menu and choose **Edit Claim Rules**. On the **Edit Claim Rules** page, choose **Add Rule**. 1. For **Claim rule template**, choose **Transform an Incoming Claim**, and then on the **Edit Rule – NameId **page, do the following: + For **Claim rule name**, enter **NameId**. + For **Incoming claim name**, choose **Windows Account Name**. + For **Outgoing claim name**, choose **Name ID**. + For **Outgoing name ID format**, choose **Persistent Identifier**. + Choose **Pass through all claim values**. 1. On the **Edit Claim Rules** page, choose **Add Rule**. On the **Select Rule Template** page, for **Claim rule template**, choose **Send LDAP Attributes as Claims**. 1. On the **Configure Rule** page, do the following: + For **Claim rule name**, enter **RoleSessionName**. + For **Attribute store**, choose **Active Directory**. + For **LDAP Attribute**, choose **Email Addresses**. + For **Outgoing Claim Type**, choose **https://aws.amazon.com/SAML/Attributes/RoleSessionName**. 1. On the **Edit Claim Rules** page, choose **Add Rule**. On the **Select Rule Template** page, for **Claim rule template**, choose **Send Claims Using a Custom Rule**. 1. On the **Edit Rule – Get AD Groups** page, for **Claim rule name**, enter **Get AD Groups**. 1. For **Custom rule**, enter the following. ``` c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => add(store = "Active Directory", types = ("http://temp/variable"), query = ";tokenGroups;{0}", param = c.Value); ``` 1. On the **Edit Claim Rules** page, choose **Add Rule**. On the **Select Rule Template** page, for **Claim rule template**, choose **Send Claims Using a Custom Rule**. 1. On the **Edit Rule – Roles** page, for **Claim rule name**, type **Roles**. 1. For **Custom rule,** enter the following. ``` c:[Type == "http://temp/variable", Value =~ "(?i)^AWS-"] => issue(Type = "https://aws.amazon.com/SAML/Attributes/Role", Value = RegExReplace(c.Value, "AWS-", "arn:aws:iam::123456789012:saml-provider/ADFS,arn:aws:iam::123456789012:role/ADFS-")); ``` Note the ARNs of the SAML provider and role to assume. In this example, `arn:aws:iam:123456789012:saml-provider/ADFS` is the ARN of the SAML provider and `arn:aws:iam:123456789012:role/ADFS-` is the ARN of the role. 1. Make sure that you have downloaded the `federationmetadata.xml` file. Check that the document contents do not have invalid characters. This is the metadata file you use when configuring the trust relationship with AWS. 1. Create an IAM SAML identity provider on the IAM console. The metadata document. that you provide is the federation metadata XML file that you saved when you set up Azure Enterprise Application. For detailed steps, see [ Creating and Managing an IAM Identity Provider (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html#idp-manage-identityprovider-console) in the *IAM User Guide*. 1. Create an IAM role for SAML 2.0 federation on the IAM console. For detailed steps, see [Creating a Role for SAML](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html#idp_saml_Create) in the *IAM User Guide*. 1. Create an IAM policy that you can attach to the IAM role that you created for SAML 2.0 federation on the IAM console. For detailed steps, see [Creating IAM Policies (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) in the *IAM User Guide*. For an Azure AD example, see [Setting up JDBC or ODBC single sign-on authentication](setup-azure-ad-identity-provider.md). ## Step 2: Set up JDBC or ODBC for authentication to AD FS ------ #### [ JDBC ] The following procedure describes how to set up a JDBC relationship to AD FS. + Configure your database client to connect to your cluster through JDBC using AD FS single sign-on. You can use any client that uses a JDBC driver to connect using AD FS single sign-on or use a language like Java to connect using a script. For installation and configuration information, see [Configuring a connection for JDBC driver version 2.x for Amazon Redshift](jdbc20-install.md). For example, you can use SQLWorkbench/J as the client. When you configure SQLWorkbench/J, the URL of your database uses the following format. ``` jdbc:redshift:iam://cluster-identifier:us-west-1/dev ``` If you use SQLWorkbench/J as the client, take the following steps: 1. Start SQL Workbench/J. In the **Select Connection Profile** page, add a **Profile Group**, for example **ADFS**. 1. For **Connection Profile**, enter your connection profile name, for example **ADFS**. 1. Choose **Manage Drivers**, and choose **Amazon Redshift**. Choose the **Open Folder** icon next to **Library**, then choose the appropriate JDBC .jar file. 1. On the **Select Connection Profile** page, add information to the connection profile as follows: + For **User**, enter your AD FS user name. This is the user name of the account that you are using for single sign-on that has permission to the cluster that you are trying to authenticate using. + For **Password**, enter your AD FS password. + For **Drivers**, choose **Amazon Redshift (com.amazon.redshift.jdbc.Driver)**. + For **URL**, enter **jdbc:redshift:iam://*your-cluster-identifier*:*your-cluster-region*/*your-database-name***. 1. Choose **Extended Properties**. For **plugin\$1name**, enter **com.amazon.redshift.plugin.AdfsCredentialsProvider**. This value specifies to the driver to use AD FS single sign-on as the authentication method. ------ #### [ ODBC ] **To set up ODBC for authentication to AD FS** + Configure your database client to connect to your cluster through ODBC using AD FS single sign-on. Amazon Redshift provides ODBC drivers for Linux, Windows, and macOS operating systems. Before you install an ODBC driver, determine whether your SQL client tool is 32-bit or 64-bit. Install the ODBC driver that matches the requirements of your SQL client tool. On Windows, in the **Amazon Redshift ODBC Driver DSN Setup** page, under **Connection Settings**, enter the following information: + For **Data Source Name**, enter ***your-DSN***. This specifies the data source name used as the ODBC profile name. + For **Auth type**, choose **Identity Provider: SAML**. This is the authentication method that the ODBC driver uses to authenticate using AD FS single sign-on. + For **Cluster ID**, enter ***your-cluster-identifier***. + For **Region**, enter ***your-cluster-region***. + For **Database**, enter ***your-database-name***. + For **User**, enter ***your-adfs-username***. This is the user name for the AD FS account that you are using for single sign-on that has permission to the cluster that you're trying to authenticate using. Use this only for **Auth type** is **Identity Provider: SAML**. + For **Password**, enter ***your-adfs-password***. Use this only for **Auth type** is **Identity Provider: SAML**. On macOS and Linux, edit the `odbc.ini` file as follows: **Note** All entries are case-insensitive. + For **clusterid**, enter ***your-cluster-identifier***. This is the name of the created Amazon Redshift cluster. + For **region**, enter ***your-cluster-region***. This is the AWS Region of the created Amazon Redshift cluster. + For **database**, enter ***your-database-name***. This is the name of the database that you're trying to access on the Amazon Redshift cluster. + For **locale**, enter **en-us**. This is the language that error messages display in. + For **iam**, enter **1**. This value specifies to the driver to authenticate using IAM credentials. + For **plugin\$1name**, do one of the following: + For AD FS single sign-on with MFA configuration, enter **BrowserSAML**. This is the authentication method that the ODBC driver uses to authenticate to AD FS. + For AD FS single sign-on configuration, enter **ADFS**. This is the authentication method that the ODBC driver uses to authenticate using Azure AD single sign-on. + For **uid**, enter ***your-adfs-username***. This is the user name of the Microsoft Azure account that you are using for single sign-on that has permission to the cluster you are trying to authenticate against. Use this only for **plugin\$1name** is **ADFS**. + For **pwd**, enter ***your-adfs-password***. Use this only for **plugin\$1name** is **ADFS**. On macOS and Linux, also edit the profile settings to add the following exports. ``` export ODBCINI=/opt/amazon/redshift/Setup/odbc.ini ``` ``` export ODBCINSTINI=/opt/amazon/redshift/Setup/odbcinst.ini ``` ------ # Azure You can use Microsoft Azure AD as an identity provider (IdP) to access your Amazon Redshift cluster. This tutorial shows you how you can use Azure as an identity provider (IdP) to access your Amazon Redshift cluster. To learn how to federate Amazon Redshift access with Microsoft Azure AD single sign-on, watch the following video. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/aXs9hEgJCss/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/aXs9hEgJCss) ## Step 1: Set up Azure and your AWS account to trust each other The following procedure describes how to set up a trust relationship. **To set up Azure AD and your AWS account to trust each other** 1. Create or use an existing Amazon Redshift cluster for your Azure AD users to connect to. To configure the connection, certain properties of this cluster are needed, such as the cluster identifier. For more information, see [Creating a Cluster](https://docs.aws.amazon.com/redshift/latest/mgmt/create-cluster.html). 1. Set up an Azure Active Directory, groups, users used for AWS on the Microsoft Azure portal. 1. Add Amazon Redshift as an enterprise application on the Microsoft Azure portal to use for single sign-on to the AWS Console and federated login to Amazon Redshift. Choose **Enterprise application**. 1. Choose **\$1New application**. The Add an application page appears. 1. Search for **AWS** in the search field. 1. Choose **Amazon Web Services (AWS)** and choose **Add**. This creates the AWS application. 1. Under **Manage**, choose **Single sign-on**. 1. Choose **SAML**. The Amazon Web Services (AWS) \$1 SAML-based Sign-on page appears. 1. Choose **Yes** to proceed to the Set up Single Sign-On with SAML page. This page shows the list of pre-configured single sign-on related attributes. 1. For **Basic SAML Configuration**, choose the edit icon and choose **Save**. 1. When you are configuring for more than one application, provide an identifier value. For example, enter ***https://signin.aws.amazon.com/saml\$12***. Note that from the second application onwards, use this format with a \$1 sign to specify a unique SPN value. 1. In the **User Attributes and Claims** section, choose the edit icon. By default, the Unique User Identifier (UID), Role, RoleSessionName, and SessionDuration claims are pre-configured. 1. Choose **\$1 Add new claim** to add a claim for database users. For **Name**, enter **DbUser**. For **Namespace**, enter **https://redshift.amazon.com/SAML/Attributes**. For **Source**, choose **Attribute**. For **Source attribute**, choose **user.userprincipalname**. Then, choose **Save**. 1. Choose **\$1 Add new claim** to add a claim for AutoCreate. For **Name**, enter **AutoCreate**. For **Namespace**, enter **https://redshift.amazon.com/SAML/Attributes**. For **Source**, choose **Attribute**. For **Source attribute**, choose **"true"**. Then, choose **Save**. Here, `123456789012` is your AWS account, *`AzureSSO`* is an IAM role you created, and *`AzureADProvider`* is the IAM provider. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/redshift/latest/mgmt/setup-identity-provider-azure.html) 1. Under **App Registration > ***your-application-name*** > Authentication**, add **Mobile And Desktop Application**. Specify the URL as http://localhost/redshift/. 1. In the **SAML Signing Certificate** section, choose **Download** to download and save the federation metadata XML file for use when you create an IAM SAML identity provider. This file is used to create the single sign-on federated identity. 1. Create an IAM SAML identity provider on the IAM console. The metadata document that you provide is the federation metadata XML file that you saved when you set up Azure Enterprise Application. For detailed steps, see [Creating and Managing an IAM Identity Provider (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html#idp-manage-identityprovider-console) in the *IAM User Guide*. 1. Create an IAM role for SAML 2.0 federation on the IAM console. For detailed steps, see [ Creating a Role for SAML](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html#idp_saml_Create) in the *IAM User Guide*. 1. Create an IAM policy that you can attach to the IAM role that you created for SAML 2.0 federation on the IAM console. For detailed steps, see [Creating IAM Policies (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) in the *IAM User Guide*. Modify the following policy (in JSON format) for your environment: + Substitute the AWS Region of your cluster for `us-west-1`. + Substitute your AWS account for *`123456789012`*. + Substitute your cluster identifier (or `*` for all clusters) for *`cluster-identifier`*. + Substitute your database (or `*` for all databases) for *`dev`*. + Substitute the unique identifier of your IAM role for *`AROAJ2UCCR6DPCEXAMPLE`*. + Substitute your tenant or company email domain for `example.com`. + Substitute the database group that you plan to assign the user to for *`my_dbgroup`*. ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "redshift:GetClusterCredentials", "Resource": [ "arn:aws:redshift:us-west-1:123456789012:dbname:cluster-identifier/dev", "arn:aws:redshift:us-west-1:123456789012:dbuser:cluster-identifier/${redshift:DbUser}", "arn:aws:redshift:us-west-1:123456789012:cluster:cluster-identifier" ], "Condition": { "StringEquals": { "aws:userid": "AROAJ2UCCR6DPCEXAMPLE:${redshift:DbUser}@example.com" } } }, { "Effect": "Allow", "Action": "redshift:CreateClusterUser", "Resource": "arn:aws:redshift:us-west-1:123456789012:dbuser:cluster-identifier/${redshift:DbUser}" }, { "Effect": "Allow", "Action": "redshift:JoinGroup", "Resource": "arn:aws:redshift:us-west-1:123456789012:dbgroup:cluster-identifier/my_dbgroup" }, { "Effect": "Allow", "Action": [ "redshift:DescribeClusters", "iam:ListRoles" ], "Resource": "*" } ] } ``` This policy grants permissions as follows: + The first section grants permission to the `GetClusterCredentials` API operation to get temporary credentials for the specified cluster. In this example, the resource is `cluster-identifier` with database *`dev`*, in account *`123456789012`*, and in AWS Region *`us-west-1`*. The `${redshift:DbUser}` clause allows only users that match the `DbUser` value specified in Azure AD to connect. + The condition clause enforces that only certain users get temporary credentials. These are users under the role specified by the role unique ID *`AROAJ2UCCR6DPCEXAMPLE`* in the IAM account identified by an email address in your company's email domain. For more information about unique IDs, see [Unique IDs](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-unique-ids) in the *IAM User Guide*. Your setup with your IdP (in this case, Azure AD) determines how the condition clause is written. If your employee's email is `johndoe@example.com`, first set `${redshift:DbUser}` to the super field that matches the employee's user name `johndoe`. Then, to make this condition work, set the AWS SAML `RoleSessionName` field to the super field that matches the employee’s email `johndoe@example.com`. When you take this approach, consider the following: + If you set `${redshift:DbUser}` to be the employee's email, then remove the `@example.com` in the example JSON to match the `RoleSessionName`. + If you set the `RoleSessionId` to be just the employee's user name, then remove the `@example.com` in the example to match the `RoleSessionName`. + In the example JSON, the `${redshift:DbUser}` and `RoleSessionName` are both set to the employee's email. This example JSON uses the Amazon Redshift database user name with `@example.com` to sign the user in to access the cluster. + The second section grants permission to create a `dbuser` name in the specified cluster. In this example JSON, it restricts creation to `${redshift:DbUser}`. + The third section grants permission to specify which `dbgroup` a user can join. In this example JSON, a user can join the `my_dbgroup` group in the specified cluster. + The fourth section grants permission to actions the user can do on all resources. In this example JSON, it allows users to call `redshift:DescribeClusters` to get cluster information such as the cluster endpoint, AWS Region, and port. It also allows users to call `iam:ListRoles` to check which roles a user can assume. ## Step 2: Set up JDBC or ODBC for authentication to Azure ------ #### [ JDBC ] **To set up JDBC for authentication to Microsoft Azure AD** + Configure your database client to connect to your cluster through JDBC using your Azure AD single sign-on. You can use any client that uses a JDBC driver to connect using Azure AD single sign-on or use a language like Java to connect using a script. For installation and configuration information, see [Configuring a connection for JDBC driver version 2.x for Amazon Redshift](jdbc20-install.md). For example, you can use SQLWorkbench/J as the client. When you configure SQLWorkbench/J, the URL of your database uses the following format. ``` jdbc:redshift:iam://cluster-identifier:us-west-1/dev ``` If you use SQLWorkbench/J as the client, take the following steps: 1. Start SQL Workbench/J. On the **Select Connection Profile** page, add a **Profile Group** called **AzureAuth**. 1. For **Connection Profile**, enter **Azure**. 1. Choose **Manage Drivers**, and choose **Amazon Redshift**. Choose the **Open Folder** icon next to **Library**, then choose the appropriate JDBC .jar file. 1. On the **Select Connection Profile** page, add information to the connection profile as follows: + For **User**, enter your Microsoft Azure user name. This is the user name of the Microsoft Azure account that you are using for single sign-on that has permission to the cluster that you are trying to authenticate using. + For **Password**, enter your Microsoft Azure password. + For **Drivers**, choose **Amazon Redshift (com.amazon.redshift.jdbc.Driver)**. + For **URL**, enter **jdbc:redshift:iam://*your-cluster-identifier*:*your-cluster-region*/*your-database-name***. 1. Choose **Extended Properties** to add additional information to the connection properties, as described following. For Azure AD single sign-on configuration, add additional information as follows: + For **plugin\$1name**, enter **com.amazon.redshift.plugin.AzureCredentialsProvider**. This value specifies to the driver to use Azure AD Single Sign-On as the authentication method. + For **idp\$1tenant**, enter ***your-idp-tenant***. Used only for Microsoft Azure AD. This is the tenant name of your company configured on Azure AD. This value can either be the tenant name or the tenant unique ID with hyphens. + For **client\$1secret**, enter ***your-azure-redshift-application-client-secret***. Used only for Microsoft Azure AD. This is your client secret of the Amazon Redshift application that you created when setting up your Azure Single Sign-On configuration. This is only applicable to the com.amazon.redshift.plugin.AzureCredentialsProvider plugin. + For **client\$1id**, enter ***your-azure-redshift-application-client-id***. Used only for Microsoft Azure AD. This is the client ID (with hyphens) of the Amazon Redshift application that you created when setting up your Azure Single Sign-On configuration. For Azure AD single sign-on with MFA configuration, add additional information to the connection properties as follows: + For **plugin\$1name**, enter **com.amazon.redshift.plugin.BrowserAzureCredentialsProvider**. This value specifies to the driver to use Azure AD single sign-on with MFA as the authentication method. + For **idp\$1tenant**, enter ***your-idp-tenant***. Used only for Microsoft Azure AD. This is the tenant name of your company configured on Azure AD. This value can either be the tenant name or the tenant unique ID with hyphens. + For **client\$1id**, enter ***your-azure-redshift-application-client-id***. This option is used only for Microsoft Azure AD. This is the client ID (with hyphens) of the Amazon Redshift application that you created when setting up your Azure AD single sign-on with MFA configuration. + For **listen\$1port**, enter ***your-listen-port***. This is the port that local server is listening to. The default is 7890. + For **idp\$1response\$1timeout**, enter ***the-number-of-seconds***. This is the number of seconds to wait before timing out when the IdP server sends back a response. The minimum number of seconds must be 10. If establishing the connection takes longer than this threshold, then the connection is aborted. ------ #### [ ODBC ] **To set up ODBC for authentication to Microsoft Azure AD** + Configure your database client to connect to your cluster through ODBC using your Azure AD single sign-on. Amazon Redshift provides ODBC drivers for Linux, Windows, and macOS operating systems. Before you install an ODBC driver, determine whether your SQL client tool is 32-bit or 64-bit. Install the ODBC driver that matches the requirements of your SQL client tool. On Windows, in the **Amazon Redshift ODBC Driver DSN Setup** page, under **Connection Settings**, enter the following information: + For **Data Source Name**, enter ***your-DSN***. This specifies the data source name used as the ODBC profile name. + For **Auth type** for Azure AD single sign-on configuration, choose **Identity Provider: Azure AD**. This is the authentication method that the ODBC driver uses to authenticate using Azure single sign-on. + For **Auth type** for Azure AD single sign-on with MFA configuration, choose **Identity Provider: Browser Azure AD**. This is the authentication method that the ODBC driver uses to authenticate using Azure single sign-on with MFA. + For **Cluster ID**, enter ***your-cluster-identifier***. + For **Region**, enter ***your-cluster-region***. + For **Database**, enter ***your-database-name***. + For **User**, enter ***your-azure-username***. This is the user name for the Microsoft Azure account that you are using for single sign-on that has permission to the cluster that you're trying to authenticate using. Use this only for **Auth Type** is **Identity Provider: Azure AD**. + For **Password**, enter ***your-azure-password***. Use this only for **Auth Type** is **Identity Provider: Azure AD**. + For **IdP Tenant**, enter ***your-idp-tenant***. This is the tenant name of your company configured on your IdP (Azure). This value can either be the tenant name or the tenant unique ID with hyphens. + For **Azure Client Secret**, enter ***your-azure-redshift-application-client-secret***. This is the client secret of the Amazon Redshift application that you created when setting up your Azure single sign-on configuration. + For **Azure Client ID**, enter ***your-azure-redshift-application-client-id***. This is the client ID (with hyphens) of the Amazon Redshift application that you created when setting up your Azure single sign-on configuration. + For **Listen Port**, enter ***your-listen-port***. This is the default listen port that local server is listening to. The default is 7890. This applies only to the Browser Azure AD plugin. + For **Response Timeout**, enter ***the-number-of-seconds***. This is the number of seconds to wait before timing out when the IdP server sends back a response. The minimum number of seconds must be 10. If establishing the connection takes longer than this threshold, then the connection is aborted. This option applies only to the Browser Azure AD plugin. On macOS and Linux, edit the `odbc.ini` file as follows: **Note** All entries are case-insensitive. + For **clusterid**, enter ***your-cluster-identifier***. This is the name of the created Amazon Redshift cluster. + For **region**, enter ***your-cluster-region***. This is the AWS Region of the created Amazon Redshift cluster. + For **database**, enter ***your-database-name***. This is the name of the database that you're trying to access on the Amazon Redshift cluster. + For **locale**, enter **en-us**. This is the language that error messages display in. + For **iam**, enter **1**. This value specifies to the driver to authenticate using IAM credentials. + For **plugin\$1name** for Azure AD single sign-on configuration, enter **AzureAD**. This specifies to the driver to use Azure Single Sign-On as the authentication method. + For **plugin\$1name** for Azure AD single sign-on with MFA configuration, enter **BrowserAzureAD**. This specifies to the driver to use Azure Single Sign-On with MFA as the authentication method. + For **uid**, enter ***your-azure-username***. This is the user name of the Microsoft Azure account you are using for single sign-on that has permission to the cluster you are trying to authenticate against. Use this only for **plugin\$1name** is **AzureAD**. + For **pwd**, enter ***your-azure-password***. Use this only for **plugin\$1name** is **AzureAD**. + For **idp\$1tenant**, enter ***your-idp-tenant***. This is the tenant name of your company configured on your IdP (Azure). This value can either be the tenant name or the tenant unique ID with hyphens. + For **client\$1secret**, enter ***your-azure-redshift-application-client-secret***. This is the client secret of the Amazon Redshift application that you created when setting up your Azure single sign-on configuration. + For **client\$1id**, enter ***your-azure-redshift-application-client-id***. This is the client ID (with hyphens) of the Amazon Redshift application that you created when setting up your Azure single sign-on configuration. + For **listen\$1port**, enter ***your-listen-port***. This is the port that local server is listening to. The default is 7890. This applies to the Browser Azure AD plugin. + For **idp\$1response\$1timeout**, enter ***the-number-of-seconds***. This is the specified period of time in seconds to wait for response from Azure. This option applies to the Browser Azure AD plugin. On macOS and Linux, also edit the profile settings to add the following exports. ``` export ODBCINI=/opt/amazon/redshift/Setup/odbc.ini ``` ``` export ODBCINSTINI=/opt/amazon/redshift/Setup/odbcinst.ini ``` ------ ## Troubleshooting To troubleshoot issues with the Browser Azure AD plugin, consider the following. + To use the Browser Azure AD plugin, you must set the reply URL specified in the request to match the reply URL configured for your application. Navigate to the **Set up Single Sign-On with SAML** page on the Microsoft Azure portal. Then check the **Reply URL** is set to http://localhost/redshift/. + If you get an IdP tenant error, verify that the **IdP Tenant** name matches the domain name you initially used to set up the Active Directory in Microsoft Azure. On Windows, navigate to the **Connection Settings** section of the **Amazon Redshift ODBC DSN Setup** page. Then check the tenant name of your company configured on your IdP (Azure) matches the domain name you initially used to set up the Active Directory in Microsoft Azure. On macOS and Linux, find the *odbc.ini* file. Then check the tenant name of your company configured on your IdP (Azure) matches the domain name you initially used to set up the Active Directory in Microsoft Azure. + If you get an error that the reply URL specified in the request does not match the reply URLs configured for your application, verify that the **Redirect URIs** is the same as the reply URL. Navigate to the **App registration** page of your application on the Microsoft Azure portal. Then check the Redirect URIs matches the reply URL. + If you get the unexpected response: unauthorized error, verify that you completed the **Mobile and desktop applications** configuration. Navigate to the ** App registration** page of your application on the Microsoft Azure portal. Then navigate to **Authentication** and check that you configured **Mobile and desktop applications** to use http://localhost/redshift/ as the redirect URIs. # Ping Identity You can use Ping Identity as an identity provider (IdP) to access your Amazon Redshift cluster. This tutorial shows you how you can use Ping Identity as an identity provider (IdP) to access your Amazon Redshift cluster. ## Step 1: Set up Ping Identity and your AWS account to trust each other The following procedure describes how to set up a trust relationship using the PingOne portal. **To set up Ping Identity and your AWS account to trust each other** 1. Create or use an existing Amazon Redshift cluster for your Ping Identity users to connect to. To configure the connection, certain properties of this cluster are needed, such as the cluster identifier. For more information, see [Creating a Cluster](https://docs.aws.amazon.com/redshift/latest/mgmt/create-cluster.html). 1. Add Amazon Redshift as a new SAML application on the PingOne portal. For detailed steps, see the [Ping Identity documentation](https://docs.pingidentity.com/). 1. Go to **My Applications**. 1. Under **Add Application**, choose **New SAML Application**. 1. For **Application Name**, enter **Amazon Redshift**. 1. For **Protocol Version**, choose **SAML v2.0**. 1. For **Category**, choose ***your-application-category***. 1. For **Assertion Consumer Service (ACS)**, type ***your-redshift-local-host-url***. This is the local host and port that the SAML assertion redirects to. 1. For **Entity ID**, enter `urn:amazon:webservices`. 1. For **Signing**, choose **Sign Assertion**. 1. In the **SSO Attribute Mapping** section, create the claims as shown in the following table. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/redshift/latest/mgmt/setup-identity-provider-ping.html) 1. For **Group Access**, set up the following group access, if needed: + **https://aws.amazon.com/SAML/Attributes/Role** + **https://aws.amazon.com/SAML/Attributes/RoleSessionName** + **https://redshift.amazon.com/SAML/Attributes/AutoCreate** + **https://redshift.amazon.com/SAML/Attributes/DbUser** 1. Review your setup and make changes, if necessary. 1. Use the **Initiate Single Sign-On (SSO) URL** as the login URL for the Browser SAML plugin. 1. Create an IAM SAML identity provider on the IAM console. The metadata document that you provide is the federation metadata XML file that you saved when you set up Ping Identity. For detailed steps, see [ Creating and Managing an IAM Identity Provider (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html#idp-manage-identityprovider-console) in the *IAM User Guide*. 1. Create an IAM role for SAML 2.0 federation on the IAM console. For detailed steps, see [ Creating a Role for SAML](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html#idp_saml_Create) in the *IAM User Guide*. 1. Create an IAM policy that you can attach to the IAM role that you created for SAML 2.0 federation on the IAM console. For detailed steps, see [Creating IAM Policies (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) in the *IAM User Guide*. For an Azure AD example, see [Setting up JDBC or ODBC single sign-on authentication](setup-azure-ad-identity-provider.md). ## Step 2: Set up JDBC or ODBC for authentication to Ping Identity ------ #### [ JDBC ] **To set up JDBC for authentication to Ping Identity** + Configure your database client to connect to your cluster through JDBC using Ping Identity single sign-on. You can use any client that uses a JDBC driver to connect using Ping Identity single sign-on or use a language like Java to connect using a script. For installation and configuration information, see [Configuring a connection for JDBC driver version 2.x for Amazon Redshift](jdbc20-install.md). For example, you can use SQLWorkbench/J as the client. When you configure SQLWorkbench/J, the URL of your database uses the following format. ``` jdbc:redshift:iam://cluster-identifier:us-west-1/dev ``` If you use SQLWorkbench/J as the client, take the following steps: 1. Start SQL Workbench/J. In the **Select Connection Profile** page, add a **Profile Group**, for example **Ping**. 1. For **Connection Profile**, enter ***your-connection-profile-name***, for example **Ping**. 1. Choose **Manage Drivers**, and choose **Amazon Redshift**. Choose the **Open Folder** icon next to **Library**, then choose the appropriate JDBC .jar file. 1. On the **Select Connection Profile** page, add information to the connection profile as follows: + For **User**, enter your PingOne user name. This is the user name of the PingOne account that you are using for single sign-on that has permission to the cluster that you are trying to authenticate using. + For **Password**, enter your PingOne password. + For **Drivers**, choose **Amazon Redshift (com.amazon.redshift.jdbc.Driver)**. + For **URL**, enter **jdbc:redshift:iam://*your-cluster-identifier*:*your-cluster-region*/*your-database-name***. 1. Choose **Extended Properties** and do one of the following: + For **login\$1url**, enter ***your-ping-sso-login-url***. This value specifies to the URL to use single sign-on as the authentication to log in. + For Ping Identity, for **plugin\$1name**, enter **com.amazon.redshift.plugin.PingCredentialsProvider**. This value specifies to the driver to use Ping Identity single sign-on as the authentication method. + For Ping Identity with single sign-on, for **plugin\$1name**, enter **com.amazon.redshift.plugin.BrowserSamlCredentialsProvider**. This value specifies to the driver to use Ping Identity PingOne with single sign-on as the authentication method. ------ #### [ ODBC ] **To set up ODBC for authentication to Ping Identity** + Configure your database client to connect to your cluster through ODBC using Ping Identity PingOne single sign-on. Amazon Redshift provides ODBC drivers for Linux, Windows, and macOS operating systems. Before you install an ODBC driver, determine whether your SQL client tool is 32-bit or 64-bit. Install the ODBC driver that matches the requirements of your SQL client tool. On Windows, in the **Amazon Redshift ODBC Driver DSN Setup** page, under **Connection Settings**, enter the following information: + For **Data Source Name**, enter ***your-DSN***. This specifies the data source name used as the ODBC profile name. + For **Auth type**, do one of the following: + For Ping Identity configuration, choose **Identity Provider: Ping Federate**. This is the authentication method that the ODBC driver uses to authenticate using Ping Identity single sign-on. + For Ping Identity with single sign-on configuration, choose **Identity Provider: Browser SAML**. This is the authentication method that the ODBC driver uses to authenticate using Ping Identity with single sign-on. + For **Cluster ID**, enter ***your-cluster-identifier***. + For **Region**, enter ***your-cluster-region***. + For **Database**, enter ***your-database-name***. + For **User**, enter ***your-ping-username***. This is the user name for the PingOne account that you are using for single sign-on that has permission to the cluster that you're trying to authenticate using. Use this only for **Auth type** is **Identity Provider: PingFederate**. + For **Password**, enter ***your-ping-password***. Use this only for **Auth type** is **Identity Provider: PingFederate**. + For **Listen Port**, enter ***your-listen-port***. This is the port that local server is listening to. The default is 7890. This applies only to the Browser SAML plugin. + For **Response Timeout**, enter ***the-number-of-seconds***. This is the number of seconds to wait before timing out when the IdP server sends back a response. The minimum number of seconds must be 10. If establishing the connection takes longer than this threshold, then the connection is aborted. This applies only to the Browser SAML plugin. + For **Login URL**, enter ***your-login-url***. This applies only to the Browser SAML plugin. On macOS and Linux, edit the `odbc.ini` file as follows: **Note** All entries are case-insensitive. + For **clusterid**, enter ***your-cluster-identifier***. This is the name of the created Amazon Redshift cluster. + For **region**, enter ***your-cluster-region***. This is the AWS Region of the created Amazon Redshift cluster. + For **database**, enter ***your-database-name***. This is the name of the database that you're trying to access on the Amazon Redshift cluster. + For **locale**, enter **en-us**. This is the language that error messages display in. + For **iam**, enter **1**. This value specifies to the driver to authenticate using IAM credentials. + For **plugin\$1name**, do one of the following: + For Ping Identity configuration, enter **BrowserSAML**. This is the authentication method that the ODBC driver uses to authenticate to Ping Identity. + For Ping Identity with single sign-on configuration, enter **Ping**. This is the authentication method that the ODBC driver uses to authenticate using Ping Identity with single sign-on. + For **uid**, enter ***your-ping-username***. This is the user name of the Microsoft Azure account you are using for single sign-on that has permission to the cluster you are trying to authenticate against. Use this only for **plugin\$1name** is **Ping**. + For **pwd**, enter ***your-ping-password***. Use this only for **plugin\$1name** is **Ping**. + For **login\$1url**, enter ***your-login-url***. This is the Initiate single sign-on URL that returns the SAML Response. This applies only to the Browser SAML plugin. + For **idp\$1response\$1timeout**, enter ***the-number-of-seconds***. This is the specified period of time in seconds to wait for response from PingOne Identity. This applies only to the Browser SAML plugin. + For **listen\$1port**, enter ***your-listen-port***. This is the port that local server is listening to. The default is 7890. This applies only to the Browser SAML plugin. On macOS and Linux, also edit the profile settings to add the following exports. ``` export ODBCINI=/opt/amazon/redshift/Setup/odbc.ini ``` ``` export ODBCINSTINI=/opt/amazon/redshift/Setup/odbcinst.ini ``` ------ # Okta You can use Okta as an identity provider (IdP) to access your Amazon Redshift cluster. This tutorial shows you how you can use Okta as an identity provider (IdP) to access your Amazon Redshift cluster. ## Step 1: Set up Okta and your AWS account to trust each other The following procedure describes how to set up a trust relationship. **To set up Okta and your AWS account to trust each other** 1. Create or use an existing Amazon Redshift cluster for your Okta users to connect to. To configure the connection, certain properties of this cluster are needed, such as the cluster identifier. For more information, see [Creating a Cluster](https://docs.aws.amazon.com/redshift/latest/mgmt/create-cluster.html). 1. Add Amazon Redshift as a new application on the Okta portal. For detailed steps, see the [Okta documentation](https://developer.okta.com/docs/). + Choose **Add Application**. + Under **Add Application**, choose **Create New App**. + On the **Create a New Add Application Integration** page, for **Platform**, choose **Web**. + For **Sign on method**, choose **SAML v2.0**. + On the **General Settings** page, for **App name**, enter ***your-redshift-saml-sso-name***. This is the name of your application. + On the **SAML Settings** page, for **Single sign on URL**, enter ***your-redshift-local-host-url***. This is the local host and port that the SAML assertion redirects to, for example `http://localhost:7890/redshift/`. 1. Use the **Single sign on URL** value as the **Recipient URL** and **Destination URL**. 1. For **Signing**, choose **Sign Assertion**. 1. For **Audience URI (SP Entity ID)**, enter **urn:amazon:webservices** for the claims, as shown in the following table. 1. In the **Advanced Settings** section, for **SAML Issuer ID**, enter ***your-Identity-Provider-Issuer-ID***, which you can find in the **View Setup Instructions** section. 1. In the **Attribute Statements** section, create the claims as shown in the following table. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/redshift/latest/mgmt/setup-identity-provider-okta.html) 1. In the **App Embed Link** section, find the URL that you can use as the login URL for the Browser SAML plugin. 1. Create an IAM SAML identity provider on the IAM console. The metadata document that you provide is the federation metadata XML file that you saved when you set up Okta. For detailed steps, see [ Creating and Managing an IAM Identity Provider (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html#idp-manage-identityprovider-console) in the *IAM User Guide*. 1. Create an IAM role for SAML 2.0 federation on the IAM console. For detailed steps, see [ Creating a Role for SAML](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html#idp_saml_Create) in the *IAM User Guide*. 1. Create an IAM policy that you can attach to the IAM role that you created for SAML 2.0 federation on the IAM console. For detailed steps, see [Creating IAM Policies (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) in the *IAM User Guide*. For an Azure AD example, see [Setting up JDBC or ODBC single sign-on authentication](setup-azure-ad-identity-provider.md). ## Step 2: Set up JDBC or ODBC for authentication to Okta ------ #### [ JDBC ] **To set up JDBC for authentication to Okta** + Configure your database client to connect to your cluster through JDBC using Okta single sign-on. You can use any client that uses a JDBC driver to connect using Okta single sign-on or use a language like Java to connect using a script. For installation and configuration information, see [Configuring a connection for JDBC driver version 2.x for Amazon Redshift](jdbc20-install.md). For example, you can use SQLWorkbench/J as the client. When you configure SQLWorkbench/J, the URL of your database uses the following format. ``` jdbc:redshift:iam://cluster-identifier:us-west-1/dev ``` If you use SQLWorkbench/J as the client, take the following steps: 1. Start SQL Workbench/J. In the **Select Connection Profile** page, add a **Profile Group**, for example **Okta**. 1. For **Connection Profile**, enter ***your-connection-profile-name***, for example **Okta**. 1. Choose **Manage Drivers**, and choose **Amazon Redshift**. Choose the **Open Folder** icon next to **Library**, then choose the appropriate JDBC .jar file. 1. On the **Select Connection Profile** page, add information to the connection profile as follows: + For **User**, enter your Okta user name. This is the user name of the Okta account that you are using for single sign-on that has permission to the cluster that you are trying to authenticate using. + For **Password**, enter your Okta password. + For **Drivers**, choose **Amazon Redshift (com.amazon.redshift.jdbc.Driver)**. + For **URL**, enter **jdbc:redshift:iam://*your-cluster-identifier*:*your-cluster-region*/*your-database-name***. 1. Choose **Extended Properties** and do one of the following: + For **login\$1url**, enter ***your-okta-sso-login-url***. This value specifies to the URL to use single sign-on as the authentication to log in to Okta. + For Okta single sign-on, for **plugin\$1name**, enter **com.amazon.redshift.plugin.OktaCredentialsProvider**. This value specifies to the driver to use Okta single sign-on as the authentication method. + For Okta single sign-on with MFA, for **plugin\$1name**, enter **com.amazon.redshift.plugin.BrowserSamlCredentialsProvider**. This value specifies to the driver to use Okta single sign-on with MFA as the authentication method. ------ #### [ ODBC ] **To set up ODBC for authentication to Okta** + Configure your database client to connect to your cluster through ODBC using Okta single sign-on. Amazon Redshift provides ODBC drivers for Linux, Windows, and macOS operating systems. Before you install an ODBC driver, determine whether your SQL client tool is 32-bit or 64-bit. Install the ODBC driver that matches the requirements of your SQL client tool. On Windows, in the **Amazon Redshift ODBC Driver DSN Setup** page, under **Connection Settings**, enter the following information: + For **Data Source Name**, enter ***your-DSN***. This specifies the data source name used as the ODBC profile name. + For **Auth type**, do one of the following: + For Okta single sign-on configuration, choose **Identity Provider: Okta**. This is the authentication method that the ODBC driver uses to authenticate using Okta single sign-on. + For Okta single sign-on with MFA configuration, choose **Identity Provider: Browser SAML**. This is the authentication method that the ODBC driver uses to authenticate using Okta single sign-on with MFA. + For **Cluster ID**, enter ***your-cluster-identifier***. + For **Region**, enter ***your-cluster-region***. + For **Database**, enter ***your-database-name***. + For **User**, enter ***your-okta-username***. This is the user name for the Okta account that you are using for single sign-on that has permission to the cluster that you're trying to authenticate using. Use this only for **Auth type** is **Identity Provider: Okta**. + For **Password**, enter ***your-okta-password***. Use this only for **Auth type** is **Identity Provider: Okta**. On macOS and Linux, edit the `odbc.ini` file as follows: **Note** All entries are case-insensitive. + For **clusterid**, enter ***your-cluster-identifier***. This is the name of the created Amazon Redshift cluster. + For **region**, enter ***your-cluster-region***. This is the AWS Region of the created Amazon Redshift cluster. + For **database**, enter ***your-database-name***. This is the name of the database that you're trying to access on the Amazon Redshift cluster. + For **locale**, enter **en-us**. This is the language that error messages display in. + For **iam**, enter **1**. This value specifies to the driver to authenticate using IAM credentials. + For **plugin\$1name**, do one of the following: + For Okta single sign-on with MFA configuration, enter **BrowserSAML**. This is the authentication method that the ODBC driver uses to authenticate to Okta single sign-on with MFA. + For Okta single sign-on configuration, enter **Okta**. This is the authentication method that the ODBC driver uses to authenticate using Okta single sign-on. + For **uid**, enter ***your-okta-username***. This is the user name of the Okta account you are using for single sign-on that has permission to the cluster you are trying to authenticate against. Use this only for **plugin\$1name** is **Okta**. + For **pwd**, enter ***your-okta-password***. Use this only for **plugin\$1name** is **Okta**. + For **login\$1url**, enter ***your-login-url***. This is the Initiate single sign-on URL that returns the SAML Response. This applies only to the Browser SAML plugin. + For **idp\$1response\$1timeout**, enter ***the-number-of-seconds***. This is the specified period of time in seconds to wait for response from PingOne. This applies only to the Browser SAML plugin. + For **listen\$1port**, enter ***your-listen-port***. This is the port that local server is listening to. The default is 7890. This applies only to the Browser SAML plugin. On macOS and Linux, also edit the profile settings to add the following exports. ``` export ODBCINI=/opt/amazon/redshift/Setup/odbc.ini ``` ``` export ODBCINSTINI=/opt/amazon/redshift/Setup/odbcinst.ini ``` ------