Skip to content

Latest commit

 

History

History
184 lines (112 loc) · 8.22 KB

README.md

File metadata and controls

184 lines (112 loc) · 8.22 KB
Raw

Crate version linux-release macos-release windows-release License

"Your trusty tool for retrieving AWS credentials securely via SAML"

Quickstart

$ crowbar profiles add <profile-name> -u <my-username> -p <idp> --url <idp-app-url>
$ AWS_PROFILE=<profile-name> aws ec2 describe-instances
$ crowbar exec <profile-name> -- aws ec2 describe-instances

It'll ask you for your IdP's password and to verify your credential request with MFA. The credentials you enter are cached securely in your OS keystore.

Note: Hover over the app that's associated with your AWS account in your IdP's dashboard and copy its link.

Supported IdPs

  • Okta, with MFA factors Push, TOTP, SMS
    • Note: the MFA selection screen will present all available methods, however, only Push, TOTP and SMS are implemented at this point
  • JumpCloud, with MFA factor TOTP (Duo is not supported for now)

Planned

  • ADFS

Installation

macOS

You can install crowbar via Homebrew:

$ brew install moritzheiber/tap/crowbar

Windows

You can install crowbar via Chocolatey:

$ choco install crowbar

Binary releases for all supported operating systems

Just download the latest release and put it somewhere in your PATH. On Linux you'll have to have DBus installed (e.g. the libdbus-1-3 package on Ubuntu), but most distributions are shipping with DBus pre-installed anyway.

Compiling your own binary

Prerequisites

All environments need a stable version fo Rust to compile (it might also compile with nightly, but no guarantees). You can use rustup to install it.

Linux

You have to have the DBus development headers (e.g. libdbus-1-dev on Ubuntu) installed to compile the crate.

macOS

A recent version of Apple's XCode.

Windows

Rust needs a C++ build environment, which rustup will help you install and configure.

Compiling the crate

$ cargo install crowbar

If you have cargo's binary location in your PATH you should be able to run crowbar afterwards.

User guide

Prerequisites

For crowbar to be useful you have to install the AWS CLI.

Adding a profile

You can use crowbar profiles to manage profiles:

$ crowbar profiles add my-profile -u my-username -p okta --url "https://example.okta.com/example/saml"

To get your respective URL, hover over the app that's associated with your AWS account in your Okta dashboard and copy its link. You can strip away the ?fromHome=true part at the end. Adding the profile using crowbar will also configure the AWS CLI appropriately.

You can also use crowbar profiles delete <profile-name> to remove profiles and crowbar profiles list to get and overview of all available profiles.

Usage

Via AWS profiles

You can now run any command that requires AWS credentials while having the profile name exported in your shell:

$ AWS_PROFILE=my-profile aws ec2 --region us-east-1 describe-instances

or, on Windows:

$ set AWS_PROFILE=my-profile
$ aws ec2 --region us-east-1 describe-instances

This will automatically authenticate you with your IdP, ask for your MFA, if needed, and the present you with a selection of roles you're able to assume to get temporary AWS credentials. If there is just one role to assume crowbar will skip the selection and directly use it for fetching credentials.

Via an execution environment

You can have crowbar expose your AWS credentials to a process you want to run via environment variables:

$ crowbar exec <my-profile> -- <your-command-here>

For example

$ crowbar exec super-duper-profile - aws sts get-caller-identity
{
    "Account": "1234567890",
    "UserId": "Some-User:[email protected]",
    "Arn": "arn:aws:sts::1234567890:assumed-role/SuperDuperUser/[email protected]"
}

More options

You can obviously also run crowbar directly:

$ crowbar creds [PROFILE]

for example:

$ crowbar creds my-profile

For further information please consult crowbar --help or crowbar creds --help.

FAQ

Why does the credential_process command added to the CLI configuration look so weird?

The sh workaround is needed because the AWS CLI captures stderr without forwarding it to the child process. crowbar uses stderr to ask for your IdP password, your selection of MFA and, if there are more than one, your selection of role to assume. There's an open issue and several PRs. If you want to see this issue solved please show them some love.

History

Crowbar is designed to securely retrieve temporary AWS credentials using its STS service, utilizing SAML as a means for authenticating and authorizing requests. Its unique feature is that it doesn't write any sensitive data (passwords, session tokens, security keys) to disk, but rather stores them in the operating system's keystore which requires the user's consent to have them retrieved from.

It is meant to be used with the AWS CLI's credential_process capabilities, to provide a seamless experience when it comes to using AWS resources on the command line.

Crowbar is a fork of oktaws, written by Jonathan Morley, whereas the main differentiating factors for forking the original project were that it does write credentials to disk and it focuses solely on Okta. Both of these are not the intentions of this project.

For the time being, only Okta is supported as an IdP, with other providers (ADFS being prioritized the highest) to be added as soon as capacity allows.

Crowbar's name was formerly used by an AWS Lambda runtime for Rust emulating a Python library prior to native runtime support in Lambda. Crowbar 0.1.x and 0.2.x users should move to the native runtime.

TODO

There are a some things still left to do:

Future

  • Add an exec mode for tools that don't support the AWS SharedProfileCredentials provider
  • Support for at least ADFS: As stated before, crowbar is supposed to be a general purpose tool, not just focusing on Okta. ADFS support is mandatory. However, other providers should be considered as well. The code will probably need major re-architecting for this to happen.
  • Support for WebAuthn: At least Okta supports WebAuthn on the command line and this tool should support it too. This largely depends on the maturity of the Rust ecosystem around handling FIDO2 security keys though. CTAP2 protocol support is mandatory to work with Okta.
  • Focus on cross-platform support: I'm running Linux, all of the code being tested on Linux. I want crowbar to be usable on all major operating systems (Linux, macOS, Windows).

Cosmetic

  • Cleaning up the code: This is my first major Rust project, and it shows. The code needs a few other pair of eyes with some more Rust experience.
  • Implement some retry logic for MFA challenges? At least the Okta API allows for it in certain conditions
  • Error handling is all over the place, including random panic! statements and inconsistent logger use. The project needs a proper error handling routine.
  • Use a role directly if only a single role is provided in the SAML assertion
  • More consistent UI experience (maybe start looking at other libraries?)