1. AODocs Knowledge Base
  2. AODocs tenant administration — for super administrators
  3. Technical details and performance recommendations

Set up AWS account trust for Amazon S3 storage in AODocs

Follow
Avatar
AODocs product

This article is for AWS administrators and AODocs super administrators. It covers the one-time setup you perform once per AWS account and region before any Amazon S3 bucket is registered with AODocs: adding Google as an OpenID Connect (OIDC) identity provider, creating the IAM role AODocs assumes to reach S3, and creating the Amazon SQS queue that bucket change events are delivered to.

This setup is distinct from per-bucket registration, which you repeat for every bucket you link. Repeat this tenant setup only when you add a new AWS account, or when you start using S3 buckets in a new region under an existing account — not for every bucket.

Note: To use Amazon S3 as your AODocs storage platform, the AMAZON_S3 storage service must be activated on your AODocs domain. Contact your AODocs sales representative or send an email to sales@aodocs.com.

Automatically generated table of contents

What you set up once

Amazon S3 storage for AODocs uses secure federation without long-lived AWS access keys:

  • On the AODocs side, a dedicated Google identity exposes an OAuth 2.0 client ID used as the trusted Audience.
  • On your AWS side, you add Google as an IAM OIDC identity provider, create an IAM role that trusts that provider, and grant the role scoped permissions on your S3 buckets.
  • You also create one customer-owned SQS notification queue per AWS account and region. Every bucket you later link in that account and region must notify the same queue.

When this guide is complete, you share the Role ARN with AODocs (or keep it ready for the registration value). Bucket name and region are combined with that ARN when you register each bucket.

Prerequisites

Before you begin, you need:

  • an AWS account where you can create IAM identity providers, IAM roles, S3 buckets, and SQS queues
  • the AMAZON_S3 storage service activated on your AODocs domain
  • the OIDC Audience value for your AODocs environment — provided by the AODocs Support team (do not reuse an audience from another environment)

Important: Use the Audience value that AODocs Support provides for your environment. If the Audience on the identity provider and on the IAM role does not match what AODocs uses, role assumption fails.

Step 1: Add Google as an Identity Provider (IdP)

  1. Log into the AWS Management Console.
  2. In the top search bar, type IAM and open IAM (Identity and Access Management).
  3. In the left navigation, under Access management, select Identity providers.
  4. Choose Add provider.

screen: The IAM Identity providers page with the Add provider action available.

Configure the provider as follows:

  • Provider type: OpenID Connect
  • Provider URL: https://accounts.google.com
  • Audience: [Audience value provided by AODocs Support]
  1. Choose Get thumbprint so AWS can verify Google’s signing certificate authority, then create the provider.

Create this identity provider once per AWS account. It is not tied to a particular bucket or region and is reused for every bucket you register under this account.

Step 2: Create the IAM role

In the IAM sidebar, open Roles and choose Create role.

Select the trusted entity

  • Trusted entity type: Web identity
  • Identity provider: https://accounts.google.com (the IdP created in Step 1)
  • Audience: the same Audience value you configured on the IdP

screen: The Create role page with Web identity selected and the Google identity provider and Audience filled in.

Attach permissions (IAM policy)

Skip the default AWS managed policies. Choose Create policy and paste a scoped JSON policy that points at your designated S3 bucket(s). One role can serve every bucket registered in this account and region: when you link a new bucket, add another Resource entry (or a new statement) to the relevant statements below — you do not need to repeat Steps 1, 3, or 4 of this guide. See Create and register an Amazon S3 bucket for AODocs for the per-bucket steps.

Required — object access, bucket metadata, and AODocs permission verification:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BucketLevelRead",
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetBucketLocation",
        "s3:GetBucketVersioning",
        "s3:GetBucketCors",
        "s3:GetBucketNotification",
        "s3:GetBucketObjectLockConfiguration",
        "s3:GetLifecycleConfiguration"
      ],
      "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME"
    },
    {
      "Sid": "ObjectLevelReadWrite",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:GetObjectVersion",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*"
    },
    {
      "Sid": "PermissionSelfCheck",
      "Effect": "Allow",
      "Action": "iam:SimulatePrincipalPolicy",
      "Resource": "arn:aws:iam::YOUR-ACCOUNT-ID:role/AODocsStorageConnectorRole"
    }
  ]
}

Replace YOUR-BUCKET-NAME, YOUR-ACCOUNT-ID, and the role name with your values. The Get* bucket-metadata actions let AODocs read the current bucket configuration during verification. They do not grant AODocs permission to change those settings.

Note: Do not put sqs:ReceiveMessage / sqs:DeleteMessage on this role’s identity policy. AODocs polls the notification queue using access granted by the queue’s own access policy (see Step 5).

Optional — only if you want AODocs to configure CORS on the bucket automatically (otherwise configure CORS manually; see below). Add this statement to the same policy:

{
  "Sid": "OptionalCorsAutoConfig",
  "Effect": "Allow",
  "Action": "s3:PutBucketCors",
  "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME"
}

Manual CORS configuration

Only needed if you did not grant s3:PutBucketCors. In the S3 console, open the bucket → Permissions → Cross-origin resource sharing (CORS) → Edit, and add a rule shaped like this:

[
  {
    "AllowedOrigins": ["[AODocs origin provided by AODocs Support, for example https://aodocs.appspot.com]"],
    "AllowedMethods": ["GET", "PUT", "POST"],
    "AllowedHeaders": ["*"],
    "MaxAgeSeconds": 3600
  }
]

AllowedOrigins must match the AODocs environment origin exactly (ask AODocs Support if unsure). AODocs verification expects the methods above, * for headers, and a MaxAgeSeconds of at least 3600.

Name the role and create it

