• Stars
    star
    902
  • Rank 50,630 (Top 1.0 %)
  • Language
    Python
  • License
    Apache License 2.0
  • Created over 7 years ago
  • Updated 8 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A CLI that utilizes Okta IdP via SAML to acquire temporary AWS credentials

Gimme AWS Creds

gimme-aws-creds is a CLI that utilizes an Okta IdP via SAML to acquire temporary AWS credentials via AWS STS.

Okta is a SAML identity provider (IdP), that can be easily set-up to do SSO to your AWS console. Okta does offer an OSS java CLI tool to obtain temporary AWS credentials, but I found it needs more information than the average Okta user would have and doesn't scale well if have more than one Okta App.

With gimme-aws-creds all you need to know is your username, password, Okta url and MFA token, if MFA is enabled. gimme-aws-creds gives you the option to select which Okta AWS application and role you want credentials for. Alternatively, you can pre-configure the app and role name by passing -c or editing the config file. This is all covered in the usage section.

Disclaimer

Okta is a registered trademark of Okta, Inc. and this tool has no affiliation with or sponsorship by Okta, Inc.

Prerequisites

Okta SAML integration to AWS using the AWS App

Python 3.7+

Optional

Gimme-creds-lambda can be used as a proxy to the Okta APIs needed by gimme-aws-creds. This removes the requirement of an Okta API key. Gimme-aws-creds authenticates to gimme-creds-lambda using OpenID Connect and the lambda handles all interactions with the Okta APIs. Alternately, you can set the OKTA_API_KEY environment variable and the gimme_creds_server configuration value to 'internal' to call the Okta APIs directly from gimme-aws-creds.

Installation

This is a Python 3 project.

Install/Upgrade from PyPi:

pip3 install --upgrade gimme-aws-creds

OR

Install/Upgrade the latest gimme-aws-creds package direct from GitHub:

pip3 install --upgrade git+git://github.com/Nike-Inc/gimme-aws-creds.git

OR

Install the gimme-aws-creds package if you have already cloned the source:

python3 setup.py install

OR

Use homebrew

brew install gimme-aws-creds

OR

Use with nix flakes

# flake.nix
# Use by running `nix develop`
{
  description = "Shell example";

  inputs.flake-utils.url = "github:numtide/flake-utils";
  inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  inputs.gimme-aws-creds.url = "github:Nike-Inc/gimme-aws-creds";

  outputs = {
    self,
    nixpkgs,
    flake-utils,
    gimme-aws-creds,
    ...
  } @ inputs:
    flake-utils.lib.eachDefaultSystem
    (
      system: let
        pkgs = nixpkgs.legacyPackages.${system};
      in {
        devShells.default = pkgs.mkShell {
          packages = [pkgs.bash gimme-aws-creds.defaultPackage.${system}];
        };
      }
    );
}

OR

Use with original nix

# shell.nix
# Use by running `nix-shell`
{pkgs ? import <nixpkgs> {}, ...}:
with pkgs; let
  gimme-src = fetchgit {
    name = "gimme-aws-creds";
    url = "https://github.com/Nike-Inc/gimme-aws-creds";
    branchName = "master";
    sha256 = "<replace>"; #nix-prefetch-url --unpack https://github.com/Nike-Inc/gimme-aws-creds/archive/master.tar.gz
  };

  gimme-aws-creds = import gimme-src;
in
  mkShell rec {
    name = "gimme-aws-creds";

    buildInputs = [
      bash
      (gimme-aws-creds.default)
    ];
  }

OR

Build the docker image locally:

docker build -t gimme-aws-creds .

To make it easier you can also create an alias for the gimme-aws-creds command with docker:

# make sure you have the "~/.okta_aws_login_config" locally first!
touch ~/.okta_aws_login_config && \
alias gimme-aws-creds="docker run -it --rm \
  -v ~/.aws/credentials:/root/.aws/credentials \
  -v ~/.okta_aws_login_config:/root/.okta_aws_login_config \
  gimme-aws-creds"

