# 注册位置
在您账户的 Amazon Web Services 区域中[创建 Amazon S3 访问权限管控实例](https://docs.amazonaws.cn/AmazonS3/latest/userguide/access-grants-instance-create.html)后，在该实例中注册 S3 位置。S3 访问权限管控位置将默认 S3 位置 (`s3://`)、存储桶或前缀映射到 Amazon Identity and Access Management（IAM）角色。S3 访问权限管控代入此 IAM 角色，来向正在访问该特定位置的被授权者提供临时凭证。您必须先在 S3 访问权限管控实例中注册至少一个位置，然后才能创建访问权限管控。
**建议的用例**
我们建议您注册默认位置 (`s3://`) 并将其映射到 IAM 角色。默认 S3 路径 (`s3://`) 中的位置涵盖了对您账户的该 Amazon Web Services 区域中所有 S3 存储桶的访问权限。创建访问权限管控时，您可以将授予范围缩小到默认位置内的存储桶、前缀或对象。
**复杂的访问管理用例**
更复杂的访问管理用例可能要求您注册比默认位置更多的位置。此类用例的一些示例为：
+ 假设 *amzn-s3-demo-bucket* 是 S3 访问权限管控实例中的一个注册位置，并且有一个 IAM 角色映射到该位置，但拒绝该 IAM 角色访问存储桶中的特定前缀。在这种情况下，您可以将 IAM 角色无权访问的前缀注册为单独的位置，并将该位置映射到具有必要访问权限的其它 IAM 角色。
+ 假设您要创建的授权将访问权限仅限制为虚拟私有云（VPC）端点中的用户。在这种情况下，您可以为存储桶注册一个位置，IAM 角色在该位置限制对 VPC 端点的访问。稍后，当被授权者向 S3 访问权限管控索取凭证时，S3 访问权限管控将代入该位置的 IAM 角色来提供临时凭证。除非调用方位于 VPC 端点内，否则此凭证将拒绝访问特定存储桶。除在授权中指定的常规 READ、WRITE 或 READWRITE 权限外，还会应用此拒绝权限。
在注册位置时，还必须指定 S3 访问权限管控代入的 IAM 角色，来提供临时凭证和确定特定授权的权限范围。
如果您的用例要求您在 S3 访问权限管控实例中注册多个位置，则可以注册以下任意位置：
| S3 URI | IAM 角色 | 说明 |
| --- | --- | --- |
| s3:// | Default-IAM-role | 默认位置 `s3://` 包括 Amazon Web Services 区域中的所有存储桶。 |
| s3://amzn-s3-demo-bucket1/ | IAM-role-For-bucket | 此位置包括指定存储桶中的所有对象。 |
| s3://amzn-s3-demo-bucket1/prefix-name | IAM-role-For-prefix | 此位置包括存储桶中对象键名称以此前缀开头的所有对象。 |
在注册特定存储桶或前缀之前，请确保执行以下操作：
+ 创建一个或多个存储桶，其中包含要授予其访问权限的数据。这些存储桶必须位于您的 S3 Access Grants 实例所在的 Amazon Web Services 区域中。有关更多信息，请参阅[创建存储桶](https://docs.amazonaws.cn/AmazonS3/latest/userguide/create-bucket-overview.html)。
添加前缀是一个可选步骤。前缀是位于对象键名称开头的字符串。可以使用它们来组织存储桶中的对象以及进行访问管理。要向存储桶添加前缀，请参阅[创建对象密钥名称](https://docs.amazonaws.cn/AmazonS3/latest/userguide/object-keys.html)。
+ 创建一个 IAM 角色，该角色有权访问 Amazon Web Services 区域中的 S3 数据。有关更多信息，请参阅《Amazon IAM Identity Center 用户指南》**中的[创建 IAM 角色](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles_create.html)。
+ 在 IAM 角色信任策略中，向 S3 访问权限管控服务 (`access-grants.s3.amazonaws.com`)主体授予对您创建的 IAM 角色的访问权限。为此，您可以创建一个包含以下语句的 JSON 文件。要将信任策略添加到您的账户，请参阅[使用自定义信任策略创建角色](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles_create_for-custom.html)。
*TestRolePolicy.json*
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "TestRolePolicy",
"Effect": "Allow",
"Principal": {
"Service": "access-grants.s3.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:SetSourceIdentity"
],
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333",
"aws:SourceArn": "arn:aws:s3::111122223333:access-grants/default"
}
}
}
]
}
```
------
或者，对于 IAM Identity Center 使用案例，请使用以下策略，其中包括第二条语句：
+ 创建 IAM 策略来将 Amazon S3 权限附加到您创建的 IAM 角色。请查看以下示例 `iam-policy.json` 文件，并将 `user input placeholders` 替换为您自己的信息。
**注意**
如果您使用采用 Amazon Key Management Service（Amazon KMS）密钥的服务器端加密来加密数据，则以下示例将在策略中包含 IAM 角色的必要 Amazon KMS 权限。如果您不使用此功能，则可以从 IAM 策略中删除这些权限。
仅当凭证由 S3 Access Grants 出售时，您才能将 IAM 角色限制为访问 S3 数据。此示例说明如何为特定 S3 Access Grants 实例添加 `Condition` 语句。要使用此 `Condition`，请将 `Condition` 语句中的 S3 访问权限管控实例 ARN 替换为您的 S3 访问权限管控实例 ARN，其格式为：`arn:aws:s3:region:accountId:access-grants/default`
*iam-policy.json*
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ObjectLevelReadPermissions",
"Effect":"Allow",
"Action":[
"s3:GetObject",
"s3:GetObjectVersion",
"s3:GetObjectAcl",
"s3:GetObjectVersionAcl",
"s3:ListMultipartUploadParts"
],
"Resource":[
"arn:aws:s3:::*"
],
"Condition":{
"StringEquals": { "aws:ResourceAccount": "accountId" },
"ArnEquals": {
"s3:AccessGrantsInstanceArn": ["arn:aws:s3:region:accountId:access-grants/default"]
}
}
},
{
"Sid": "ObjectLevelWritePermissions",
"Effect":"Allow",
"Action":[
"s3:PutObject",
"s3:PutObjectAcl",
"s3:PutObjectVersionAcl",
"s3:DeleteObject",
"s3:DeleteObjectVersion",
"s3:AbortMultipartUpload"
],
"Resource":[
"arn:aws:s3:::*"
],
"Condition":{
"StringEquals": { "aws:ResourceAccount": "accountId" },
"ArnEquals": {
"s3:AccessGrantsInstanceArn": ["arn:aws:s3:Amazon Web Services 区域:accountId:access-grants/default"]
}
}
},
{
"Sid": "BucketLevelReadPermissions",
"Effect":"Allow",
"Action":[
"s3:ListBucket"
],
"Resource":[
"arn:aws:s3:::*"
],
"Condition":{
"StringEquals": { "aws:ResourceAccount": "accountId" },
"ArnEquals": {
"s3:AccessGrantsInstanceArn": ["arn:aws:s3:Amazon Web Services 区域:accountId:access-grants/default"]
}
}
},
//Optionally add the following section if you use SSE-KMS encryption
{
"Sid": "KMSPermissions",
"Effect":"Allow",
"Action":[
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource":[
"*"
]
}
]
}
```
您可以使用 Amazon S3 控制台、Amazon Command Line Interface（Amazon CLI）、Amazon S3 REST API 和 Amazon SDK 在 S3 Access Grants 实例中注册位置。
**注意**
在 S3 访问权限管控实例中注册第一个位置后，您的实例中仍没有任何单个访问权限管控。要创建访问权限管控，请参阅[创建授权](access-grants-grant-create.md)。
## 使用 S3 控制台
您必须先注册至少一个位置，之后才能使用 S3 Access Grants 授予对 S3 数据的访问权限。
**在 S3 Access Grants 实例中注册位置**
1. 登录到 Amazon Web Services 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.amazonaws.cn/s3/)。
1. 在左侧导航窗格中，选择 **Access Grants**。
1. 在 **S3 Access Grants** 页面上，选择包含要使用的 S3 Access Grants 实例的区域。
如果您是首次使用 S3 Access Grants 实例，请确保已完成[步骤 1 - 创建 S3 Access Grants 实例](https://docs.amazonaws.cn/AmazonS3/latest/userguide/access-grants-instance-create.html)，并导航到**设置 Access Grants 实例**向导的**步骤 2**。如果您已拥有 S3 Access Grants 实例，请选择**查看详细信息**，然后从**位置**选项卡中选择**注册位置**。
1. 对于**位置范围**，请选择**浏览 S3** 或输入要注册的位置的 S3 URI 路径。有关 S3 URI 格式，请参阅[位置格式](#location-types)表。输入 URI 后，您可以选择**查看**来浏览该位置。
1. 对于 **IAM 角色**，请选择下列选项之一：
+ **从现有 IAM 角色中选择**
从下拉列表中选择 IAM 角色。选择一个角色后，选择**查看**，确保该角色具有管理要注册的位置所需的权限。具体而言，请确保此角色向 S3 Access Grants 授予 `sts:AssumeRole` 和 `sts:SetSourceIdentity` 权限。
+ **输入 IAM 角色 ARN**
导航到 [IAM 控制台](https://console.amazonaws.cn/iam/)。复制 IAM 角色的 Amazon 资源名称（ARN），并将它粘贴到此框中。
1. 要完成此操作，请选择**下一步**或**注册位置**。
1. 故障排除：
**无法注册位置**
+ 该位置可能已被注册。
您可能没有 `s3:CreateAccessGrantsLocation` 权限，无法注册位置。请联系您的账户管理员。
## 使用 Amazon CLI
要安装 Amazon CLI，请参阅 *Amazon Command Line Interface 用户指南*中的[安装 Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/getting-started-install.html)。
您可以在 S3 Access Grants 实例中注册默认位置 `s3://` 或自定义位置。请确保先创建一个具有该位置的主体访问权限的 IAM 角色，然后确保授予 S3 Access Grants 权限以代入此角色。
要使用以下示例命令，请将 `user input placeholders` 替换为您自己的信息。
**Example 创建资源策略**
创建允许 S3 Access Grants 代入 IAM 角色的策略。为此，您可以创建一个包含以下语句的 JSON 文件。要将资源策略添加到您的账户，请参阅[创建和附加您的第一个客户管理型策略](https://docs.amazonaws.cn//IAM/latest/UserGuide/tutorial_managed-policies.html)。
*TestRolePolicy.json*
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1234567891011",
"Action": ["sts:AssumeRole", "sts:SetSourceIdentity"],
"Effect": "Allow",
"Principal": {"Service": "access-grants.s3.amazonaws.com"}
}
]
}
```
**Example 创建角色**
运行以下 IAM 命令以创建该角色。
```
aws iam create-role --role-name accessGrantsTestRole \
--region us-east-2 \
--assume-role-policy-document file://TestRolePolicy.json
```
运行 `create-role` 命令将返回策略：
```
{
"Role": {
"Path": "/",
"RoleName": "accessGrantsTestRole",
"RoleId": "AROASRDGX4WM4GH55GIDA",
"Arn": "arn:aws:iam::111122223333:role/accessGrantsTestRole",
"CreateDate": "2023-05-31T18:11:06+00:00",
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1685556427189",
"Action": [
"sts:AssumeRole",
"sts:SetSourceIdentity"
],
"Effect": "Allow",
"Principal": {
"Service":"access-grants.s3.amazonaws.com"
}
}
]
}
}
}
```
**Example**
创建一个 IAM 策略，将 Amazon S3 权限附加到 IAM 角色。请查看以下示例 `iam-policy.json` 文件，并将 `user input placeholders` 替换为您自己的信息。
如果您使用具有 Amazon Key Management Service（Amazon KMS）密钥的服务器端加密来加密数据，则以下示例将在策略中添加 IAM 角色的必要 Amazon KMS 权限。如果您不使用此功能，则可以从 IAM 策略中删除这些权限。
为了确保在凭证由 S3 Access Grants 分发时，IAM 角色只能用于访问 S3 中的数据，此示例向您说明了如何在 IAM 策略中添加一个指定 S3 Access Grants 实例（`s3:AccessGrantsInstance: InstanceArn`）的 `Condition` 语句。在使用以下示例策略时，请将 `user input placeholders` 替换为您自己的信息。
*iam-policy.json*
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ObjectLevelReadPermissions",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:GetObjectVersion",
"s3:GetObjectAcl",
"s3:GetObjectVersionAcl",
"s3:ListMultipartUploadParts"
],
"Resource": [
"arn:aws:s3:::*"
],
"Condition": {
"StringEquals": { "aws:ResourceAccount": "111122223333" },
"ArnEquals": {
"s3:AccessGrantsInstanceArn": ["arn:aws:s3:us-east-1::access-grants/default"]
}
}
},
{
"Sid": "ObjectLevelWritePermissions",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:PutObjectAcl",
"s3:PutObjectVersionAcl",
"s3:DeleteObject",
"s3:DeleteObjectVersion",
"s3:AbortMultipartUpload"
],
"Resource": [
"arn:aws:s3:::*"
],
"Condition": {
"StringEquals": { "aws:ResourceAccount": "111122223333" },
"ArnEquals": {
"s3:AccessGrantsInstanceArn": ["arn:aws:s3:us-east-1::access-grants/default"]
}
}
},
{
"Sid": "BucketLevelReadPermissions",
"Effect": "Allow",
"Action": [
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::*"
],
"Condition": {
"StringEquals": { "aws:ResourceAccount": "111122223333" },
"ArnEquals": {
"s3:AccessGrantsInstanceArn": ["arn:aws:s3:us-east-1::access-grants/default"]
}
}
},
{
"Sid": "KMSPermissions",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": [
"*"
],
"Condition": {
"StringEquals": {
"kms:ViaService": "s3.us-east-1.amazonaws.com"
}
}
}
]
}
```
**Example**
运行如下命令：
```
aws iam put-role-policy \
--role-name accessGrantsTestRole \
--policy-name accessGrantsTestRole \
--policy-document file://iam-policy.json
```
**Example 注册默认位置**
```
aws s3control create-access-grants-location \
--account-id 111122223333 \
--location-scope s3:// \
--iam-role-arn arn:aws:iam::111122223333:role/accessGrantsTestRole
```
响应：
```
{"CreatedAt": "2023-05-31T18:23:48.107000+00:00",
"AccessGrantsLocationId": "default",
"AccessGrantsLocationArn": "arn:aws:s3:us-east-2:111122223333:access-grants/default/location/default",
"LocationScope": "s3://"
"IAMRoleArn": "arn:aws:iam::111122223333:role/accessGrantsTestRole"
}
```
**Example 注册自定义位置**
```
aws s3control create-access-grants-location \
--account-id 111122223333 \
--location-scope s3://DOC-BUCKET-EXAMPLE/ \
--iam-role-arn arn:aws:iam::123456789012:role/accessGrantsTestRole
```
响应：
```
{"CreatedAt": "2023-05-31T18:23:48.107000+00:00",
"AccessGrantsLocationId": "635f1139-1af2-4e43-8131-a4de006eb456",
"AccessGrantsLocationArn": "arn:aws:s3:us-east-2: 111122223333:access-grants/default/location/635f1139-1af2-4e43-8131-a4de006eb888",
"LocationScope": "s3://DOC-BUCKET-EXAMPLE/",
"IAMRoleArn": "arn:aws:iam::111122223333:role/accessGrantsTestRole"
}
```
## 使用 REST API
有关用于管理 S3 Access Grants 实例的 Amazon S3 REST API 支持的信息，请参阅**《Amazon Simple Storage Service API 参考》中的以下部分：
+ [https://docs.amazonaws.cn/AmazonS3/latest/API/API_control_CreateAccessGrantsLocation.html](https://docs.amazonaws.cn/AmazonS3/latest/API/API_control_CreateAccessGrantsLocation.html)
+ [https://docs.amazonaws.cn/AmazonS3/latest/API/API_control_DeleteAccessGrantsLocation.html](https://docs.amazonaws.cn/AmazonS3/latest/API/API_control_DeleteAccessGrantsLocation.html)
+ [https://docs.amazonaws.cn/AmazonS3/latest/API/API_control_GetAccessGrantsLocation.html](https://docs.amazonaws.cn/AmazonS3/latest/API/API_control_GetAccessGrantsLocation.html)
+ [https://docs.amazonaws.cn/AmazonS3/latest/API/API_control_ListAccessGrantsLocations.html](https://docs.amazonaws.cn/AmazonS3/latest/API/API_control_ListAccessGrantsLocations.html)
+ [https://docs.amazonaws.cn/AmazonS3/latest/API/API_control_UpdateAccessGrantsLocation.html](https://docs.amazonaws.cn/AmazonS3/latest/API/API_control_UpdateAccessGrantsLocation.html)
## 使用 Amazon SDK
此部分中的示例说明了如何使用 Amazon SDK 注册位置。
要使用以下示例，请将 `user input placeholders` 替换为您自己的信息。
------
#### [ Java ]
您可以在 S3 Access Grants 实例中注册默认位置 `s3://` 或自定义位置。请确保先创建一个具有该位置的主体访问权限的 IAM 角色，然后确保授予 S3 Access Grants 权限以代入此角色。
要使用以下示例命令，请将 `user input placeholders` 替换为您自己的信息。
**Example 注册默认位置**
请求:
```
public void createAccessGrantsLocation() {
CreateAccessGrantsLocationRequest createRequest = CreateAccessGrantsLocationRequest.builder()
.accountId("111122223333")
.locationScope("s3://")
.iamRoleArn("arn:aws:iam::123456789012:role/accessGrantsTestRole")
.build();
CreateAccessGrantsLocationResponse createResponse = s3Control.createAccessGrantsLocation(createRequest);
LOGGER.info("CreateAccessGrantsLocationResponse: " + createResponse);
}
```
响应:
```
CreateAccessGrantsLocationResponse(
CreatedAt=2023-06-07T04:35:11.027Z,
AccessGrantsLocationId=default,
AccessGrantsLocationArn=arn:aws:s3:us-east-2:111122223333:access-grants/default/location/default,
LocationScope=s3://,
IAMRoleArn=arn:aws:iam::111122223333:role/accessGrantsTestRole
)
```
**Example 注册自定义位置**
请求:
```
public void createAccessGrantsLocation() {
CreateAccessGrantsLocationRequest createRequest = CreateAccessGrantsLocationRequest.builder()
.accountId("111122223333")
.locationScope("s3://DOC-BUCKET-EXAMPLE/")
.iamRoleArn("arn:aws:iam::111122223333:role/accessGrantsTestRole")
.build();
CreateAccessGrantsLocationResponse createResponse = s3Control.createAccessGrantsLocation(createRequest);
LOGGER.info("CreateAccessGrantsLocationResponse: " + createResponse);
}
```
响应:
```
CreateAccessGrantsLocationResponse(
CreatedAt=2023-06-07T04:35:10.027Z,
AccessGrantsLocationId=18cfe6fb-eb5a-4ac5-aba9-8d79f04c2012,
AccessGrantsLocationArn=arn:aws:s3:us-east-2:111122223333:access-grants/default/location/18cfe6fb-eb5a-4ac5-aba9-8d79f04c2666,
LocationScope= s3://test-bucket-access-grants-user123/,
IAMRoleArn=arn:aws:iam::111122223333:role/accessGrantsTestRole
)
```
------