Notice: New customer sign-ups and account upgrades are no longer available for Amazon WorkDocs. Learn about migration steps here: How to migrate data from Amazon WorkDocs.

Authentication and access control for user applications

Amazon WorkDocs user level applications are registered and managed through the Amazon WorkDocs console. Developers should register their applications on the My Applications page on the Amazon WorkDocs console which will provide unique IDs for each application. During registration, developers should specify redirect URIs where they will receive access tokens as well as application scopes.

Currently, applications can only access Amazon WorkDocs sites within the same AWS account where they are registered.

Granting permissions to call the Amazon WorkDocs APIs

Command line interface users must have full permissions to Amazon WorkDocs and AWS Directory Service. Without the permissions, any API calls return UnauthorizedResourceAccessException messages. The following policy grants full permissions.

{
  "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": "*"
    }
  ]
}

If you want to grant read-only permissions, use this policy.

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

In the policy, the first action grants access to all the Amazon WorkDocs Describe operations. The DescribeDirectories action obtains information about your AWS Directory Service directories. The Amazon EC2 operations enable Amazon WorkDocs to obtain a list of your VPCs and subnets.

Using folder IDs in API calls

Whenever an API call accesses a folder, you must use the folder ID, not the folder name. For example, if you pass client.get_folder(FolderId='MyDocs'), the API call returns an UnauthorizedResourceAccessException message and the following 404 message.

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.

To avoid that, use the ID in the folder's URL.

site.workdocs/index.html#/folder/abc123def456ghi789jkl789mno4be7024df198736472dd50ca970eb22796082e3d489577.

Passing that ID returns a correct result.

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

Create an application

As an Amazon WorkDocs administrator, create your application using the following steps.

Application scopes

Amazon WorkDocs supports the following application scopes:

Authorization

After application registration is complete, an application can request authorization on behalf of any Amazon WorkDocs user. To do this, the application should visit the Amazon WorkDocs OAuth endpoint, https://auth.amazonworkdocs.com/oauth, and provide the following query parameters:

A sample GET request to initiate the OAuth flow to obtain an access token:

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

The following takes place during the OAuth authorization flow:

A sample GET request from Amazon WorkDocs:

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

In addition to the access token, the Amazon WorkDocs OAuth service also returns region as a query parameter for the selected Amazon WorkDocs site. External applications should use the region parameter to determine the Amazon WorkDocs service endpoint.

If you require FIPS 140-2 validated cryptographic modules when accessing AWS through a command line interface or an API, use a FIPS endpoint. For more information about the available FIPS endpoints, see Federal Information Processing Standard (FIPS) 140-2.

Invoking Amazon WorkDocs APIs

After obtaining the access token, your application can make API calls to Amazon WorkDocs services.

This example shows how to use a curl GET request to obtain a document's metadata.

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

A sample JavaScript function to describe a user's root folders:

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);
    });     
}

A sample Java-based API invocation is described below:

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());
}