rolemodel 0.1.0

Description:

rolemodel 0.1.0

rolemodel=========**Rolemodel** is a command line tool that helps you set up and maintaincross-account IAM roles for the purpose of using them in the new[switch role](https://aws.amazon.com/blogs/aws/new-cross-account-access-in-the-aws-management-console/)capability of the AWS management console. These same cross-account rolescan also be used with the AWSCLI as described[here](http://lexical.scopely.com/2015/01/09/switching-roles/).The main benefit of enabling these cross-account roles is that you onlyhave to maintain a single set of IAM users in one "master" AWS account.By controlling which IAM groups these users are members of, you can controlwhich other accounts they have access to and what privileges they havein each of those accounts.A Little Terminology--------------------For the purposes of this document, lets define a couple of terms.* **Assumable Account** is an AWS account in which IAM roles have been created for the purpose of allowing cross-account access. You can have any number of assumable accounts.* **Master Account** is the account in which you will create and maintain IAM users. This is the account your users will log into to switch to other assumable accounts. You can have only one master account.What Does rolemodel Do?-----------------------The ``rolemodel`` tool:* Uses CloudFormation to create a consistent set of roles across all assumabe accounts you specify.* Creates IAM groups in the master account to control which IAM users in the master account can assume which roles in which assumable accounts. If you have defined four roles and you have 4 assumable accounts, ``rolemodel`` will create a total of 16 groups in the master account.* Optionally, ``rolemodel`` can also be used to map existing IAM users in the master account into the appropriate roles for each of the assumable accounts. It will not create IAM users for you.The ``rolemodel`` tool will create all roles and groups initially but can alsobe used to update roles over time. If you add more roles or change thepolicies of existing roles you can run the ``update`` command and ``rolemodel``will take care of the rest.What Do I Have To Do?---------------------As an administrator you are responsible for:* Defining the IAM roles and related policies that you want to enable in all of your assumable accounts.* Running the ``rolemodel`` tool to create and update the IAM roles when necessary.* Manage the membership in the IAM groups created in the master account. By adding an IAM user to one of the IAM groups you are granting that user the ability to switch to that account with the privileges granted by the IAM policies associated with that IAM role.* Carefully control IAM access in the master account. Any IAM user that can change group membership in the master account has the ability to elevate any IAM user in the master account to the most-privileged IAM role in all assumable accounts. You should control this carefully!Getting Started---------------First, you need to install ``rolemodel``. The easiest way is with pip,preferably inside a virtualenv. pipinstallrolemodelYoucanalsoclonethe[Githubrepo](https://github.com/scopely−devops/rolemodel)andthenrun‘‘pythonsetup.pyinstall‘‘insidethecloneddirectory.‘‘rolemodel‘‘isbuiltwith[botocore](https://github.com/boto/botocore)andusesthesamecredentialfileasdefinedby[AWSCLI](https://github.com/aws/aws−cli).ThenextstepistodefineyourmastersetofrolesinaCloudFormationtemplate.Thereisasamplesetofrolescontainedinthefile‘‘samples/roles.cf‘‘butyoushouldeditthistosuityourneeds.EachroledefinedinyourCloudFormationtemplatewillbecreatedinalloftheassumableaccountsyouspecify.Thenextthingyouneedtodoiscreateaconfigurationfiletotell‘‘rolemodel‘‘aboutyourassumableaccountsandotherinfo.ThereisasampleYAMLconfigfilein‘‘samples/config.yml‘‘.Youneedtoprovidethefollowinginformationintheconfigfile.∗∗∗assumableroles∗∗shouldbethepathtotheCloudFormationtemplatedefiningtheIAMrolesthatwillbecreatedineachassumableaccount.∗∗∗masteraccountid∗∗isthe12−digitIDfortheaccountthatwillbethemasteraccount.∗∗∗masteraccountprofile∗∗isthenameoftheprofilewithinyourAWSconfigorcredentialfilethatcontainsthecredentialsforthemasteraccount.∗foreachassumableaccount:∗∗∗name∗∗isthesymbolicnameoftheassumableaccount.Thisnameisusedwhenconstructingthegroupnamesinthemasteraccount.∗∗∗profile∗∗isthenameoftheprofilewithinyourAWSconfigorcredentialfilethatcontainsthecredentialsforthisassumableaccount.ThesecredentialsmustbeabletocreateIAMroleswithintheassumablaccount.OnceyouhavetheIAMrolesdefinedandyourconfigurationfilecreatedyoucanrunthe‘‘rolemodel‘‘commandlinetool. rolemodel <path to config file> updateThis will create or update all of the IAM roles defined in your CloudFormationtemplate in all assumable accounts specified in your configuration file. Itwill then create or update all required IAM groups in your master account. Youcan run this command multiple times. If no changes have been made in your IAMroles then nothing will be done by ``rolemodel``.If you want to get a list of all roles and all assumable accounts, use: rolemodel<pathtoconfigfile>listFinally,ifyouwanttodeleteallIAMrolesinallassumableaccountsandalsodeleteallIAMgroupsinthemasteraccount,use: rolemodel <path to config file> deleteManaging Users in Master Account--------------------------------You can do the above steps and then manually manage the process of making IAMusers in the master account members of the appropriate groups to allow them toassume roles in assumable accounts. However, ``rolemodel`` does provide amechanism to support this part of the process as well.To take advantage of this feature, you need an additional YAML file that mapsexisting IAM users in the master account into the necessary IAM groups. Thestructure of this file is shown below. --- acct1: role1: - user1 - user2 role2: - user3 - user4 acct2: role1: - user1 - user3 role2: - user5 - user6The main keys in this dictionary are the names of the assumable accounts.Within each of the accounts are additionaly dictionaries for each of theassumable roles that are defined. And each role name contains a list ofexisting IAM users in the master account that should be allowed to assume thatrole.Once you have defined this file for your accounts, you can run the command tosync your groups with this file. $ rolemodel <path to config file> sync_users <path to user map file>The ``sample`` directory includes an example of a user map file you can editfor your purposes.Groups In Master Account------------------------The name of each group created in the master account will be of the form: RM.<assumble account name>.<role name>The ``assumable account name`` comes from the name you provide for theassumable account in the config file. The ``role name`` comes from the nameused for the role in the CloudFormation template.