View source for Overview of Getting and Using an AWS IAM Account

__TOC__

== Getting AWS (Amazon Web Services) Access ==

The Genomics Institute has a series of AWS Accounts that all support different projects.  Often if you become associated with one or more of those projects, you will need access to that account or accounts.  The way we are managing AWS IAM Account Access is that we have one AWS account that is the 'top level' account that everyone gets access to, and then, once you log in there, you can "Switch Role" into another sub-account that you are running things in.  

To get access, you will need your PI or Project Manager to email cluster-admin (cluster-admin@soe.ucsc.edu) asking for an AWS account for you, and also in that email to name the projects you will have access to.  The cluster-admin group will contact you with your credentials to login.  Once you login, you can change your password if you want to and also you will be able to set up MFA (Multi Factor Authentication) for your account.  You will be required to use MFA in order to "Switch Role" into any of the sub-accounts for the projects you are working on.

The login URL to use when logging in to the top level account is listed below.  The top level account is known as "gi-gateway":

 https://gi-gateway.signin.aws.amazon.com/console

When you login, you '''may''' see a couple error messages on the AWS dashboard saying you don't have access to view certain resources - '''this is normal''', so just ignore the error messages.

== Configuring Account Credentials ==

Once you login to the gi-gateway, you will have very few permissions to do anything there - which is normal, since you will not be working in that account anyway.  The gi-gateway account is just there to authenticate you to AWS.

'''Changing Your Password'''

You can change your password by clicking on your username on the top right of the web browser window, just to the right of the little bell.  If your username is melinda@ucsc.edu, for example:

 * Click '''"melinda@ucsc.edu @ gi-gateway"''' on the top right of your browser window.
 * Click the '''"My Security Credentials"''' drop-down menu option.
 * Click the '''"Change Password"''' button to change your password.

Note that we have a password strength policy in place, so your password must conform to the following requirements:

 * Your password must be at least 10 characters long
 * Your password must contain at least one lowercase letter
 * Your password must contain at least one non-alphanumeric character
 * Your password must contain at least one number

You will also need to configure MFA on your account before you will be allowed to switch roles into another account.

'''Configuring MFA'''

To configure MFA (Multi Factor Authentication), the most common way to do it is to use '''Google Authenticator''', which is an app available for Apple and Android based cell phones and mobile devices.  The app is free, simply download it from the app store to your cell phone or tablet to get started.  Other MFA apps may also work but we have not tested everything out there.

Once you have Google Authenticator installed, log into the gi-gateway account using the above URL, then:

 * Click '''"melinda@ucsc.edu @ gi-gateway"''' on the top right of your browser window (again, melinda@ucsc.edu is an example).
 * Click the '''"Security Credentials"''' drop-down menu option.
 * Scroll down to the MFA (Multi-Factor Authentication) section of the page, and click '''"Assign MFA Device"'''.
 * In the following menu select '''"Authenticator App", and for the device name, use your username (which is your email address used to login)'''.
 * In the following window click the '''"Show QR Code"''' link, and the MFA QR barcode will appear on your screen.
 * Open the Google Authenticator app on your mobile device, and click the little "+" symbol in the top right corner
   of the app to add an account.
 * You will then need to select "Scan Barcode" in the Google Authenticaor app to continue, and aim your mobile device camera
   at the QR barcode.
 * The new account MFA device should then be set up and you should see a 6 digit number with a small timer to the right of it.
   You must type in one 6 digit code that it displays into your web browser when asked, then wait for the next code to appear
   after the timer expires, and type that into the second field.  It should then inform you that you have successfully associated
   an MFA device with your account.

Once you have associated an MFA device with the 'gi-gateway' Account, '''log out''', then log back in.  It will ask for your username and password, and then ask for your MFA code, which you can view by opening Google Authenticator and seeing what code it is displaying at that time.  The code changes every 30 seconds or so.   '''You must log out first and log back in using MFA in order to be able to switch roles!!!'''

== Switching Roles into Another AWS Account ==

Now that you have configured a password and enabled MFA, you will be allowed to "Switch Roles" into another account such that you can begin work there.  The first time you switch roles into an account it will ask you a few questions, but subsequently it will remember which roles you have access to and they will become a menu item you can click on to quickly switch roles.  

First, you need the name of the account you want to switch to. Select the name from the list at [[AWS Account List and Numbers]].

Let's assume that you want to switch to  the 'pangenomics' AWS account, and you have been already granted access to do so by the cluster-admin group.  After logging into the 'gi-gateway' account at the URL listed here (same as above):

 https://gi-gateway.signin.aws.amazon.com/console

Do the following to switch roles into the 'pangenomics' account (as an example):

 * Click '''"melinda@ucsc.edu @ gi-gateway"''' on the top right of your browser window (again, melinda@ucsc.edu is an example).
 * Click the '''"Switch Role"''' option in the drop-down menu.
 * In the following menu it will ask you about the role you will be assuming.  In our example we will use the following:
 
   -Account*     = pangenomics
   -Role*        = developer
   -Display Name = [leave blank, or use a short phrase]
   -Color        = [choose a color for this role]
 
 * Then click the "Switch Role" button.

If all went well you should be dumped into the 'pangenomics' account, and you should be identified in the top right hand corner of the page as '''"developer @ pangenomics"''', indicating your role and the account you are active in.  You can then work as normal in that account.  If you have not yet been given access to that role, you will receive an error message and not be allowed to switch roles.

'''NOTE:''' When you switch roles, it may dump you into a region that you don't expect it to.  Always verify the region you are in by looking at the top right of the web page - it will display your region there.  Most of our stuff exists in "Oregon" (us-west-2), but some items appear in other regions on a per-case basis.

If you wish to switch context back to the 'gi-gateway' account in order to manage something, or to switch to another role in another account, simple:

 * Click '''"developer @ pangenomics"''' in the top right corner of the window.
 * Select '''"Back to melinda@ucsc.edu"'''

You will then be sent back to the 'gi-gateway' context, and you can add another role to switch into, manage your credentials and further switch roles.

== API Access and Secret Keys ==

If you require programmatic access to AWS, you will very likely be familiar with the AWS concept of Access Keys and Secret Keys, which can be used by scripts to authenticate yourself to AWS and use the APIs there without using the web console to authenticate.  In the past, access keys and secret keys could be used by users with no further authentication.  This introduces a security risk, as the management of those keys must be carefully guarded - if anyone gets your keys, they can rack up charges on your AWS account without your knowledge!

Using the "Assume Role" mechanism we are now using, Access Keys and Secret Keys can still be created by users '''while logged into the gi-gateway account only'''.  Do not try to create keys while you have "Switched Roles" into another account.  Keys you create in the top level 'gi-gateway' account will work for you in any sub-account you have access to switch roles to.  You will need to do a little more configuration for your keys to work from a UNIX command line however.

To set up your access and secret keys for the first time (again, logged into the 'gi-gateway' account only), follow these instructions.  Once you log into the gi-gateway web interface, click on your username in the top right corner of the browser window, then click "My Security Credentials".  In that screen you will see an "Access Keys" section, and you will have one key listed.  Delete that key (using the "Delete" button on the right side of the key), then create a new key using the "Create Access Key" button.  It will show you your access and secret key ONCE, so make sure to copy and paste it somewhere.

It should be noted that we recommend awscli version 1.16.187 or later, as earlier versions have documented issues with using profiles and MFA related actions.  You can determine your version of awscli by doing:

 aws --version

=== Entering Base Credentials ===

Generically, if you plan on using keys for API Access, minimally you will need to configure the "aws" utility and then tweak the config a bit for our setup.  To start, run "aws configure".  It should look something like this (put in your access and secret keys that you created in the previous step):

 $ aws configure
 AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
 AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
 Default region name [None]: us-west-2
 Default output format [None]:

Most folks do that to start.  It creates two files:

 ~/.aws/config
 ~/.aws/credentials

Those two files are important to access AWS via the 'aws' command.

'''~/.aws/credentials'''

This file contains your access key and secret key, and should not need to be modified after running 'aws configure'.  Your same keys can be used to access any roles in any accounts you have access to.

'''~/.aws/config'''

This file contains some account information you will need to tweak.  There are a few ways you could set it up.

=== Adjusting Configuration for Toil or a Single Role ===

If you usually use a single role for a single project, or if you need to use Toil with a particular role, you should configure it like this, so that that role is automatically assumed for every operation by default:

 [default]
 region = us-west-2
 source_profile = default
 role_arn = arn:aws:iam::422448306679:role/developer
 mfa_serial = arn:aws:iam::652235167018:mfa/melinda@ucsc.edu
 duration_seconds = 43200

The "role_arn" line contains the role and account number you are accessing.  You can see a list of live account numbers here:

 [[AWS Account List and Numbers]]

Find the account number you need and enter it on the role_arn line, as well as the role name.  You will get the role name from the cluster-admin group when you get access.

The 'mfa_serial' line contains the identifier for your MFA device.  It will always look like '''"arn:aws:iam::652235167018:mfa/[your_iam_username]"'''.  The account number listed there will always be "652235167018" because that is the account number of the top level "gi-gateway" account.

The "duration_seconds" parameter says that your session token will be 43200 seconds long (12 hours).  That means you will only have to authenticate with MFA once every 12 hours.  12 hours is the maximum you can request, although you can specify less than that.  This means it won't ask you for MFA every time you run a command for the next 12 hours.

Once that is configured, you should be able to use the aws command without any profile specified, and have it automatically assume a role to grant you access:

 $ aws s3 ls

It will ask you for your MFA code and then run the command.  Once you enter the MFA code, the token it creates will be valid for 12 hours if you specified "duration_seconds = 43200", or if you omitted that line, the default session duration is one hour, so you can run other 'aws' cli commands without the need to re-authenticate with MFA for the duration of the session.  After the session expires, you will need to authenticate via MFA again.

=== Adjusting Configuration for Multiple Roles ===

If you have multiple roles that you use equally often, and you don't need to use Toil, you can configure it something like this, with multiple profiles:

 [default]
 region = us-west-2
 
 [profile pangenomics-developer]
 source_profile = default
 role_arn = arn:aws:iam::422448306679:role/developer
 mfa_serial = arn:aws:iam::652235167018:mfa/melinda@ucsc.edu
 duration_seconds = 43200
 
Once that is configured, you should be able to reference the profile you just created when using the aws command, like so:

 $ aws s3 ls --profile pangenomics-developer

==Tag Your Resources==

When you start using AWS resources (instances, networks, etc), it is very important that you "tag" your resources with the "Owner" tag (note the capital "O").  "Owner" is the key, and the value assigned to it will be your IAM username (i.e. your email address).  So, for example, if I spin up an instance, I would tag it during or after creation with something like:

 Owner = bob@ucsc.edu

If you do not tag your instances, '''they will automatically be terminated within 10 minutes.'''  Tag your instances especially, but tag every resource you create!  This allows us to perform accounting tasks much more easily and allows the Program Managers to know which resources are controlled by who.