rh-aws-saml-login

A CLI tool that allows you to log in and retrieve AWS temporary credentials using Red Hat SAML IDP.

Pre-requisites

• Python 3.11 or later
• Connected to Red Hat VPN
• A Red Hat managed computer (Kerberos must be installed and configured) and you are logged in with your Red Hat account

How it works

The rh-aws-saml-login CLI is a tool that simplifies the process of logging into an AWS account via Red Hat SSO. It retrieves a SAML token from the Red Hat SSO server, then fetches and parses the AWS SSO login page to present you with a list of all available accounts and their respective roles. You can then choose your desired account and role, and rh-aws-saml-login uses the SAML token to generate temporary AWS role credentials. Finally, it spawns a new shell with the necessary AWS_ environment variables already set up, so you can immediately use the aws CLI without any further configuration.

Installation

Prerequisites

rh-aws-saml-login needs the krb5 library to work. On most system, e.g., MacOS, this library is already installed. On CSB Fedora, you need to install the Kerberos development package:

sudo dnf install krb5-devel

Recommended Installation Method

The recommended way to install rh-aws-saml-login is to use the uv tool:

uv tool install rh-aws-saml-login

and upgrade an existing installation with:

uv tool upgrade rh-aws-saml-login

Alternative Installation Methods

You can install this library from PyPI with pip:

python3 -m pip install rh-aws-saml-login

or install it with pipx:

pipx install rh-aws-saml-login

and upgrade an existing installation with:

pipx upgrade rh-aws-saml-login

Usage

Interactive mode

Just run rh-aws-saml-login to start the interactive mode. It will list all available AWS accounts and roles, and you can choose the one you want to log in to:

$ rh-aws-saml-login

         __                                                         __      __            _
   _____/ /_        ____ __      _______      _________ _____ ___  / /     / /___  ____ _(_)___
  / ___/ __ \______/ __ `/ | /| / / ___/_____/ ___/ __ `/ __ `__ \/ /_____/ / __ \/ __ `/ / __ \
 / /  / / / /_____/ /_/ /| |/ |/ (__  )_____(__  ) /_/ / / / / / / /_____/ / /_/ / /_/ / / / / /
/_/  /_/ /_/      \__,_/ |__/|__/____/     /____/\__,_/_/ /_/ /_/_/     /_/\____/\__, /_/_/ /_/
                                                                                /____/

✅ Test for a valid Kerberos ticket ...
✅ Getting SAML token ...
✅ Getting AWS accounts ...
✅ Getting temporary AWS credentials ...

Spawning a new shell. Use exit or CTRL+d to leave it!

🤓 app-sre
🚀 1234567890-app-sre
⌛ 59 minutes from now (2024-10-07 11:16:54+02:00)

$ aws s3 ls
...

This spawns a new shell with all required AWS environment variables set. See the Environment Variables section for more information.

Non-interactive mode

Instead of running the interactive mode, you can also use rh-aws-saml-login to run any arbitrary command with the AWS environment variables set:

rh-aws-saml-login <ACCOUNT_NAME> -- <COMMAND> [ARGUMENTS]

For example:

$ rh-aws-saml-login app-sre-stage -- aws s3 ls

         __                                                         __      __            _
   _____/ /_        ____ __      _______      _________ _____ ___  / /     / /___  ____ _(_)___
  / ___/ __ \______/ __ `/ | /| / / ___/_____/ ___/ __ `/ __ `__ \/ /_____/ / __ \/ __ `/ / __ \
 / /  / / / /_____/ /_/ /| |/ |/ (__  )_____(__  ) /_/ / / / / / / /_____/ / /_/ / /_/ / / / / /
/_/  /_/ /_/      \__,_/ |__/|__/____/     /____/\__,_/_/ /_/ /_/_/     /_/\____/\__, /_/_/ /_/
                                                                                /____/

✅ Test for a valid Kerberos ticket ...
✅ Getting SAML token ...
✅ Getting AWS accounts ...
✅ Getting temporary AWS credentials ...
2022-05-17 13:48:49 bucket-name-stage
2022-12-13 13:21:02 bucket-name-tfstate-stage
Thank you for using rh-aws-saml-login. 🙇‍♂️ Have a great day ahead! ❤️

Environment Variables

rh-aws-saml-login sets the following environment variables:

• AWS_ACCOUNT_NAME: The name/alias of the AWS account
• AWS_ROLE_NAME: The name of the role
• AWS_ROLE_ARN: The ARN of the role
• AWS_ACCESS_KEY_ID: The access key used by the AWS CLI
• AWS_SECRET_ACCESS_KEY: The secret access key used by the AWS CLI
• AWS_SESSION_TOKEN: The session token used by the AWS CLI
• AWS_REGION: The default region used by the AWS CLI

Features

rh-aws-saml-login currently provides the following features (get help with -h or --help):

• No configuration needed

• Uses Kerberos authentication

• Open the AWS web console for an account with the --console option

• Assume a role with the --assume-uid option

• Shell auto-completion (bash, zsh, and fish) including AWS account names

• Integrates nicely with the starship

   [env_var.AWS_ACCOUNT_NAME]
   format = "$symbol$style [$env_value]($style) "
   style = "cyan"
   symbol = "🚀"

Assume Role

AWS allows to switch to another AWS account via the assume role feature. rh-aws-saml-login supports this feature with the --assume-uid and --assume-role options. This options allows you to switch to another AWS account by providing the account ID and the role name:

rh-aws-saml-login --assume-uid <TARGET_AWS_ACCOUNT_UID> --assume-role <ROLE_NAME> <PARENT_ACCOUNT>

For example:

rh-aws-saml-login --assume-uid 1234567890 rh-payer-account

Console

Instead of spawning a new shell, you can open the AWS web console for an account with the --console and --console-serice option:

rh-aws-saml-login --console --console-service <SERVICE> <ACCOUNT_NAME>

For example:

rh-aws-saml-login --console --console-service s3 app-sre

Opens the AWS web console for the s3 service in the app-sre account.

Development

• Update CHANGELOG.md with the new version number and date
• Bump the version number in pyproject.toml