--- schema_version: "1" id: 80970af074fc5c0f6c41cdaa9a21202cb59d7b875213bffcd29fa9f097052e54 title: Set Up Amazon Redshift IAM OAuth collection: tableau version: next locale: en-us portal_url: https://docs.salesforce.com/tableau/next/en-us/online/config_oauth_redshift_iam.md canonical_url: https://help.tableau.com/v0.0/online/en-us/config_oauth_redshift_iam.htm source_site: help.tableau.com content_type: documentation content_hash: 19152f407da00b1638c634fb7048f4ccac15119944e18c0da0301bc65cdb9059 description: Set up Amazon Redshift IAM OAuth identity federation from an external IdP for Tableau. --- [Skip to main content](#main-content) # Set Up Amazon Redshift IAM OAuth These instructions are for the older AWS IAM service. For IAM IDC integration see [Set Up Amazon Redshift IAM Identity Center OAuth](https://help.tableau.com/v0.0/online/en-us/config_oauth_redshift_iam_idc.htm). Depending on the identity provider, there are different steps needed to configure the integration. This is a high-level overview. Tableau cannot provide detailed instructions for how to configure AWS or the IDP, but the general approach is described below. **Note**: Single use refresh tokens (sometimes called rolling refresh tokens or refresh token rotation) are not supported for OAuth connections using Tableau Bridge to Tableau Cloud. Support for these tokens are planned for a future release. ## Step 1: Configure the IDP 1. Create OAuth clients on the IDP for Tableau Desktop, and Tableau Server or Tableau Cloud. The Desktop client should enable `PKCE` and use `http://localhost` redirects. 2. Add custom claims to use for authorization to roles. In particular, if you are using original IAM, you may want to add claims for `DbUser` and `DbGroups`. These can be used in your IAM policies later. 3. Create the Tableau OAuth config files. See documentation on [GitHub](https://tableau.github.io/connector-plugin-sdk/docs/oauth "OAuth documentation on GitHub"), and examples [here](https://github.com/tableau/connector-plugin-sdk/tree/master/samples/components/oauth "OAuth examples on GitHub."). We welcome examples for other IDPs. 1. Be sure to prefix the Tableau OAuth config IDs with "`custom_`". **Note:** Oauth config IDs have a maximum limit of 36 characters. IDs longer than this may not generate an error, but will not work. 2. If your IDP supports dynamic localhost port then disable `OAUTH_CAP_FIXED_PORT_IN_CALLBACK_URL`. If your IDP does not support this, make sure to add several localhost callback URLs to the allowlist in the config file and on the IDP. 4. Install the new Tableau OAuth configuration files in the `OAuthConfigs` folder associated with each application on desktop hosts (Tableau Desktop, Tableau Prep Builder, Tableau Bridge), and on each Tableau Server and Tableau Cloud site that will be using OAuth. ## Configure IDP on AWS 1\. Create the IDP model on the AWS. See Amazon docs [Web Identity Federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html "AWS documentation on Web Identity Federation") and [Create OIDC Identity Provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html "AWS documentation on creating OIDC Identity Provider"). 2\. Create roles and policies specifically for the IDP. See [Create Role for OIDC](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html "AWS documentation for creating roles for OIDC") in the AWS docs. ## Configure Roles for Redshift Users Attach the policies needed for Redshift. You may use custom claims from the token to authorize to roles. There are several examples with SAML in [the AWS documentation](https://docs.aws.amazon.com/redshift/latest/mgmt/options-for-providing-iam-credentials.html "AWS documentation for providing IAM credentials"). These can be easily adapted to OAuth. In the case of OAuth, the claims are just "`DbUser`", "`DbGroups`", etc. Here is an example of the policy from the AWS documentation: { "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:12345:dbuser:cluster-identifier/${redshift:DbUser}" }, { "Effect": "Allow", "Action": "redshift:JoinGroup", "Resource": "arn:aws:redshift:us-west-1:12345:dbgroup:cluster-identifier/my\_dbgroup" }, { "Effect": "Allow", "Action": \[ "redshift:DescribeClusters", "iam:ListRoles" \], "Resource": "\*" } \] } ## Connect to Redshift The user must specify the role ARN to assume, and select the OAuth config installed earlier. ![](/tableau/next/en-us/online/en-us/Img/redshift_oauth__iam_connect.png) When properly configured, the user will be redirected to the IDP to authenticate and authorize tokens for Tableau. Tableau will receive openid and refresh tokens. AWS is able to validate the token and signature from the IDP, extract the claims from the token, look up the mapping of claims to IAM role, and either permit or block Tableau from assuming the role on the user's behalf. (in other words, [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html "AWS documentation for AssumeRoleWithWebIdentity")). ## Tokens By default Redshift OAuth IAM passes the ID token to the driver. For on-premise customers, including those using Tableau Bridge, you may use a TDC file to pass the access token instead. For more information about configuring and installing .tdc files, see [Customize and Tune a Connection](https://help.tableau.com/current/pro/desktop/en-us/connect_customize.htm) and [Using a .tdc File with Tableau Server](https://help.salesforce.com/s/articleView?id=001458291&type=1). ## About Group Federation When using OAuth authentication with an IAM Role, you can select whether or not you are using Group Federation. This will change how the connector interacts with the authentication API to interface with Redshift. - When the Group Federation box (available in versions 2025.1 and beyond) is checked while connecting, the Redshift driver will use the `[getClusterCredentialsWithIAM](https://docs.aws.amazon.com/redshift/latest/APIReference/API_GetClusterCredentialsWithIAM.html)` API for obtaining the credentials in provisioned clusters. - When the Group Federation box is not checked, the `[getClusterCredentials](https://docs.aws.amazon.com/redshift/latest/APIReference/API_GetClusterCredentials.html)` API will be used instead. These two APIs will return IAM tokens with slightly different properties. For more information, consult the AWS API documentation linked above, and [ODBC driver options](https://docs.aws.amazon.com/redshift/latest/mgmt/odbc20-configuration-options.html "Information on configuring ODBC 2.0 with AWS"). #### Usage Notes - For Tableau Desktop and Tableau Prep Builder before version 2024.3, this can be set in the advanced driver configuration field using 'group\_federation=1'. It can also be configured by using a TDC file to define custom connection properties. For more information on using a TDC, see [Customize and Tune a Connection](https://help.tableau.com/current/pro/desktop/en-us/connect_customize.htm). - Starting in version 2024.3, there is a group\_federation field in the connection dialog for on-premise (Tableau Desktop, Tableau Prep Builder, and Tableau Server). This will be available in Tableau Cloud starting in 2025.1 (Available in February 2025). - To use Group Federation with Tableau Server, group\_federation must be added to the ODBC extras allowlist. For more information, see [Customize Connection String for Native Connectors](https://help.tableau.com/current/pro/desktop/en-us/connect_string_custom.htm). ## Okta If using Okta it's better to use a "custom authorization server" rather than the "org authorization server." The custom authorization servers are more flexible. There is a custom authorization server created by default, which is called "default". The authorization URL should look like this: https://${yourOktaDomain}/oauth2/{authServerName}/v1/authorize ![](/tableau/next/en-us/online/en-us/Img/redshift_oauth_iam_okta_800x332.png) ## Update Driver For Redshift OAuth using the original IAM service, you may use either: - Redshift ODBC v1 driver starting with version 1.59, which can be downloaded from [https://docs.aws.amazon.com/redshift/latest/mgmt/configure-odbc-connection.html](https://docs.aws.amazon.com/redshift/latest/mgmt/configure-odbc-connection.html "Download Redshift ODBC V1 driver from Amazon"). - Redshift ODBC v2 driver starting with version 2.0.1.0, which can be downloaded from [https://github.com/aws/amazon-redshift-odbc-driver/tags](https://github.com/aws/amazon-redshift-odbc-driver/tags "Download the Redshift ODBC V2 driver from Amazon"). Note there is no v2 driver for OSX. ## Troubleshooting The best way to diagnose errors is to remove Tableau from the picture. You can instead test using the driver manager or a similar tool. This is just for troubleshooting - you shouldn't use a DSN or the "Other ODBC" connector for regular usage of this feature. To help ensure a valid test, the parameters should be the same as shown below, except for the cluster information, database, token, and namespace. **Note:** Don't specify DbUser or DbGroups in the connection string of the DSN when testing because Tableau does not have access to these and cannot include them in the connection string. You may include it in the token claims. If you see an error message about invalid/expired token coming from the driver on the first connection (it will have a SQLState error code like \[28000\] or \[08001\] in the error message), then Tableau successfully completed the OAuth flow, and failed in the driver. This means there is a misconfiguration on either the AWS side or the IDP side. There may also be permissions or authorization errors returned from the driver, which is also out of Tableau's control. Before you begin testing, you first need to get an access token (the default for IAM IDC) or refresh token (if customized) to send to the driver. Here is an example with Okta. Almost all IDPs have a way to do this which is quite similar. Note that to use this flow you need to have enabled resource owner password grant type. Substitute the IDP URL, client secret, client ID, username, and password. curl -X POST "https://OKTA\_URL/v1/token" \\ \-H 'accept: application/json' \\ \-H "Authorization: Basic $(echo -n 'CLIENTID:CLIENTSECRET' | base64)" \\ \-H "Content-Type: application/x-www-form-urlencoded" \\ \-d "grant\_type=password&username=USER&password=PASSWORD&scope=openid" Once you have the token, you can use a DSN to test. For Windows, you can use the ODBC driver manager. On Mac you can use the iODBC driver manager UI. On Linux you can use the isql command line tool that is included with Tableau Server in the customer-bin folder. The plugins that use a fixed AWS profile won't work unless you want to use the same profile for all users for that connection. The other OAuth plugins require direct access to the system browser, which doesn't work on the server side. Below is an example of using the ODBC driver manager on Windows. ![](/tableau/next/en-us/online/en-us/Img/redshift_oauth_iam_troubleshoot.jpg)