Integrating the Amazon Web Services Command Line Interface Using Okta Skip to main content
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Integrating the Amazon Web Services Command Line Interface Using Okta
Published: Dec 9, 2015   -   Updated: Jun 22, 2018

This article contains the following sections:


When using the Security Assertion Markup Language (SAML) to enable Amazon Web Services (AWS), the AWS Command Line Interface (CLI) does not inherit that configuration by default. However, most customers who integrate with AWS also want a Sign Sign-On (SSO) solution for the CLI.

This article, adapted from the Amazon Web Services and Okta Integration Guide, shows how you can leverage the CLI with Okta and the cross-account role design highlighted in that guide.

AWS Architecture

AWS provides the ability to obtain an AWS security token in exchange for a SAML assertion, using their Security Token Service (STS)/Application Program Interfaces (API)s. The CLI can take advantage of this functionality, and, through the process outlined below, allow SAML-based authentication.

CLI Integration Process using the AWS Security Token Service API

This process consists of the following three steps
  1. Call the Okta IdP to obtain a SAML assertion.
  2. Call the AWS STS API and exchange the SAML assertion for a temporary, 1-hour long, security token.
  3. Invoke the AWS CLI with the temporary security token.

Okta Solution Overview

A custom tool was developed using Okta as an IdP to invoke steps 1 and 2 in the AWS architecture process, showcasing how customers can take advantage of the solution. At a high level the custom tool performs the following actions:

  1. Prompts the user for Okta credentials (which can be AD or LDAP credentials replicated with Okta).
  2. Call Okta's AWS Embed URL to generate the SAML assertion and extracts the AWS IAM Roles assigned to the user from that assertion.
  3. Prompts the user to select one of the available AWS IAM Roles.
  4. Submits the resultant SAML assertion to the AWS STS API along with the selected role.
  5. Extracts the AWS IAM Roles assigned to the user from the SAML assertion and prompts the user to choose one of them.
  6. Optionally, if the user selected a cross-account role, the tool extracts the target role ARN (Amazon Resource Name, such as arn:aws:iam::253541269580:role/EC2_Admins) and writes a linked profile entry into the local AWS config file.

Solution Overview Diagram

User-added image


Before implementing the custom code sample, the following should be in place:

In your Okta tenant:

  • The Okta SAML integration to AWS must be completed and functional.

Note: The only supported Sign On method is SAML. SWA, Federated User Login, and Amazon AWS IAM Role Sign On methods are not supported for CLI integration.

In your AWS instance:
  • Go to the Identity and Access Management page and create an IAM user with specific permissions, as mentioned in Appendix A. Generate an Access Key ID and Secret Access Key and store them in a temporary location: you will need them in order to write a specific entry into the ~/.aws/config file.
  • We strongly recommend that cross-account roles set up on the Identity account be only associated with one AssumeRole action. This is because the current version of the tool only considers the first AssumeRole action it finds when it introspects the selected role on the Identity account.

On your AWS Client workstation:

  • Install Java
    • The custom tool requires Java 1.8 or better.
    • Verify that your AWS CLI version is 1.8 or higher (required by the tool).

Installation and Configuration

Follow these steps to install and configure the custom tool:
  1. Download the package from and place the JAR file in a newly-created .okta directory in the user home folder
  2. in the .okta folder, create a file named, using the following file as an example:
  3.  edit the file to represent your environment:
    • OKTA_ORG is the FQDN of your Okta org (such as
    • OKTA_AWS_APP_URL is the AWS App Embed URL from the General tab of your AWS application in your Okta org.
    • AWS_IAM_KEY (optional) is the Access Key ID for the IAM User you previously created
    • AWS_IAM_SECRET (optional) is the Secret Access Key for the IAM User you previously created

An example file is shown below: 


You're now ready to execute the custom tool.


Part 1 (Obtain Assertion and Request Token)

  1. Navigate to the directory that contains the Okta AWS-CLI Assume Role tool.
  2. Run the following command from a command line:
    ./awscli.command (this must be followed by a valid AWS command.  For example: ./awscli.command -sts get-caller-identity)
  3. Enter the username and password of a valid Okta user assigned to the AWS Okta app.

    User-added image

  4. If applicable, select an MFA Factor

    User-added image
    Note: At this time, per-app MFA is not supported in this integration. Only organization-level MFA is supported.

  5. Select the AWS role you would like to assume (among all the AWS roles the user was assigned to in Okta).

    User-added image

    The tool acquires temporary, 1-hour long credentials from the AWS Security Token Service (STS) and stores them in the local ~/.aws/credentials file. Optionally, if the tool detects that the selected AWS role is mapped to an AssumeRole action, it will also write a corresponding entry in the ~/.aws/config file that will allow the user to automatically access the permissions assigned to the AssumeRole in question. It will then output a message similar to the following one:

    Your new access key pair has been stored in the aws configuration file with the following profile name: 671250123543/Retail-EC2-Admins/
    The AWS Credentials file is located in /Users/username/.aws/credentials.
    Note that it will expire at X/X/XX 0:00 PM

    After this time you may safely rerun this script to refresh your access key pair.

    To use these credentials, please call the aws cli with the --profile option (e.g. aws --profile 671250123543/Retail-EC2-Admins/ ec2 describe-instances)

  6. Take note of the profile name you just generated (in this case, 671250123543/Retail-EC2-Admins/ as you will need it to call the AWS Command Line Interface (as shown in the next section).

Appendix A: How to Create an IAM User for Role Introspection

With its new support of cross-account roles, the Assume Role tool introduces a new convenience for AWS users to enhance the usability of the AWS CLI. When using our Assume Role tool, the AWS Security Token Service will generate temporary credentials that have the permissions associated with the selected role in the Identity account. However, when used as a proxy to a cross-account role located in another account, this role in the Identity account typically only has sts:AssumeRole permissions which do not give it sufficient permissions to execute the AWS operations assigned to the cross-account role it is associated with (such as ec2 describe-instances). To solve this issue, AWS allows local users to add an entry to their ~/.aws/config file mentioning the target role ARN (see AWS documentation).

The Assume Role tool provides an optional convenience that allows the automation of the second option but it requires the creation of a specific IAM User with specific permissions as well as the distribution of this user’s Access Key and Secret to AWS users who will want to take advantage of this convenience.

If you want to go ahead with that automation, you will need to create an IAM user with the following read-only permissions (for instance, added in an inline policy, using the Policy Generator and the Identity and Access Management service) :

  • iam:GetPolicy
  • iam:GetPolicyVersion
  • iam:GetRole
  • iam:GetRolePolicy
  • iam:ListAttachedRolePolicies
  • iam:ListRolePolicies
User-added image

Once the permissions above have been assigned to the IAM User, go to the Security Credentials tab and press the Create Access Key button. Then copy the resulting Access Key ID and Secret Access Key into the AWS_IAM_KEY and AWS_IAM_SECRET parameters values of the file located in the out directory.

If you do not want to use this automation, you will have to figure out a way to provide the cross-account role ARN (mentioned in the AssumeRole policy) to the AWS user so that it can be manually added to her ~/.aws/config file. The format of the expected entry in the config file is the following:

[profile {profile_name_from_credentials_file}] (such as 671250594556/Retail-EC2-Admins/

role_arn={role arn in target AWS account} (such as arn:aws:iam::253541269580:role/EC2_Admins)

source_profile={profile_name_from_credentials_file} (same as in [profile] line above)