Skip to content

Generating an Authentication Token in Amazon Aurora DSQL

Overview

To connect to Amazon Aurora DSQL with a SQL client, generate an authentication token to use as the password. This token is used only for authenticating the connection. After the connection is established, the connection remains valid even if the authentication token expires.

Token Expiration and Duration

  • AWS Console: Token automatically expires in one hour by default
  • CLI or SDKs: Default is 15 minutes
  • Maximum duration: 604,800 seconds (one week)

To connect to Aurora DSQL from your client again, you can use the same authentication token if it hasn't expired, or you can generate a new one.

Prerequisites

To get started with generating a token: 1. Create an IAM policy 2. Create a cluster in Aurora DSQL

At a minimum, you must have the IAM permissions for connecting to clusters, depending on which database role you use to connect.

Using the AWS Console to Generate an Authentication Token

Aurora DSQL authenticates users with a token rather than a password. You can generate the token from the console.

To generate an authentication token:

  1. Sign in to the AWS Console and open the Aurora DSQL console at https://console.aws.amazon.com/dsql

  2. Choose the cluster ID of the cluster for which you want to generate an authentication token

  3. Choose Connect and then select Get Token

  4. Choose whether you want to connect as an admin or with a custom database role

  5. Copy the generated authentication token and use it for connecting with SQL clients

Using AWS CloudShell to Generate an Authentication Token

Before you can generate an authentication token using CloudShell, make sure that you have created an Aurora DSQL cluster.

To generate an authentication token using CloudShell:

  1. Sign in to the AWS Console and open the Aurora DSQL console at https://console.aws.amazon.com/dsql

  2. At the bottom left of the AWS console, choose CloudShell

  3. Run the following command to generate an authentication token for the admin role:

# Use `generate-db-connect-auth-token` if you are _not_ logging in as `admin` user
aws dsql generate-db-connect-admin-auth-token \
  --expires-in 3600 \
  --region us-east-1 \
  --hostname your_cluster_endpoint

Note: If you're not connecting as admin, use generate-db-connect-auth-token instead.

  1. Use the following command to use psql to start a connection to your cluster:
PGSSLMODE=require \
psql --dbname postgres \
  --username admin \
  --host cluster_endpoint

  1. When prompted for a password, paste the generated token

  2. Press Enter to see the PostgreSQL prompt: postgres=>

Using the AWS CLI to Generate an Authentication Token

When your cluster is ACTIVE, you can generate an authentication token using the aws dsql command:

  • Admin role: Use generate-db-connect-admin-auth-token
  • Custom database role: Use generate-db-connect-auth-token

The following example uses these attributes to generate an authentication token for the admin role: - your_cluster_endpoint: The endpoint of the cluster (format: your_cluster_identifier.dsql.region.on.aws) - region: The AWS Region, such as us-east-2 or us-east-1

Linux and macOS: 

# Use `generate-db-connect-auth-token` if you are _not_ logging in as `admin` user
aws dsql generate-db-connect-admin-auth-token \
  --region region \
  --expires-in 3600 \
  --hostname your_cluster_endpoint

Windows: 

# Use `generate-db-connect-auth-token` if you are _not_ logging in as `admin` user
aws dsql generate-db-connect-admin-auth-token ^
  --region=region ^
  --expires-in=3600 ^
  --hostname=your_cluster_endpoint

Using the SDKs to Generate a Token

You can generate an authentication token for your cluster when it is in ACTIVE status. The SDK examples use the following attributes to generate an authentication token for the admin role:

  • your_cluster_endpoint: The endpoint of your Aurora DSQL cluster (format: your_cluster_identifier.dsql.region.on.aws)
  • region: The AWS Region in which your cluster is located

Python SDK

You can generate the token in the following ways: - Admin role: Use generate_db_connect_admin_auth_token - Custom database role: Use generate_connect_auth_token

import boto3

def generate_token(your_cluster_endpoint, region):
    client = boto3.client("dsql", region_name=region)
    # use `generate_db_connect_auth_token` instead if you are not connecting as admin.
    token = client.generate_db_connect_admin_auth_token(your_cluster_endpoint, region)
    print(token)
    return token

C++ SDK

You can generate the token in the following ways: - Admin role: Use GenerateDBConnectAdminAuthToken - Custom database role: Use GenerateDBConnectAuthToken

#include <aws/core/Aws.h>
#include <aws/dsql/DSQLClient.h>
#include <iostream>

using namespace Aws;
using namespace Aws::DSQL;

std::string generateToken(String yourClusterEndpoint, String region) {
    Aws::SDKOptions options;
    Aws::InitAPI(options);
    DSQLClientConfiguration clientConfig;
    clientConfig.region = region;
    DSQLClient client{clientConfig};
    std::string token = "";

    // If you are not using the admin role to connect, use GenerateDBConnectAuthToken instead
    const auto presignedString = client.GenerateDBConnectAdminAuthToken(yourClusterEndpoint, region);
    if (presignedString.IsSuccess()) {
        token = presignedString.GetResult();
    } else {
        std::cerr << "Token generation failed." << std::endl;
    }

    std::cout << token << std::endl;

    Aws::ShutdownAPI(options);
    return token;
}

