ikerry/aws-adfs repository overview

⁠aws-adfs

The project provides two command line tools:

1. aws-adfs to ease aws cli authentication against ADFS (multi factor authentication with active directory) and
2. awsr to ease automatic re-authentication against ADFS server in case of AWS token expiration.

⁠aws-adfs command line tool

Thanks to Brandond⁠ contribution - "Remove storage of credentials, in favor of storing ADFS session cookies" aws-adfs:

Thanks to Brandond⁠ contribution - "Add support for legacy aws_security_token key in credentials file" aws-adfs supports ansible by providing two keys with security token:

• AWS_SESSION_TOKEN and
• AWS_SECURITY_TOKEN

Thanks to Brandond⁠ contribution - "Add support for Kerberos SSO on Windows via requests_negotiate_sspi"

• on windows os will be used Security Support Provider Interface

⁠Compatibility

As of version 0.2.0, this tool acts on the 'default' profile unless an alternate profile name has been specified on the command line or in your environment. Previous versions acted on the 'adfs' profile by default.

⁠MFA integration

aws-adfs integrates with:

• duo security⁠ MFA provider
• Symantec VIP⁠ MFA provider

⁠awsr command line tool

awsr command decorates aws command provided by awscli python package. It delegates the execution to aws command and verifies the return code. When the return code indicates that AWS token has expired then aws-adfs is invoked for an attempt of re-authentication. If re-authentication is finished with success then original aws command is invoked for the second time.

⁠Replacing aws command with awsr

Replacement of aws command with awsr can be done by aliasing aws command.

• bash: alias aws='awsr'
• fish: alias aws 'awsr'

⁠Fish command completion

Place somewhere in your config.fish

test -x (which aws_completer); and complete --command awsr --no-files --arguments '(begin; set --local --export COMP_SHELL fish; set --local --export COMP_LINE (commandline); aws_completer | sed \'s/ $//\'; end)'

⁠Installation

• user local installation

  pip install aws-adfs
  

  Copy

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

• system wide installation

  sudo pip install aws-adfs
  

  Copy

• virtualenvs

  virtualenv -p /usr/bin/python2.7 aws-adfs
  source aws-adfs/bin/activate
  pip install aws-adfs
  ...
  ...
  deactivate
  

  Copy

⁠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
  

  Copy

  and verification

  aws --profile=adfs s3 ls
  

  Copy

• 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
  

  Copy

  and verification

  aws --profile=specified-profile s3 ls
  

  Copy

• 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
  

  Copy

• help, help, help?

  $ aws-adfs --help
  Usage: aws-adfs [OPTIONS] COMMAND [ARGS]...
  
  Options:
    --version  Show current tool version
    --help  Show this message and exit.
  
  Commands:
    list   lists available profiles
    login  Authenticates an user with active directory...
    reset  removes stored profile
  

  Copy

  $ aws-adfs list --help
  Usage: aws-adfs list [OPTIONS]
  
    lists available profiles
  
  Options:
    --version  Show current tool version
    --help  Show this message and exit.
  

  Copy

  $ 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-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
    --env                           Read username, password from environment
                                    variables (username and password).
    --stdin                         Read username, password from standard input
                                    separated by a newline.
    --stdout                        Print aws_session_token in json on stdout.
    --role-arn TEXT                 Predefined role arn to selects, 
                                    e.g. aws-adfs login --role-arn arn:aws:iam::123456789012:role/YourSpecialRole
    --help                          Show this message and exit.
  

  Copy

  $ aws-adfs reset --help                                                                                                                                              13:39
  Usage: aws-adfs reset [OPTIONS]
  
    removes stored profile
  
  Options:
    --profile TEXT  AWS cli profile that will be removed
    --help          Show this message and exit.
  

  Copy

⁠awsr

• list buckets on s3

  awsr s3 ls
  

  Copy
• list buckets on s3 using sandbox profile

  awsr --profile sandbox s3 ls
  

  Copy

⁠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-sercurity settings (settings' -> 'My Settings & Devices').

• in cases of trouble with lxml please install

  sudo apt-get install python-dev libxml2-dev libxslt1-dev zlib1g-dev
  

  Copy

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

  brew upgrade openssl
  

  Copy

  AND add explicit directive to .bash_profile:

  export PATH=$(brew --prefix openssl)/bin:$PATH
  

  Copy

• python 2.6 is not supported

• python 3.2 is not supported

⁠Credits

• Brandond⁠ for: Remove storage of credentials, in favor of storing ADFS session cookies
• Brandond⁠ for: Add support for legacy aws_security_token key in credentials file
• Brandond⁠ for: Store last username in profile config; use it as default for prompt
• Brandond⁠ for: python 3 compatibility
• Brandond⁠ for: Add support for Kerberos SSO on Windows via requests_negotiate_sspi
• Brandond⁠ for: ssl_verification must be a str
• Brandond⁠ for: Move pytest-runner out of setup-requires
• Brandond⁠ for: Improve handling of role selection
• Brandond⁠ for: Improve handling of errors caused by excessive cookie growth
• Brandond⁠ for: Default to 'default' profile, in line with other AWS tools
• kwhitlock⁠ for: Added extra option "--provider-id"
• SydOps⁠ for: add additional information in list command's output
• eric-nord⁠ for: bringing topic of duo security⁠ MFA integration
• roblugton⁠ for: Fix formatting in README.md
• cliv⁠ for: pointing out the issue with missing preferred device for duo-security and providing workaround
• AndrewFarley⁠ for: Bug in parsing Duo host and signature, backwards compatible
• eikenb⁠ for: Version 0.3.4 returns no roles - thanks for vigilance of eikenb⁠ spoiled egg was identified
• eikenb⁠ for: add login argument to accept username/password from stdin
• irgeek⁠ for: Add Symantec VIP Access support
• Brandond⁠ for: Fix Negotiate auth on non-domain-joined Windows hosts
• giafar⁠ for: Role arn as parameter
• zanettibo⁠ for: Add support for Ansible Tower/AWX workflow authentication