使用者應用程式的身分驗證與存取控制 - Amazon WorkDocs
授予呼叫 Amazon WorkDocs APIs許可在 API 呼叫中使用資料夾 IDs 建立應用程式應用程式範圍授權叫用 Amazon WorkDocs APIs

請注意：Amazon WorkDocs 不再提供新客戶註冊和帳戶升級。在此處了解遷移步驟：如何從 Amazon WorkDocs 遷移資料。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用者應用程式的身分驗證與存取控制

Amazon WorkDocs 使用者層級應用程式是透過 Amazon WorkDocs 主控台註冊和管理。開發人員應該在 Amazon WorkDocs 主控台的 My Applications 頁面上註冊其應用程式，該主控台會為每個應用程式提供唯一的 IDs。在註冊期間，開發人員應指定重新導向 URI，以讓他們接收存取字符以及應用程式範圍。

目前，應用程式只能存取註冊相同 AWS 帳戶中的 Amazon WorkDocs 網站。

授予呼叫 Amazon WorkDocs APIs許可

命令列界面使用者必須擁有 Amazon WorkDocs 和 的完整許可 AWS 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": "*"
    }
  ]
}

在政策中，第一個動作會授予所有 Amazon WorkDocs Describe操作的存取權。DescribeDirectories 動作會取得 AWS Directory Service 目錄的相關資訊。Amazon EC2 操作可讓 Amazon WorkDocs 取得 VPCs和子網路的清單。

在 API 呼叫中使用資料夾 IDs

當 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'}}

建立應用程式

身為 Amazon WorkDocs 管理員，請使用下列步驟建立您的應用程式。

建立應用程式

  1. 開啟 Amazon WorkDocs 主控台，網址為 https://console.aws.amazon.com/zocalo/。

  2. 選擇 My Applications (我的應用程式)、Create an Application (建立應用程式)。

  3. 輸入下列值：

    Application Name (應用程式名稱)

    應用程式名稱。

    電子郵件

    與應用程式建立關聯的電子郵件地址。

    Application Description (應用程式描述)

    應用程式的描述。

    Redirect URIs (重新導向 URI)

    您希望 Amazon WorkDocs 重新導向流量的位置。

    Application Scopes (應用程式範圍)

    您希望您的應用程式擁有的讀取或寫入範圍。如需詳細資訊，請參閱應用程式範圍。

  4. 選擇 Create (建立)。

應用程式範圍

Amazon WorkDocs 支援下列應用程式範圍：

  • Content Read (workdocs.content.read)，可讓您的應用程式存取下列 Amazon WorkDocs APIs：

    • Get* (取得)

    • Describe* (描述)

  • 內容寫入 (workdocs.content.write)，可讓您的應用程式存取下列 Amazon WorkDocs APIs：

    • 建立*

    • 更新*

    • 刪除*

    • Initiate* (啟動)

    • Abort* (中止)

    • Add* (新增)

    • Remove* (移除)

授權

應用程式註冊完成後，應用程式可以代表任何 Amazon WorkDocs 使用者請求授權。若要這樣做，應用程式應造訪 Amazon 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 端點的更多相關資訊，請參閱聯邦資訊處理標準 (FIPS) 140-2 概觀。

範例 GET 請求以啟動 OAuth 流程以取得存取字符：

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. 系統會提示應用程式使用者輸入 Amazon WorkDocs 網站名稱。

  2. 系統會將使用者重新導向至 Amazon WorkDocs 身分驗證頁面，以輸入其登入資料。

  3. 身分驗證成功後，使用者會收到同意畫面，允許使用者授予或拒絕應用程式存取 Amazon WorkDocs 的授權。

  4. 在使用者選擇同意畫面上的 Accept 後，他們的瀏覽器將重新導向至您應用程式的回呼 URL，以及做為查詢參數的存取字符與區域資訊。

來自 Amazon WorkDocs 的範例 GET 請求：

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

除了存取權杖之外，Amazon WorkDocs OAuth 服務也會傳回region為所選 Amazon WorkDocs 網站的查詢參數。外部應用程式應使用 region 參數來判斷 Amazon WorkDocs 服務端點。

如果您在透過命令列介面或 API 存取 AWS 時，需要 FIPS 140-2 驗證的加密模組，請使用 FIPS 端點。如需有關 FIPS 和 FIPS 端點的更多相關資訊，請參閱聯邦資訊處理標準 (FIPS) 140-2 概觀。

叫用 Amazon WorkDocs APIs

取得存取權杖後，您的應用程式可以對 Amazon 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());
}