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"

saml2aws
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:

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

usage: saml2aws [<flags>] <command> [<args> ...]

A command line tool to help with SAML access to the AWS token service.

Flags:
      --help                   Show context-sensitive help (also try --help-long and --help-man).
      --version                Show application version.
      --verbose                Enable verbose logging
      --quiet                  silences logs
  -i, --provider=PROVIDER      This flag is obsolete. See: https://github.com/Versent/saml2aws#configuring-idp-accounts
      --config=CONFIG          Path/filename of saml2aws config file (env: SAML2AWS_CONFIGFILE)
  -a, --idp-account="default"  The name of the configured IDP account. (env: SAML2AWS_IDP_ACCOUNT)
      --idp-provider=IDP-PROVIDER
                               The configured IDP provider. (env: SAML2AWS_IDP_PROVIDER)
      --mfa=MFA                The name of the mfa. (env: SAML2AWS_MFA)
  -s, --skip-verify            Skip verification of server certificate. (env: SAML2AWS_SKIP_VERIFY)
      --url=URL                The URL of the SAML IDP server used to login. (env: SAML2AWS_URL)
      --username=USERNAME      The username used to login. (env: SAML2AWS_USERNAME)
      --password=PASSWORD      The password used to login. (env: SAML2AWS_PASSWORD)
      --mfa-token=MFA-TOKEN    The current MFA token (supported in Keycloak, ADFS, GoogleApps). (env: SAML2AWS_MFA_TOKEN)
      --role=ROLE              The ARN of the role to assume. (env: SAML2AWS_ROLE)
      --aws-urn=AWS-URN        The URN used by SAML when you login. (env: SAML2AWS_AWS_URN)
      --skip-prompt            Skip prompting for parameters during login.
      --session-duration=SESSION-DURATION
                               The duration of your AWS Session. (env: SAML2AWS_SESSION_DURATION)
      --disable-keychain       Do not use keychain at all. This will also disable Okta sessions & remembering MFA device. (env: SAML2AWS_DISABLE_KEYCHAIN)
  -r, --region=REGION          AWS region to use for API requests, e.g. us-east-1, us-gov-west-1, cn-north-1 (env: SAML2AWS_REGION)
      --prompter=PROMPTER      The prompter to use for user input (default, pinentry)

Commands:
  help [<command>...]
    Show help.


  configure [<flags>]
    Configure a new IDP account.

        --app-id=APP-ID            OneLogin app id required for SAML assertion. (env: ONELOGIN_APP_ID)
        --client-id=CLIENT-ID      OneLogin client id, used to generate API access token. (env: ONELOGIN_CLIENT_ID)
        --client-secret=CLIENT-SECRET
                                   OneLogin client secret, used to generate API access token. (env: ONELOGIN_CLIENT_SECRET)
        --subdomain=SUBDOMAIN      OneLogin subdomain of your company account. (env: ONELOGIN_SUBDOMAIN)
        --mfa-ip-address=MFA-IP-ADDRESS
                                   IP address whitelisting defined in OneLogin MFA policies. (env: ONELOGIN_MFA_IP_ADDRESS)
    -p, --profile=PROFILE          The AWS profile to save the temporary credentials. (env: SAML2AWS_PROFILE)
        --resource-id=RESOURCE-ID  F5APM SAML resource ID of your company account. (env: SAML2AWS_F5APM_RESOURCE_ID)
        --credentials-file=CREDENTIALS-FILE
                                   The file that will cache the credentials retrieved from AWS. When not specified, will use the default AWS credentials file location. (env: SAML2AWS_CREDENTIALS_FILE)
        --cache-saml               Caches the SAML response (env: SAML2AWS_CACHE_SAML)
        --cache-file=CACHE-FILE    The location of the SAML cache file (env: SAML2AWS_SAML_CACHE_FILE)
        --disable-sessions         Do not use Okta sessions. Uses Okta sessions by default. (env: SAML2AWS_OKTA_DISABLE_SESSIONS)
        --disable-remember-device  Do not remember Okta MFA device. Remembers MFA device by default. (env: SAML2AWS_OKTA_DISABLE_REMEMBER_DEVICE)

  login [<flags>]
    Login to a SAML 2.0 IDP and convert the SAML assertion to an STS token.

    -p, --profile=PROFILE        The AWS profile to save the temporary credentials. (env: SAML2AWS_PROFILE)
        --duo-mfa-option=DUO-MFA-OPTION
                                 The MFA option you want to use to authenticate with (supported providers: okta). (env: SAML2AWS_DUO_MFA_OPTION)
        --client-id=CLIENT-ID    OneLogin client id, used to generate API access token. (env: ONELOGIN_CLIENT_ID)
        --client-secret=CLIENT-SECRET
                                 OneLogin client secret, used to generate API access token. (env: ONELOGIN_CLIENT_SECRET)
        --mfa-ip-address=MFA-IP-ADDRESS
                                 IP address whitelisting defined in OneLogin MFA policies. (env: ONELOGIN_MFA_IP_ADDRESS)
        --force                  Refresh credentials even if not expired.
        --credential-process     Enables AWS Credential Process support by outputting credentials to STDOUT in a JSON message.
        --credentials-file=CREDENTIALS-FILE
                                 The file that will cache the credentials retrieved from AWS. When not specified, will use the default AWS credentials file location. (env: SAML2AWS_CREDENTIALS_FILE)
        --cache-saml             Caches the SAML response (env: SAML2AWS_CACHE_SAML)
        --cache-file=CACHE-FILE  The location of the SAML cache file (env: SAML2AWS_SAML_CACHE_FILE)
        --download-browser-driver  Automatically download browsers for Browser IDP. (env: SAML2AWS_AUTO_BROWSER_DOWNLOAD)
        --disable-sessions         Do not use Okta sessions. Uses Okta sessions by default. (env: SAML2AWS_OKTA_DISABLE_SESSIONS)
        --disable-remember-device  Do not remember Okta MFA device. Remembers MFA device by default. (env: SAML2AWS_OKTA_DISABLE_REMEMBER_DEVICE)

  exec [<flags>] [<command>...]
    Exec the supplied command with env vars from STS token.

    -p, --profile=PROFILE      The AWS profile to save the temporary credentials. (env: SAML2AWS_PROFILE)
        --exec-profile=EXEC-PROFILE
                               The AWS profile to utilize for command execution. Useful to allow the aws cli to perform secondary role assumption. (env: SAML2AWS_EXEC_PROFILE)
        --credentials-file=CREDENTIALS-FILE
                               The file that will cache the credentials retrieved from AWS. When not specified, will use the default AWS