With this config, you will be able to run further commands seamlessly!

Command Auto Completion

If you are using Bash or Zsh, you can add autocompletion for the gimme-aws-creds commandline options and profile names. To add the autocomplete config, add the following to the end of your .bashrc or .zshrc:

.bashrc

INSTALL_DIR=$(dirname $(which gimme-aws-creds))
source ${INSTALL_DIR}/gimme-aws-creds-autocomplete.sh"

.zshrc

INSTALL_DIR=$(dirname $(which gimme-aws-creds))
autoload bashcompinit
bashcompinit
source ${INSTALL_DIR}/gimme-aws-creds-autocomplete.sh

Using gimme-aws-creds with Okta Identity Engine

To use gimme-aws-creds with an Okta Identity Engine (OIE) domain, you must create a new OIDC Native Application and connect it to your AWS integration app(s).

The OIDC Native Application requires Grant Types Authorization Code, Device Authorization , and Token Exchange. These settings are in the Okta Admin UI at Applications > [the OIDC app] > General Settings > Grant type.

The pairing with the AWS Federation Application is achieved in the Fed app's Sign On Settings. These settings are in the Okta Admin UI at Applications > [the AWS Fed app] > Sign On. Make sure to set the Allowed Web SSO Client value to the Client ID of the OIDC Native Application. Repeat that setting for each AWS application you want to access with gimme-aws-creds.

Finally, set the Client ID in gimme-aws-creds (gimme-aws-creds --action-configure or update the client_id parameter in your config file)

When using gimme-aws-creds with an OIE domain, you will authenticate using your browser. Storing credentials in keychain or passing MFA codes through the command-line is NOT POSSIBLE.

Configuration

To set-up the configuration run:

gimme-aws-creds --action-configure

You can also set up different Okta configuration profiles, this is useful if you have multiple Okta accounts or environments you need credentials for. You can use the configuration wizard or run:

gimme-aws-creds --action-configure --profile profileName

A configuration wizard will prompt you to enter the necessary configuration parameters for the tool to run, the only one that is required is the okta_org_url. The configuration file is written to ~/.okta_aws_login_config, but you can change the location with the environment variable OKTA_CONFIG.

  • conf_profile - This sets the Okta configuration profile name, the default is DEFAULT.

  • okta_org_url - This is your Okta organization url, which is typically something like https://companyname.okta.com.

  • okta_auth_server - Okta API Authorization Server used for OpenID Connect authentication for gimme-creds-lambda

  • client_id - OAuth client ID for user authentication in Okta Identity Engine and gimme-creds-lambda in Okta "classic"

  • gimme_creds_server

    • URL for gimme-creds-lambda
    • 'internal' for direct interaction with the Okta APIs (OKTA_API_KEY environment variable required)
    • 'appurl' to set an aws application link url. This setting removes the need of an OKTA API key.
  • write_aws_creds - True or False - If True, the AWS credentials will be written to ~/.aws/credentials otherwise it will be written to stdout.

  • cred_profile - If writing to the AWS cred file, this sets the name of the AWS credential profile.

    • The reserved word role will use the name component of the role arn as the profile name. i.e. arn:aws:iam::123456789012:role/okta-1234-role becomes section [okta-1234-role] in the aws credentials file
    • The reserved word acc-role will use the name component of the role arn prepended with account number (or alias if resolve_aws_alias is set to y) to avoid collisions, i.e. arn:aws:iam::123456789012:role/okta-1234-role becomes section [123456789012-okta-1234-role], or if resolve_aws_alias [-okta-1234-role] in the aws credentials file
    • If set to default then the temp creds will be stored in the default profile
    • Note: if there are multiple roles, and default is selected it will be overwritten multiple times and last role wins. The same happens when role is selected and you have many accounts with the same role names. Consider using acc-role if this happens.
  • aws_appname - This is optional. The Okta AWS App name, which has the role you want to assume.

  • aws_rolename - This is optional. The ARN of the role you want temporary AWS credentials for. The reserved word 'all' can be used to get and store credentials for every role the user is permissioned for.

  • aws_default_duration = This is optional. Lifetime for temporary credentials, in seconds. Defaults to 1 hour (3600)

  • app_url - If using 'appurl' setting for gimme_creds_server, this sets the url to the aws application configured in Okta. It is typically something like https://something.okta[preview].com/home/amazon_aws/app_instance_id/something

  • okta_username - use this username to authenticate

  • preferred_mfa_type - automatically select a particular device when prompted for MFA:

    • push - Okta Verify App push or DUO push (depends on okta supplied provider type)
    • token:software:totp - OTP using the Okta Verify App
    • token:hardware - OTP using hardware like Yubikey
    • call - OTP via Voice call
    • sms - OTP via SMS message
    • email - OTP via email
    • web - DUO uses localhost webbrowser to support push|call|passcode
    • passcode - DUO uses OKTA_MFA_CODE or --mfa-code if set, or prompts user for passcode(OTP).
  • resolve_aws_alias - y or n. If yes, gimme-aws-creds will try to resolve AWS account ids with respective alias names (default: n). This option can also be set interactively in the command line using -r or --resolve parameter

  • include_path - (optional) Includes full role path to the role name in AWS credential profile name. (default: n). If y: <acct>-/some/path/administrator. If n: <acct>-administrator

  • remember_device - y or n. If yes, the MFA device will be remembered by Okta service for a limited time. This option can also be set interactively in the command line using -m or --remember-device

  • output_format - json , export or windows, determines default credential output format, can be also specified by --output-format FORMAT and -o FORMAT.

  • open-browser - Open the device authentication link in the default web browser automatically (Okta Identity Engine domains only)

