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
From the menu in the top right, select “Switch Role”
Screenshot of the switch role menu item
Fill in the account number or account alias and role you’re switching to
Screenshot of the switch role page
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:
[gds-users] aws_access_key_id = MYACCESSKEYID aws_secret_access_key = MYSECRETACCESSKEY
You can find your
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:
[your-account-name] source_profile = gds-users region = eu-west-1 role_arn = <role arn> mfa_serial = <mfa device arn>
<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
Security credentials tab
Assigned MFA device
Create tokens for command line use
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
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