Please note that gossamer has been deprecated in favor of Gossamer 3.
CLI app to help you manage assuming lots of roles (concurrently) across multiple AWS accounts and set them up as profile entries in an AWS credentials file.
Gossamer is good at a few things:
- Assume lots of roles from a set of starter credentials with MFA and multi credential chaining.
- Assume lots of roles from a SAML assertion and use those creds to assume other roles
It won't mess with your existing profile entries and will instead add/modify it's own entries.
Sample resulting profile entry:
[admin-role]
# DO NOT EDIT
# ACFMGR MANAGED SECTION
# (Will be overwritten regularly)
####################################################
# ASSUMED ROLE: arn:aws:iam::1234567899012:role/admin
# ASSUMED FROM INSTANCE ROLE: NA
# GENERATED: 2020-01-04 18:34:24.563761 +0000 UTC
# EXPIRES@ 2020-01-04 19:34:23 +0000 UTC
# DESCRIPTION: classic
region = us-east-1
aws_access_key_id = ASISUDIWNEIVJUEWDF6RPF
aws_secret_access_key = Ttc8aalkasdnf3olaknoi23o2FLAQE9
aws_session_token = FwoGZXIvYXdzEPz//////////wEaaoiwenfawoifawpinawofinawapiuawapoeuiawfopiauoawiuefEIIEEaieiEIEOEOOoowoEOEEOEOogoEOEogoocNNNNenweOeienDnDndDDDDDDDDDDDDDDDDDDJDDDDDDDDDDDDDDDDDJJJJJJJJJJJJJJJJJJJJJJJJJJJJJJJjjjjjEEEEEEEEEEEEEEEEEEEEEEEFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEeeasdofwoeifapuhviuabviUDUDUFBDUFBIUEBFIEUBIFUBEFZG2KG6HhrBqGfg5n7mk/URw=
From which you can run commands using the profile like
aws --profile admin-role iam list users
On a mac you can do a Homebrew install.
mkdir ~/gossamer
brew tap GESkunkworks/gossamer https://github.com/GESkunkworks/geskunkworks-taps
brew install gossamer
For Windows and Linux you can grab one of the releases and unzip it to your desired location.
Assumes you want to use a SAML login to assume all roles that come back from the SAML assertion.
Generate a sample config file using ./gossamer -generate @sample and then modify the resulting file to look something like:
output_file: "~/.aws/credentials"
flows:
- name: sample-saml
saml_config:
username:
source: env
value: SAML_USER
password:
source: prompt
url:
source: config
value: https://my.saml.auth.url.com/auth.fcc
target:
source: config
value: https://my.auth.target.com/fss/idp/startSSO.ping?PartnerSpId=urn:amazon:webservices
primary_assumptions:
all_roles: trueObviously you'll need to update the URL and target parameters with whatever is necessary for your organization.
Save the file as config.yml and run gossamer -c config.yml.
You'll be prompted to enter the value for the SAML password since you set the password parameter to be of source type prompt. After entering your password you should see gossamer attempt to assume all of the roles that come back in your SAML assertion since you set all_roles: true under primary_assumptions.
From there you should see a bunch of entries in ~/.aws/credentials with auto generated profile names in the format [<account_number>_<role_name>]. If you want to give these a friendlier name you can add specific arn-to-profile name mappings to the mappings list.
From there you can use the entries with the AWS CLI running commands such as:
aws --profile 123456789012_admin ec2 describe-instances
Assumes you want to start with a local profile entry that has the permission--if logged in with MFA--to assume multiple additional roles.
First add your user's permanent keys to the ~/.aws/credentials file with the profile name [giam] like so:
[giam]
output = json
region = us-east-1
aws_access_key_id = AKILDOIAOFIFEFOEFSMA
aws_secret_access_key = KBhehehehehehenotgonnaguessmenowZW
Next, find out what the ARN or serial number of the same user's MFA device is that is associated with the above perm creds.
Generate a sample config file using ./gossamer -generate @sample and then modify the resulting file to look something like:
output_file: "~/.aws/credentials"
flows:
- name: sample-permanent-creds-mfa
permanent:
profile_name: giam
mfa:
serial:
source: config
value: "GAKT0008D4BC"
token:
source: prompt
primary_assumptions:
mappings:
- role_arn: arn:aws:iam::123456789012:role/sub-admin
profile_name: sub-admin
region: us-west-2
- role_arn: arn:aws:iam::123456789012:role/role2
profile_name: role2Save the file as config.yml and then run ./gossamer -c config.yml
From there it will prompt you for the token for the MFA device with serial number GAKT0008D4BC and if successful it will assume the two roles provided in the mappings list under primary assumptions.
You should see output that indicates the role assumptions were successful and your ~/.aws/credentials file will have new entries.
Below is a sample configuration file YML with comments explaining each section. You can always generate your own sample using the gossamer -generate @sample command.
# the file to which the AWS profile entries will be written
output_file: ./path/to/credentials/file
# flows define authentication workflows. They can use different types of
# starter credentials to get their primary assumptions (e.g., SAML or permanent)
# from which secondary assumptions can be made with the primary assumptions
# as sponsors
flows:
# name is a simple identifier for the flow and will be used in logging
# and will also be included in the resulting profile entry
- name: sample-permanent-creds-mfa
# when the 'permanent' block is present gossamer will assume you want to
# run a flow using permament credentials. If no other sub-parameters
# are present under permanent then it will try to use the normal auth
# flow provided by AWS (e.g., ENV vars, instance-profile, etc)
session_duration_seconds: 8600 # if you want every mapping to try and use the parent Flow's session duration you can set it here
permanent:
# profile_name refers to the profile entry in your AWS credentials file that will be used
# to assume the primary_assumptions
profile_name: seedprofile
# mfa section being present will force the starter creds to first
# get an mfa enabled session using the provided serial and token
# before attempting to assume roles in the primary assumptions
mfa:
serial:
source: config # config means the value for this param comes from this config file in the below 'value'
value: sampleserial # the value for the desired source (see more advanced in SAML section below)
token:
source: config
value: sampletoken
# primary_assumptions is what the starter creds (permament or SAML) will assume after
# the intial session is established using the above auth information for the flow.
primary_assumptions:
all_roles: false # in a permanent creds flow all_roles is ignored anyway
# mappings are a list of roles to assume using the above starter creds
mappings:
- role_arn: arn:aws:iam::123456789012:role/role2 # the only mandatory field is a role_arn
- role_arn: arn:aws:iam::123456789012:role/sub-admin
profile_name: sub-admin # the optional profile name to give this credential. If not provided one will be generated using the format '<account_number>_<rolename>'
region: us-west-2 # this region will override any imnherited region from parent flow
no_output: true # in case you don't want the creds written to the output file
session_duration_seconds: 43200 # if you want to override the session duration at a mapping level you can do it here
allow_failure: true # if no creds are generated during this flow gossamer will ignore and move to next flow
do_not_propagate_region: false # in case you don't want to propagate the region down to the mappings from the flow's region
- name: sample-saml
# saml_config when provided indicates to gossamer that you want to run a SAML flow
saml_config:
# username, password, url, and target are required parameters
username:
source: env # you can use keyword 'env' if you want to source this parameter from the value stored in the environment variable provided in the 'value' field. For example, here the value will be provided from $SAML_USER
value: SAML_USER
password:
source: prompt # you can use the keyword 'prompt' if you want gossamer to pause and ask you for the value for this input parameter. You can use 'prompt' as the source for any parameter but when used for password the input is hidden
url: # url is where your username, password, and target will be sent to
source: config
value: https://my.saml.auth.url.com/auth.fcc
target: # target will be passed as a url param to the provided URL. This is crucial for some SAML providers such as Ping
source: config
value: https://my.auth.target.com/fss/idp/startSSO.ping?PartnerSpId=urn:amazon:webservices
# in a SAML flow the session duration coming from the SAML assertion will take precedence
# unless the allow_mapping_duration_override is set to true in which case the flow and and
# mapping can set custom durations as in the permanent flow
allow_mapping_duration_override: true
primary_assumptions:
all_roles: true # in SAML flows you can request that all roles that can be assumed in the SAML assertion be assumed
mappings: # when providing mappings when all_roles = true, all roles in the assertion will be assumed but the provided mappings will be given the additional metadata you specify. This is useful if you want to give user friendly names to the profile entries
- role_arn: arn:aws:iam::123456789012:role/sub-admin
profile_name: sub-admin
region: us-west-2
no_output: true
- role_arn: arn:aws:iam::123456789012:role/role2
profile_name: role2
secondary_assumptions:
all_roles: false # this is always ignored under secondary_assumptions
# mappings under secondary assumptions will be assumed using one of the primary assumption credentials
mappings:
- role_arn: arn:aws:iam::123456789012:role/admin
profile_name: admin
region: us-west-2
sponsor_creds_arn: arn:aws:iam::123456789012:role/sub-admin # if there are multiple primary assumptions then a sponsor_creds_arn is required in order to let gossamer know which primary credential to use to assume this secondary credential
region: us-east-2
allow_failure: false
do_not_propagate_region: trueAs many flows can be defined as desired by the user. For example, it may be useful to define multiple SAML flows for MFA enabled SAML providers and non MFA SAML providers as well as a few testing flows for permanent creds.
You can get some of the non-SAML functionality out of gossamer without ever having to make a config file. This is mostly here as legacy support for gossamer 1.x users' aliases but can be helpful for one off commands.
We'll go over a few here but see the full list of parameters at the bottom of the README or by running gossamer -help.
The following command will load roles to assume from a legacy "rolesfile" formatted JSON file and assume them using an MFA enabled session from the giam profile.
gossamer -o ./creds -rolesfile "./roles.json" -profile giam -serialnumber $MFA -tokencode 1234567
You can find a sample legacy rolesfile in the ./samples directory but here's a quick reference:
{
"Roles": [{
"RoleArn": "arn:aws:iam::123456789101:role/prod-role",
"AccountName": "prod-account",
"Region": "us-east-1"
}, {
"RoleArn": "arn:aws:iam::110987654321:role/dev-role",
"AccountName": "dev-account",
"Region": "us-west-1"
}]
}You can also just assume a single role without needing a config file. For example, in Windows the command would look something like:
gossamer -o %HOMEPATH%\.aws\credentials -a arn:aws:iam::8765448765487:role/sadmin -profile default -serialnumber arn:aws:iam::876548765487:mfa/rendicott -tokencode 123456
Users of previous versions of gossamer and probably not familiar with the concept of the config file and flows. The good news is that most of the 1.x command arguments are supported in 2.x except for the daemon mode functionality which has been removed. What this means is that most users can use their existing command aliases with the new version while they work on converting to the new config/flow flormat.
Running your "legacy" gossamer command and adding the -generate my-config.yml parameter will translate your command arguments to a gossamer 2.x config file.
go get ./...
go build -o ./build/gossamer -ldflags "-X main.version=v0.0.0"
sudo mv ./build/gossamer /usr/bin/gossamer
Here's the output of the contextual --help flag:
-a string
Role ARN to assume.
-c string
path to yml config file that overrides all other parameters
-duration int
Duration of token in seconds. Duration longer than 3600 seconds only supported by AWS when assuming a single role per tokencode. When assuming multiple roles from rolesfile max duration will always be 3600 as restricted by AWS. (min=900, max=[read AWS docs]) (default 3600)
-entryname string
when used with single ARN this is the entry name that will be added to the creds file (e.g., 'test-env') (default "gossamer")
-force
LEGACY: ignored and only included so it doesn't break 1.x commands
-generate string
translates command arguments into config file for those who wish to convert from legacy parameters to new config file format. Will also generate a sample config file when this parameter is passed the '@sample' value.
-logfile string
JSON logfile location (default "gossamer.log.json")
-loglevel string
Log level (info or debug) (default "info")
-o string
Output credentials file. (default "./gossamer_creds")
-profile string
Cred file profile to use. This overrides the default of using standard AWS session workflow (env var, instance-profile, etc)
-region string
desired region for the primary flow (default "us-east-1")
-rolesfile string
LEGACY: File that contains json list of roles to assume and add to file.
-serialnumber string
Serial number of MFA device
-tokencode string
Token code of mfa device.
-v print version and exit