# Authenticate with an IAM role

> An AWS handler can assume an IAM role instead of holding an access key and secret key

---

Site [llms.txt](/llms.txt)

---

Access keys have to be rotated and tracked, which gets tedious across many accounts. With the IAM role option, the keys live in one place: an AWS account profile stored under Connection Info. Each handler then names the role Cloud Management Platform (CMP) should assume.

## Create the AWS account profile

The profile holds the access key and secret key CMP uses to assume the role. Create it before the handler, because the add dialog offers only profiles that already exist.

1. Go to **Admin** > **Connection Info**.
1. Select **AWS Account Profile**.
1. Enter a **Name**, the **Access Key ID**, and the **Secret Access Key**.
1. Select **Enable Verification** to have CMP check the keys against AWS before saving. This calls `ec2:DescribeAccountAttributes`, so the key must carry that permission or the check fails. Leave it clear to save without checking.
1. Select **Create**.

![Screenshot of the Create new AWS Account Profile dialog.](/img/cmp/configure/infrastructure/resource-handlers/aws/iam-role/create-aws-account-profile.png)

One access key ID can be used by one AWS account profile. Adding a second profile with the same key is rejected.

## Create the handler

1. Go to **Admin** > **Resource Handlers** and select **Add**.
1. Select the **Amazon Web Services** tile.
1. Leave **Credentials Type** set to **Account Credentials** and set **Authentication Type** to **IAM Role**.
1. Select the **AWS Account Profile** you created.
1. Enter the **IAM Role ARN** for the role CMP should assume, in the form arn:aws:iam::account-id:role/role-name. The role is defined in the target AWS account. See [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the AWS documentation.
1. Select **Continue**, then complete the handler's settings and select at least one region, as described under [Add an AWS resource handler](/docs/cmp/configure/infrastructure/resource-handlers/aws/#add-an-aws-resource-handler).

![Screenshot of the Create a Resource Handler for Amazon Web Services dialog with IAM Role selected.](/img/cmp/configure/infrastructure/resource-handlers/aws/iam-role/create-aws-resource-handler-iam-role.png)

The role ARN appears on the handler's Overview tab. Use **Verify Connection** to confirm CMP can assume it.

## Create the IAM role with CloudFormation

A CloudFormation template creates the role with a trust policy that allows the account holding your access key to assume it.

1. Download [cloudbolt_assume_iam_role_template.json](https://raw.githubusercontent.com/CloudBoltSoftware/cloudbolt-forge/master/internal/cloudformation_templates/cloudbolt_assume_iam_role_template.json) from CloudBolt Forge.
1. In the AWS console, go to **CloudFormation** and create a stack.
1. Under Prerequisite, select **Template is ready**. Under Specify template, select **Upload a template file** and upload the template.
1. Enter a stack name, then enter the AWS account ID that will assume the role. Enter a role name to override the default.
1. Review the stack, acknowledge that it creates IAM resources, and submit it.

The role needs the permissions listed under [AWS permissions](/docs/cmp/configure/infrastructure/resource-handlers/aws/#aws-permissions).

## Related

- [AWS](/docs/cmp/configure/infrastructure/resource-handlers/aws/): the other credentials types, and what an AWS handler needs permission to do.
- [Import AMIs](/docs/cmp/configure/infrastructure/resource-handlers/aws/import-amis/): bring AMIs into CMP as OS builds.
- [Connection Info](/docs/cmp/configure/integrations/connection-info/): where the AWS account profile is stored.