On the final step, name the role (for example, AODocsStorageConnectorRole) and choose Create role.

screen: The role summary page showing the new AODocsStorageConnectorRole.

Permission reference

The following table lists every IAM action involved in the Amazon S3 connector setup, in customer language.

Permission Resource Needed for Status
s3:ListBucket bucket Confirm the bucket exists and is reachable; future object listing Required
s3:GetBucketLocation bucket Read the bucket region during verification Required
s3:GetBucketVersioning bucket Confirm versioning is enabled (required for write attribution) Required
s3:GetLifecycleConfiguration bucket Confirm an enabled, unfiltered noncurrent-version expiration lifecycle rule exists Required
s3:GetBucketCors bucket Detect a missing or incorrect CORS rule Required
s3:GetBucketNotification bucket Read the bucket’s SQS notification configuration during verification Required
s3:GetBucketObjectLockConfiguration bucket Read-only informational check of Object Lock configuration Required
s3:GetObject object Download links, object metadata reads, copy (source), permission probe Required
s3:GetObjectVersion object Read a specific object version when processing change notifications Required
s3:PutObject object Upload links, copy (destination), permission probe Required
s3:DeleteObject object Cleanup step of the permission probe (upload and delete a temporary test object) Required
iam:SimulatePrincipalPolicy (scoped to the role’s own ARN) role (self only) Declarative permission self-check during bucket verification Required
sqs:ReceiveMessage queue — granted by the queue’s access policy, not this role policy Long-polling the S3 event notification queue Required
sqs:DeleteMessage queue — same as above Acknowledging a processed notification message Required
s3:PutBucketCors bucket Let AODocs configure CORS automatically Optional — otherwise configure CORS manually

Note: AODocs does not request permission to change bucket notification configuration, versioning, or Object Lock settings. You configure those yourself. Bucket versioning must still be enabled on each bucket — see the per-bucket guide.

Step 3: Assign the role to the identity provider

After the role is created, assign it to the Google OIDC identity provider so federated Google identities can assume it.

  1. In the IAM console, open Identity providers and select the accounts.google.com provider created in Step 1.
  2. Choose Assign role.
  3. Choose Use an existing role, then select the role created in Step 2 (for example, AODocsStorageConnectorRole).
  4. Confirm the assignment.

Without this step, AODocs cannot assume the role even if the Audience value is correct.

screen: The identity provider details page with Assign role and the AODocsStorageConnectorRole selected.

Step 4: Share the Role ARN

Copy the Role ARN from the role summary page.

screen: The role summary page highlighting the Role ARN.

Share this Role ARN with your AODocs contact — it identifies the tenant-level trust relationship. It is not enough by itself to register a bucket: AODocs also needs the bucket’s region and name, which are combined with this ARN into a single registration value when you link a bucket. See Create and register an Amazon S3 bucket for AODocs.

Step 5: Create the SQS notification queue

AODocs derives write attribution and change tracking from S3 event notifications delivered to a customer-owned SQS queue.

Like the IAM role, this queue is scoped to the AWS account and region, not to an individual bucket. AODocs expects one queue per account+region pair, and every bucket in that account and region must notify the same queue. Create the queue once here, then reuse it for every bucket you later link in this account and region — the only per-bucket action is pointing the bucket’s event notifications at it.

  1. In the AWS Management Console, search for and open SQS.
  2. Choose Create queue.
  3. Type: Standard (S3 event notifications are not supported on FIFO queues).
  4. Region: must match the region of the buckets that will notify it — S3 can only deliver notifications to a queue in the same region as the bucket.
  5. Name: any name you choose, for example aodocs-notification-queue.
  6. Visibility timeout: set to 2 minutes. The AWS 30-second default is too short for reliable processing before a message becomes visible again.
  7. Leave the other default queue-level encryption and retention settings, then choose Create queue.

screen: The Create queue page with Type set to Standard and Visibility timeout set to 2 minutes.

Open the new queue → Access policy → Edit, and paste a policy shaped like this:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowS3EventDelivery",
      "Effect": "Allow",
      "Principal": { "Service": "s3.amazonaws.com" },
      "Action": "SQS:SendMessage",
      "Resource": "arn:aws:sqs:us-east-1:YOUR-ACCOUNT-ID:aodocs-notification-queue",
      "Condition": {
        "ArnLike": { "aws:SourceArn": "arn:aws:s3:::YOUR-BUCKET-NAME" },
        "StringEquals": { "aws:SourceAccount": "YOUR-ACCOUNT-ID" }
      }
    },
    {
      "Sid": "AllowConnectorRolePolling",
      "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::YOUR-ACCOUNT-ID:role/AODocsStorageConnectorRole" },
      "Action": [
        "sqs:ReceiveMessage",
        "sqs:DeleteMessage"
      ],
      "Resource": "arn:aws:sqs:us-east-1:YOUR-ACCOUNT-ID:aodocs-notification-queue"
    }
  ]
}

Replace the account ID, region, queue name, role name, and bucket name with your values.

  • AllowS3EventDelivery lets a bucket’s event notification configuration deliver messages into this queue. Without it, S3 accepts the notification config but every delivery attempt fails silently. Add another aws:SourceArn entry (or a new statement) each time you point another bucket in this account and region at this same queue.
  • AllowConnectorRolePolling grants the AODocs connector role sqs:ReceiveMessage and sqs:DeleteMessage on this queue. This lives on the queue’s access policy rather than the role’s identity policy.

What’s next

Once this guide is complete for an AWS account and region, proceed to Create and register an Amazon S3 bucket for AODocs for each bucket you want to link.

Was this article helpful? 0 out of 0 found this helpful
If you didn’t find what you were looking for, don’t hesitate to leave a comment!
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.

Articles in this section

See more

Related articles