AWS CLI Assume Role
The OneLogin + Amazon Web Services (AWS) CLI client lets you securely obtain temporary AWS access credentials via an easy to use command line interface.
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.
The default timeout for AWS credentials generated by this tool is 1 hour. You can extend the credential time out period to 12 hours via the AWS Console.
Configuring your AWS connection
In order to use this CLI tool you must first configure the AWS Multi Account app in your OneLogin admin portal.
Once the initial configuration is complete you should test the login to AWS via the OneLogin portal. If that all works then you’re good to move on to the fun part.
There is both a Java and a Python version of the CLI client to choose from.
This CLI client is developed in Java and therefore requires a minimum of Java 7.0 to be installed. Download the latest Java runtime here.
Both version 2 and 3 of Python are supported.
Installation of the Java version
All of the source for the OneLogin AWS CLI client is available on Github but if you want to get up and running quickly then we recommend using the precompiled distribution.
Update onelogin.sdk.properties with valid OneLogin API credentials. At a minimum you will need credentials that have been configured with “Authentication Only” access.
See Working with API Credentials for help generating credentials.
onelogin.sdk.client_id= onelogin.sdk.client_secret= onelogin.sdk.region= onelogin.sdk.ip=
- client_id - A valid OneLogin API Client ID
- client_secret - The corresponding OneLogin API Client Secret
- region - Indicates the region of the Onelogin instance. Possible values: ‘us’ or ‘eu’.
- ip - If you are using this API in a scenario in which MFA is required and you’ll need to be able to honor IP address whitelisting defined in MFA policies, provide this parameter and set its value to the whitelisted IP address that needs to be bypassed.
Installation of the Python version
All of the source for the OneLogin AWS CLI client is available on Github.
The usage and installation is similar to the Java version and is well documented in the Github repo.
For a complete list of configuration options checkout the help available in the jar.
java -jar onelogin-aws-cli.jar --help
Assuming you have your AWS Multi Account app set up correctly and you’re using valid API credentials, using this tool is as simple as following the prompts.
Open a terminal and execute the jar file
java -jar onelogin-aws-cli.jar
You will now be prompted for the following OneLogin account details
- AWS App Id
- You can obtain this number by inspecting the URL for the AWS Multi Account App that you have in your OneLogin portal.
- OneLogin Instance Sub Domain
- e.g. If you login at https://awesome.onelogin.com then your sub domain is awesome.
If you have MFA enabled you will be prompted to select a device and enter a token. If not then you will automatically skip this step.
You are now prompted with the AWS Roles that are available to you. Enter the number of the role that you want to assume.
Enter the AWS region that you want to access.
You’re done. The CLI tool will output the following temporary AWS Credentials and can be instantly used to access AWS resources.
Test your credentials with AWS CLI
AWS 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.
Using an AWS profile
In Step 1 above if you provide an additional profile parameter this tool will create/update a profile with the temporary AWS credentials that were created.
java -jar onelogin-aws-cli.jar --profile profilename
In this case you can then instantly call the AWS CLI using the profile that you have just updated.
aws ec2 describe-instances --profile profilename
Using AWS Environment Variables
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
- 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
Keeping the session alive
If you want to keep the session alive you can make use of the
--loop option which will login every 60 minutes for number of times you specify.
To enforce MFA when using the `—loop` command you must enable the “Skip if OTP received within last X minutes” on App Policy.
e.g. Keep the session alive for 10 hours
java -jar onelogin-aws-cli.jar --profile myoneloginclicreds --loop 10
Note: That you will need to keep the terminal window open to keep the session loop active.
The OneLogin AWS CLI client will dump verbose errors to the terminal if there is a problem. Typically these come down to a few common issues.
If it fails with an error that mentions OAuth 400 - Bad Request then its most likely that either:
- Your OneLogin Client ID or Client Secret is invalid or entered incorrectly
- Your onelogin.sdk.properties file is not in the same directory as the onelogin-aws-cli.jar file.
If it prompts for a MFA token and then errors after you enter the token then you most likely have not entered the correct token for the device that you selected.