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.14 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

On Fedora (RH CSB at least), the following libraries are required:

sudo dnf install krb5-devel python3-devel clang

These libraries should be pre-installed on MacOS but you may need to install them in other Linuxes.

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 -p python3.14

and upgrade an existing installation with:

uv tool upgrade rh-aws-saml-login -p python3.14

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.

Instead of selecting an account interactively, you can also provide the account name (including the role) as argument:

rh-aws-saml-login <ACCOUNT_NAME>

The <ACCOUNT_NAME> parameter supports several formats for flexible account and role specification:

• Account name only: Use the AWS account name or alias (e.g., my-shiny-aws-account, app-sre-stage)
• Account with specific role: Specify both account and role using the format <ACCOUNT>/<ROLE> (e.g., my-shiny-aws-account/PowerUserAccess, app-sre/1234-Admin)
• Current already logged-in account: Use . to automatically use the value from the $AWS_ACCOUNT_NAME environment variable

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]

The <ACCOUNT_NAME> parameter follows the same format as described in the interactive mode section above (account name, account/role, environment variable).

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! ❤️

Another non-interactive alternative is to use the --output option to retrieve the AWS credentials in a specific format. For example, to get the credentials in shell environment format:

$ rh-aws-saml-login --output env <ACCOUNT_NAME>
AWS_ACCOUNT_NAME=<ACCOUNT_NAME>
...
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

The <ACCOUNT_NAME> parameter supports the same formats as described above.

Feel free to import those environment variables in your shell or script. E.g.

$ export $(rh-aws-saml-login --output env <ACCOUNT_NAME>)
$ aws s3 ls
...

You can also use the shared_credentials output format to write the credentials to a file and set the AWS_SHARED_CREDENTIALS_FILE environment variable:

$ export $(rh-aws-saml-login --output shared_credentials <ACCOUNT_NAME>)
$ aws s3 ls
...

This writes the credentials to a temporary file in the standard AWS shared credentials format and outputs the path via AWS_SHARED_CREDENTIALS_FILE.

Environment Variables

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

• AWS_ACCOUNT_NAME: The name/alias of the AWS account
• AWS_ACCOUNT_UID: The uid 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

• Library usage, e.g. in Jupyter notebooks

• 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.

Library Usage

rh-aws-saml-login is primarily designed to be used as CLI tool. However, it can also be used as library in any Python application or script, e.g., in Jupyter notebooks:

import boto3

from rh_aws_saml_login import get_aws_credentials

# Get AWS credentials
aws_credentials = get_aws_credentials(account_name="my-shiny-aws-account-name")

# Use the credentials with boto3
s3_client = boto3.client(
    "s3",
    aws_access_key_id=credentials.access_key,
    aws_secret_access_key=credentials.secret_key,
    aws_session_token=credentials.session_token,
    region_name=credentials.region,
)

s3_client.list_buckets()

Development

rh-aws-saml-login uses uv for project and dependency management. Follow the uv installation instructions to install it in on your local machine.

Setup

1. Fork the repository and clone it
2. Create a Python development environment with make dev-venv
3. Activate the virtual environment with source .venv/bin/activate
4. Happy coding!

Release

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