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

Click on the AWS Console url - https://eu-west-2.console.aws.amazon.com/
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).
Enter your user details (your MFA and console password must be set up first)
Once you are logged in, switch role to the relevant account.
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

Navigate to your application infrastructure code - cd modernisation-platform-environments/terraform/environments/my-application
Run a Terraform init - terraform init
View the workspaces (you have different workspaces for your different environment accounts) - terraform workspace list
Select the required workspace - terraform workspace select my-application-development
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.

Download the AWS CLI
Ensure you have your AWS credentials
In your terminal enter aws configure to set up credentials and enter the key and access key created in the previous step.
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

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>

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"]}'

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

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

Create a bastion EC2 using the bastion module
Create or share your public key and preferred username as detailed in the bastion readme
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"

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.