aws-keyhub v1.5.0
aws-keyhub
CLI login helper for the AWS CLI when using SAML based federated login with Topicus KeyHub.
Usage
Installation
Release version
Run npm install -g aws-keyhub
Configuration
To set-up the aws-keyhub tool we need the KeyHub username, password and url. Configuring these properties can be done by running with the -c
param: aws-keyhub -c
Note: the KeyHub url should be the SAML IDP initiated-flow url. It's similar to: https://keyhub.domain.tld/login/initiate?client=urn:amazon:webservices
Authenticate
When the application is configured you can run the tool by executing aws-keyhub
.
It will prompt you for the 2FA token and the role you want to use. This roles are the AWS roles that you have access to in one or more AWS accounts.
If you provide the --role-arn
parameter along with a valid role ARN for your account, that role will be automatically selected and you won't be prompted for a choice.
Session duration
Due to restrictions by Amazon Web Services the maximum duration of the session is 12 hours. If authentication fails when using the AWS CLI please re-run the aws-keyhub
command to get a new session. The default session duration is 12 hours (43200 sec). If you need a shorter duration please reconfigure with aws-keyhub -c
.
Topicus KeyHub configuration
For optimal usage of this tool your KeyHub instance needs to be configured to send additional SAML payload. The payload helps a user to select the right role if they have access to multiple AWS accounts by displaying a description. Add the custom attribute https://github.com/topicuskeyhub/aws-keyhub/groups
with the following code to build the descriptive array.
// Function returns a list of descriptive objects based on a UUID match
var mapping = new Map();
mapping.set('aaabbbcc-2222-aaaa-3333-fffff0000000', {
'account' : 'example-account-name',
'role' : 'inzicht',
'arn' : 'arn:aws:iam::123456789012:role/MyCustomRole,arn:aws:iam::123456789012:saml-provider/keyhub'
});
return groups.filter(function (group) {
return mapping.has(group.uuid);
}).map(function (group) {
return "{\"description\": \"" + mapping.get(group.uuid).account + " - " + mapping.get(group.uuid).role + "\", \"arn\": \"" + mapping.get(group.uuid).arn + "\"}";
});
FAQ
How is my KeyHub password stored?
To make the login process as easy as possible we store your password when running the configure command. To make sure it's stored safely we use keytar. Keytar stores the password in a native way depending on your operating system. For MacOS the native Keychain is used, for Windows keytar relies on Credential Vault. On Linux the libsecret library is used. More information about keytar is found here: https://www.npmjs.com/package/keytar
Where is the configuration stored?
The configuration is stored in ~/.aws-keyhub/config.json
Help! The login flow is broken, something seems to be corrupt.
aws-keyhub uses headless Chrome to login. It is possible that something is wrong with your Chrome profile. If this occures you can delete the Chrome profile which can be found at ~/.aws-keyhub/puppeteer_profile