See api-docs Menu

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.

OneLogin AWS CLI

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.

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.


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 ( files from the /dist folder of the Github repository. These files need to reside in the same directory on your machine.

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

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

Configuration Options

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.

  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 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. OneLogin AWS CLI with MFA

  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.


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.

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.

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

StackOverflow discussions about "[onelogin] aws cli"

  • 9

    Q: AWS API credentials with OneLogin SAML and MFA

    Asked Oct 30 2016

    We want to allow our users to retrieve a set of temporary CLI credentials for a given AWS role by signing in to OneLogin with password and MFA. We have a working solution, but it requires the user to … fully re-authenticate to OneLogin (including MFA) every 60 minutes as the AWS temporary credentials expire. I think that won't fly - our users are accustomed to permanent API credentials tied to a …

  • 2

    Q: AWS CLI SAML Integration

    Asked Apr 27 2017

    I'm using OneLogin to federate user credentials in my organization. We already have the AWS console connected as an app, but we want do something similar with the AWS CLI. Would it be possible to use … SAML 2.0 authentication to give federated users access to the AWS CLI? How? I've looked through dozens of forums and loads of documentation, but nothing really matches what I'm trying to do. (Nearly all of it pertains to AD FS, which we don't use.) …

  • 1

    Q: How to activate OneLogin Protect push challenge with SAML assertions

    Asked Feb 23 2018

    -factor-authentication/overview but that requires me to give either Manage users or Manage All permissions to the API keys. As this is a Python cli utility to handle aws saml auth, and one way or … another, we need to distribute those API keys to users, this seems like excessive privileges for a user to log into AWS. Does anyone know how can I check the status of an OTP for OneLogin Protect with …

  • 1

    Q: Getting a SAML assertion after creating a session via API

    Asked Apr 04 2017

    Related to Accessing Third Party Apps After Creating A Session Via API Token and to AWS API credentials with OneLogin SAML and MFA Since AWS assumeRoleWithSAML temporary security credentials are … because of the short validity. It's totally odd to the web base OneLogin usage, where he is logged in once for the whole day or even week (depending on the policy). I know how to get a session via API …

  • 1

    A: AWS API credentials with OneLogin SAML and MFA

    Answered Nov 01 2017

    always use the OneLogin MFA APIs to bake in an MFA flow into the tool... Check it out here: … We're in the process of officially adding an option to in our official CLI tool to re-use the user credentials similarly to what you're describing. Essentially our CLI tool has an option to reuse …