saml2aws

saml2aws

CLI tool which enables you to login and retrieve AWS temporary credentials using with ADFS or PingFederate Identity Providers.

This is based on python code from How to Implement a General Solution for Federated API/CLI Access Using SAML 2.0.

The process goes something like this:

• Setup an account alias, either using the default or given a name
• Prompt user for credentials
• Log in to Identity Provider using form based authentication
• Build a SAML assertion containing AWS roles
• Optionally cache the SAML assertion (the cache is not encrypted)
• Exchange the role and SAML assertion with AWS STS service to get a temporary set of credentials
• Save these credentials to an aws profile named "saml"

Table of Contents

• saml2aws
  • Table of Contents
  • Requirements
  • Caveats
  • Install
    • macOS
    • Windows
    • Linux
      • Ubuntu
      • Other
      • Using Make
      • Arch Linux and its derivatives
      • Void Linux
  • Autocomplete
    • Bash
    • Zsh
  • Dependency Setup
  • Usage
    • saml2aws script
    • saml2aws exec
    • Configuring IDP Accounts
  • Example
  • Advanced Configuration
    • Windows Subsystem Linux (WSL) Configuration
      • Option 1: Disable Keychain
      • Option 2: Configure Pass to be the default keyring
    • Configuring Multiple Accounts
      • Dev Account Setup
      • Test Account Setup
  • Advanced Configuration (Multiple AWS account access but SAML authenticate against a single 'SSO' AWS account)
  • Advanced Configuration - additional parameters
  • Building
    • macOS
    • Linux
  • Environment vars
• Dependencies
• Releasing
• Debugging Issues with IDPs
• Using saml2aws as credential process
• Caching the saml2aws SAML assertion for immediate reuse
• Okta Sessions
• License

Requirements

• One of the supported Identity Providers
  • ADFS (2.x or 3.x)
  • AzureAD
  • PingFederate + PingId
  • Okta
  • KeyCloak + (TOTP)
  • Google Apps
  • Shibboleth
  • F5APM
  • Akamai
  • OneLogin
  • NetIQ
  • Browser, this uses playwright-go to run a sandbox chromium window.
  • Auth0 NOTE: Currently, MFA not supported
  • JumpCloud
• AWS SAML Provider configured

Caveats

Aside from Okta, most of the providers in this project are using screen scraping to log users into SAML, this isn't ideal and hopefully vendors make this easier in the future. In addition to this there are some things you need to know:

1. AWS defaults to session tokens being issued with a duration of up to 3600 seconds (1 hour), this can now be configured as per Enable Federated API Access to your AWS Resources for up to 12 hours Using IAM Roles and --session-duration flag.
2. Every SAML provider is different, the login process, MFA support is pluggable and therefore some work may be needed to integrate with your identity server
3. By default, the temporary security credentials returned do not support SigV4A. If you need SigV4A support then you must set the AWS_STS_REGIONAL_ENDPOINTS enviornment variable to regional when calling saml2aws so that aws-sdk-go uses a regional STS endpoint instead of the global one. See the note at the bottom of Signing AWS API requests and AWS STS Regionalized endpoints.

Install

macOS

If you're on macOS you can install saml2aws using homebrew!

brew install saml2aws
saml2aws --version

Windows

If you're on Windows you can install saml2aws using chocolatey!

choco install saml2aws
saml2aws --version

Linux

While brew is available for Linux you can also run the following without using a package manager.

Ubuntu

Some users of Ubuntu have reported issue with the Others Install instruction and reported the following to work (may required using sudo command like for the "mv" function)

