Metadata-Version: 2.0
Name: aws-role-credentials
Version: 0.6.4
Summary: Generates AWS credentials for roles using STS
Home-page: https://github.com/petergillardmoss/aws_role_credentials
Author: Peter Gillard-Moss
Author-email: pgillard@thoughtworks.com
License: ISCL
Keywords: aws_role_credentials
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Requires-Dist: boto
Requires-Dist: six

===============================
AWS Role Credentials
===============================

.. image:: https://img.shields.io/pypi/v/aws_role_credentials.svg
        :target: https://pypi.python.org/pypi/aws_role_credentials

.. image:: https://snap-ci.com/ThoughtWorksInc/aws_role_credentials/branch/master/build_image
        :target: https://snap-ci.com/ThoughtWorksInc/aws_role_credentials/branch/master

Generates AWS credentials for roles using STS and writes them to ```~/.aws/credentials```

Usage
=====

Simply pipe a SAML assertion into awssaml

.. code-block:: shell

    # create credentials from saml assertion
    $ oktaauth -u jobloggs | aws_role_credentials saml --profile dev

Or for assuming a known role name:

.. code-block:: shell

    # create credentials from saml assertion using a known role ARN
    $ oktaauth -u jobloggs | aws_role_credentials saml --profile dev --role-arn arn:aws:iam::098765432109:role/ReadOnly

Or for assuming a role using an IAM user:

.. code-block:: shell

    # create credentials from an iam user
    $ aws_role_credentials user \
      arn:aws:iam::111111:role/dev jobloggs-session \
      --profile dev

For roles that require MFA:

.. code-block:: shell

    # create credentials from an iam user with mfa
    $ aws_role_credentials user \
      arn:aws:iam::111111:role/dev jobloggs-session \
      --profile dev \
      --mfa-serial-number arn:aws:iam::111111:mfa/Jo \
      --mfa-token 102345

Transient mode
--------------

```aws_role_credentials``` also supports 'transient' mode where the
credentials are passed to a command as environment variables within
the process.  This adds an extra layer of safety and convinience.

To use transient mode simply pass a command to the ```--exec``` option
like so:

.. code-block:: shell

    # run 'aws s3 ls' with the generated role credentials from an iam user
    $ aws_role_credentials user \
      arn:aws:iam::111111:role/dev jobloggs-session \
      --exec 'aws s3 ls'


Options
=======

    --profile          Use a specific profile in your credential file (e.g. Development).  Defaults to sts.
    --region           The region to use. Overrides config/env settings.  Defaults to us-east-1.
    --role-arn         Optional `role ARN`_ to use when multiple roles are available.
    --exec             The command to execute with the AWS credentials

.. _role ARN: http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html

Thanks
======

Thanks to Quint Van Deman of AWS for demonstrating how to do this. https://blogs.aws.amazon.com/security/post/Tx1LDN0UBGJJ26Q/How-to-Implement-Federated-API-and-CLI-Access-Using-SAML-2-0-and-AD-FS


Authors
=======

* Peter Gillard-Moss




History
-------

0.1.0 (2015-01-11)
---------------------

* First release on PyPI.


