Connect an AWS account

Connect an AWS account and your agents can run aws --profile <name> … against it straight away. Agents only ever get short-lived credentials, and you decide which roles they can use.

This page covers both ways to connect, choosing roles, what the agent gets, and how access is secured and revoked.

Before you start

• You need permission to manage connections at the scope you’re connecting to. See Connection scopes.
• Use the dashboard at app.alfe.ai or the desktop app. The mobile app lists AWS connections but can’t add or manage them.
• Have access to the AWS account. For the role method, you need permission to create a CloudFormation stack and an IAM role.
• Use an account in the standard (commercial) AWS partition. AWS GovCloud (US) and AWS China accounts can’t be connected.

Choose a connection method

You can connect an account in one of two ways:

• Connect with a role (recommended) — you create an IAM role in your account with one click. Alfe assumes it with an external ID that only your setup link carries. No long-lived keys are shared.
• Use access keys — you paste the access key of an IAM user. Alfe stores the keys encrypted and never sends them to an agent. Root account keys are always rejected.

Prefer the role method. It needs no key rotation, and its Direct profile can call IAM APIs. The access-keys Direct profile can’t; see Limitations.

Connect with a role

1. In the Connections hub, choose the scope, then select Add new connection and pick AWS.
2. Select Connect with a role.
3. Under What can agents do in this account?, choose an access level. See Access levels for what each one grants.
4. Leave Let the agent switch into other roles ticked if agents should use other roles in your accounts. Untick it to limit agents to this one role. See Role chaining.
5. Select Launch in AWS. AWS CloudFormation opens in a new tab with every parameter filled in.
6. Sign in to AWS if prompted, acknowledge that the stack creates IAM resources, and select Create stack.
7. Back in Alfe, enter your 12-digit AWS account ID. You can paste the role ARN instead; the stack’s RoleArn output shows it.
8. Pick a Default region and, optionally, a Label such as “Production”. Then select Continue.

Alfe verifies that it can assume the new role. It also checks that the role refuses requests without the external ID, and rejects a role that doesn’t. If the stack is still finishing, you’ll see Waiting for AWS… while Alfe retries for up to 30 seconds. Next, choose the roles agents can use.

Note

CloudFormation opens in us-east-1. IAM roles are global, so the role works in every region. The default region only sets where agent commands run when they don’t pass --region.

What the stack creates

The stack creates one IAM role, named AlfeAgentAccess-…. The role:

• Trusts one Alfe principal — and only when the request carries the external ID from your setup link. You can see both in the role’s trust policy.
• Has the AWS managed policy for your access level attached.
• Can discover other roles — an inline policy named AlfeDiscoveryAndChaining allows iam:ListRoles, iam:ListAccountAliases, and organizations:ListAccounts.
• Can or can’t switch into other roles — the same policy allows sts:AssumeRole when role chaining is on, and explicitly denies it when it’s off.
• Has a maximum session duration of one hour.

The stack’s AllowRoleChaining parameter holds your choice: Yes (the default) or No.

Role chaining

Role chaining lets the Alfe role switch into other roles, so agents can use the roles you select in Choose the roles agents can use. It’s on by default.

With chaining on, the role can assume any role, in any account, whose trust policy trusts this role or this account. That includes a role that trusts arn:aws:iam::<ACCOUNT_ID>:root with no conditions. Such a role can grant more than the access level you picked.

The profiles you select decide which roles Alfe issues credentials for. They don’t limit the role itself: an agent using the Direct profile can call sts:AssumeRole with it. The real boundary is the trust policies in your accounts, so check which roles trust this account before you leave chaining on.

Turn chaining off when agents only need the Alfe role itself. The explicit deny overrides every access level, including Administrator. Role discovery still works, but you can only save the Direct profile. To add chained roles later, select Re-issue link and run the update with chaining turned on.

Access levels

The access level picks the AWS managed policy attached to the role:

Access level	AWS managed policy	What agents can do
Read-only (default)	ReadOnlyAccess	Look at everything, change nothing.
Power user	PowerUserAccess	Create and change resources, but not IAM users, roles, or account settings.
Administrator	AdministratorAccess	Full control of the account, including IAM.