JavaScript SDK

You can generate the token in the following ways: - Admin role: Use getDbConnectAdminAuthToken - Custom database role: Use getDbConnectAuthToken

import { DsqlSigner } from "@aws-sdk/dsql-signer";

async function generateToken(yourClusterEndpoint, region) {
  const signer = new DsqlSigner({
    hostname: yourClusterEndpoint,
    region,
  });
  try {
    // Use `getDbConnectAuthToken` if you are _not_ logging in as the `admin` user
    const token = await signer.getDbConnectAdminAuthToken();
    console.log(token);
    return token;
  } catch (error) {
      console.error("Failed to generate token: ", error);
      throw error;
  }
}

Java SDK

You can generate the token in the following ways: - Admin role: Use generateDbConnectAdminAuthToken - Custom database role: Use generateDbConnectAuthToken

import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
import software.amazon.awssdk.services.dsql.DsqlUtilities;
import software.amazon.awssdk.regions.Region;

public class GenerateAuthToken { 
    public static String generateToken(String yourClusterEndpoint, Region region) {
        DsqlUtilities utilities = DsqlUtilities.builder()
                .region(region)
                .credentialsProvider(DefaultCredentialsProvider.create())
                .build();

        // Use `generateDbConnectAuthToken` if you are _not_ logging in as `admin` user 
        String token = utilities.generateDbConnectAdminAuthToken(builder -> {
            builder.hostname(yourClusterEndpoint)
                    .region(region);
        });

        System.out.println(token);
        return token;
    }
}

Rust SDK

You can generate the token in the following ways: - Admin role: Use db_connect_admin_auth_token - Custom database role: Use db_connect_auth_token

use aws_config::{BehaviorVersion, Region};
use aws_sdk_dsql::auth_token::{AuthTokenGenerator, Config};

async fn generate_token(your_cluster_endpoint: String, region: String) -> String {
    let sdk_config = aws_config::load_defaults(BehaviorVersion::latest()).await;
    let signer = AuthTokenGenerator::new(
        Config::builder()
            .hostname(&your_cluster_endpoint)
            .region(Region::new(region))
            .build()
            .unwrap(),
    );

    // Use `db_connect_auth_token` if you are _not_ logging in as `admin` user
    let token = signer.db_connect_admin_auth_token(&sdk_config).await.unwrap();
    println!("{}", token);
    token.to_string()
}

Ruby SDK

You can generate the token in the following ways: - Admin role: Use generate_db_connect_admin_auth_token - Custom database role: Use generate_db_connect_auth_token

require 'aws-sdk-dsql'

def generate_token(your_cluster_endpoint, region)
  credentials = Aws::SharedCredentials.new()

  begin
      token_generator = Aws::DSQL::AuthTokenGenerator.new({
          :credentials => credentials
      })

      # if you're not using admin role, use generate_db_connect_auth_token instead
      token = token_generator.generate_db_connect_admin_auth_token({
          :endpoint => your_cluster_endpoint,
          :region => region
      })
  rescue => error
    puts error.full_message
  end
end

.NET SDK

Note: The official SDK for .NET doesn't include a built-in API call to generate an authentication token for Aurora DSQL. Instead, you must use DSQLAuthTokenGenerator, which is a utility class.

You can generate the token in the following ways: - Admin role: Use DbConnectAdmin - Custom database role: Use DbConnect

using Amazon;
using Amazon.DSQL.Util;
using Amazon.Runtime;

var yourClusterEndpoint = "insert-dsql-cluster-endpoint";

AWSCredentials credentials = FallbackCredentialsFactory.GetCredentials();

// Use `DSQLAuthTokenGenerator.GenerateDbConnectAuthToken` if you are _not_ logging in as `admin` user
var token = DSQLAuthTokenGenerator.GenerateDbConnectAdminAuthToken(credentials, RegionEndpoint.USEast1, yourClusterEndpoint);

Console.WriteLine(token);

Golang SDK

Note: The Golang SDK doesn't provide a built-in method for generating a pre-signed token. You must manually construct the signed request.

In the following code example, specify the action based on the PostgreSQL user: - Admin role: Use the DbConnectAdmin action - Custom database role: Use the DbConnect action

import (
    "context"
    "time"

    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/feature/dsql/auth"
)

func GenerateDbConnectAdminAuthToken(ctx context.Context, clusterEndpoint, region string, expiry time.Duration) (string, error) {
    cfg, err := config.LoadDefaultConfig(ctx)
    if err != nil {
        return "", err
    }

    tokenOptions := func(options *auth.TokenOptions) {
        options.ExpiresIn = expiry
    }

    // Use `auth.GenerateDbConnectAuthToken` if you are _not_ logging in as `admin` user
    token, err := auth.GenerateDBConnectAdminAuthToken(ctx, clusterEndpoint, region, cfg.Credentials, tokenOptions)
    if err != nil {
        return "", err
    }

    return token, nil
}