aws-adfs 2.11.2

Description:

awsadfs 2.11.2

aws-adfs



The project provides command line tool - aws-adfs to ease AWS cli authentication against ADFS (multi factor authentication with active directory).
aws-adfs command line tool


allows you to re-login to STS without entering credentials for an extended period of time, without having to store the user's actual credentials. It also lets an organization control the period in which a user can re-login to STS without entering credentials, by altering the ADFS session lifetime.


supports automation tools like ansible by providing security token in AWS_SESSION_TOKEN/AWS_SECURITY_TOKEN environment variables.


supports using Security Support Provider Interface (SSPI) on Windows OS.


MFA integration
aws-adfs integrates with:

duo security MFA provider with support for:

Duo mobile application push (verified by code or not) using the Duo Push authentication method.
Phone call using the Phone Call authentication method.
OTP 6 digit codes generated by Duo Mobile application, and hardware tokens (e.g. RSA or Yubikey) using the Passcode authentication method.
FIDO U2F (CTAP1) / FIDO2 (CTAP2) hardware authenticators using the WebAuthn Security Key authentication method.


Symantec VIP MFA provider
RSA SecurID MFA provider
Azure AD MFA with support for:

Microsoft Authenticator app
OTP 6 digit codes
SMS codes
Phone call


Silverfort MFA provider
Thales/SafeNet Trusted Access MFA provider

OTP 6 digit codes generated by MobilePASS+ Authenticator app



Setup Dependencies

build-essential (provides C/C++ compilers)
python3 >= 3.7 <4.0
python3-dev
libkrb5-dev
libxml2-dev

Installation


user local installation with pipx
pipx install aws-adfs



user local installation with pip
pip3 install --user aws-adfs

Please note, that you need to add $HOME/.local/bin to your PATH


system wide installation
sudo pip3 install aws-adfs



virtualenvs
virtualenv aws-adfs
source aws-adfs/bin/activate
pip install aws-adfs
...
...
deactivate



Windows 10

Install latest supported Visual C++ downloads from Microsoft for Visual Studio 2015, 2017 and 2019:

https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads
https://aka.ms/vs/16/release/vc_redist.x64.exe


Install Python 3.7 from Microsoft Store:

https://www.microsoft.com/en-us/p/python-37/9nj46sx7x90p


Start PowerShell as Administrator
Go to C:\Program Files:
C:
cd 'C:\Program Files\'


Create virtual env:
python3 -m venv aws-adfs


Install aws-adfs:
& 'C:\Program Files\aws-adfs\Scripts\pip' install aws-adfs


Run it:
& 'C:\Program Files\aws-adfs\Scripts\aws-adfs' login --adfs-host=your-adfs-hostname





Examples of usage
aws-adfs


login to your adfs host with disabled ssl verification on aws cli profile: adfs
aws-adfs login --adfs-host=your-adfs-hostname --no-ssl-verification

and verification
aws --profile=adfs s3 ls



login to your adfs host with disabled ssl verification on specified aws cli profile: specified-profile
aws-adfs login --profile=specified-profile --adfs-host=your-adfs-hostname --no-ssl-verification

and verification
aws --profile=specified-profile s3 ls



login to your adfs host and fetch roles for AWS GovCloud (US)
aws-adfs login --adfs-host=your-adfs-hostname --provider-id urn:amazon:webservices:govcloud --region us-gov-west-1

and verification
aws s3 ls



login to your adfs host within ansible playbook
---
- name: "Auth sts aws"
command: "aws-adfs login --adfs-host sts.example.com --env --stdout --role-arn arn:aws:iam::000123456789:role/ADMIN"
register: sts_result
environment:
- username: "{{ ansible_user }}@example.com"
- password: "{{ ansible_ssh_pass }}"

- name: "Set sts facts"
set_fact:
sts: "{{ sts_result.stdout | from_json }}"

- name: "List s3 Buckets"
aws_s3_bucket_facts:
aws_access_key: "{{ sts.AccessKeyId }}"
aws_secret_key: "{{ sts.SecretAccessKey }}"
security_token: "{{ sts.SessionToken }}"
region: "us-east-1"
register: buckets

- name: "Print Buckets"
debug:
var: buckets



login to your adfs host by passing username and password credentials via a file
aws-adfs login --adfs-host=your-adfs-hostname --authfile=/path/and/file/name

Auth file should be in format of
[profile_name]
username = your_username
password = your_password



.aws/config profile for automatically refreshing credentials
[profile example-role-ue1]
credential_process=aws-adfs login --region=us-east-1 --role-arn=arn:aws:iam::1234567891234:role/example-role --adfs-host=adfs.example.com --stdout

Warning: see AWS documentation about security considerations to take when sourcing credentials with an external process.


help, help, help?

$ aws-adfs --help
Usage: aws-adfs [OPTIONS] COMMAND [ARGS]...

Options:
--version Show current tool version
-v, --verbose Enables debug information on stdout. By default log level is
set on ERROR
--help Show this message and exit.

Commands:
list lists available profiles
login Authenticates an user with active directory credentials
reset removes stored profile



$ aws-adfs list --help
Usage: aws-adfs list [OPTIONS]

lists available profiles

Options:
--help Show this message and exit.



$ aws-adfs login --help
Usage: aws-adfs login [OPTIONS]

Authenticates an user with active directory credentials

