1. Home >
2. API >
3. 1 >
4. Samples >
5. AWS CLI Assume Role

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.

Smart MFA cannot be enforced with OneLogin’s AWS CLI utility.

Prerequisites

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.

Java Runtime

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.

Python

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.

1. Download the binary (onelogin-aws-cli.jar) and config (onelogin.sdk.properties) files from the /dist folder of the Github repository. These files need to reside in the same directory on your machine.

2. 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 allow-listing defined in MFA policies, provide this parameter and set its value to the allowed 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.

Configuration Options

For a complete list of configuration options checkout the help available in the jar.

java -jar onelogin-aws-cli.jar --help

Usage

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.

1. Open a terminal and execute the jar file

   java -jar onelogin-aws-cli.jar
   

2. You will now be prompted for the following OneLogin account details

   • Username
   • Password
   • 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.

3. 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.

4. You are now prompted with the AWS Roles that are available to you. Enter the number of the role that you want to assume.

5. Enter the AWS region that you want to access.

6. 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.

e.g.

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 ~/.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

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.

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.

Troubleshooting

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.

1. 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.

2. 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.

---