Team Onboarding

Onboarding has three steps: an administrator creates the member, the member enrolls MFA, and the administrator activates access.

This page covers IAM team members. To give someone scoped access without an AWS key, use an operator enrollment and capability grants instead.

The three steps

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

This creates a dedicated IAM user ([email protected] under /keel/), issues an access key, and records the member in the keel-team table. The key initially permits only MFA enrollment. Send the secret to the member through a secure channel; Keel prints it once and does not store it.

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

enroll generates the MFA secret on the member's machine and displays it as a QR code and text. The MFA secret remains separate from the access key sent by the administrator.

# 3. Admin activates access after enrollment
keel auth team activate [email protected]

activate requires exactly one MFA device, then replaces enrollment access with the assume policy for the member's role. Keel stops if it finds multiple devices so the administrator can investigate.

Why the two phases

Separating enrollment from role assumption prevents a stolen access key from enrolling another MFA device and using it to satisfy the role's MFA requirement.

join asks STS which Keel role the credentials can assume and records that access level. --role provides an expected role; Keel reports a mismatch and uses the role granted by IAM.

Lost devices

If someone loses their phone, an admin resets them:

keel auth team reenroll [email protected]

This clears the member's devices, returns them to enrollment, and issues a replacement access key. Pass --keep-key to reset only the MFA device.

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 enroll
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, members retain their existing assume policy while gaining enrollment rights. enforce removes enrollment rights as it enables the MFA requirement. After enforcement, use keel auth team reenroll to reset an individual member.

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 Admin tab surfaces the per-role state.