How to give an external tool access with a cross-account IAM role (no keys)

When an external tool needs to get into your AWS account there are two routes. The familiar one: create an IAM user and give it an access key, which is a password that never expires and can end up in a configuration file, a repository or an email. The good one: create a role that the tool assumes from its own AWS account. There is no key to store or leak; AWS hands out temporary credentials that expire on their own, and you can cut off access in a second by deleting the role.

For this the tool has to support it (it will ask you for "role-based access", a "cross-account role" or the "role ARN") and give you two pieces of information: its AWS account number and an external ID. With those, it is done in ten minutes.

Step by step

1. Gather the provider's details

   Note down the tool's account ID (twelve digits) and the external ID it assigns you, a string that is unique to you. The external ID prevents the so-called "confused deputy problem": another customer of the same tool being able to make it use your role. Do not share it or reuse it.

2. Create the minimal-permissions policy

   In the IAM console, Policies, Create policy, JSON tab. Paste only the actions the tool needs; a serious provider gives you the exact list. For example, to view and manage Lightsail machines:

   {
     "Version": "2012-10-17",
     "Statement": [{
       "Effect": "Allow",
       "Action": [
         "lightsail:GetInstances", "lightsail:GetInstance", "lightsail:GetInstanceState",
         "lightsail:StartInstance", "lightsail:StopInstance", "lightsail:RebootInstance",
         "lightsail:GetInstanceSnapshots", "lightsail:CreateInstanceSnapshot"
       ],
       "Resource": "*"
     }]
   }

   Give it a recognisable name, such as PanelExterno-Maquinas. If they ask you for AdministratorAccess, ask why.

3. Create the role with the other account as the trusted entity

   IAM, Roles, Create role. Trusted entity type: AWS account, option Another AWS account, and type the provider's account ID. Tick Require external ID and paste the external ID. Do not tick "Require MFA": the tool is a program, not a person. Next.

4. Attach the policy and name the role

   Search for the policy you created in step 2, tick it and continue. Role name: something that says what it is for and whose it is, for example PanelExterno-Simplio. Review the summary: the trust policy must show the provider's account and the sts:ExternalId condition. Create the role.

5. Hand over the role ARN

   Open the newly created role and copy its ARN, of the form arn:aws:iam::123456789012:role/PanelExterno-Simplio. It is the only thing the tool needs; paste it wherever it asks for it. It is not a secret in itself (without the external ID and without being in the trusted account it is of no use), but there is no need to publish it either.

6. Check access and the log

   The tool should connect straight away. To see what it does, in CloudTrail, event history, filter by the role name: every action it runs appears with the role as the identity. If one day you want to cut off access, delete the role or change the external ID; the effect is immediate as soon as the temporary credentials in use expire, which last at most one hour unless you have extended it.

What can go wrong