Skip to main content

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

Amazon Web Services (AWS)

Several teams in GDS use Amazon Web Services (AWS) as their infrastructure provider. GDS teams manage their own AWS accounts, but users must first sign into a shared base AWS account managed by the Reliability Engineering team.

Access AWS Accounts

People joining GDS do not automatically have access to Amazon Web Services (AWS). To grant a user access to AWS you’ll need to add them to the gds-users base account.

To add a user to the gds-users base account, complete the Request user access section of the request an AWS account form form.

After a user is added to the GDS base account it’s the individual teams’ responsibility to grant that user access to any team specific roles.

Once setup is complete users can access AWS using the AWS Console or the command line.

Use AWS Console

  • Sign in to the GDS base account at:
    Screenshot of the sign in page Screenshot of the sign in page
  • From the top right dropdown menu, select Switch Role
    Screenshot of the switch role menu item Screenshot of the sign in page
  • Complete Account with account or account alias and the 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, for example GOV.UK, Verify, and Digital Marketplace.

Use 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. We recommend using gds-cli to manage your credentials.

Installing gds-cli

gds-cli needs to be installed and available on your PATH. The easiest way to do this is via Homebrew: brew install alphagov/gds/gds-cli.

When you run gds aws <some-role> for the first time, it will prompt for your Access Key ID and Secret Access Key for AWS access and store them using aws-vault.

You can find your aws_access_key_id and aws_secret_access_key by logging into the GDS base account using the AWS Console.

If you get MFA codes from your phone, run gds config yubikey false

Using gds-cli

To use gds-cli, run gds aws to list all available accounts, then select one to access with gds aws <some-role>.

Further usage instructions can be found in the gds-cli README.

Create AWS Accounts

GDS teams can request as many AWS accounts as required, for example one production and one non-production account.

Using multiple AWS accounts allows GDS teams to:

  • enforce administrative isolation between workloads
  • minimize the impact of security breaches
  • isolate audit data in separate accounts

AWS Answers has more information about AWS Multiple Account Security Strategy.

Request an account

To request an AWS account complete and submit the request an AWS account form.

Reliability Engineering will confirm if your account can be included in GDS AWS billing and perform the initial account setup.

Once your account is created you’ll receive an email with the account ID and will be able to assume an administrative role from the GDS users base account.

Set up an account

Your new account will come with a GDS created bootstrap role which has full admin rights.

All users in the Request an AWS account form will be able to assume the bootstrap role from the GDS users base account.

You should use the bootstrap role to set up your new account following your team’s best practices, for example using Terraform.

As part of your account setup, ensure your users can assume roles with permissions relevant to their role.

Remove the bootstrap role once you’ve added a properly configured admin role.

Manage AWS accounts

If you’re setting up a new AWS account and your team want to use cross-account access use the gds-users account as your base account.

Use multiple AWS accounts to:

  • enforce administrative isolation between workloads
  • minimize the impact of security breaches
  • isolate audit data in separate accounts

By having separate AWS accounts for production and test workloads teams can restrict the security impact of a compromised AWS credential.

To avoid managing several sets of AWS credentials for multiple accounts, teams should use roles and cross-account access. AWS describe this approach as multiple account security strategy.

Cross account access

AWS cross account access allows user accounts held in the gds-users base account to access resources in target AWS account’s created by your team.

Access to resources within a target AWS account is controlled using AWS Identity and Access Management (IAM) roles managed within that AWS account.

IAM roles establish trust relationships between the target’s (trusting) AWS account and the GDS base (trusted) AWS account.

Manage Access to Resources

Users exist in the GDS base account and have permission to assume a role into a target account. The target account defines the roles users in the base account can assume, for example a Data Analyst:

Assume Role Diagram

The Trust Relationship (Assume Role Policy)

The trust relationship describes what entities can assume the role (principles) and imposes conditions on how and when those entities can assume the role. An AWS principle can be a user account, an AWS account or a role, principle entities are expressed as an Amazon Resource Name (ARN).

Use conditions to enforce the presence of Multifactor authentication (MFA), for example restricting access to particular IP addresses or particular times of the day.

It’s strongly recommended not to trust an AWS base account. Trusting an AWS base account allows all of the entities within that base account to assume that particular role.

Example Trust Relationship policy:

  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::123456789012:user/" },
    "Action": "sts:AssumeRole",
    "Condition": { "Bool": { "aws:MultiFactorAuthPresent": "true" } }

Resource Permissions (Policies)

Access to resources are managed through IAM Policies which can be custom built or defined by Amazon. Design your roles around the permissions people need to complete a task.

Amazon provides some examples of AWS policies related to IAM permissions.

Manage “admin” permissions

It is strongly recommended that anyone supporting an AWS account in an engineering capacity should have admin access. Admin access should allow an engineer to completely recreate any given resource running in the account.

In AWS one can restrict access to resources by only allowing only certain permissions:

data "aws_iam_policy_document" "admin" {
  statement {
    actions = [
     resources = [""]
    effect    = "Allow"

This should be done where we do not want services to be run for proprietary service proliferation reasons, not for security reasons. The use case for this is so that we can manage what AWS services we consume, for instance not allowing people to spin up an AWS Neptune database.

Services can be managed at the organisation level using service control policies, but this is not something we currently use. More information can be found here.

It is an anti-pattern for administrators to not have full IAM permissions. The reasoning behind this decision is that it prevents untracked access to things. However in practice it leads to the use of shared users and roles rather than the creation of a single user and/or role for a given purpose, which violates the principle of least privilege.

Name IAM roles

For IAM roles attached to human IAM users, they should have descriptive names and ideally conform to the following (except for extenuating circumstances):

  • Admin: Can do everything in the account including IAM administration
  • Trusted user: Can do most things in the account excluding IAM administration
  • Read only: Can read things in the account but not perform any side-effects; should NOT be able to do things like ssm:DescribeParameters

Delete AWS accounts

When your team no longer requires an AWS account, contact Reliability Engineering using the #Reliability-eng Slack Channel.

GDS teams are responsible for managing their own leavers’ process.

Remove access to AWS accounts

When someone no longer requires access to AWS (for example, because they’ve left GDS or your team) remove them from the gds-users base account using the Request user removal section of the:

Request an AWS account form.

Before you request someone’s removal make sure they do not need access to AWS in another team within GDS.

GDS teams are responsible for managing their own leavers’ process.