Configuration File

The config file follows a configfile format. By default, it is located in $HOME/.okta_aws_login_config

Example file:

[myprofile]
client_id = myclient_id

Configurations can inherit from other configurations to share common configuration parameters.

[my-base-profile]
client_id = myclient_id
[myprofile]
inherits = my-base-profile
aws_rolename = my-role

Usage

If you are not using gimme-creds-lambda nor using appurl settings, make sure you set the OKTA_API_KEY environment variable.

After running --action-configure, just run gimme-aws-creds. You will be prompted for the necessary information.

$ ./gimme-aws-creds
Username: [email protected]
Password for [email protected]:
Authentication Success! Calling Gimme-Creds Server...
Pick an app:
[ 0 ] AWS Test Account
[ 1 ] AWS Prod Account
Selection: 1
Pick a role:
[ 0 ]: OktaAWSAdminRole
[ 1 ]: OktaAWSReadOnlyRole
Selection: 1
Multi-factor Authentication required.
Pick a factor:
[ 0 ] Okta Verify App: SmartPhone_IPhone: iPhone
[ 1 ] token:software:totp: [email protected]
Selection: 0
Okta Verify push sent...
export AWS_ACCESS_KEY_ID=AQWERTYUIOP
export AWS_SECRET_ACCESS_KEY=T!#$JFLOJlsoddop1029405-P

You can automate the environment variable creation by running $(gimme-aws-creds) on linux or gimme-aws-creds | iex using Windows Powershell

You can run a specific configuration profile with the --profile parameter:

./gimme-aws-creds --profile profileName

The username and password you are prompted for are the ones you login to Okta with. You can predefine your username by setting the OKTA_USERNAME environment variable or using the -u username parameter.

If you have not configured an Okta App or Role, you will prompted to select one.

If all goes well you will get your temporary AWS access, secret key and token, these will either be written to stdout or ~/.aws/credentials.

You can always run gimme-aws-creds --help for all the available options.

