本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 IAM 身份进行身份验证
<a name="iam-identity-auth"></a>

Amazon DocumentDB 用户和应用程序可以使用 IAM 用户和角色进行身份验证，以便进入 Amazon DocumentDB 集群。Amazon DocumentDB IAM 身份验证是一种无需密码的身份验证方法。此外，使用 IAM 时，客户端应用程序不会将密码密钥发送到 Amazon DocumentDB 集群。 roles/users相反， AWS STS 使用临时安全令牌对客户端连接进行身份验证。 Non-administrative 现在，用户和应用程序在连接到不同的 Amazon DocumentDB 集群和其他服务时可以使用相同的 IAM 身份 ARN。 AWS 

您也可以选择同时使用基于密码的身份验证和 IAM 身份验证，对访问 Amazon DocumentDB 集群的用户和应用程序进行身份验证。只有 Amazon DocumentDB 基于实例的集群版本 5.0 才可以使用 IAM 身份验证。Amazon DocumentDB 主用户不支持用 IAM 身份 ARN 进行 IAM 身份验证。

**注意**  
主用户只能使用现有基于密码的身份验证进行身份验证。

**Topics**
+ [开始使用 IAM 用户和角色进行身份验证](#iam-identity-auth-get-started)
+ [配置 AWS 使用以下方法计算要向 Amazon DocumentDB 进行身份验证的类型 AWS IAM](#iam-identity-auth-compute-types)
+ [监控 IAM 身份验证请求](#iam-identity-auth-monitoring)
+ [使用 IAM 身份验证](#iam-identity-auth-using)
+ [支持 IAM 的驱动程序](#iam-identity-drivers)
+ [IAM 身份验证的常见问题解答](#iam-identity-auth-faq)

## 开始使用 IAM 用户和角色进行身份验证
<a name="iam-identity-auth-get-started"></a>

具有 IAM 身份的 Amazon DocumentDB 用户和角色在 `$external` 数据库中进行创建和管理。

**创建用户**

以主用户身份进行连接，然后创建 IAM 用户和角色：

```
use $external;
db.createUser(
    {
        user: "arn:aws:iam::123456789123:user/iamuser",
        mechanisms: ["MONGODB-AWS"],
        roles: [ { role: "readWrite", db: "readWriteDB" } ]
    }
);
```

或者，使用 IAM 角色添加 Amazon DocumentDB 用户：

```
use $external;
db.createUser(
    {
        user: "arn:aws:iam::123456789123:role/iamrole",
        mechanisms: ["MONGODB-AWS"],
        roles: [ { role: "readWrite", db: "readWriteDB" } ]
    }
);
```

**修改 IAM 用户或角色**

修改现有 IAM 用户：

```
use $external;
db.updateUser(
  "arn:aws:iam::123456789123:user/iamuser",
  { 
    roles: [ { role: "read", db: "readDB" } ] 
  }
);
```

修改现有 IAM 角色：

```
use $external;
db.updateUser(
  "arn:aws:iam::123456789123:role/iamrole",
  { 
    roles: [ { role: "read", db: "readDB" } ] 
  }
);
```

授予或撤消 IAM 用户的角色：

```
use $external;
db.grantRolesToUser(
  "arn:aws:iam::123456789123:user/iamuser", 
  [ { db: "admin", role: "readWriteAnyDatabase" } ]
);
```

```
use $external;
db.revokeRolesFromUser(
  "arn:aws:iam::123456789123:user/iamuser", 
  [ { db: "admin", role: "readWriteAnyDatabase" } ]
);
```

授予或撤消 IAM 角色的角色：

```
use $external;
db.grantRolesToUser(
  "arn:aws:iam::123456789123:user/iamrole", 
  [ { db: "admin", role: "readWriteAnyDatabase" } ]
);
```

```
use $external;
db.revokeRolesFromUser(
  "arn:aws:iam::123456789123:user/iamrole", 
  [ { db: "admin", role: "readWriteAnyDatabase" } ]
);
```

**删除 IAM 用户或角色**

删除现有 IAM 用户：

```
use $external;
db.dropUser("arn:aws:iam::123456789123:user/iamuser");
```

删除现有 IAM 角色：

```
use $external;
db.dropUser("arn:aws:iam::123456789123:role/iamrole");
```

**配置连接 URI 以使用 AWS IAM 进行身份验证**

要使用 AWS IAM 进行身份验证，请使用以下 URI 参数：`authSource`as `$external` 和 `authMechanism` as `MONGODB-AWS`。如果使用 IAM 用户，则将用户名和密码字段分别替换为访问密钥和私有密钥。如果代入 IAM 角色，则将该角色附加到您所在的环境（例如， AWS Lambda 函数、Amazon EC2 实例）。利用 `MONGODB-AWS` 机制进行身份验证时，无需专门传递任何凭证。如果使用支持 `MONGODB-AWS` 身份验证机制的 MongoDB 驱动程序，这些驱动程序还可以从计算实例（例如 Amazon EC2、Lambda 函数等）检索 IAM 角色凭证。以下示例使用 mongo Shell 进行身份验证，方法是使用 `MONGODB-AWS` 机制，通过手动传递（IAM 用户的）访问密钥和私有密钥来演示对 Amazon DocumentDB 进行身份验证。

以下示例使用 Python 代码进行身份验证，方法是使用 `MONGODB-AWS` 机制演示对 Amazon DocumentDB 进行身份验证，无需显式传递任何凭证（使用附加到此环境的 IAM 角色）。

```
##Create a MongoDB client, open a connection to Amazon DocumentDB using an IAM role
    client = pymongo.MongoClient(‘mongodb://<DocDBEndpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false&authSource=%24external&authMechanism=MONGODB-AWS')
```

以下示例使用 mongo Shell 进行身份验证，方法是使用 `MONGODB-AWS` 机制，通过手动传递（IAM 用户的）访问密钥和私有密钥来演示对 Amazon DocumentDB 进行身份验证。

```
$ mongo 'mongodb://<access_key>:<secret_key>@<cluster_endpoint>:<db_port>/test?authSource=%24external&authMechanism=MONGODB-AWS'
```

以下示例使用 mongo Shell 进行身份验证，方法是使用 `MONGODB-AWS` 机制演示对 Amazon DocumentDB 进行身份验证，无需显式传递任何凭证（使用附加到此环境的 IAM 角色）。

```
$ mongo 'mongodb://<cluster_endpoint>:<db_port>/test?authSource=%24external&authMechanism=MONGODB-AWS'
```

## 配置 AWS 使用以下方法计算要向 Amazon DocumentDB 进行身份验证的类型 AWS IAM
<a name="iam-identity-auth-compute-types"></a>

**使用 Amazon EC2/AWS Lambda/AWS Fargate**

Amazon EC2 使用以下环境变量。如果有附加到 EC2 实例的 IAM 角色，或与 Lambda 函数或 Amazon ECS 任务关联的执行 IAM 角色，则这些变量会自动填充，驱动程序可以从环境中获取这些值：

```
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN
```

有关环境变量的更多信息，请参阅*《AWS Lambda 开发人员指南》*中的[使用 Lambda 环境变量](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html)。

**使用 Amazon EKS**

向 Amazon Elastic Kubernetes Service (Amazon EKS) 容器组分配角色会自动设置以下两个环境变量：

```
AWS_WEB_IDENTITY_TOKEN_FILE - path of web identity token file
AWS_ROLE_ARN - Name of IAM role to connect with
```

借助这些变量，使用 AWS SDK 调用手动代入您的代码中的角色`AssumeRoleWithWebIdentity`：
+ 省略 `ProviderID` 参数。
+ 在 `AWS_WEB_IDENTITY_TOKEN_FILE` 环境变量所述的文件中查找 `WebIdentityToken` 参数的值。

有关更多信息，请参阅*《Amazon EKS 用户指南》中*的[什么是 Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html)。

## 监控 IAM 身份验证请求
<a name="iam-identity-auth-monitoring"></a>

**使用 Amazon DocumentDB 审核**

前往 Amazon 中的审核日志文件夹 CloudWatch，使用不同的搜索模式获取 IAM 身份验证的日志。例如，用 `{ $.param.mechanism = "MONGODB-AWS" }` 作为“搜索所有日志流” 的搜索模式。

有关审核中所支持事件的更多信息，请参阅 [审核 Amazon DocumentDB 事件](event-auditing.md)。

**使用亚马逊 CloudWatch 指标**

**`StsGetCallerIdentityCalls`**：该指标显示了 Amazon DocumentDB 实例对区域化 AWS Security Token Service ()AWS STS终端节点的`GetCallerIdentity`调用次数。有关数据库实例需要进行 STS `GetCallerIdentity` 调用的原因，请参阅`MONGODB-AWS`身份验证规范。

## 使用 IAM 身份验证
<a name="iam-identity-auth-using"></a>

如果您不想在自己的数据库中管理用户名和密码，可以使用 IAM 身份验证。只有 Amazon DocumentDB 基于实例的集群版本 5.0 才可以使用 IAM 身份验证。

IAM 身份验证依赖于 STS 服务。在使用 IAM 身份验证进行连接并收到 STS 节流异常时，我们建议您评估是否可以降低连接速率。

有关 IAM 配额的信息，请参阅 [IAM *用户指南中的 IAM* 和 AWS STS 配额](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html)。

## 支持 IAM 的驱动程序
<a name="iam-identity-drivers"></a>

支持 Amazon DocumentDB 5.0 和 `MONGODB-AWS` 身份验证机制的驱动程序应与 Amazon DocumentDB 中的 IAM 身份验证实现配合使用。

**重要**  
版本早于 6.13.1 的 Node.js 驱动程序存在已知限制，Amazon DocumentDB 的 IAM 身份验证目前不支持这些限制。 Node.js 使用驱动程序（例如 mongosh）的 Node.js 驱动程序和工具必须升级为使用 Node.js 驱动程序版本 6.13.1 或更高版本。

## IAM 身份验证的常见问题解答
<a name="iam-identity-auth-faq"></a>

**是否有我可以参考的示例？**

请参阅以下页面了解示例用例和配置：
+ [人类用户如何使用 IAM 用户和 IAM 角色对 Amazon DocumentDB 进行身份验证](https://github.com/aws-samples/amazon-documentdb-samples/tree/master/samples/iam_user_sample_code)
+ [Password-less 使用 IAM 角色对亚马逊文档数据库进行身份验证](https://github.com/aws-samples/amazon-documentdb-samples/tree/master/samples/iam_role_sample_code)

我在@@ **使用我的 Python 驱动程序时遇到了一个错误：“pymongo.errors。 ConfigurationError: MONGODB-AWS 身份验证需要 pymongo- auth-aws”。我该如何解决这个问题？**

安装带有 IAM 身份验证的 Python 驱动程序时，请务必使用以下语句：

`pip install 'pymongo[aws]'`

这将安装 IAM 身份验证正常运行所需的其他 AWS 依赖项。

**当我的 IAM 角色临时凭证到期时，连接会中断吗？**

 不会，临时 IAM 凭证仅用于建立连接和身份验证。然后，所有进一步的身份验证都是在 Amazon DocumentDB 集群中完成的。即使有 IAM 证书 rotate/expire，连接也不会中断或失效。