How to Setup AWS Assume Role for AWS Secret Manager

March 12, 2026

This guide walks you through configuring AWS IAM Assume Role so that Unified can securely access AWS Secrets Manager in your account — without sharing long-lived AWS access keys.

Overview

Instead of providing static AWS credentials (access key + secret), you can create an IAM role in your AWS account and grant Unified permission to assume it. Unified uses AWS STS (Security Token Service) to obtain short-lived, temporary credentials scoped to your Secrets Manager.

How it works

┌───────────────┐         STS AssumeRole          ┌────────────────────┐
│  Unified API  │ ──────────────────────────────► │  Your AWS Account  │
│  (account     │   (with External ID check)      │                    │
│   944579081756│ ◄────────────────────────────── │  IAM Role          │
└───────────────┘    temporary credentials        │  Secrets Manager   │
                                                  └────────────────────┘

1. You create an IAM role in your AWS account with a trust policy that allows Unified's AWS account to assume it.
2. You attach a permissions policy to that role granting access to Secrets Manager.
3. You provide the role's ARN and an External ID in the Unified dashboard.
4. Unified calls sts:AssumeRole with the External ID, receives temporary credentials, and uses them to read/write secrets.

Prerequisites

• An AWS account with permissions to create IAM roles and policies
• Access to the Unified dashboard with workspace admin permissions

Step 1: Create an IAM Policy for Secrets Manager

In the AWS Console, create a policy that grants the permissions Unified needs on Secrets Manager.

1. Go to IAM > Policies > Create policy
2. Select the JSON tab and paste the following:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "secretsmanager:CreateSecret",
                   "secretsmanager:GetSecretValue",
                   "secretsmanager:UpdateSecret",
                   "secretsmanager:DeleteSecret"
               ],
               "Resource": "arn:aws:secretsmanager:YOUR_REGION:YOUR_ACCOUNT_ID:secret:*"
           }
       ]
   }
   

   
   Replace YOUR_REGION (e.g. us-east-1) and YOUR_ACCOUNT_ID with your values.
   Tip: To restrict access further, you can narrow the Resource to a specific prefix, for example: arn:aws:secretsmanager:us-east-1:123456789012:secret:unified/*
3. Name the policy (e.g. UnifiedSecretsManagerAccess) and create it.

Step 2: Create an IAM Role with a Trust Policy

1. Go to IAM > Roles > Create role
2. Select Custom trust policy and paste the following:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Principal": {
                   "AWS": "arn:aws:iam::944579081756:user/unified_assume_role_user"
               },
               "Action": "sts:AssumeRole",
               "Condition": {
                   "StringEquals": {
                       "sts:ExternalId": "YOUR_EXTERNAL_ID"
                   }
               }
           }
       ]
   }
   

   
   Replace YOUR_EXTERNAL_ID with a unique, hard-to-guess string of your choice (e.g. a UUID). You will enter this same value in the Unified dashboard later.
   Why an External ID? The External ID prevents the confused deputy problem. It ensures that only requests originating through your Unified workspace — and not a third party who happens to know the role ARN — can assume the role.
3. Click Next, then attach the UnifiedSecretsManagerAccess policy you created in Step 1.
4. Name the role (e.g. UnifiedSecretsManagerRole) and create it.
5. Copy the role's ARN from the role summary page. It will look like: arn:aws:iam::123456789012:role/UnifiedSecretsManagerRole

Step 3: Configure Unified

1. Log in to the Unified dashboard.
2. Navigate to Settings > Workspace Settings.
3. Under the secrets manager section, select AWS Secret Manager.
4. Fill in the following fields:

   Field	Value
   AWS Region	The region where your Secrets Manager secrets are stored (e.g. us-east-1)
   AWS ARN	The full ARN of the IAM role you created (e.g. arn:aws:iam::123456789012:role/UnifiedSecretsManagerRole)
   AWS External ID	The same External ID string you used in the trust policy

   
   Note: When using Assume Role, you do not need to fill in the AWS Key and AWS Secret fields. Those fields are only required for the static-credentials approach.
5. Save your workspace settings.

Step 4: Verify the Setup

Once saved, Unified will automatically use the Assume Role flow for all new connections in your workspace. To verify:

1. Create or update a connection in your workspace.
2. Check your AWS Secrets Manager console — you should see a new secret created with a name that includes your workspace ID.
3. If there are any issues, Unified will surface errors in the connection status.

Troubleshooting

'Missing role ARN or region'

Ensure both the AWS Region and AWS ARN fields are filled in on your workspace settings.

'Access Denied' or 'Not authorized to perform sts:AssumeRole'

• Verify the trust policy on your IAM role references the correct Unified AWS principal: arn:aws:iam::944579081756:user/unified_assume_role_user
• Verify the External ID in the trust policy matches exactly what you entered in Unified.
• Ensure the IAM role's permissions policy includes the required secretsmanager:* actions.

'The security token included in the request is expired'

Temporary credentials are cached for up to 55 minutes and refreshed automatically. If you see this error persistently, confirm that your IAM role allows a session duration of at least 1 hour (the default).

Secrets are not being stored

• Confirm the IAM role's permissions policy allows actions on the correct region and account.
• Check that the Resource in your permissions policy matches the region configured in Unified.

Migrating from Static Credentials

If you are currently using the static AWS Key / AWS Secret approach:

1. Follow Steps 1-3 above to set up the IAM role and configure Unified.
2. Once the ARN and External ID are saved, Unified will prefer the Assume Role flow over static credentials.
3. After verifying that secrets are being read and written correctly, you can remove the static AWS Key and AWS Secret from your workspace settings.
4. Revoke or delete the old IAM user credentials in your AWS account.

Security Best Practices

• Use a unique External ID per workspace. This prevents cross-workspace role assumption.
• Scope the permissions policy narrowly. Restrict the Resource to only the secret prefixes Unified needs.
• Rotate the External ID periodically. Update both the IAM trust policy and the Unified dashboard when you do.
• Enable CloudTrail logging. Monitor AssumeRole events in your AWS account to audit access.
• Do not share the External ID publicly. Treat it as a sensitive configuration value.