Alternatively, you can overwrite values in the config section with environment variables for instances where say you may want to change the duration of your token. A list of values of to change with environment variables are:

  • AWS_DEFAULT_DURATION - corresponds to aws_default_duration configuration
  • AWS_SHARED_CREDENTIALS_FILE - file to write credentials to, points to ~/.aws/credentials by default
  • GIMME_AWS_CREDS_CLIENT_ID - corresponds to client_id configuration
  • GIMME_AWS_CREDS_CRED_PROFILE - corresponds to cred_profile configuration
  • GIMME_AWS_CREDS_OUTPUT_FORMAT - corresponds to output_format configuration and --output-format CLI option
  • OKTA_AUTH_SERVER - corresponds to okta_auth_server configuration
  • OKTA_DEVICE_TOKEN - corresponds to device_token configuration, can be used in CI
  • OKTA_MFA_CODE - corresponds to --mfa-code CLI option
  • OKTA_PASSWORD - provides password during authentication, can be used in CI
  • OKTA_USERNAME - corresponds to okta_username configuration and --username CLI option

Example: GIMME_AWS_CREDS_CLIENT_ID='foobar' AWS_DEFAULT_DURATION=12345 gimme-aws-creds

For changing variables outside of this, you'd need to create a separate profile altogether with gimme-aws-creds --action-configure --profile profileName

Viewing Profiles

gimme-aws-creds --action-list-profiles will go to your okta config file and print out all profiles created and their settings.

Viewing roles

gimme-aws-creds --action-list-roles will print all available roles to STDOUT without retrieving their credentials.

Credential expiration time

Writing to the AWS credentials file will include the x_security_token_expires value in RFC3339 format. This allows tools to validate if the credentials are expiring or are expiring soon and warn the user or trigger a refresh.

Generate credentials as json

gimme-aws-creds -o json will print out credentials in JSON format - 1 entry per line

Store credentials from json

gimme-aws-creds --action-store-json-creds will store JSON formatted credentials from stdin to aws credentials file, eg: gimme-aws-creds -o json | gimme-aws-creds --action-store-json-creds. Data can be modified by scripts on the way.

Usage in python code

Configuration and interactions can be configured using gimme_aws_creds.ui, UserInterfaces support all kind of interactions within library including: asking for input, sys.argv and os.environ overrides.

import sys
import gimme_aws_creds.main
import gimme_aws_creds.ui

account_ids = sys.argv[1:] or [
  '123456789012',
  '120123456789',
]

pattern = "|".join(sorted(set(account_ids)))
pattern = '/:({}):/'.format(pattern)
ui = gimme_aws_creds.ui.CLIUserInterface(argv=[sys.argv[0], '--roles', pattern])
creds = gimme_aws_creds.main.GimmeAWSCreds(ui=ui)

# Print out all selected roles:
for role in creds.aws_selected_roles:
    print(role)

# Generate credentials overriding profile name with `okta-<account_id>`
for data in creds.iter_selected_aws_credentials():
    arn = data['role']['arn']
    account_id = None
    for piece in arn.split(':'):
        if len(piece) == 12 and piece.isdigit():
            account_id = piece
            break
  
    if account_id is None:
        raise ValueError("Didn't find aws_account_id (12 digits) in {}".format(arn))

    data['profile']['name'] = 'okta-{}'.format(account_id)
    creds.write_aws_creds_from_data(data)

MFA security keys support

gimme-aws-creds works both on FIDO1 enabled org and WebAuthN enabled org

Note that FIDO1 will probably be deprecated in the near future as standards moves forward to WebAuthN

WebAuthN support is available for usb security keys (gimme-aws-creds relies on the yubico fido2 lib).

To use your local machine as an authenticator, along with Touch ID or Windows Hello, if available, you must register a new authenticator via gimme-aws-creds, using:

gimme-aws-creds --action-setup-fido-authenticator

Then, you can choose the newly registered authenticator from the factors list.

Running Tests

You can run all the unit tests using pytest. Most of the tests are mocked.

pytest -vv tests

Maintenance

This project is maintained by Eric Pierce

Thanks and Credit

I came across okta_aws_login written by Joe Keegan, when I was searching for a CLI tool that generates AWS tokens via Okta. Unfortunately it hasn't been updated since 2015 and didn't seem to work with the current Okta version. But there was still some great code I was able to reuse under the MIT license for gimme-aws-creds. I have noted in the comments where I used his code, to make sure he receives proper credit.

