Skip to main content

AWS CLI authenticator via ADFS - small command-line tool to authenticate via ADFS and assume chosen role

Project description

aws-adfs

PyPI version Travis build Build Status

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

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.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aws_adfs-2.11.2.tar.gz (36.0 kB view hashes)

Uploaded Source

Built Distribution

aws_adfs-2.11.2-py3-none-any.whl (42.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page