Table of contents

This documentation is intended for internal use by the GDS community.

Accessing AWS Accounts

GDS manages a number of Amazon Web Services (AWS) accounts. User accounts are managed centrally by Reliability Engineering with a base GDS account. Users must sign into the base account through which they can access their own AWS accounts through a process called assuming roles.

Add new users to GDS AWS accounts

People joining GDS do not automatically have access to AWS.

To grant a user access to AWS you’ll need to add them to the gds-users base account. Once a user is added to the GDS base account it’s up to individual teams to grant the user access to any roles they need.

Fill in the request an AWS account form to add a user to the gds-users base account.

Access the AWS Console

  • Sign in to the GDS base account at:
    Screenshot of the sign in page Screenshot of the sign in page
  • From the menu in the top right, select “Switch Role”
    Screenshot of the switch role menu item Screenshot of the sign in page
  • Fill in the account number or account alias and role you’re switching to
    Screenshot of the switch role page Screenshot of the sign in page

Teams manage their own lists of accounts and roles (see GOV.UK, Verify, and Digital Marketplace’s lists of accounts).

Access AWS from the command line

There are several command line tools you can use to work with AWS, such as:

These tools need credentials to access AWS. The simplest way of managing these credentials is to use an AWS credentials file, though you may prefer to use a tool like aws-vault to manage your credentials for you.

Create an AWS credentials file

Create a local on your computer file at ~/.aws/credentials and add:

aws_access_key_id = MYACCESSKEYID
aws_secret_access_key = MYSECRETACCESSKEY

You can find your aws_access_key_id and aws_secret_access_key by logging into the the GDS base account using the AWS console. You’ll need to use the AWS instructions about creating, modifying, and viewing Access Keys (Console) to do this.

For each role you need to assume, add a section like:

source_profile = gds-users
region = eu-west-1
role_arn = <role arn>
mfa_serial = <mfa device arn>

Where <role arn> is taken from your team’s list of accounts and roles (see GOV.UK, Verify, and Digital Marketplace’s lists of accounts) and <mfa device arn> is your user’s assigned Multi-Factor Authentication (MFA) device.

How to find your MFA device ARN
  • sign in to the base account using the AWS console
  • navigate to IAM > Users > $your-user
  • select the Security credentials tab
  • look for the Assigned MFA device
  • Create tokens for command line use

    Some tools, such as Terraform can’t ask the user for an MFA token. To use these tools you’ll need to create a token using the AWS Security Token Service (STS).

    Using AWS CLI, run:

    aws sts assume-role \
      --role-session-name "$(whoami)-$(date +%d-%m-%y_%H-%M)" \
      --role-arn <role arn> \
      --serial-number <mfa device arn> \
      --duration-seconds "$((1*60*60))" \
      --token-code <mfa token>

    (Read the AWS CLI documentation to learn about assume-role in AWS).

    Use the values set in ~/.aws/credentials (see Creating an AWS credentials file) for <role arn> and <mfa device arn>. Use the current token shown by your MFA device for <mfa token>.

    This returns some JSON which contains keys and tokens, use it to set these environment variables:

    export AWS_ACCESS_KEY_ID=... # Credentials.AccessKeyId
    export AWS_SECRET_ACCESS_KEY=... # Credentials.SecretAccessKey
    export AWS_SESSION_TOKEN=... # Credentials.SessionToken

    Tools like Terraform will use these environment variables instead of the credentials file.

    Be aware the SessionToken will expire after one hour, or whatever time you supply in --duration-seconds (up to the maximum session duration for the role).