Options:
--profile TEXT AWS cli profile that will be authenticated.
After successful authentication just use:
aws --profile <authenticated profile>
<service> ...
--region TEXT The default AWS region that this script will
connect to for all API calls
--ssl-verification / --no-ssl-verification
SSL certificate verification: Whether or not
strict certificate verification is done,
False should only be used for dev/test
--adfs-ca-bundle TEXT Override CA bundle for SSL certificate
verification for ADFS server only.
--adfs-host TEXT For the first time for a profile it has to
be provided, next time for the same profile
it will be loaded from the stored
configuration
--output-format [json|text|table]
Output format used by aws cli
--provider-id TEXT Provider ID, e.g urn:amazon:webservices
(optional)
--s3-signature-version [s3v4] s3 signature version: Identifies the version
of AWS Signature to support for
authenticated requests. Valid values: s3v4
--username-password-command TEXT
Read username and password from the output
of a shell command (expected JSON format:
`{"username": "myusername", "password":
"mypassword"}`)
--mfa-token-command TEXT Read MFA token for Symantec or RSA
authenticators from the output of a shell
command (expected JSON format:
`{"mfa_token": "123654"}`)
--env Read username, password and optionally an
MFA token from environment variables
(username, password and mfa_token).
--stdin Read username, password from standard input
separated by a newline.
--authfile TEXT Read username, password from a local file
(optional)
--stdout Print aws_session_token in json on stdout.
--printenv Output commands to set AWS_ACCESS_KEY_ID,
AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN,
AWS_DEFAULT_REGION environmental variables
instead of saving them to the aws
configuration file.
--print-console-signin-url Output a URL that lets users who sign in to
your organization's network securely access
the AWS Management Console.
--console-role-arn TEXT Role to assume for use in conjunction with
--print-console-signin-url
--console-external-id TEXT External ID to pass in assume role for use
in conjunction with --print-console-signin-
url
--role-arn TEXT Predefined role arn to selects, e.g. aws-
adfs login --role-arn arn:aws:iam::123456789
012:role/YourSpecialRole
--session-duration INTEGER Define the amount of seconds you want to
establish your STS session, e.g. aws-adfs
login --session-duration 3600
--no-session-cache Do not use AWS session cache in
~/.aws/adfs_cache/ directory.
--assertfile TEXT Use SAML assertion response from a local
file
--sspi / --no-sspi Whether or not to use Kerberos SSO
authentication via SSPI (Windows only,
defaults to True).
--duo-factor TEXT Use a specific Duo factor, overriding the
default one configured server side. Known
Duo factors that can be used with aws-adfs
are "Duo Push", "Passcode", "Phone Call" and
"WebAuthn Security Key".
--duo-device TEXT Use a specific Duo device, overriding the
default one configured server side. Depends
heavily on the Duo factor used. Known Duo
devices that can be used with aws-adfs are
"phone1" for "Duo Push" and "Phone Call"
factors. For "Passcode" and "WebAuthn
Security Key" factors, it is always "None".
--enforce-role-arn Only allow the role passed in by --role-arn.
--aad-verification-code TEXT Verification code for Azure AD multi-factor
authentication.
--help Show this message and exit.



$ aws-adfs reset --help
Usage: aws-adfs reset [OPTIONS]

removes stored profile

Options:
--profile TEXT AWS cli profile that will be removed
--help Show this message and exit.




Known issues


duo-security
Error: Cannot begin authentication process. The error response: {"message": "Unknown authentication method.", "stat": "FAIL"}
Please setup preferred auth method in duo-security settings (settings' -> 'My Settings & Devices').


USB FIDO2 does not work in Windows Subsystem for Linux (WSL)
OSError: [Errno 2] No such file or directory: '/sys/class/hidraw'
USB devices are not accessible in WSL, please install and run aws-adfs on the Windows 10 host and then access the credentials in WSL from the filesystem. Example:
export AWS_CONFIG_FILE=/mnt/c/Users/username/.aws/config
export AWS_SHARED_CREDENTIALS_FILE=/mnt/c/Users/username/.aws/credentials



FIDO2 devices are not detected on Windows 10 build 1903 or newer
Running aws-adfs as Administrator is required since Windows 10 build 1903 to access FIDO2 devices, cf. https://github.com/Yubico/python-fido2/issues/55)


in cases of trouble with lxml please install
sudo apt-get install python3-dev libxml2-dev libxslt1-dev zlib1g-dev



in cases of trouble with pykerberos please install
sudo apt-get install python3-dev libkrb5-dev



in cases of trouble with OSX Sierra (obsolete OpenSSL), upgrade OpenSSL. Example:
brew upgrade openssl

AND add explicit directive to .bash_profile:
export PATH=$(brew --prefix openssl)/bin:$PATH



only python >= 3.7 to <4.0 are supported:

python 2.6 is not supported
python 2.7 is not supported
python 3.2 is not supported
python 3.3 is not supported
python 3.4 is not supported
python 3.5 is not supported
python 3.6 is not supported



Development

update dependencies:

poetry update


run unit tests:

poetry run pytest


release:

export CHANGELOG_GITHUB_TOKEN=$(gopass show -o pins/Github/github-changelog-generator)
./scripts/release.sh patch # or minor, major, prepatch, preminor, premajor, prerelease, or a valid semver string

Changelog
See the CHANGELOG.md file, which is generated using github-changelog-generator.