Overview of Getting and Using an AWS IAM Account

From UCSC Genomics Institute Computing Infrastructure Information

Revision as of 18:45, 7 February 2019 by Weiler (talk | contribs)

Getting 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 will 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 bill@ucsc.edu, for example: 

* Click "bill@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.

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 "bill@ucsc.edu @ gi-gateway" on the top right of your browser window (again, bill@ucsc.edu is an example).
* Click the "My 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 "Virtual MFA Device".
* 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. 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 "bill@ucsc.edu @ gi-gateway" on the top right of your browser window (again, bill@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 "develop @ pangenomics" in the top right corner of the window.
* Select "Back to bill@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.

When using the "aws" command line tool, assuming you have it installed (the process of which is outside the scope of this document), you would use the steps outlined in this document to configure it: 

https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html

That document has a lot of other really useful information in it - if you plan on using keys for API access, we highly recommend reading it through.

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: 

$ 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. You may want to configure something like this: 

[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/bill@ucsc.edu

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 'mda_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.

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

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 by default for one hour, so you can run other 'aws' cli commands for one hour without the need to re-authenticate with MFA. After one hour, you will need to authenticate via MFA again.

You can extend your session length from one hour to twelve hours but utilizing the AWS Security Token Service (AWS STS). See this page for more information on how to do this: 

https://docs.aws.amazon.com/cli/latest/reference/sts/assume-role.html#examples

The examples at the bottom are particularly useful.

Retrieved from "http://giwiki.gi.ucsc.edu/index.php?title=Overview_of_Getting_and_Using_an_AWS_IAM_Account&oldid=121"