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


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.

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.


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.



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 that will expire in 1 hour 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


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"

  • 5

    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: 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 …

  • 0

    A: Can I use OneLogin API to generate SAML assertions in a standalone app?

    Answered Apr 01 2017

    exactly what we will do at the first step with our OneLogin AWS-STS CLI tool. Of course we could have a rogue employee abusing this, but it's an edge case and really easy to revoke the client ID/secret and rollout a new version with a new client ID/secret. … Verify Factor (Login) Create Session Login Token Log User Out Writing a web app to get the SAML assertation would be the best solution and let the CLI interact with it. Especially if you consider the …

  • 0

    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 …