The access level covers the Alfe role only. Chained roles carry their own permissions; see Role chaining.

Administrator at the organization level

A connection at the organization scope is available to every team, project, and agent. Choosing Administrator there gives all of them full control of the account. Prefer Read-only or Power user, or connect at a single agent’s scope instead.

Connect with access keys

1. In the Connections hub, choose the scope, then select Add new connection and pick AWS.
2. Select Use access keys.
3. Enter the IAM user’s Access key ID and Secret access key. The key ID must be a long-term key that starts with AKIA. Temporary ASIA keys and root account keys are rejected.
4. Pick a Default region and, optionally, a Label. Then select Continue.

Alfe checks the keys with AWS. Next, choose the roles agents can use.

Choose the roles agents can use

After verifying, Alfe shows the identities agents can use. Each one you tick becomes a named AWS CLI profile on the agent.

• Direct — the connected identity itself: the Alfe role, or the IAM user behind your access keys. It’s ticked by default.
• Discovered roles — roles Alfe found that may trust the connected identity. These include roles whose trust policy names your account. If you use AWS Organizations, they also include standard roles in member accounts, such as OrganizationAccountAccessRole.
• Role ARN — add any role discovery missed by pasting its ARN.

Discovered roles are candidates until you save. If the identity isn’t allowed to list roles, or the list is cut short, Alfe says so and you can still add roles by ARN. If you turned role chaining off, you can only save the Direct profile.

To finish:

1. Tick the identities agents should use.
2. Edit each profile name if you like. Names use lower-case letters, numbers, -, and _, up to 63 characters. Each must be unique, and default is reserved.
3. Select Save and activate.

Alfe test-assumes every selected profile. If one fails, it’s flagged inline and nothing is activated. Fix or untick it, then save again. When every profile passes, the connection becomes Active.

To change the roles later, select Manage roles on the connection.

Give your agent the AWS CLI

The connection holds the access. The AWS integration puts it to work on the agent. You don’t need to install it: once the connection is Active, Alfe adds it automatically to every agent that can see the connection, and removes it when the last AWS connection goes away.

The integration:

• Installs AWS CLI v2 on the agent host.
• Writes one named profile per selected identity into ~/.aws/config.
• Teaches the agent how to use those profiles safely.

It manages only its own block in ~/.aws/config. It never writes a [default] profile and never changes profiles you created yourself.

What the agent gets

Each identity you selected appears as an AWS CLI profile. The agent lists them with:

Terminal

alfe aws profiles

Output

PROFILE      ACCOUNT       ROLE                                       REGION     LABEL
production   123456789012  (direct)                                   us-east-1  Production
prod-deploy  123456789012  arn:aws:iam::123456789012:role/DeployRole  us-east-1

Add --json to get the same list as a JSON array.

The agent then names a profile on every AWS command:

Terminal

aws sts get-caller-identity --profile production
aws s3 ls --profile prod-deploy
aws ec2 describe-instances --profile production --region eu-west-1

There’s no default profile, so every command must pass --profile. Credentials are fetched and refreshed automatically; the agent never runs aws configure or handles keys.

Security model

Alfe keeps your long-lived secrets out of the agent’s reach:

• Keys never leave Alfe. Access keys are stored encrypted and used only inside Alfe to request temporary credentials. They’re never sent to an agent or shown in the dashboard.
• Agents get short-lived credentials. Every session lasts at most one hour. The agent caches a session on its host, readable only by its own user, and refreshes it before it expires.
• Agents ask by profile, not by ARN. An agent can only request the profiles you selected on a connection in its scope.
• Every session is attributable. Sessions use the name alfe-<agentId>, so you can trace each agent’s activity in AWS CloudTrail. Calls Alfe makes during setup use alfe-setup.
• The external ID binds the role to your setup. Each setup link carries a new external ID. It works once and expires after 24 hours.

Revoke access

You can cut off access from Alfe or from AWS:

