session

iam-session

usage: iam-session [<flags>] [<command>...]

Start a new session under a different role.

Flags:
      --[no-]help                Show context-sensitive help (also try --help-long and --help-man).
  -q, --[no-]quiet               Do not output anything
  -s, --save-profile=SAVE-PROFILE
                                 Save the profile in the AWS credentials storage
      --[no-]overwrite-profile   Overwrite the profile if it already exists
      --[no-]print-identity-url  Print the identity URL
      --assume-role-arn=ASSUME-ROLE-ARN
                                 Role to assume
      --assume-role-external-id=ASSUME-ROLE-EXTERNAL-ID
                                 External ID of the role to assume
      --assume-role-session-name=ASSUME-ROLE-SESSION-NAME
                                 Role session name
      --assume-role-policy=ASSUME-ROLE-POLICY
                                 IAM policy to use when assuming the role
      --region=REGION            AWS Region
      --mfa-serial-number=MFA-SERIAL-NUMBER
                                 MFA Serial Number
      --mfa-token-code=MFA-TOKEN-CODE
                                 MFA Token Code
      --session-duration=1h      Session Duration
  -v, --[no-]version             Display the version
      --log-level=warn           Log level
      --log-format=text          Log format

Args:
  [<command>]  Command to run, prefix with -- to pass args

Features

• Supports the standard AWS authentication
  • credentials file (choose different profiles with AWS_PROFILE)
  • environment variables
  • instance profiles
• Use it to assume role between different AWS accounts

Examples

Here are some examples of invocation. All parameters can be used together.

Run a command under a different role

iam-session --assume-role-arn arn:aws:iam::123456789012:role/my-role aws ec2 describe-instances

Will describe ec2 instances accessible to the role my-role. When the command is run the session doesn't exist anymore. The command has its environment set to the parent environment with the new AWS environment variables injected.

Open a new shell authenticated as a different role

iam-session --assume-role-arn arn:aws:iam::123456789012:role/my-role bash

Will open a new shell under a new session for my-role. Like the previous example the AWS environment variables will be set. Note that the session is only valid for 15 minutes.

Create a new temporary session with MFA

iam-session --mfa-serial-number arn:aarn:aws:iam::123456789012:mfa/nico/my-mfa bash

The new session will have its MFA age set in IAM. Valid for 15 mins. You will be prompted for the MFA token code, but you can also pass it with --mfa-token-code

iam-session --mfa-serial-number arn:aarn:aws:iam::123456789012:mfa/nico/my-mfa --mfa-token-code 012345 bash

Save a temporary session to the AWS credentials file to reuse it

iam-session --mfa-serial-number arn:aarn:aws:iam::123456789012:mfa/nico/my-mfa --save-profile new-profile
aws --profile=new-profile ec2 describe-instances

The new profile will be added to ~/.aws/credentials and ~/.aws/config

If the profile already exists you will be prompted to confirm its replacement. You can avoid the prompt by using --overwrite-profile

Print a STS URL to prove your identity

iam-session --print-identity-url

The URL printed is a signed GetCallerIdentity request that can be fetched by anyone to get verify the IAM ARN of the caller of the command.