Skip to main content

Working as a Collaborator

A member of the ministryofjustice GitHub Organisation can request the set up of a new external collaborator here.

Once you have been set up as a collaborator you can -

Logging in to the AWS Console

  1. Click on the AWS Console url - https://eu-west-2.console.aws.amazon.com/

  2. You will see the sign on screen, choose IAM user and enter the Modernisation Platform landing zone account number (this will be provided to you on set up).

  3. Enter your user details (your MFA and console password must be set up first)

  4. Once you are logged in, switch role to the relevant account.

  5. You will need to know the account number of the AWS account you want to switch to and the role you have been assigned, these will be told to you on initial user set up, the valid roles are:

Role Description Typical User
read-only Read only console access Used by read only users such as security testers
security-audit AWS security-audit policy Used by security testers
developer Read only console plus other permissions such as the ability to set secrets,restart EC2s, raise support tickets. Used by engineers working on the application infrastructure
sandbox Admin role to perform most AWS actions via the console Used by engineers to make development easier in some situations, only allowed in the development account
migration Role with developer and AWS migration services permissions Used by engineers to migrate applications, will be removed before application goes into production
instance-access Role for login access to EC2 instances and secret access controlled by instance-access-policy resource tag Used by application support teams.
instance-management Role for use by instance management with permissions for EC2 and RDS instances and all secrets Used by database or EC2 administrators to migrate services and perform tasks.
security-audit Role with AWS managed SecurityAudit policy Used by members of security and audit teams.

You can see the accounts and roles assigned to you here

Getting access credentials

AWS provides credentials which can give you programmatic access to your AWS account. This enables you to run AWS CLI commands or Terraform plans locally.

Running a Terraform plan locally as a collaborator

Set credentials

To run a Terraform locally as a collaborator, you will need to get your AWS credentials. See above for creating and obtaining these, you will need use a tool such as aws-vault to handle MFA, or you can generate a session token using the AWS CLI. (Terraform does not support the use of MFA well when assuming roles.)

Set the role you assume

There are different access levels that map to different roles that you can assume when running Terraform.

By default if you do nothing the role you assume will be the developer role.

If you wish to assume another role, eg migration or sandbox you will need to set an environment variable:

export TF_VAR_collaborator_access=migration

Install Terraform

Follow the instructions here to install the latest version of Terraform according to your platform.

Run Terraform plan

  1. Navigate to your application infrastructure code - cd modernisation-platform-environments/terraform/environments/my-application
  2. Run a Terraform init - terraform init
  3. View the workspaces (you have different workspaces for your different environment accounts) - terraform workspace list
  4. Select the required workspace - terraform workspace select my-application-development
  5. Run a Terraform plan - terraform plan

Running a plan locally has read only permissions, you will not be able to run an apply, destroy or import.

Accessing EC2s as a Collaborator

You will need to have the developer, instance-management or instance-access role in order to use SSM/Bastion.

  1. Download the AWS CLI
  2. Ensure you have your AWS credentials
  3. In your terminal enter aws configure to set up credentials and enter the key and access key created in the previous step.
  4. Open ~/.aws/config in a text editor and enter the following to create your AWS profile:
[profile <my-application-account-name>]
source_profile = default
role_arn:arn:aws:iam::<your application account number>:role/developer
mfa_serial = arn:aws:iam::<landing zone account number>:mfa/<your user name>
role_session_name=<my-application-account-name>

Accessing EC2s with SSM Agent installed

Most modern AMIs will already have the SSM Agent installed. You can connect to these instances directly with Session Manager.

The developer and instance-management role allow full SSM access to all resources. The instance-access role allows restricted access based on the instance-access-policy resource tag:

Resource instance-access-policy tag value Description
EC2 undefined Full SSM access allowed
EC2 none No access via SSM allowed
EC2 limited SSH and Port Forwarding over SSM allowed
EC2 full Full SSM access allowed
SecretsManager Secret undefined No access to secret
SecretsManager Secret none No access to secret
SecretsManager Secret limited Read-only access to secret
SecretsManager Secret full Read-Write access to secret

The instance-management role allows restricted access to secrets based on the instance-management-policy resource tag: |SecretsManager Secret|undefined|Read-only access to secret| |SecretsManager Secret|full|Read-Write access to secret|

  1. Start a basic Session Manager session

This will give you a Linux shell or a Windows powershell with root/Admin access.

aws ssm start-session --target i-12345bc --profile <my aws profile>

  1. Start a port forwarding Session Manager session

The following example starts a port forwarding session mapping remote port 1521 to local port 1521.

aws ssm start-session --target i-12345bc --profile <my aws profile> --document-name AWS-StartPortForwardingSession --parameters '{"portNumber":["1521"],"localPortNumber":["1521"]}'

  1. Start an SSH session using Session Manager

Connect using SSH over SSM. Useful if you want to restrict sudo access. The relevant user and ssh key-pair must be configured on the EC2.

Example SSH config ~/.ssh/config

Host i-*
   ProxyCommand sh -c "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p' --profile <my aws profile>"
   User <my ec2 username>

And then just ssh i-12345bc

  1. Accessing Windows EC2 via Fleet Manager Remote Desktop console

Launch Fleet Manager RDP Connect and add the relevant node.

Log-in using either: - Single Sign-On (for local admin user) - Key Pair (providing Administrator key pair is configured) - User credentials (if EC2 is joined to a domain for example, or another local user configured)

Accessing EC2s via a bastion

  1. Create a bastion EC2 using the bastion module
  2. Create or share your public key and preferred username as detailed in the bastion readme
  3. Open ~/.ssh/config in a text editor and enter the following:
Host bastion
     IdentityFile ~/.ssh/id_rsa #local path to the public key provided in earlier
     User <your user name>
     ProxyCommand sh -c "aws ssm start-session --target $(aws ec2 describe-instances --no-cli-pager --filters "Name=tag:Name,Values=bastion_linux" --query 'Reservations[0].Instances[0].InstanceId' --profile <my aws profile>) --document-name AWS-StartSSHSession --parameters 'portNumber=%p' --profile <my aws profile> --region eu-west-2"
  1. To SSH or other port tunneling (eg to connect to a database) through the bastion to your EC2 instance, using the relevant ports:
  ssh -L 33389:<IP address of destination instance>:3389 bastion

Useful Tips

AWS Vault is a useful tool, and can be found here. Mac users can install it using Homebrew.

This page was last reviewed on 27 September 2024. It needs to be reviewed again on 27 March 2025 by the page owner #modernisation-platform .
This page was set to be reviewed before 27 March 2025 by the page owner #modernisation-platform. This might mean the content is out of date.