Etc

okta-aws-cli

okta-aws-cli-assume-role

AWS - How to Implement Federated API and CLI Access Using SAML 2.0 and AD FS

Contributing

License

Gimme AWS Creds is released under the Apache License, Version 2.0

More Repositories

1

Willow

Willow is a powerful, yet lightweight logging library written in Swift.
Swift
1,334
star
2

Elevate

Elevate is a JSON parsing framework that leverages Swift to make parsing simple, reliable and composable.
Swift
612
star
3

koheesio

Python framework for building efficient data pipelines. It promotes modularity and collaboration, enabling the creation of complex pipelines from simple, reusable components.
Python
595
star
4

burnside

Fast and Reliable E2E Web Testing with only Javascript
JavaScript
381
star
5

wingtips

Wingtips is a distributed tracing solution for Java based on the Google Dapper paper.
Java
326
star
6

hal

hal provides an AWS Lambda Custom Runtime environment for your Haskell applications.
Haskell
235
star
7

brickflow

Pythonic Programming Framework to orchestrate jobs in Databricks Workflow
Python
187
star
8

spark-expectations

A Python Library to support running data quality rules while the spark job is running⚑
Python
161
star
9

SQift

Powerful Swift wrapper for SQLite
Swift
141
star
10

riposte

Riposte is a Netty-based microservice framework for rapid development of production-ready HTTP APIs.
Java
122
star
11

timeseries-generator

A library to generate synthetic time series data by easy-to-use factors and generator
Python
122
star
12

bartlett

A simple Jenkins command line client to serve your needs.
Haskell
81
star
13

cerberus-doc-site

Secure Property Store for Cloud Applications
CSS
81
star
14

aws-greengrass-core-sdk-rust

Provides an idiomatic Rust wrapper around the AWS Greengrass Core C SDK to more easily enable Greengrass native lambda functions in Rust.
Rust
71
star
15

cerberus

The Cerberus micro-service, a secure property store for cloud applications. It includes a REST API, authentication and encryption features, as well as a self-service web UI for users.
Java
62
star
16

referee

Referee is a UI for using Spinnaker Kayenta as a standalone service.
TypeScript
59
star
17

moirai

Libraries that can be used to determine if a feature should be exposed to a user.
Java
53
star
18

riposte-microservice-template

An example template for quickly creating a new Riposte microservice project.
Java
51
star
19

harbormaster

Harbormaster is a webhook handler for the Kubernetes API.
Go
42
star
20

fastbreak

Fastbreak is a simple Java 8 native circuit breaker supporting async future, blocking, and callback/manual modes.
Java
40
star
21

signal_analog

A troposphere-inspired library for programmatic, declarative definition and management of SignalFx Charts, Dashboards, and Detectors.
Python
39
star
22

backstopper

Backstopper is a framework-agnostic API error handling and (optional) model validation solution for Java 7 and up.
Java
38
star
23

react-virtualized-item-grid

React component for efficiently rendering a large, scrollable list of items in a series of wrapping rows
JavaScript
38
star
24

knockoff-factory

A library for generating fake data and populating database tables.
Python
34
star
25

pterradactyl

Pterradactyl is a library developed to abstract Terraform configuration from the Terraform environment setup.
Python
32
star
26

lambda-logger-node

A middleware logger that implements the MDC logging pattern for use in AWS NodeJS Lambdas.
TypeScript
29
star
27

lambda-router

JavaScript
23
star
28

bokor

Bokor is a simple, Record and Playback Mock Server written in Node.js, utilized for Service Virtualization.
JavaScript
23
star
29

piggyback

This tool allows you to tunnel SSH (using ProxyCommand) via HTTPS (with Squid Proxy). It is a python implementation of corkscrew, but over https (TLS) instead of http (plaintext).
Python
17
star
30

cerberus-node-client

