aws-mfa-credentials

Keep your AWS credentials file up to date with MFA-carrying temporary credentials

Usage

aws-mfa-credentials --mfa-serial-number SERIAL_NUMBER

See Locking protcol for important information about avoiding data loss!

From the API reference for GetSessionToken:

SerialNumber: The identification number of the MFA device that is associated with the IAM user who is making the GetSessionToken call. Specify this value if the IAM user has a policy that requires MFA authentication. The value is either the serial number for a hardware device (such as GAHT12345678) or an Amazon Resource Name (ARN) for a virtual device (such as arn:aws:iam::123456789012:mfa/user). You can find the device for an IAM user by going to the AWS Management Console and viewing the user's security credentials.

Optional flags:

• --duration DURATION_SECONDS The lifetime of the credentials. Defaults to AWS default (43200 at the time of this writing).
• --profile PROFILE The name of the profile whose credentials we're managing. Defaults to 'default'.
• --refresh-lead-time LEAD_SECONDS The amount of time before credential expiry to refresh the credentials. Defaults to 300.

Environment variables:

• PATH: A program named ssh-askpass, accepting a prompt as an argument and outputting a password to stdout, must be available on the path.
• HOME: The home directory containing the .aws/credentials file

Operation

aws-mfa-credentials will request an MFA code from the user using ssh-askpass, request temporary credentials from Amazon, and update the credentials file with the temporary credentials.

The new credentials are placed into a profile named PROFILE-mfa, e.g. when the --profile flag is not given they are placed in default-mfa. Use the AWS_PROFILE environment variable or other profile-specifying mechanisms to use the credentials.

aws-mfa-credentials exits on any error, you may want to run it in a retry loop (with backoff).

Locking protocol

To allow safe usage of multiple instances of aws-mfa-credentials in parallel, a locking protocol is used for the credentials file: An exclusive fcntl lock is held on the file $HOME/.aws/.credentials.lock when writing (and thus data read before the lock is obtained must be rechecked within the lock).

Unfortunately, the AWS cli and other tools do not respect this protocol. Therefore, if you are modifying the credentials file in any way besides aws-mfa-credentials, you should either stop any existing instances of aws-mfa-credentials or obtain the lock yourself. Credential loss may occur if this is not followed!