--- title: "How to Setup AWS Assume Role for AWS Secret Manager" img: https://unified.to/images/logo.svg date: 2026-03-12T15:37:00.000Z tag: Guides description: "This guide walks you through configuring AWS IAM Assume Role so that Unified can securely access AWS Secrets Manager in your account — without sharing..." url: "https://docs.unified.to/guides/how_to_setup_aws_assume_role_for_aws_secret_manager" --- # 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 ```plain text ┌───────────────┐ 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: ```json { "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: ```json { "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](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html). 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](https://app.unified.to/). 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.