Node client for interacting with a Cerberus backend. It can be used in Amazon EC2 instances and Amazon Lambdas.
JavaScript
16
star
31

cerberus-java-client

Java Client for Cerberus
Java
14
star
32

cerberus-lifecycle-cli

Command Line Interface for managing a Cerberus environment in AWS
Java
14
star
33

cerberus-python-client

Python Client for Cerberus
Python
13
star
34

cerberus-management-dashboard

A single page react app that is the self service web UI for administration of Safe Deposit Boxes, access control, and data.
HTML
13
star
35

tdd-training-cube

Papercraft cube used as training aid for Outside-In Test Driven Development
11
star
36

cerberus-serverless-components

A collection of AWS Serverless components for Cerberus
Java
11
star
37

cerberus-go-client

A Golang client for interacting with Cerberus, a secure property store for cloud applications.
Go
11
star
38

gradle-localstack

Gradle plugin for working with mock AWS endpoints using LocalStack.
Java
11
star
39

aws-thin-dynamo-node

A small, fast re-implementation of the AWS Dynamo DocumentClient
JavaScript
10
star
40

cerberus-archaius-client

An Archaius property provider implementation backed by Cerberus.
Java
9
star
41

epc-standards

Implementation of decoding GS1 EPC tags
Java
9
star
42

lambda-zipper

Zip up your node lambda code and production dependencies without pruning node_modules
JavaScript
9
star
43

java-vault-client

This is a java based Vault client library for communicating with Vault via HTTP.
Java
8
star
44

cerberus-cli

A CLI for the Cerberus API.
Go
8
star
45

cerberus-integration-tests

Groovy
8
star
46

cerberus-gateway-puppet-module

Puppet Module for installing Nginx and config downloader scripts
Python
8
star
47

Fleam

Scala
7
star
48

cerberus-consul-puppet-module

A Puppet module for installing Hashicorp's Consul as a service with customized start up scripts for Cerberus.
HTML
7
star
49

bluegreen-manager

Java
6
star
50

aws-thin-s3-node

A super-thin AWS S3 client
JavaScript
5
star
51

homebrew-nike

Homebrew formulas provided by Nike, Inc.
Ruby
5
star
52

sagerender

A library for configuring SageMaker pipelines using hierarchical configuration pattern.
Python
5
star
53

dynamo-arc

TypeScript
5
star
54

metrics-new-relic-insights

Reporter to send Dropwizard Metrics to New Relic Insights.
Java
5
star
55

cerberus-vault-puppet-module

A Puppet module for installing Hashicorp's Vault as a service with customized start up scripts for Cerberus.
HTML
5
star
56

cerberus-spring-boot-client

Spring Boot client for interacting with a Cerberus backend.
Java
4
star
57

aws-thin-ses-node

A super-thin AWS Simple Email Service client
JavaScript
3
star
58

dabber

Dabber is a Node CLI tool and AWS Lambda that helps you work with Dynamo.
JavaScript
3
star
59

actions-cerberus-secrets

Read secrets from Cerberus and make it as environment variables in GitHub Actions job so that it can be used in CICD process.
TypeScript
3
star
60

nike-inc.github.io

HTML
3
star
61

phiera

Python
2
star
62

Fawcett

A collection of Monocle lenses for navigating Amazon's API models.
Scala
2
star
63

cerberus-ruby-client

Ruby Client for Cerberus
Ruby
2
star
64

aws-scale

AWS Scaling Made Simple
JavaScript
2
star
65

gimme-a-cli

Gimme a CLI is a Java library for creating quick and easy command line interfaces (CLIs) using JCommander and Spring dependency injection.
Java
2
star
66

gradle-localdynamodb-plugin

XSLT
1
star
67

dynamo-butter

JavaScript
1
star
68

redwiggler

The composting worm. Composts your contract specification and tests and confirms that the contract specification is being followed.
Scala
1
star
69

gimme-a-cli-starter-project

Clone and modify this project to quickly create your own CLI based on the Gimme a CLI library.
Java
1
star