`aws-vault` docs should cite limitations of GetSessionToken and how to solve

[Christopher Hackett]

Buried in the AWS documentation it says:

The temporary security credentials created by GetSessionToken can be used to make API calls to any AWS service with the following exceptions:
You cannot call any IAM API operations unless MFA authentication information is included in the request.
You cannot call any AWS STS API except AssumeRole or GetCallerIdentity.

This causes confusion to users of aws-vault who are using an IAM user in their profile. When they attempt to use calls for IAM they get InvalidClientTokenId.

[profile a]
region=us-east-2

$ aws-vault exec a -- aws iam list-users

An error occurred (InvalidClientTokenId) when calling the ListUsers operation: The security token included in the request is invalid

AWS documentation for this error is poor:

InvalidClientTokenId
The X.509 certificate or AWS access key ID provided does not exist in our records.
HTTP Status Code: 403

Users of aws-vault should have a clear way to understand why they get the InvalidClientTokenId error and be directed to one of the following options
a. (recommended) Attach mfa to the IAM user and configure a profile to use MFA
b. (discouraged) Use --no-session to bypass the use of GetSessionToken

I'll look at making a PR but if there is any input anyone wants to make first it will be taken onboard.

[Michael Tibben]

I believe there are references to these limitations in the USAGE doc

[Christopher Hackett]

I've provided a PR on the USAGE doc.

There was one line I found odd

If you have an account with an MFA associated, but you don't provide the IAM ARN, you are unable to call IAM services, even if you have the correct permissions to do so.

This does not match my experience (below). Is the line outdated? Or does it apply under a more specific scenario?

[profile a]
region=us-east-2

$ aws-vault exec a --no-session -- aws iam list-users
{
    "User": {
        "UserName": "REDACTED", 
        "PasswordLastUsed": "2022-10-15T14:36:31Z", 
        "CreateDate": "2022-10-15T14:32:02Z", 
        "UserId": "REDACTED", 
        "Path": "/", 
        "Arn": "arn:aws:iam::REDACTED:user/REDACTED"
    }
}

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.