# 在 Amazon Aurora DSQL 中生成身份验证令牌
<a name="SECTION_authentication-token"></a>

要使用 SQL 客户端连接到 Amazon Aurora DSQL，请生成要用作密码的身份验证令牌。此令牌仅用于对连接进行身份验证。建立连接后，连接将保持有效，即使身份验证令牌过期也是如此。

如果您使用 AWS 管理控制台、AWS CLI 或 SDK 创建身份验证令牌，默认情况下，该令牌将在 15 分钟后自动过期。最大持续时间为 604800 秒，也就是一周。要再次从客户端连接到 Aurora DSQL，您可以使用相同的身份验证令牌（如果该令牌尚未过期），也可以生成一个新令牌。

要开始生成令牌，请[创建 IAM 策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html)和 [a cluster in Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html#getting-started-quickstart)。然后，使用 AWS 管理控制台、AWS CLI 或 AWS SDK 来生成令牌。

您必须至少拥有[使用 IAM 连接到集群](authentication-authorization.md#authentication-authorization-iam-role-connect)中列出的 IAM 权限，具体取决于您使用哪个数据库角色进行连接。

**Topics**
+ [使用 AWS 管理控制台在 Aurora DSQL 中生成身份验证令牌](#authentication-token-console)
+ [使用 AWS CloudShell 在 Aurora DSQL 中生成身份验证令牌](#authentication-token-cloudshell)
+ [使用 AWS CLI 在 Aurora DSQL 中生成身份验证令牌](#authentication-token-cli)
+ [使用 SDK 在 Aurora DSQL 中生成令牌](#authentication-token-sdks)

## 使用 AWS 管理控制台在 Aurora DSQL 中生成身份验证令牌
<a name="authentication-token-console"></a>

Aurora DSQL 使用令牌而不是密码来对用户进行身份验证。您可以从控制台生成令牌。

**生成身份验证令牌**

1. 登录 AWS 管理控制台并打开 Aurora DSQL 控制台，网址为 [https://console.aws.amazon.com/dsql](https://console.aws.amazon.com/dsql)。

1. 选择您要为其生成身份验证令牌的集群的集群 ID。如果您尚未创建集群，请按照[步骤 1：创建 Aurora DSQL 单区域集群](getting-started.md#getting-started-create-cluster)或[步骤 4（可选）：创建多区域集群](getting-started.md#getting-started-multi-region)中的步骤操作。

1. 选择**连接**，然后选择**获取令牌**。

1. 选择是要以 `admin` 身份还是要使用[自定义数据库角色](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html#authentication-authorization-iam-role-connect)进行连接。

1. 复制生成的身份验证令牌并将其用于[使用 SQL 客户端访问 Aurora DSQL](accessing.md#accessing-sql-clients)。

要了解有关 Aurora DSQL 中的自定义数据库角色和 IAM 的更多信息，请参阅[Aurora DSQL 的身份验证和授权](authentication-authorization.md)。

## 使用 AWS CloudShell 在 Aurora DSQL 中生成身份验证令牌
<a name="authentication-token-cloudshell"></a>

在使用 AWS CloudShell 生成身份验证令牌之前，请确保您[创建 Aurora DSQL 集群](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html#getting-started-quickstart)。

**使用 AWS CloudShell 生成身份验证令牌**

1. 登录 AWS 管理控制台并打开 Aurora DSQL 控制台，网址为 [https://console.aws.amazon.com/dsql](https://console.aws.amazon.com/dsql)。

1. 在 AWS 管理控制台的左下角，选择 AWS CloudShell。

1. 运行以下命令以生成 `admin` 角色的身份验证令牌。将 {{us-east-1}} 替换为您的区域，并将 {{your\_cluster\_endpoint}} 替换为您自己的集群的端点。
**注意**  
如果您没有以 `admin` 身份进行连接，请改用 `generate-db-connect-auth-token`。

   ```
   aws dsql generate-db-connect-admin-auth-token \
     --expires-in 3600 \
     --region {{us-east-1}} \
     --hostname {{your_cluster_endpoint}}
   ```

   如果您遇到问题，请参阅[排查 IAM 问题](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot.html)和[如何使用 IAM 策略解决“访问被拒绝”或“未经授权的操作”错误？](https://repost.aws/knowledge-center/troubleshoot-iam-policy-issues)

1. 使用以下命令，通过 `psql` 开始与集群的连接。

   ```
   PGSSLMODE=require \
   psql --dbname postgres \
     --username admin \
     --host cluster_endpoint
   ```

1. 您应该会看到要求您提供密码的提示符。复制您生成的令牌，并确保不包含任何额外的空格或字符。将其从 `psql` 粘贴到以下提示符下。

   ```
   Password for user admin: 
   ```

1. 按 **Enter** 键。您应该看到 PostgreSQL 提示符。

   ```
   postgres=>
   ```

   如果您收到拒绝访问错误，请确保您的 IAM 身份具有 `dsql:DbConnectAdmin` 权限。如果您拥有此权限，但继续收到拒绝访问错误，请参阅[排查 IAM 问题](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot.html)和[如何使用 IAM 策略解决“访问被拒绝”或“未经授权的操作”错误？](https://repost.aws/knowledge-center/troubleshoot-iam-policy-issues) 

要了解有关 Aurora DSQL 中的自定义数据库角色和 IAM 的更多信息，请参阅[Aurora DSQL 的身份验证和授权](authentication-authorization.md)。

## 使用 AWS CLI 在 Aurora DSQL 中生成身份验证令牌
<a name="authentication-token-cli"></a>

当集群处于 `ACTIVE` 状态时，可以在 CLI 上使用 `aws dsql` 命令来生成身份验证令牌。使用以下任一方法：

**注意**  
令牌生成是一项本地操作，它使用您当前的 IAM 凭证对请求进行签名。它不会联系 AWS 以验证凭证。如果您的凭证已过期或无效，令牌生成仍会成功，但连接尝试会失败。在生成令牌之前，请确保您的 IAM 凭证有效。
+ 如果您要使用 `admin` 角色进行连接，请使用 `generate-db-connect-admin-auth-token` 选项。
+ 如果您要使用自定义数据库角色进行连接，请使用 `generate-db-connect-auth-token` 选项。

下面的示例使用以下属性为 `admin` 角色生成身份验证令牌。
+ {{your\_cluster\_endpoint}}：集群的端点 它遵循格式 `{{your_cluster_identifier}}.dsql.{{region}}.on.aws`，如示例 `01abc2ldefg3hijklmnopqurstu.dsql.us-east-1.on.aws` 所示。
+ {{region}}：AWS 区域，例如 `us-east-2` 或 `us-east-1`。

以下示例将令牌的到期时间设置为 3600 秒（1 小时）。

------
#### [ Linux and macOS ]

```
aws dsql generate-db-connect-admin-auth-token \
  --region {{region}} \
  --expires-in 3600 \
  --hostname {{your_cluster_endpoint}}
```

------
#### [ Windows ]

```
aws dsql generate-db-connect-admin-auth-token ^
  --region={{region}} ^
  --expires-in=3600 ^
  --hostname={{your_cluster_endpoint}}
```

------

## 使用 SDK 在 Aurora DSQL 中生成令牌
<a name="authentication-token-sdks"></a>

当集群处于 `ACTIVE` 状态时，您可以为其生成身份验证令牌。SDK 示例使用以下属性为 `admin` 角色生成身份验证令牌：
+ {{your\_cluster\_endpoint}}（或 {{yourClusterEndpoint}}）：Aurora DSQL 集群的端点。命名格式为 `{{your_cluster_identifier}}.dsql.{{region}}.on.aws`，如示例 `01abc2ldefg3hijklmnopqurstu.dsql.us-east-1.on.aws` 中所示。
+ {{region}}（{{RegionEndpoint}}）：您的集群所在的 AWS 区域，例如 `us-east-2` 或 `us-east-1`。

------
#### [ Python SDK ]

**提示**  
AWS 建议使用[适用于 Python 的 Aurora DSQL 连接器关于连接器什么是 Aurora DSQL 身份验证？功能快速入门指南要求安装单独安装 psycopg、psycopg2 或 asyncpg基本用法psycopgpsycopg2asyncpg仅使用主机psycopgpsycopg2asyncpg仅使用集群 IDpsycopgpsycopg2asyncpgpsycopgpsycopg2asyncpg连接字符串psycopgpsycopg2asyncpg高级配置psycopgpsycopg2asyncpg配置选项将适用于 Python 的 Aurora DSQL 连接器与连接池结合使用psycopgpsycopg2asyncpg身份验证管理员用户与普通用户示例psycopgpsycopg2asyncpg](SECTION_program-with-dsql-connector-for-python.md)，它会自动处理令牌生成。

您可以通过以下方式生成令牌：
+ 如果您要使用 `admin` 角色进行连接，请使用 `generate_db_connect_admin_auth_token`。
+ 如果您要使用自定义数据库角色进行连接，请使用 `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 ]

您可以通过以下方式生成令牌：
+ 如果您要使用 `admin` 角色进行连接，请使用 `GenerateDBConnectAdminAuthToken`。
+ 如果您要使用自定义数据库角色进行连接，请使用 `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) {
    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;
    return token;
}

int main() {
    Aws::SDKOptions options;
    Aws::InitAPI(options);
    // Replace with your cluster endpoint and region
    std::string token = generateToken("your_cluster_endpoint.dsql.us-east-1.on.aws", "us-east-1");
    Aws::ShutdownAPI(options);
    return 0;
}
```

------
#### [ JavaScript SDK ]

**提示**  
AWS 建议使用[适用于 Node.js 的 Aurora DSQL 连接器](SECTION_Node-js-connectors.md)，它会自动处理令牌生成。

您可以通过以下方式生成令牌：
+ 如果您要使用 `admin` 角色进行连接，请使用 `getDbConnectAdminAuthToken`。
+ 如果您要使用自定义数据库角色进行连接，请使用 `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 ]

**提示**  
AWS 建议使用[适用于 Java JDBC 的 Aurora DSQL 连接器](SECTION_program-with-jdbc-connector.md)，它会自动处理令牌生成。

您可以通过以下方式生成令牌：
+ 如果您要使用 `admin` 角色进行连接，请使用 `generateDbConnectAdminAuthToken`。
+ 如果您要使用自定义数据库角色进行连接，请使用 `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.builder().build())
                .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 ]

**提示**  
AWS 建议使用[适用于 Rust SQLx 的 Aurora DSQL 连接器](SECTION_program-with-dsql-connector-for-rust-sqlx.md)，它会自动处理令牌生成。

您可以通过以下方式生成令牌：
+ 如果您要使用 `admin` 角色进行连接，请使用 `db_connect_admin_auth_token`。
+ 如果您要使用自定义数据库角色进行连接，请使用 `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 ]

**提示**  
AWS 建议使用[适用于 Ruby pg 的 Aurora DSQL 连接器](SECTION_program-with-dsql-connector-for-ruby-pg.md)，它会自动处理令牌生成。

您可以通过以下方式生成令牌：
+ 如果您要使用 `admin` 角色进行连接，请使用 `generate_db_connect_admin_auth_token`。
+ 如果您要使用自定义数据库角色进行连接，请使用 `generate_db_connect_auth_token`。

```
require 'aws-sdk-dsql'

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

  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
  })
end
```

------
#### [ PHP SDK ]

**提示**  
AWS 建议使用[适用于 PHP `PDO_PGSQL` 的 Aurora DSQL 连接器](SECTION_program-with-dsql-connector-for-php-pdo-pgsql.md)，它会自动处理令牌生成。

您可以通过以下方式生成令牌：
+ 如果您要使用 `admin` 角色进行连接，请使用 `generateDbConnectAdminAuthToken`。
+ 如果您要使用自定义数据库角色进行连接，请使用 `generateDbConnectAuthToken`。

```
<?php
require 'vendor/autoload.php';

use Aws\DSQL\AuthTokenGenerator;
use Aws\Credentials\CredentialProvider;

function generateToken(string $yourClusterEndpoint, string $region): string {
    $provider = CredentialProvider::defaultProvider();
    $generator = new AuthTokenGenerator($provider);

    // Use generateDbConnectAuthToken if you are not connecting as admin
    $token = $generator->generateDbConnectAdminAuthToken($yourClusterEndpoint, $region);

    echo $token . PHP_EOL;
    return $token;
}
```

------
#### [ .NET ]

**提示**  
AWS 建议使用[适用于 .NET Npgsql 的 Aurora DSQL 连接器](SECTION_program-with-dsql-connector-for-dotnet-npgsql.md)，它会自动处理令牌生成。

**注意**  
官方适用于 .NET 的 SDK 不包括用于为 Aurora DSQL 生成身份验证令牌的内置 API 调用。而是必须使用 `DSQLAuthTokenGenerator`，这是一个实用程序类。以下代码示例展示了如何为 .NET 生成身份验证令牌。

您可以通过以下方式生成令牌：
+ 如果您要使用 `admin` 角色进行连接，请使用 `DbConnectAdmin`。
+ 如果您要使用自定义数据库角色进行连接，请使用 `DbConnect`。

以下示例使用 `DSQLAuthTokenGenerator` 实用程序类为具有 `admin` 角色的用户生成身份验证令牌。将 {{insert-dsql-cluster-endpoint}} 替换为您的集群端点。

```
using Amazon;
using Amazon.DSQL.Util;

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

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

Console.WriteLine(token);
```

------
#### [ Go ]

**提示**  
AWS 建议使用[适用于 Go pgx 的 Aurora DSQL 连接器](SECTION_program-with-go-pgx-connector.md)，它会自动处理令牌生成。

适用于 Go 的 AWS SDK v2 提供了一种内置方法，用于在 [https://github.com/aws/aws-sdk-go-v2/tree/main/feature/dsql/auth](https://github.com/aws/aws-sdk-go-v2/tree/main/feature/dsql/auth) 软件包中生成身份验证令牌。
+ 如果您要使用 `admin` 角色进行连接，请使用 `auth.GenerateDBConnectAdminAuthToken`。
+ 如果您要使用自定义数据库角色进行连接，请使用 `auth.GenerateDbConnectAuthToken`。

```
package main

import (
	"context"
	"fmt"

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

func main() {
	ctx := context.Background()

	cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("{{region}}"))
	if err != nil {
		panic(err)
	}

	// Use auth.GenerateDbConnectAuthToken for non-admin users
	token, err := auth.GenerateDBConnectAdminAuthToken(ctx, "{{yourClusterEndpoint}}", "{{region}}", cfg.Credentials)
	if err != nil {
		panic(err)
	}

	fmt.Println(token)
}
```

------