Quickstart

elhaz can be used locally to manage automatically refreshed temporary AWS credentials for multiple IAM roles simultaneously. Those credentials can be passed to AWS profiles, SDKs, CLIs, scripts, processes, local developer environments, and tools in a variety of creative ways.

To quickly get started using elhaz, follow this basic guide.

For more detailed information on the concepts and architecture behind elhaz, see the Concepts documentation.

For technical information on all of the available commands and options, see the CLI documentation.

Initialization

Tip

To see all of the available commands and options, use --help on any command.

In order to use elhaz, you must set up at least one “config”.

A config represents a set of parameters that boto3-refresh-session uses in order to initialize an AWS session which automatically refreshes temporary AWS credentials.

To create a config, run this:

elhaz config add

elhaz config add will present you with a set of interactive prompts which help you create the config piece by piece.

Tip

The only required config parameter is RoleArn in the AssumeRole object. All other parameters are completely optional.

Next, initialize the daemon, like so:

elhaz daemon start

In order to use the config you just created, you must initialize the AWS session for your config and add it into the daemon’s session cache, like this:

elhaz daemon add -n <your config name>

Commands

Export the automatically refreshed temporary AWS credenitals from your config to stdout.

elhaz export -n <your config name>

Or export env vars.

elhaz export -n <your config name> -f env

Or export the credentials in a format compatible with credential_process in your AWS profile.

[profile my-role]
credential_process = elhaz export -n <your config name> -f credential-process

You may also execute a one-off AWS CLI command using the config’s credentials.

elhaz exec -n <your config name> --- aws s3 ls

Or initialize a shell and run as many AWS commands as you want for however long you like.

Tip

The shell can be terminated by entering exit.

elhaz shell -n <your config name>
aws s3 ls
aws s3 cp s3://my-bucket/my-file.txt .
...

If you forget who you are, fret not.

elhaz whoami -n <your config name>

You can also read the logs from the daemon.

elhaz daemon logs

You can also list all active AWS sessions in the daemon’s session cache.

elhaz daemon list

IAM Identity Center (SSO)

If you haven’t already locally configured AWS IAM Identity Center (SSO), do so like this:

aws configure sso

Follow the prompts to complete the configuration according to your IAM Identity Center setup.

Next, login to SSO like this:

aws sso login

Depending on your SSO configuration, you may be prompted to open a browser and authenticate against your Identity Center account in order to complete the login. This process may require OTP’s, may employ Okta/Google Workspace, etc. Whatever the exact process, complete it like you normally would in order to authenticate yourself against IAM Identity Center. Once completed, you may now begin using elhaz to acquire temporary credentials for assumed roles.

Don’t forget to logout when you’re done with your SSO session, like this:

aws sso logout

Shutdown

When you’re done working, stop the daemon.

elhaz daemon stop