Team Onboarding

Adding a member takes two commands from the admin, with the member enrolling an MFA device in between.

The three steps

# 1. Admin provisions the member
keel auth team add [email protected] developer

This creates a dedicated IAM user ([email protected], under the /keel/ path), issues an access key, and records the member in the keel-team table.

The new key cannot reach anything yet. It carries the enrollment policy and no assume policy, so the only thing it can do is register an MFA device. Send the secret — printed once, never stored — to the member over a secure channel, with the commands Keel prints:

# 2. Run by the new member, in their project directory
keel auth join --account 123456789012 --region us-east-1
keel auth mfa enroll

enroll shows a QR code and the secret in text. The secret is generated on the member's machine and never leaves it — which is what keeps the two factors on separate channels, since the access key travelled through chat.

# 3. Admin finishes the job once the member says they have enrolled
keel auth team activate [email protected]

activate checks the member has exactly one MFA device, then swaps their enrollment rights for the assume policy of their role. More than one device stops the activation rather than being resolved: a second device is what it looks like when someone holding a copy of the access key enrols their own.

Why the two phases

If one credential could both enrol a device and assume a role, a stolen access key could enrol an attacker-controlled device and satisfy the MFA requirement by itself. An IAM user may hold up to eight devices, so doing that would neither disturb the member's real device nor be noticed. The two capabilities are therefore never held at the same time.

join does not take the member's word for their access level: it asks STS which Keel role their credentials can actually assume and records that. Passing --role only states an expectation — if it does not match what the admin granted, Keel says so and uses the real one.

Lost devices

If someone loses their phone, an admin resets them:

keel auth team reenroll [email protected]

That clears their devices, returns them to the enrollment state, and issues a replacement access key — someone who lost the phone may have lost the laptop holding the key with it. Pass --keep-key to reset the device only.

Managing the roster

add, remove, reenroll and mfa enforce all show what they are about to do and ask for confirmation; pass --force to skip the prompt in scripts.

# List active members (--all also shows removed ones)
keel auth team list

# Change a member's role — re-scopes their IAM user immediately
keel auth team set [email protected] admin

# Revoke access: deletes their access keys and IAM user
keel auth team remove [email protected]

# Also delete the roster record instead of marking it disabled
keel auth team remove [email protected] --purge

A role change takes effect on the member's next keel auth login; the session they already hold stays valid until it expires, up to 8 hours. Removal deletes their access keys first, so their credentials stop working immediately.

Accounts that manage identities elsewhere (IAM Identity Center, SSO) can track members on the roster without Keel touching IAM:

keel auth team add [email protected] developer --no-user

Keel never modifies or deletes an IAM user it did not create — those records are marked (unmanaged) in keel auth team list and left alone by remove.

Turning on MFA for a team that already exists

Members provisioned before MFA hold an assume policy and no way to register a device, so bringing them across takes four steps. Order matters — enabling enforcement before everyone has enrolled locks them out.

# 1. Admin, with the elevated AWS credentials.
#    Upgrades the policies and moves you onto a Keel admin user with MFA.
#    Enforcement stays off: it detects the unenrolled members and declines.
keel auth setup

# 2. Give existing members the ability to enrol
keel auth mfa open

# 3. Each member, at their own pace
keel auth mfa enroll

# 4. Track progress, then cut over when everyone is ready
keel auth mfa status
keel auth mfa enforce

Between steps 2 and 4 a member holds both enrollment rights and their assume policy. That costs nothing while MFA is not yet required — their access key already worked unaided — and enforce closes the window by detaching enrollment in the same run that adds the requirement. For that reason mfa open refuses to run once MFA is enforced; use keel auth team reenroll for a single member instead.

Anyone still unenrolled at step 4 is listed before you confirm, and loses access until an admin runs keel auth team reenroll for them. Sessions already in hand keep working until they expire. keel auth mfa enforce --disable rolls the requirement back without disturbing anyone's device.

Known gap: enforcement is not atomic

keel auth mfa enforce applies one trust policy to all three roles, but a failure partway can leave some roles enforced and the rest open. The dashboard's Team tab surfaces the per-role state. See the MFA Enforcement design note for the full write-up.