Assume an AWS Role and get temporary credentials using Onelogin.
Users will be able to choose from among multiple AWS roles in multiple AWS accounts when they sign in using OneLogin in order to assume an AWS Role and obtain temporary AWS access credentials.
This is really useful for customers that run complex environments with multiple AWS accounts, roles and many different people that need periodic access as it saves manually generating and managing AWS credentials.
This repository contains a python script at src/aws_assume_role/aws_assume_role.py that you can execute using onelogin-aws-assume-role in order to retrieve the AWS credentials.
OneLogin's Smart MFA cannot be enforced with OneLogin's AWS CLI utility
The "Configuring SAML for Amazon Web Services (AWS) with Multiple Accounts and Roles" guide explains how to:
- Add the AWS Multi Account app to OneLogin
- Configure OneLogin as an Identity Provider for each AWS account
- Add or update AWS Roles to use OneLogin as the SAML provider
- Add external roles to give OneLogin access to your AWS accounts
- Complete your AWS Multi Account configuration in OneLogin
The project is hosted at github. You can download it from:
- Latest release: https://github.com/onelogin/onelogin-python-aws-assume-role/releases/latest
- Master repo: https://github.com/onelogin/onelogin-python-aws-assume-role/tree/master
The toolkit is hosted in pypi, you can find the python-saml package at https://pypi.python.org/pypi/onelogin-aws-assume-role
It works with python2 and python3.
- boto3 AWS Python SDK
- onelogin OneLogin Python SDK
- pyyaml YAML parser
- lxml XML and HTML processor
The use of a virtualenv is highly recommended.
Virtualenv helps isolating the python environment used to run the toolkit. You can find more details and an installation guide in the official documentation.
Once you have your virtualenv ready and loaded, then you can install the toolkit on it in development mode executing this:
python setup.py develop
Using this method of deployment the toolkit files will be linked instead of copied, so if you make changes on them you won't need to reinstall the toolkit.
If you want install it in a normal mode, execute:
python setup.py install
The python script uses a settings file, where OneLogin SDK properties are placed.
Is a json file named onelogin.sdk.json as follows:
{
"client_id": "",
"client_secret": "",
"region": "",
"ip": ""
}Where:
- client_id Onelogin OAuth2 client ID
- client_secret Onelogin OAuth2 client secret
- region Indicates where the instance is hosted. Possible values: 'us' or 'eu'.
- ip Indicates the IP to be used on the method to retrieve the SAMLResponse in order to bypass MFA if that IP was previously whitelisted.
For security reasons, IP only can be provided in onelogin.sdk.json.
On a shared machine where multiple users has access, That file should only be readable by the root of the machine that also controls the
client_id / client_secret, and not by an end user, to prevent him manipulate the IP value.
Place the file in the ~/.onelogin directory or in the same path where the python script is invoked or provide the path with the -c option.
There is an optional file onelogin.aws.json, that can be used if you plan to execute the script with some fixed values and avoid providing it on the command line each time.
{
"app_id": "123456",
"subdomain": "myolsubdomain",
"username": "user.name",
"profile": "profile-1",
"duration": 3600,
"aws_region": "us-west-2",
"aws_account_id": "",
"aws_role_name": "",
"profiles": {
"profile-1": {
"aws_account_id": "",
"aws_role_name": "",
"aws_region": "",
"app_id": ""
},
"profile-2": {
"aws_account_id": ""
}
}
}Where:
- app_id Onelogin AWS integration app id
- subdomain Needs to be set to the correct subdomain for your AWS integration
- username The email address that is used to authenticate against Onelogin
- profile The AWS profile to use in ~/.aws/credentials
- duration Desired AWS Credential Duration in seconds. Default: 3600, Min: 900, Max: 43200
- aws_region AWS region to use
- aws_account_id AWS account id to be used
- aws_role_name AWS role name to select
- profiles Contains a list of profile->account id, and optionally role name mappings. If this attribute is populated
aws_account_id,aws_role_name,aws_region, andapp_idwill be set based on theprofileprovided when running the script.
Note: The values provided on the command line will take precedence over the values defined on this file and, values defined at the global scope in the file, will take precedence over values defined at the profiles level. IN addition, each attribute is treating individually, so be aware that this may lead to somewhat strange behaviour when overriding a subset of parameters, when others are defined at a lower level and not overridden. For example, if you had a onelogin.aws.json config file as follows:
{
...
"aws_region": "eu-east-1",
"profiles": {
"my-account": {
"aws_account_id": "11111111",
"aws_role_name": "Administrator"
}
}
}And, you you subsequently ran the application with the command line arguments --profile my-account --aws-account-id 22222222 then the application would ultimately attempt to log in with the role Administrator on account 22222222, with region set to eu-east-1 and, if successful, save the credentials to profile my-account.
In addition, there is another optional file that can be created to give more human readable names to the account list, named accounts.yaml, which should be placed in the same path where the python script is invoked:
accounts:
"987654321012": Prod account
"123456789012": Dev AccountThis isn't needed for the script to function but it provides a better user experience.
git clone git@github.com:onelogin/onelogin-python-aws-assume-role.gitcd onelogin-python-aws-assume-role- Enter your credentials in the
onelogin.sdk.jsonfile as explained above - Save the
onelogin.sdk.jsonfile in the root directory of the repo docker build . -t awsaccess:latestdocker run -it -v ~/.aws:/root/.aws awsaccess:latest onelogin-aws-assume-role --onelogin-username {user_email} --onelogin-subdomain {subdomain} --onelogin-app-id {app_id} --aws-region {aws region} --profile default
- Provide OneLogin's username/mail and password to authenticate the user
- Provide the OneLogin's App ID to identify the AWS app
- Provide the domain of your OneLogin's instance.
Note: If you're bored typing your
username (--onelogin-username),
App ID (--onelogin-app-id),
subdomain (--onelogin-subdomain) or
AWS region (--aws-region)
every time, you can specify these parameters as command-line arguments and
the tool won't ask for them any more.
You can specify
OTP Code (--otp)
and the cli will use this otp only for the first interaction
requiring a manual OTP Code
Note: Specifying your password directly with --onelogin-password is bad practice,
you should use that flag together with password managers, eg. with the OSX Keychain:
--onelogin-password $(security find-generic-password -a $USER -s onelogin -w),
so your password won't be saved in you command line history.
Please note that your password will be visible in your process list,
if you use this flag (as the expanded command line arguments are part of the name of the process).
With that data, a SAMLResponse is retrieved. And possible AWS Role are retrieved.
- Provide the desired AWS Role to be assumed.
- Provide the AWS Region instance (required in order to execute the AWS API call).
A temporal AWS AccessKey and secretKey are retrieved in addition to a sessionToken. Those data can be used to generate an AWS BasicSessionCredentials to be used in any AWS API SDK.
After checking out the repository, let's use a virtual environment
cd <repository>
virtualenv venv
Activate then the environment
> source venv/bin/activateThen run
> python setup.py installor
> python setup.py developto install dependencies.
Assuming you have your AWS Multi Account app set up correctly and you’re using valid OneLogin API credentials stored on the onelogin.sdk.json placed at the root of the repository, using this tool is as simple as following the prompts.
> onelogin-aws-assume-roleOr alternately save them to your AWS credentials file to enable faster access from any terminal.
> onelogin-aws-assume-role --profile profilenameBy default, the credentials only last for 1 hour, but you can edit that restriction on AWS and set a max of 12h session duration.
Then set the -z or duration with the desired credentials session duration. The possible value to be used is limited by the AWS Role. Read more at https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html#id_roles_use_view-role-max-session
You can also make it regenerate and update the credentials file by using the --loop option to specify the number of iterations, and --time to specify the minutes between iterations. If you specified a duration, be sure the value you set for the duration session of the credential is bigger than the value you set for the time, so your credentials will be renewed before expiration.
You can provide an specific path where locate the settings file by providing the -c or --config-file-path option.
You can also make it interactive, with the -x or --interactive option, and at the end of the iteration, you will be asked if want to generate new credentials for a new user or a new role.
The selection of the AWS account and Role can be also be done with the --aws-account-id and --aws-role-name parameters. If both parameters are set then both will be matched against the list of available accounts and roles. If only --aws-account-id is specified and you only have one available role in that account, then that role will be chosen by default. If you have more than one role in the given account then you will need to select the appropriate one as per normal.
If you plan to execute the script several times over different Accounts/Roles of the user and you want to cache the SAMLResponse, set the --cache-saml option
By default in order to select Account/Role, the list will be ordered by account ids. Enable the --role_order option to list by role name instead.
For more info execute:
> onelogin-aws-assume-role --helpAWS provide a CLI tool that makes remote access and management of resources super easy. If you don’t have it already then read more about it and install it from here.
For convenience you can simply copy and paste the temporary AWS access credentials generated above to set them as environment variables. This enables you to instantly use AWS CLI commands as the environment variables will take precedence over any credentials you may have in your ~/.aws directory.
Assuming that:
- you have the AWS CLI installed
- you have set the OneLogin generated temporary AWS credentials as environment variables
- the role you selected has access to list EC2 instances
You should find success with the following AWS CLI command.
aws ec2 describe-instances
After checking out the repo, run pip setup install or python setup.py develop to install dependencies.
To release a new version, update the version number in src/onelogin/api/version.py and commit it, then you will be able to update it to pypi.
with python setup.py sdist upload and python setup.py bdist_wheel upload.
Create also a release tag on github.
Bug reports and pull requests are welcome on GitHub at https://github.com/onelogin/onelogin-python-aws-assume-role. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the OneLogin Assume AWS Role project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.