BMX

BMX provides API access to your AWS accounts using existing Okta credentials. Instead of long-term IAM user access keys, BMX creates short-term AWS STS tokens using your Okta identity.

Installation

Download the appropriate binary from the releases page. For D2Lers, visit bmx.d2l.dev for installation.

Usage

Flags

BMX command line flags (a.k.a. "options", i.e. command line arguments that start with --) are optional unless otherwise stated. If not provided, BMX will prompt you to input the data interactively as needed.

Global configuration

To set up the BMX global configuration file at ~/.bmx/config, run

bmx configure --org <okta_organization> --user <okta_username>

Okta user sessions are automatically cached when this configuration file is present. As such, it is not recommended to run bmx configure or create this configuration file manually on a machine with shared access.

AWS credentials as environment variables

To set up AWS credentials as environment variables, in PowerShell, run

bmx print --account <aws_account_name> --role <aws_role_name> | iex

or in Bash/sh/Zsh, run

eval "$(bmx print --account <aws_account_name> --role <aws_role_name>)"

Static AWS credentials in a profile

To set up AWS credentials in a profile, run

bmx write --account <aws_account_name> --role <aws_role_name> --profile <aws_profile>

You can use your profile by configuring any supporting AWS client. For example, for the AWS CLI:

aws sts get-caller-identity --profile <aws_profile>

Provide dynamic AWS credentials to a profile

To set up an AWS profile that sources credentials from BMX on-the-fly, run

bmx write --use-credential-process --account <aws_account_name> --role <aws_role_name> --profile <aws_profile>

(Note: the --use-credential-process flag must be provided on the command line.)

AWS clients using this profile will call BMX to obtain credentials on-the-fly. BMX caches the credentials it provides, and will automatically refresh them as needed, as long as it has a valid Okta session.

This use case is only supported when you have set up the BMX global configuration file.

Refresh Okta session

To force refresh your Okta session, run

bmx login

Passwordless authentication

If your Okta organization is configured for Desktop Single Sign-on and your computer is connected and signed in to the Active Directory network, BMX will authenticate you to Okta without prompting for password input.

This is currently only supported on Windows. Support for macOS is pending.

Local configuration

You can create local configuration files named .bmx, where you can define default values for most BMX flags. A local configuration file takes effect for BMX commands executed in the current directory or its subdirectories. Its values override the values in the global configuration file.

Here's an example of a typical .bmx file:

account = <aws_account_name>
role = <aws_role_name>
duration = 15