Okta AWS CLI Assume Role tool
New to Amazon Web Services with Okta? **Start with the Configuring AWS in Okta.
This tool has been verified to work on macOS Sierra, High Sierra, Windows Server 2012 R2, Windows 10, and Ubuntu 16.04 LTS, and is expected to work on other Linux systems as well.
- Compiling the application
- Configuring AWS in Okta
- Configuring the application
- Getting help
- Run the following in a PowerShell console
Set-ExecutionPolicy -Scope Process -ExecutionPolicy unrestricted -Force; Invoke-Expression ((New-Object Net.WebClient).DownloadString('https://raw.githubusercontent.com/oktadeveloper/okta-aws-cli-assume-role/master/bin/Install-OktaAwsCli.ps1')); .$profile
- Customize %userprofile%\.okta\config.properties and set OKTA_ORG and OKTA_AWS_APP_URL appropriately. For example,
Run the following in a Terminal:
export PREFIX=/usr/local curl 'https://raw.githubusercontent.com/oktadeveloper/okta-aws-cli-assume-role/master/bin/install.sh' | bash
Customize ~/.okta/config.properties and set OKTA_ORG and OKTA_AWS_APP_URL appropriately. For example,
Make sure /usr/local/bin (or whatever $PREFIX/bin is) is in your PATH
~/.okta/config.propertiesand set OKTA_ORG and OKTA_AWS_APP_URL appropriately. For example,
Run this command:
docker run -v ~/.okta/config.properties:/root/.okta/config.properties -it tomsmithokta/okta-awscli-java
Read more at @tom-smith-okta's okta-awscli-java Docker repo.
.okta directory in your home directory. For example,
Download the latest release JAR and put it in
~/.okta/config.properties and set
OKTA_ORG and OKTA_AWS_APP_URL appropriately. For example,
Copy scripts from
.okta/bin to somewhere on your PATH.
Verify your setup with a simple command:
okta-aws test sts get-caller-identity
This will prompt for Okta credentials, log you into AWS, let you pick a role, and store a session profile called test for you.
Run the program again to see session resumption (you won't be asked for Okta credentials until the session expires):
okta-aws test sts get-caller-identity
NOTE: okta-aws is a function loaded from your shell profile, not a typical program or command stored in a file.
Compiling the application
The application was built and compiled with JetBrains' IntelliJ IDEA. Note that you don't have to compile the application in order to be able to execute it, since the compiled executable (a JAR file) is available on GitHub.
Then you will need Maven 2 or later to run the build.
Building on the command line
Get a single JAR with all dependencies:
git clone https://github.com/oktadeveloper/okta-aws-cli-assume-role.git to clone the repository locally. Then, build with Maven:
mvn package cp target/okta-aws-cli-*.jar out/oktaawscli.jar
Opening the project with IntelliJ Idea
- Open the IntelliJ Idea IDE and browse to the
okta-aws-cli-assume-rolefolder you have cloned from GitHub inside the
- Go to
File => Project Structureand in the Libraries menu, fix the Java references that don't match your local setup.
- Go to
Build => Make Projectin order to compile the project.
- The project also builds the JAR artifact, so if you browse to the
outsub-folder, you will see the
- Make sure the
awscli.commandfile is in the
Configuring AWS in Okta
Configuring the application
Here is the list of parameters that can be environment variables or settings in the
OKTA_ORGwhich is the url of your Okta org (starting with https://).
OKTA_AWS_APP_URLis the url link of your Okta AWS application url (see below for more info)
OKTA_USERNAMEis the username to use. If present will skip username input.
OKTA_PASSWORD_CMDis the command to fetch your password instead of showing a password prompt. Read more...
OKTA_ENV_MODEset to true to run sub-command with AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN env vars set. Temporary credentials are shared in memory and kept off disk in this mode. (default: false)
OKTA_BROWSER_AUTHset to true to use integrated web browser for authentication (default: false)
OKTA_COOKIES_PATHis directory path to store cookies.properties for Okta. This is particularly useful when running this tool in many concurrent processes like you might with OKTA_ENV_MODE (default: ~/.okta)
OKTA_PROFILEis the name of the AWS profile to create/reuse. May also be specified on the commandline by
--profile. (default: get AWS profile name based on per-session STS user name)
OKTA_AWS_REGIONis the default AWS region to store with the created profile.
OKTA_AWS_ROLE_TO_ASSUMEis the role to use. If present will try to match okta account's retrieved role list and use it. Will still prompt if no match found.
OKTA_STS_DURATIONis the duration the role will be assumed, in seconds. The maximum session duration allowed by AWS is 12 hours and this needs to be set on the role as well. Defaults to 1hr.
Obtaining the AWS app url
- Navigate to the
Admin Dashboardof you Okta organization
- Select the
Applicationstab and click on your AWS Application
- Under the
Generalmenu, scroll down to find the
App Embed Linksection
- Your link is located under
- Navigate to the
Replace the example values in
config.propertieswith your values
Note: environment variables take precedence over the config file.
I get "You have no factors enrolled"
This means that MFA is enforced, but you have no factors enrolled on your user.
You should enrol a CLI-supported factor (all except Duo as far as I know).
If you are using Duo Push, consider setting OKTA_BROWSER_AUTH=true in the configuration.
I have Duo, but I get "None of your factors are supported"
This means that MFA is enforced, but none of the factors you have enrolled are supported.
Okta's integration with Duo requires an iframe which isn't practical to interact with from a CLI context.
If you find a security vulnerability, please follow our Vulnerability Reporting Process.
Copyright 2017 Okta, Inc. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.