Skip to content
RingDNA Communications Hub
Call Recording
Amazon S3 Bucket Setup (Role-Based / STS AssumeRole)

Amazon S3 Bucket Setup (Role-Based / STS AssumeRole)

This document describes the current, recommended way to give Revenue.io access to your own S3 bucket for call recordings using an IAM role and AWS STS AssumeRole.

This replaces the older, identity‑based approach where you granted our AWS account direct access to your bucket.

1. Overview: Role-based access with STS

Instead of granting our AWS account permissions on your bucket, you will:

  1. Create or choose an S3 bucket for call recordings.
  2. Create an IAM Role in your AWS account that:
    1. Has S3 permissions only to that bucket.
    2. Trusts Revenue’s AWS principal and requires a customer‑defined External ID.
  3. Optionally restrict the bucket policy so only that IAM Role can access the bucket.
  4. Share three values with Revenue Support:
    1. S3 Recording Bucket name
    2. S3 Recording Role name ARN
    3. S3 External ID

When our platform needs to upload recordings, it calls STS AssumeRole using that role and External ID. STS returns short‑lived, scoped credentials that are valid only for your bucket.

Why this is more secure

Compared with directly granting our AWS account access to your bucket, this approach is more secure because:

  • No long‑lived cross‑account permissions: Our account does not permanently have access to your bucket.
  • Least privilege: The role policy can be restricted to exactly one bucket and specific actions.
  • Easy revocation: You can immediately revoke access by disabling or editing the IAM role or its trust policy.
  • External ID protection: The External ID helps prevent “confused deputy” issues, ensuring only our service (with the correct External ID) can assume the role.

2. S3 bucket naming requirements

Our application uses virtual‑hosted–style S3 access over HTTPS (SSL). Because of how SSL certificates are handled, bucket names must not contain dots (.).

  • Allowed: customer-name-recordings, customername-recordings-prod
  • Not allowed: customer.name.recordings, recordings.customer-name.com

For the full AWS naming rules, see AWS bucket naming rules

Choose or create a bucket that meets these requirements and note:

  • Bucket name (e.g., customer-name-recordings)
  • Bucket region (e.g., us-east-1)

3. Configure S3 object ownership (bucket owner preferred)

To ensure your AWS account remains the owner of all objects (even those uploaded by Revenue or other third parties), configure Object Ownership to Bucket owner preferred:

  1. Sign in to the AWS Management Console and open the S3 console: Amazon S3 console
  2. In the Buckets list, choose your recording bucket.
  3. Select the Permissions tab.
  4. Under Object Ownership, click Edit.
  5. Choose Bucket owner preferred.
  6. Click Save.

With this setting enabled, any new objects written by other accounts (including Revenue and third‑party tools such as analytics or QA platforms) will be owned by your AWS account.

4. Create the IAM role for Revenue.io

You will create an IAM role that:

  • Has S3 permissions to your recording bucket.
  • Can be assumed by Revenue’s AWS principal via STS.
  • Requires a customer‑defined External ID.

4.1 Create the role (console steps)

  1. Open the IAM console: AWS IAM console
  2. In the left navigation, choose Roles → Create role.
  3. Under Trusted entity type, choose AWS account.
  4. Select Another AWS account and set:
    1. Account ID: 103850359708 (Revenue’s AWS account that will assume this role.)
  5. Check Require external ID, and enter a value you choose, for example:
    1. YOUR-EXTERNAL-ID
    2. A GUID or securely generated random string is ideal.
  6. (Optional but recommended) Leave Require MFA unchecked (our service cannot use MFA).
  7. Click Next and proceed to Permissions (you will add a custom policy next).
  8. Click Next until Role name and Description:
    1. Role name (example): revenue-call-recording-writer
  9. Click Create role.

You will edit the role to attach a policy and confirm the trust relationship.

5. Attach an S3 permissions policy to the role

This policy grants our assumed role the minimum permissions required to upload and manage call recordings in your bucket.

Replace customer-name-recordings with the actual name of your bucket.

Inline role policy example (JSON):

{

 "Version": "2012-10-17",

 "Statement": [

   {

     "Effect": "Allow",

     "Action": [

       "s3:PutObject",

       "s3:PutObjectAcl",

       "s3:GetObject",

       "s3:DeleteObject"

     ],

     "Resource": "arn:aws:s3:::customer-name-recordings/*"

   }

 ]

}

How to attach this policy

  1. In the IAM console, open Roles.
  2. Click your role (e.g., revenue-call-recording-writer).
  3. On the Permissions tab, click Add permissions → Create inline policy.
  4. Choose the JSON tab, paste the policy above (with your bucket name), and click Review policy.
  5. Name the policy (e.g., revenue-call-recording-s3-access) and Create policy.

6. Configure the role trust relationship (STS AssumeRole)

Ensure the trust policy allows Revenue’s AWS principal to assume the role using the External ID you defined earlier.

Replace:

  • YOUR_EXTERNAL_ID_HERE with the exact External ID you chose.
  • Keep the AWS principal as shown below.

Trust relationship policy (JSON):

{

 "Version": "2012-10-17",

 "Statement": [

   {

     "Effect": "Allow",

     "Principal": {

       "AWS": "arn:aws:iam::103850359708:user/RingDNA_Web"

     },

     "Action": "sts:AssumeRole",

     "Condition": {

       "StringEquals": {

         "sts:ExternalId": "YOUR-EXTERNAL-ID"

       }

     }

   }

 ]

}

How to set this trust policy

  • In the IAM console, go to Roles and open your role.
  • On the Trust relationships tab, click Edit trust policy.
  • Replace any existing JSON with the JSON above (using your External ID).
  • Click Update policy.

7. Information you must provide to Revenue.io Support

After completing the setup, please provide Revenue Support with:

  • S3 Recording Bucket name
    • What it is: The name of your S3 bucket for recordings configured above.
    • Example: customer-name-recordings
    • How to find it: In the S3 console, find your bucket → copy the bucket name used in this setup.
  • S3 Recording Role Name ARN
    • What it is: The Amazon Resource Name that uniquely identifies your Role.
    • Example: arn:aws:iam::11111111:role/revenue-call-recording-writer
    • How to find it: In the IAM console → Roles → Role Name → copy ARN from summary
  • S3 External ID
    • What it is: A string you chose and configured in the role’s trust relationship under sts:ExternalId.
    • Purpose: Prevents unauthorized third parties from attempting to use our principal to access your resources (mitigates “confused deputy” issues). Only calls to STS that include this exact External ID can assume the role.
    • Example: customer-name-revenue-recordings-EXTERNAL-ID or a random GUID such as c3a4f5f0-1a2b-4c5d-8e9f-0123456789ab.

Revenue Support will use these values to configure our systems so that:

  • We call sts:AssumeRole on your S3 Recording Role.
  • We provide the correct External ID.
  • We upload call recordings to your S3 Recording Bucket using temporary credentials issued by STS.
Last updated on