CURRENT_VERSION=$(curl -Ls https://api.github.com/repos/Versent/saml2aws/releases/latest | grep 'tag_name' | cut -d'v' -f2 | cut -d'"' -f1)
wget https://github.com/Versent/saml2aws/releases/download/v${CURRENT_VERSION}/saml2aws_${CURRENT_VERSION}_linux_amd64.tar.gz
tar -xzvf saml2aws_${CURRENT_VERSION}_linux_amd64.tar.gz
mv saml2aws /usr/local/bin/
chmod u+x /usr/local/bin/saml2aws
saml2aws --version

For U2F support, replace wget line above with wget https://github.com/Versent/saml2aws/releases/download/v${CURRENT_VERSION}/saml2aws-u2f_${CURRENT_VERSION}_linux_amd64.tar.gz

Other

mkdir -p ~/.local/bin
CURRENT_VERSION=$(curl -Ls https://api.github.com/repos/Versent/saml2aws/releases/latest | grep 'tag_name' | cut -d'v' -f2 | cut -d'"' -f1)
wget -c "https://github.com/Versent/saml2aws/releases/download/v${CURRENT_VERSION}/saml2aws_${CURRENT_VERSION}_linux_amd64.tar.gz" -O - | tar -xzv -C ~/.local/bin
chmod u+x ~/.local/bin/saml2aws
hash -r
saml2aws --version

If saml2aws --version does not work as intended, you may need to update your terminal configuration file (like ~/.bashrc, ~/.profile, ~/.zshrc) to include export PATH="$PATH:$HOME/.local/bin/" at the end of the file.

For U2F support, replace wget line above with wget -c "https://github.com/Versent/saml2aws/releases/download/v${CURRENT_VERSION}/saml2aws-u2f_${CURRENT_VERSION}_linux_amd64.tar.gz" -O - | tar -xzv -C ~/.local/bin

Using Make

You will need Go Tools (you can check your package maintainer as well) installed and the Go Lint tool

Clone this repo to your $GOPATH/src directory

Now you can install by running

make
make install

Arch Linux and its derivatives

The saml2aws tool is available in AUR (saml2aws-bin), so you can install it using an available AUR helper:

• Manjaro: $ pamac build saml2aws-bin

Void Linux

If you are on Void Linux you can use xbps to install the saml2aws package!

xbps-install saml2aws

Autocomplete

saml2aws can generate completion scripts.

Bash

Add the following line to your .bash_profile (or equivalent):

eval "$(saml2aws --completion-script-bash)"

Zsh

Add the following line to your .zshrc (or equivalent):

eval "$(saml2aws --completion-script-zsh)"

Dependency Setup

Install the AWS CLI see, in our case we are using homebrew on macOS.

brew install awscli

Usage

…

saml2aws script

If the script sub-command is called, saml2aws will output the following temporary security credentials:

export AWS_ACCESS_KEY_ID="ASIAI....UOCA"
export AWS_SECRET_ACCESS_KEY="DuH...G1d"
export AWS_SESSION_TOKEN="AQ...1BQ=="
export AWS_SECURITY_TOKEN="AQ...1BQ=="
export AWS_CREDENTIAL_EXPIRATION="2016-09-04T38:27:00Z00:00"
SAML2AWS_PROFILE=saml

Powershell, sh and fish shells are supported as well. Env is useful for all AWS SDK compatible tools that can source an env file. It is a powerful combo with docker and the --env-file parameter.

If you use eval $(saml2aws script) frequently, you may want to create a alias for it:

zsh:

alias s2a="function(){eval $( $(command saml2aws) script --shell=bash --profile=$@);}"

bash:

function s2a { eval $( $(which saml2aws) script --shell=bash --profile=$@); }

env:

docker run -ti --env-file <(saml2aws script --shell=env) amazon/aws-cli s3 ls

saml2aws exec

If the exec sub-command is called, saml2aws will execute the command given as an argument: By default saml2aws will execute the command with temp credentials generated via saml2aws login.

The --exec-profile flag allows for a command to execute using an aws profile which may have chained "assume role" actions. (via 'source_profile' in ~/.aws/config)

options:
--exec-profile           Execute the given command utilizing a specific profile from your ~/.aws/config file

Configuring IDP Accounts

This is the new way of adding IDP provider accounts, it enables you to have named accounts with whatever settings you like and supports having one default account which is used if you omit the account flag. This replaces the --provider flag and old configuration file in 1.x.

To add a default IdP account to saml2aws just run the following command and follow the prompts.

$ saml2aws configure
? Please choose a provider: Ping
? AWS Profile myaccount

? URL https://example.com
? Username [email protected]

? Password
No password supplied

account {
  URL: https://example.com
  Username: [email protected]
  Provider: Ping
  MFA: Auto
  SkipVerify: false
  AmazonWebservicesURN: urn:amazon:webservices
  SessionDuration: 3600
  Profile: myaccount
  Region: us-east-1
}

Configuration saved for IDP account: default

Then to login using this account.

saml2aws login

You can also add named accounts, below is an example where I am setting up an account under the wolfeidau alias, again just follow the prompts.

saml2aws configure -a wolfeidau

You can also configure the account alias without prompts.

saml2aws configure -a wolfeidau --idp-provider KeyCloak --username [email protected] -r cn-north-1  \
  --url https://keycloak.wolfe.id.au/auth/realms/master/protocol/saml/clients/amazon-aws --skip-prompt

Then your ready to use saml2aws.

Example

Log into a service (without MFA).

…

Log into a service (with MFA).

…

Advanced Configuration

Windows Subsystem Linux (WSL) Configuration

If you are using WSL1 or WSL2, you might get the following error when attempting to save the credentials into the keychain

 No such interface “org.freedesktop.DBus.Properties” on object at path /

This happens because the preferred keyring back-end - uses the gnome-keyring by default - which requires X11 - and if you are not