**注意**：亚马逊 WorkDocs不再提供新买家注册和账户升级服务。在此处了解迁移步骤：[如何从中迁移数据 WorkDocs](https://aws.amazon.com/blogs/business-productivity/how-to-migrate-content-from-amazon-workdocs)。

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

# 用户应用程序的身份验证和访问控制
<a name="wd-auth-user"></a>

WorkDocs 用户级应用程序通过 WorkDocs 控制台进行注册和管理。开发人员应在 WorkDocs 控制台的`My Applications`页面上注册他们的应用程序，该页面将 IDs 为每个应用程序提供唯一的功能。在注册期间，开发者应指定重定向，他们将在 URIs 哪里接收访问令牌以及应用程序范围。

当前，应用程序只能使用其注册的同一 AWS 帐户访问 WorkDocs 站点。

**Topics**
+ [授予调用权限 WorkDocs APIs](#api-auth)
+ [IDs 在 API 调用中使用文件夹](#use-folder-ids)
+ [创建 应用程序](#wd-app-create-app)
+ [应用程序范围](#wd-app-scopes)
+ [授权](#wd-authorization)
+ [正在调用 WorkDocs APIs](#wd-auth-invoke)

## 授予调用权限 WorkDocs APIs
<a name="api-auth"></a>

命令行界面用户必须拥有 WorkDocs 和的完全权限 Directory Service。如果没有权限，任何 API 调用都会返回**UnauthorizedResourceAccessException**消息。以下策略可授予完全权限。

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
          "workdocs:*",
          "ds:*",
          "ec2:CreateVpc",
          "ec2:CreateSubnet",
          "ec2:CreateNetworkInterface",
          "ec2:CreateTags",
          "ec2:CreateSecurityGroup",
          "ec2:DescribeVpcs",
          "ec2:DescribeSubnets",
          "ec2:DescribeNetworkInterfaces",
          "ec2:DescribeAvailabilityZones",
          "ec2:AuthorizeSecurityGroupEgress",
          "ec2:AuthorizeSecurityGroupIngress",
          "ec2:DeleteSecurityGroup",
          "ec2:DeleteNetworkInterface",
          "ec2:RevokeSecurityGroupEgress",
          "ec2:RevokeSecurityGroupIngress"
          ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}
```

如果您需要授予只读权限，请使用以下策略。

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
          "workdocs:Describe*",
          "ds:DescribeDirectories",       
          "ec2:DescribeVpcs",
          "ec2:DescribeSubnets"
          ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}
```

在策略中，第一个操作授予对所有 WorkDocs `Describe`操作的访问权限。该`DescribeDirectories `操作将获取有关您的 Directory Service 目录的信息。通过 Amazon EC2 操作 WorkDocs ，可以获取您的 VPCs 和子网的列表。

## IDs 在 API 调用中使用文件夹
<a name="use-folder-ids"></a>

每当 API 调用访问文件夹时，您都必须使用文件夹 ID，而不是文件夹名称。例如，如果您通过`client.get_folder(FolderId='MyDocs')`，API 调用将返回一条**UnauthorizedResourceAccessException**消息和以下 404 消息。

```
client.get_folder(FolderId='MyDocs')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "C:\Users\{{user-name}}\AppData\Local\Programs\Python\Python36-32\lib\site-packages\botocore\client.py", line 253, in _api_call
    return self._make_api_call(operation_name, kwargs)
  File "C:\Users\{{user-name}}\AppData\Local\Programs\Python\Python36-32\lib\site-packages\botocore\client.py", line 557, in _make_api_call
    raise error_class(parsed_response, operation_name)
botocore.errorfactory.UnauthorizedResourceAccessException: An error occurred (UnauthorizedResourceAccessException) when calling the GetFolder operation: 
Principal [arn:aws:iam::395162986870:user/Aman] is not allowed to execute [workdocs:GetFolder] on the resource.
```

为避免这种情况，请使用文件夹 URL 中的 ID。

`{{site.workdocs}}/index.html#/folder/abc123def456ghi789jkl789mno4be7024df198736472dd50ca970eb22796082e3d489577`.

传递该 ID 将返回正确的结果。

```
client.get_folder(FolderId='abc123def456ghi789jkl789mno4be7024df198736472dd50ca970eb22796082e3d489577')
{'ResponseMetadata': {'RequestId': 'f8341d4e-4047-11e7-9e70-afa8d465756c', 'HTTPStatusCode': 200, 'HTTPHeaders': {'x-amzn-requestid': 'f234564e-1234-56e7-89e7-a10fa45t789c', 'cache-control': 'private, no-cache, no-store, max-age=0', 'content-type': 'application/json', 'content-length': '733', 'date': 'Wed, 24 May 2017 06:12:30 GMT'}, 'RetryAttempts': 0}, 'Metadata': {'Id': 'abc123def456ghi789jkl789mno4be7024df198736472dd50ca970eb22796082e3d489577', 'Name': 'sentences', 'CreatorId': 'S-1-5-21-2125721135-1643952666-3011040551-2105&d-906724f1ce', 'ParentFolderId': '0a811a922403ae8e1d3c180f4975f38f94372c3d6a2656c50851c7fb76677363', 'CreatedTimestamp': datetime.datetime(2017, 5, 23, 12, 59, 13, 8000, tzinfo=tzlocal()), 'ModifiedTimestamp': datetime.datetime(2017, 5, 23, 13, 13, 9, 565000, tzinfo=tzlocal()), 'ResourceState': 'ACTIVE', 'Signature': 'b7f54963d60ae1d6b9ded476f5d20511'}}
```

## 创建 应用程序
<a name="wd-app-create-app"></a>

作为 WorkDocs 管理员，请使用以下步骤创建您的应用程序。

**创建应用程序**

1. 打开 WorkDocs 控制台，网址为[https://console.aws.amazon.com/zocalo/](https://console.aws.amazon.com/zocalo/)。

1. 依次选择**我的应用程序**和**创建应用程序**。

1. 输入以下值：  
**应用程序名称**  
应用程序的名称。  
**电子邮件**  
要与应用程序关联的电子邮件地址。  
**应用程序描述**  
应用程序的描述。  
**重定向 URIs**  
您要将流量重定 WorkDocs 向到的位置。  
**应用程序范围**  
希望应用程序具有的读取或写入范围。有关更多详细信息，请参阅[应用程序范围](#wd-app-scopes)。

1. 选择**创建**。

## 应用程序范围
<a name="wd-app-scopes"></a>

WorkDocs 支持以下应用程序范围：
+ Content Read (`workdocs.content.read`)，它允许您的应用程序访问以下内容 WorkDocs APIs：
  + Get\*
  + Describe\*
+ Content Write (`workdocs.content.write`)，它允许您的应用程序访问以下内容 WorkDocs APIs：
  + Create\*
  + Update\*
  + Delete\*
  + Initiate\*
  + Abort\*
  + Add\*
  + Remove\*

## 授权
<a name="wd-authorization"></a>

应用程序注册完成后，应用程序可以代表任何 WorkDocs 用户请求授权。为此，应用程序应访问 WorkDocs OAuth端点`https://auth.amazonworkdocs.com/oauth`，并提供以下查询参数：
+ [必需] `app_id` – 注册应用程序时生成的应用程序 ID。
+ [必需`auth_type`]-请求的 OAuth 类型。支持的值为 `ImplicitGrant`。
+ [必需] `redirect_uri` – 为应用程序注册以接收访问令牌的重定向 URI。
+ [可选] `scopes` – 范围的逗号分隔列表。如果未指定，将会使用在注册期间选择的范围的列表。
+ [可选] `state` – 与访问令牌一起返回的字符串。

**注意**  
如果在通过命令行界面或 API 访问 AWS 时需要经过 FIPS 140-2 验证的加密模块，请使用 FIPS 端点。有关可用的 FIPS 端点的更多信息，请参阅[《美国联邦信息处理标准（FIPS）第 140-2 版》](https://aws.amazon.com/compliance/fips/)。

用于启动 OAuth 流程以获取访问令牌的 GET 请求示例：

```
GET https://auth.amazonworkdocs.com/oauth?app_id=my-app-id&auth_type=ImplicitGrant&redirect_uri=https://myapp.com/callback&scopes=workdocs.content.read&state=xyz
```

以下是在 OAuth 授权流程中发生的：

1. 系统会提示应用程序用户输入 WorkDocs 站点名称。

1. 用户被重定向到 WorkDocs 身份验证页面以输入其凭据。

1. 成功进行身份验证后，用户将看到同意屏幕，允许用户授予或拒绝您的应用程序的访问授权 WorkDocs。

1. 在用户选择同意屏幕上的 `Accept` 后，他们的浏览器将连同作为查询参数的访问令牌和区域信息一起被重定向到应用程序的回调 URL。

来自 GET 请求的示例 WorkDocs：

```
GET https://myapp.com/callback?acessToken=accesstoken&region=us-east-1&state=xyz
```

除了访问令牌外，该 WorkDocs OAuth 服务还会`region`作为所选 WorkDocs 站点的查询参数返回。外部应用程序应使用`region`参数来确定 WorkDocs 服务端点。

如果在通过命令行界面或 API 访问 AWS 时需要经过 FIPS 140-2 验证的加密模块，请使用 FIPS 端点。有关可用的 FIPS 端点的更多信息，请参阅[《美国联邦信息处理标准（FIPS）第 140-2 版》](https://aws.amazon.com/compliance/fips/)。

## 正在调用 WorkDocs APIs
<a name="wd-auth-invoke"></a>

在获取访问令牌后，应用程序可以对 WorkDocs 服务进行 API 调用。

**重要**  


以下示例展示了如何使用 curl GET 请求获取文档的元数据。

```
Curl "https://workdocs.us-east-1.amazonaws.com/api/v1/documents/{document-id}" -H "Accept: application/json" -H "Authentication: Bearer accesstoken"
```

描述用户根文件夹的示例 JavaScript 函数：

```
function printRootFolders(accessToken, siteRegion) {
    var workdocs = new AWS.WorkDocs({region: siteRegion});
    workdocs.makeUnauthenticatedRequest("describeRootFolders", {AuthenticationToken: accessToken}, function (err, folders) {
        if (err) console.log(err);
        else console.log(folders);
    });     
}
```

以下展示了基于 Java 的 API 调用示例：

```
AWSCredentialsProvider credentialsProvider = new AWSCredentialsProvider() {
  @Override
  public void refresh() {}

  @Override
  public AWSCredentials getCredentials() {
    new AnonymousAWSCredentials();
  }
};

// Set the correct region obtained during OAuth flow.
workDocs =
    AmazonWorkDocsClient.builder().withCredentials(credentialsProvider)
        .withRegion(Regions.US_EAST_1).build();

DescribeRootFoldersRequest request = new DescribeRootFoldersRequest();
request.setAuthenticationToken("access-token-obtained-through-workdocs-oauth");
DescribeRootFoldersResult result = workDocs.describeRootFolders(request);

for (FolderMetadata folder : result.getFolders()) {
  System.out.printf("Folder name=%s, Id=%s \n", folder.getName(), folder.getId());
}
```