• In Alfe — select Disconnect on the connection, or untick a role in Manage roles. Alfe stops issuing credentials for it immediately.
• In AWS — delete the CloudFormation stack, or remove the Alfe principal from a role’s trust policy. For access keys, deactivate the key in IAM.

Allow up to an hour

Revoking stops new credentials, but sessions already issued stay valid until they expire. Because agents cache sessions, that can take up to one hour. To end a role’s sessions sooner, use Revoke active sessions on that role in the IAM console.

Limitations

• Direct access-key profiles can’t call IAM APIs. An access-key Direct profile uses a temporary session token, and AWS blocks IAM API calls from those without MFA. Use a role profile for IAM work.
• Sessions last at most one hour. AWS caps chained role sessions at one hour. Credentials refresh automatically, but a single long-running command can outlive its session.
• Commercial AWS partition only. Accounts and regions in AWS GovCloud (US) and AWS China aren’t supported.
• Add and manage from the dashboard or desktop app. The mobile app shows AWS connections but can’t add them or change their roles.

Troubleshooting

“Waiting for AWS…” doesn’t finish

The stack hasn’t finished creating the role. Open the stack in CloudFormation and wait for CREATE_COMPLETE, then select Try again.

Alfe can’t use the role

Check the account ID or role ARN you entered. Also check that you created the stack from the link Alfe gave you, because that link carries the matching external ID. If you edited the stack’s parameters, launch it again from Alfe.

The setup link expired or was already used

Setup links expire after 24 hours and work once:

• During setup — select Launch in AWS again for a fresh link, then update the stack with it.
• For an existing role connection — select Re-issue link on the connection. Alfe opens an Update stack link with a new external ID. When the stack shows UPDATE_COMPLETE, select I’ve updated the stack so Alfe can re-check access. An active connection stays active throughout.

Check the external ID on Update stack

AWS may not fill in the new external ID when you update a stack. Alfe shows the new value in a copy field next to the link. If the stack’s ExternalId parameter isn’t already set to it, paste it in before you update.

Alfe says the role doesn’t require the external ID

The role’s trust policy lets Alfe in without the external ID. Alfe refuses these roles, because anyone who learned the role ARN could reach your account through Alfe.

Update the trust policy to require sts:ExternalId, then try again. The CloudFormation template from Alfe already does this, so recreating the role from the setup link also fixes it.

Alfe says STS isn’t activated

AWS Security Token Service (STS) is turned off for your account in the region Alfe requests credentials from. In the IAM console, open Account settings and activate the inactive STS regional endpoints. Then try again.

Agents see the same message when they request credentials until STS is activated.

Alfe says there were too many attempts

Alfe limits how often AWS is called during setup and for each agent profile. The message tells you how long to wait. Wait that long, then try again.

Agents cache each session for up to an hour, so a healthy agent rarely hits the limit. If one does, look for a script that requests credentials in a tight loop.

The connection shows “Setup incomplete”

The account is verified, but no roles are saved yet, so agents can’t use it. Select Finish setup to choose roles, or disconnect it if you no longer need it.

The agent is denied when it requests credentials

AWS refused to issue a session for the profile, so the AWS command fails before it runs. The agent reports the reason. Common causes:

• The role, or its trust policy, was changed or deleted in AWS.
• A chained role no longer trusts the connected identity.
• STS isn’t activated in the region Alfe uses; see Alfe says STS isn’t activated.

For a role connection, select Re-issue link and run the update. That puts the Alfe role back to the shape Alfe expects. For a chained role, fix its trust policy in AWS.

AWS returns AccessDenied

The profile’s role doesn’t allow that action. The agent reports which profile and which action was denied. To fix it, either:

• add the permission to the role’s policy in AWS, or
• connect a role with a broader access level and select it in Manage roles.

AWS rejects the access keys

Check the access key ID and secret, and that the key is still Active in IAM. Root account keys are never accepted; create an IAM user, or use the role method.

Related resources

• Connection scopes — choose who can use the connection.
• Providers & managing connections — label, move, or disconnect a connection.
• Managing integrations — install integrations on an agent.
• AWS CloudTrail User Guide — trace agent activity by session name.