New to this tool? Start with the Okta-AWS Integration Guide. We highly recommend that you first read it to understand how Okta and AWS integrate with each other.
This tool has been verified to work on Mac OS X El Capitan and Windows Server 2012 R2, and is expected to work on Linux and Unix as well.
- Installation
- Usage
- Compiling the application
- Configuring AWS IAM
- Configuring the application
- History
- Troubleshooting
- Getting help
- License
Create a .okta directory in your home directory. For example, ~/.okta.
Download the latest release JAR and put it in .okta:
https://github.com/oktadeveloper/okta-aws-cli-assume-role/releases
Copy config.properties to .okta/config.properties and set
OKTA_ORG and OKTA_AWS_APP_URL appropriately. For example,
OKTA_ORG=acmecorp.oktapreview.com
OKTA_AWS_APP_URL=https://acmecorp.oktapreview.com/home/amazon_aws/0oa5zrwfs815KJmVF0h7/137Copy scripts from .okta/bin to somewhere on your PATH.
Verify your setup with a simple command:
awscli sts get-caller-identityThis will prompt for Okta credentials, log you into AWS, let you pick a role, and store a session for you.
Run the program again to see session resumption (you won't be asked for Okta credentials until the session expires):
awscli sts get-caller-identityThe 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.
First of all, it goes without saying that you will need to install the Java SE 8x or the Java JDK 8x.
Next, in order to compile the application, you will need to download and install the AWS Java SDK as well as the AWS Command Line Interface. Once you have downloaded the AWS Java SDK, make sure you copy the latest AWS JAR file (currently aws-java-sdk-1.10.74.jar) into the lib folder of this tool (otherwise, you will not be able to compile or run it).
You will also need the Okta Java SDK but we provide a compiled version of it within this repository so there's nothing specific you need to do at this point. We used the following path structure to manage our IntelliJ project: $HOME/Projects/okta-aws-cli-assume-role and we recommend you do the same to avoid fixing too many references. We've also created a lib sub-folder inside the okta-aws-cli-assume-role root folder where we're storing the AWS Java SDK (aws-java-sdk-1.10.74.jar), the Okta Java SDK (okta-sdk.jar) and other dependencies. We strongly recommend that you do the same.
Get a single JAR with all dependencies:
Use 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- Open the IntelliJ Idea IDE and browse to the
okta-aws-cli-assume-rolefolder you have cloned from GitHub inside theProjectsfolder. - 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 theoktaawscli.jarJAR artifact. - Make sure the
awscli.commandfile is in theoutsub-folder.
Because this tool aims at facilitating your interaction with the AWS CLI, it must be able to look into the role you select to assume in order to figure out whether it's a role with direct permissions on the account, or a cross-account role that allows you to assume a role (with real permissions) in another account. To perform this introspection into the AWS roles, the tool must be granted AIM Read Only Access in AWS so that it can automatically add the proper role_arn and source_profile entries into the AWS config file.
In order to generate the key and secret to be configured in the config.properties file, please follow the steps highlighted in Appendix A: How to create a IAM user for role introspection in the Okta-AWS Integration Guide
It is essential that config.properties be in the same directory as the oktaawscli.jar file (i.e. in the out directory). The config.properties config file holds information specific to each Okta organization (or "tenant") and needs to be configured on an org to org basis. Please copy it from the src/com/okta/tools folder to the out folder.
Here is the list of parameters that must be maintained in the config.properties file:
-
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_PASSWORDis the password to use. If present will skip password input. -
OKTA_BROWSER_AUTHset to true to use integrated web browser for authentication (default: false) -
OKTA_PROFILEis the name of the AWS profile to create/reuse (default: get AWS profile name based on per-session STS user name) -
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 theApp Embed Linksection - Your link is located under
EMBED LINK
- Navigate to the
-
Replace the example values in
config.propertieswith your values
Stored IAM credentials are no longer used: you no longer need to distribute or rotate these credentials.
Minimal config requires only your orgname and Amazon Web Services Okta app embed link:
OKTA_ORG=acmecorp.oktapreview.com
OKTA_AWS_APP_URL=https://acmecorp.oktapreview.com/home/amazon_aws/0oa5zrwfs815KJmVF0h7/137If the role you are assuming does not have sts:AssumeRole, you will need to attach an inline policy like this to it to at least allow the role to assume itself:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sts:AssumeRole"
],
"Resource": [
"arn:aws:iam::123456789012:role/ReadOnly"
]
}
]
}Add config.properties parameters to support silent mode without prompt for user input (2017/6/8 update)
- OKTA_USERNAME
- OKTA_PASSWORD
- OKTA_AWS_ROLE_TO_ASSUME
Same parameters can be set as environment variable. config.properties parameter has priority over environment variable.
You can now use this tool with the cross-account role architecture recommended in the Okta-AWS Integration Guide, i.e. you can assign multiple AssumeRole policies to a single cross-account role.
The AWS-CLI tool currently only supports single-statement policies, i.e. policies with one single AssumeRole action (pointing to a role in a separate account). Additionally, the tool only supports managed policies. Support for inline policies is planned in the near future.
The Okta AWS-CLI Tool allows Okta customers to take advantage of Okta to use the AWS Command Line Interface without relying on permanent AWS keys. More specifically, it allows them to generate temporary 60-minute keys
that are stored for each profile in the ~/.aws/credentials file. Additionally, if the AWS environment is leveraging cross-account roles and the AssumeRole AWS function, the tool will be able to detect that you choose
to assume a cross-account role and will be able to extract the actual role in the target account as well as add an additional profile line the ~/.aws/config file.
Important note: please note that this tool only supports Okta MFA set up at the organization level (i.e. not at the sign-on policy level).
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).
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 see an error like this:
User arn:aws:iam::123456789012:assumed-role/RoleName/user.name@example.com is not authorized to perform:
sts:AssumeRole on resource: arn:aws:iam::123456789012:role/RoleName
Then you will need to attach an inline policy like this to the role to allow the role to assume itself:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sts:AssumeRole"
],
"Resource": [
"arn:aws:iam::123456789012:role/RoleName"
]
}
]
}Have a question or see a bug? Post a question on the Okta Dev Forums or email developers@okta.com. For feature requests, feel free to open an issue on this repo.
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.