Emergency access

Emergency access signs you in to the console with AWS credentials instead of your identity provider. Use it:

• for the first sign-in, before single sign-on is configured;
• when your identity provider is down or misconfigured.

An emergency session is an owner session that lasts one hour and can't be renewed. It requires a session of the stack's emergency role, proven to the server through AWS STS.

Choose who may use itCopy Anchor Link

EmergencyAccessMode decides who may assume the emergency role (output EmergencyRoleArn). The role itself has no AWS permissions; it only identifies you to Tracemill.

identity-center sessions don't carry the MFA flag that mfa-iam-users checks, which is why it's a separate mode. In the identity-center pattern, never put a / directly after a *: the role path has no Region segment when Identity Center runs in us-east-1, and such a pattern would never match.

Keep at least one way to reach this account that doesn't depend on your corporate identity provider. If your IdP is down and your only route into AWS is the same IdP, emergency access can't help.

Sign inCopy Anchor Link

You need the Tracemill CLI and the AWS CLI.

1. Get a challenge. Open https://<ConsoleHostname>/emergency, or choose Use emergency access on the sign-in page. The page shows a command containing a one-time challenge, and the emergency role ARN. The challenge expires after five minutes, works once, and only in this browser.

2. Clear stale AWS credentials from your shell. Exported AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN override AWS_PROFILE, so leftovers from earlier work make the next steps fail or sign as the wrong identity:

   Copy Text

   unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

3. Assume the emergency role and export its credentials. For mfa-iam-users, add your MFA device:

   Copy Text

   eval "$(aws sts assume-role \
     --role-arn <EmergencyRoleArn> \
     --role-session-name <your-name> \
     --serial-number <your MFA device ARN> --token-code <current MFA code> \
     --query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' --output text \
     | awk '{print "export AWS_ACCESS_KEY_ID="$1" AWS_SECRET_ACCESS_KEY="$2" AWS_SESSION_TOKEN="$3}')"

   For identity-center, sign in with your Identity Center profile first (aws sso login --profile <profile>) and run the same assume-role with --profile <profile> and without the MFA options. For supplied, assume your role the way you normally do. The session name you choose is recorded with the sign-in.

4. Sign the challenge. Run the command from the page, adding the stack's Region (output Region):

   Copy Text

   tracemill byoc emergency-login <challenge> --region <Region>

   Without --region, the CLI uses the Region of your AWS configuration and fails if there's none. It makes no network call: it signs an STS GetCallerIdentity request with your credentials and prints it as a proof.

5. Paste the proof into the page and choose Sign in. The server sends the signed request to STS, checks that the caller is a session of the emergency role, and signs you in.

If you signed with the wrong credentials, the page names the identity that signed and the role to assume; start again from step 2. Any other rejection says only that the proof wasn't accepted: request a new challenge and repeat.

What's recordedCopy Anchor Link

The session belongs to a user named Emergency plus your role session name, and the server logs the caller's ARN and session name for each emergency sign-in. Changes made in the session are attributed to that user like any other member's.