Amazon Redshift
Cluster Management Guide (API Version 2012-12-01)

Generating IAM Database Credentials Using the Amazon Redshift CLI or API

To programatically generate temporary database user credentials, Amazon Redshift provides the get-cluster-credentials command for the AWS Command Line Interface (AWS CLI) and the GetClusterCredentials API action. Alternatively, you can configure your SQL client with Amazon Redshift JDBC or ODBC drivers that manage the process of calling the GetClusterCredentials action, 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.


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 action 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 an IAM user or role with the required permissions. For more information about IAM permissions, see Create an IAM Role or User With Permissions to Call GetClusterCredentials.

  2. As an IAM user or role you authorized in the previous step, execute the get-cluster-credentials CLI command or call the GetClusterCredentials API action 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 is not specified, the user can log on to any cluster database.

    • Database groups – (Optional) A list of existing database user groups. Upon successful log on, the database user is added to the specified user groups. If no group is specified, the user has only PUBLIC permissions.This user group names must match the dbgroup resources ARNs specified in the IAM policy attached to the IAM 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.

  3. Amazon Redshift verifies that the IAM user has permission to call the GetClusterCredentials operation with the specified resources.

  4. 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 true --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=="
  5. Establish a Secure Socket Layer (SSL) authentication connection with the Amazon Redshift cluster and send a logon 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.


    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 Configure Security Options for Connections.

  6. If the connection doesn't use SSL, the connection attempt fails.

  7. The cluster sends an authentication request to the SQL client.

  8. The SQL client then sends the temporary password to the cluster.

  9. If the password is valid and has not expired, the cluster completes the connection.